tests: add full PHPStan typing tests

src/Collection.php

@@ -190,6 +190,7 @@ public function count(): int;
 	 * Returns the number of elements matching the predicate.
 	 *
 	 * @param Closure(E, int):bool $predicate
+	 * @return int<0, max>
 	 */
 	public function countWhere(Closure $predicate): int;
 

src/List/ListInterface.php

@@ -42,6 +42,16 @@ public function get(int $index);
 	 */
 	public function getOrNull(int $index): mixed;
 
+	/**
+	 * Returns the element at the specified index, or throws if out of bounds.
+	 * Alias of get() for array access syntax `$list[0]`.
+	 *
+	 * @param int $offset
+	 * @return E
+	 * @throws IndexOutOfBoundsException
+	 */
+	public function offsetGet(mixed $offset): mixed;
+
 	/**
 	 * Returns the element at the specified index, or the default value if out of bounds.
 	 *

src/Map/Map.php

@@ -79,6 +79,16 @@ interface Map extends IteratorAggregate, Countable, ArrayAccess, JsonSerializabl
 	 */
 	public function get(string|int|bool|float|object $key);
 
+	/**
+	 * Retrieves the value associated with the given key, or throws if absent.
+	 * Alias of get() for array access syntax `$map['key']`.
+	 *
+	 * @param K $offset
+	 * @return V
+	 * @throws NoSuchElementException
+	 */
+	public function offsetGet(mixed $offset): mixed;
+
 	/**
 	 * Retrieves the value associated with the given key.
 	 * Returns null if the key does not exist in the map.
@@ -163,6 +173,7 @@ public function count(): int;
 	 * Returns the number of entries matching the predicate.
 	 *
 	 * @param Closure(V, K):bool $predicate
+	 * @return int<0, max>
 	 */
 	public function countWhere(Closure $predicate): int;
 

tests/Type/Collection/AccessTypeTest.php

@@ -0,0 +1,30 @@
+<?php
+
+/**
+ * This file is part of the Noctud Collection.
+ * Copyright (c) Noctud.dev
+ */
+
+declare(strict_types=1);
+
+namespace Noctud\Collection\Tests\Type\Collection;
+
+use Noctud\Collection\Collection;
+use function Noctud\Collection\listOf;
+use function PHPStan\Testing\assertType;
+
+/** @var Collection<int> $c */
+$c = listOf([1, 2, 3]);
+
+assertType('int', $c->first());
+assertType('int|null', $c->firstOrNull());
+assertType('int', $c->last());
+assertType('int|null', $c->lastOrNull());
+assertType('int', $c->single());
+assertType('int|null', $c->singleOrNull());
+assertType('int|null', $c->find(fn (int $x): bool => $x > 0));
+assertType('int|null', $c->findLast(fn (int $x): bool => $x > 0));
+assertType('int', $c->expect(fn (int $x): bool => $x > 0));
+assertType('int', $c->expectLast(fn (int $x): bool => $x > 0));
+assertType('int', $c->random());
+assertType('int|null', $c->randomOrNull());

tests/Type/Collection/AggregationTypeTest.php

@@ -0,0 +1,42 @@
+<?php
+
+/**
+ * This file is part of the Noctud Collection.
+ * Copyright (c) Noctud.dev
+ */
+
+declare(strict_types=1);
+
+namespace Noctud\Collection\Tests\Type\Collection;
+
+use Noctud\Collection\Collection;
+use function Noctud\Collection\listOf;
+use function PHPStan\Testing\assertType;
+
+/** @var Collection<int> $c */
+$c = listOf([1, 2, 3]);
+
+// fold: return type follows the initial accumulator type R.
+assertType('int', $c->fold(0, fn (int $acc, int $x): int => $acc + $x));
+assertType('string', $c->fold('', fn (string $acc, int $x): string => $acc . $x));
+
+assertType('int', $c->reduce(fn (int $acc, int $x): int => $acc + $x));
+assertType('int|null', $c->reduceOrNull(fn (int $acc, int $x): int => $acc + $x));
+
+// min/max return the element type E (declared `: mixed`), not a fixed scalar.
+assertType('int', $c->min());
+assertType('int|null', $c->minOrNull());
+assertType('int', $c->max());
+assertType('int|null', $c->maxOrNull());
+
+// sum: a collection of ints sums to an int.
+assertType('int', listOf([1, 2, 3])->sum());
+
+// As soon as a float is involved, the sum widens back to int|float.
+assertType('float|int', listOf([1.0, 2.0])->sum());
+assertType('float|int', listOf([1, 2.0])->sum());
+
+// With a selector declared to return int, the sum narrows to int.
+assertType('int', listOf([1, 2, 3])->sum(fn (int $x): int => $x * 2));
+// Any other selector return type (float, or an un-inferrable/mixed one) stays int|float.
+assertType('float|int', listOf([1, 2, 3])->sum(fn (int $x): float => $x / 2));

tests/Type/Collection/ConversionTypeTest.php

@@ -0,0 +1,34 @@
+<?php
+
+/**
+ * This file is part of the Noctud Collection.
+ * Copyright (c) Noctud.dev
+ */
+
+declare(strict_types=1);
+
+namespace Noctud\Collection\Tests\Type\Collection;
+
+use Noctud\Collection\Collection;
+use function Noctud\Collection\listOf;
+use function PHPStan\Testing\assertType;
+
+/** @var Collection<string> $c */
+$c = listOf(['a', 'b', 'c']);
+
+// toMap: value defaults to the element type unless a value transform is given.
+assertType(
+	'Noctud\Collection\Map\ImmutableMap<string, string>',
+	$c->toMap(fn (string $x): string => $x),
+);
+assertType(
+	'Noctud\Collection\Map\ImmutableMap<string, bool>',
+	$c->toMap(fn (string $x): string => $x, fn (string $x): bool => $x !== ''),
+);
+
+assertType('Noctud\Collection\List\ImmutableList<string>', $c->toList());
+assertType('Noctud\Collection\Set\ImmutableSet<string>', $c->toSet());
+assertType('list<string>', $c->toArray());
+assertType('Noctud\Collection\MutableCollection<string>', $c->toMutable());
+assertType('Noctud\Collection\ImmutableCollection<string>', $c->toImmutable());
+assertType('Noctud\Collection\Collection<string>', $c->forEach(fn (string $x): null => null));

tests/Type/Collection/OrderingTypeTest.php

@@ -0,0 +1,25 @@
+<?php
+
+/**
+ * This file is part of the Noctud Collection.
+ * Copyright (c) Noctud.dev
+ */
+
+declare(strict_types=1);
+
+namespace Noctud\Collection\Tests\Type\Collection;
+
+use Noctud\Collection\Collection;
+use function Noctud\Collection\listOf;
+use function PHPStan\Testing\assertType;
+
+/** @var Collection<int> $c */
+$c = listOf([1, 2, 3]);
+
+assertType('Noctud\Collection\Collection<int>', $c->sorted());
+assertType('Noctud\Collection\Collection<int>', $c->sortedDesc());
+assertType('Noctud\Collection\Collection<int>', $c->sortedBy(fn (int $x): int => $x));
+assertType('Noctud\Collection\Collection<int>', $c->sortedByDesc(fn (int $x): int => $x));
+assertType('Noctud\Collection\Collection<int>', $c->sortedWith(fn (int $a, int $b): int => $a <=> $b));
+assertType('Noctud\Collection\Collection<int>', $c->reversed());
+assertType('Noctud\Collection\Collection<int>', $c->shuffled());

tests/Type/Collection/QueryTypeTest.php

@@ -0,0 +1,27 @@
+<?php
+
+/**
+ * This file is part of the Noctud Collection.
+ * Copyright (c) Noctud.dev
+ */
+
+declare(strict_types=1);
+
+namespace Noctud\Collection\Tests\Type\Collection;
+
+use Noctud\Collection\Collection;
+use function Noctud\Collection\listOf;
+use function PHPStan\Testing\assertType;
+
+/** @var Collection<string> $c */
+$c = listOf(['a', 'b', 'c']);
+
+// countWhere() pins the declared @return int<0, max>.
+// count() itself is native-typed (`: int`, no PHPDoc) and needs no type test.
+assertType('int<0, max>', $c->countWhere(fn (string $x): bool => $x !== ''));
+
+// countBy: the key selector's return becomes the map key, values are the counts.
+assertType(
+	'Noctud\Collection\Map\ImmutableMap<string, int>',
+	$c->countBy(fn (string $x): string => $x),
+);

tests/Type/Collection/TransformTypeTest.php

@@ -0,0 +1,68 @@
+<?php
+
+/**
+ * This file is part of the Noctud Collection.
+ * Copyright (c) Noctud.dev
+ */
+
+declare(strict_types=1);
+
+namespace Noctud\Collection\Tests\Type\Collection;
+
+use Noctud\Collection\Collection;
+use stdClass;
+use function Noctud\Collection\listOf;
+use function PHPStan\Testing\assertType;
+
+/** @var Collection<string> $c */
+$c = listOf(['a', 'b', 'c']);
+
+// Filtering preserves the element type.
+assertType('Noctud\Collection\Collection<string>', $c->filter(fn (string $x): bool => $x !== ''));
+assertType('Noctud\Collection\Collection<string>', $c->filterNotNull());
+assertType('Noctud\Collection\Collection<stdClass>', $c->filterInstanceOf(stdClass::class));
+
+/** @var Collection<string|null> $nullable */
+$nullable = listOf(['a', null]);
+assertType('Noctud\Collection\Collection<string>', $nullable->filterNotNull());
+
+// Mapping changes the element type.
+assertType('Noctud\Collection\Collection<int>', $c->map(fn (string $x): int => (int) $x));
+assertType('Noctud\Collection\Collection<int>', $c->mapNotNull(fn (string $x): ?int => $x !== '' ? 1 : null));
+assertType('Noctud\Collection\Collection<int>', $c->flatMap(fn (string $x): array => [(int) $x]));
+assertType('Noctud\Collection\Collection<mixed>', $c->flatten());
+
+// Slicing preserves the element type.
+assertType('Noctud\Collection\Collection<string>', $c->takeFirst(2));
+assertType('Noctud\Collection\Collection<string>', $c->dropFirst(2));
+assertType('Noctud\Collection\Collection<string>', $c->takeLast(2));
+assertType('Noctud\Collection\Collection<string>', $c->dropLast(2));
+assertType('Noctud\Collection\Collection<string>', $c->takeWhile(fn (string $x): bool => $x !== ''));
+assertType('Noctud\Collection\Collection<string>', $c->dropWhile(fn (string $x): bool => $x !== ''));
+assertType('Noctud\Collection\Collection<string>', $c->takeLastWhile(fn (string $x): bool => $x !== ''));
+assertType('Noctud\Collection\Collection<string>', $c->dropLastWhile(fn (string $x): bool => $x !== ''));
+assertType('Noctud\Collection\Collection<string>', $c->distinct());
+assertType('Noctud\Collection\Collection<string>', $c->distinctBy(fn (string $x): int => (int) $x));
+
+// Grouping into lists of lists.
+assertType('Noctud\Collection\List\ListInterface<Noctud\Collection\List\ListInterface<string>>', $c->chunked(2));
+assertType('Noctud\Collection\List\ListInterface<Noctud\Collection\List\ListInterface<string>>', $c->windowed(2));
+assertType('Noctud\Collection\List\ListInterface<array{string, int}>', $c->zip([1, 2]));
+assertType('Noctud\Collection\List\ListInterface<array{string, string}>', $c->zipWithNext());
+assertType('array{Noctud\Collection\List\ImmutableList<mixed>, Noctud\Collection\List\ImmutableList<mixed>}', $c->unzip());
+assertType('array{Noctud\Collection\Collection<string>, Noctud\Collection\Collection<string>}', $c->partition(fn (string $x): bool => $x !== ''));
+
+// groupBy is conditional on the value transform.
+assertType(
+	'Noctud\Collection\Map\ImmutableMap<string, Noctud\Collection\Collection<string>>',
+	$c->groupBy(fn (string $x): string => $x),
+);
+assertType(
+	'Noctud\Collection\Map\ImmutableMap<string, Noctud\Collection\List\ImmutableList<int>>',
+	$c->groupBy(fn (string $x): string => $x, fn (string $x): int => (int) $x),
+);
+
+// Set operations.
+assertType('Noctud\Collection\Set\Set<string>', $c->intersect(['a', 'b']));
+assertType('Noctud\Collection\Set\Set<string>', $c->union(['a', 'b']));
+assertType('Noctud\Collection\Set\Set<string>', $c->subtract(['a', 'b']));

tests/Type/FunctionsTypeTest.php

@@ -0,0 +1,46 @@
+<?php
+
+/**
+ * This file is part of the Noctud Collection.
+ * Copyright (c) Noctud.dev
+ */
+
+declare(strict_types=1);
+
+namespace Noctud\Collection\Tests\Type;
+
+use function Noctud\Collection\intMapOf;
+use function Noctud\Collection\listOf;
+use function Noctud\Collection\mapOf;
+use function Noctud\Collection\mapOfPairs;
+use function Noctud\Collection\mutableIntMapOf;
+use function Noctud\Collection\mutableListOf;
+use function Noctud\Collection\mutableMapOf;
+use function Noctud\Collection\mutableMapOfPairs;
+use function Noctud\Collection\mutableSetOf;
+use function Noctud\Collection\mutableStringMapOf;
+use function Noctud\Collection\setOf;
+use function Noctud\Collection\stringMapOf;
+use function PHPStan\Testing\assertType;
+
+// Lists
+assertType('Noctud\Collection\List\ImmutableList<string>', listOf(['a', 'b']));
+assertType('Noctud\Collection\List\MutableList<int>', mutableListOf([1, 2]));
+
+// Sets
+assertType('Noctud\Collection\Set\ImmutableSet<string>', setOf(['a', 'b']));
+assertType('Noctud\Collection\Set\MutableSet<int>', mutableSetOf([1, 2]));
+
+// Hash maps (assoc + pairs)
+assertType('Noctud\Collection\Map\ImmutableMap<string, int>', mapOf(['a' => 1, 'b' => 2]));
+assertType('Noctud\Collection\Map\ImmutableMap<string, int>', mapOfPairs([['a', 1], ['b', 2]]));
+assertType('Noctud\Collection\Map\MutableMap<string, int>', mutableMapOf(['a' => 1]));
+assertType('Noctud\Collection\Map\MutableMap<string, int>', mutableMapOfPairs([['a', 1]]));
+
+// String maps
+assertType('Noctud\Collection\Map\ImmutableMap<string, int>', stringMapOf(['a' => 1]));
+assertType('Noctud\Collection\Map\MutableMap<string, int>', mutableStringMapOf(['a' => 1]));
+
+// Int maps
+assertType('Noctud\Collection\Map\ImmutableMap<int, string>', intMapOf([1 => 'a']));
+assertType('Noctud\Collection\Map\MutableMap<int, string>', mutableIntMapOf([1 => 'a']));