Merge branch '0.1.x' into 0.2.x

Author: delacry

bin/NarrowingGenerator.php

@@ -203,6 +203,7 @@ public static function generateSetNarrowing(string $collectionContent, array $bl
 			': Collection' => ': Set',
 			'Collection<E>' => 'Set<E>',
 			'Collection<(E is null ? never : E)>' => 'Set<(E is null ? never : E)>',
+			'Collection<(E is iterable<mixed> ? value-of<E|array{}> : E)>' => 'Set<(E is iterable<mixed> ? value-of<E|array{}> : E)>',
 			'Collection<R>' => 'Set<R>',
 			'Collection<mixed>' => 'Set<mixed>',
 			'Collection<T>' => 'Set<T>',
@@ -233,6 +234,7 @@ public static function generateImmutableSetNarrowing(string $immutableCollection
 			': ImmutableCollection' => ': ImmutableSet',
 			'ImmutableCollection<E>' => 'ImmutableSet<E>',
 			'ImmutableCollection<(E is null ? never : E)>' => 'ImmutableSet<(E is null ? never : E)>',
+			'ImmutableCollection<(E is iterable<mixed> ? value-of<E|array{}> : E)>' => 'ImmutableSet<(E is iterable<mixed> ? value-of<E|array{}> : E)>',
 			'ImmutableCollection<E|NE>' => 'ImmutableSet<E|NE>',
 			'ImmutableCollection<R>' => 'ImmutableSet<R>',
 			'ImmutableCollection<mixed>' => 'ImmutableSet<mixed>',
@@ -288,6 +290,7 @@ public static function generateListNarrowing(string $collectionContent, array $b
 			': Collection' => ': ListInterface',
 			'Collection<E>' => 'ListInterface<E>',
 			'Collection<(E is null ? never : E)>' => 'ListInterface<(E is null ? never : E)>',
+			'Collection<(E is iterable<mixed> ? value-of<E|array{}> : E)>' => 'ListInterface<(E is iterable<mixed> ? value-of<E|array{}> : E)>',
 			'Collection<R>' => 'ListInterface<R>',
 			'Collection<mixed>' => 'ListInterface<mixed>',
 			'Collection<T>' => 'ListInterface<T>',
@@ -318,6 +321,7 @@ public static function generateImmutableCollectionNarrowing(string $collectionCo
 			': Collection' => ': ImmutableCollection',
 			'Collection<E>' => 'ImmutableCollection<E>',
 			'Collection<(E is null ? never : E)>' => 'ImmutableCollection<(E is null ? never : E)>',
+			'Collection<(E is iterable<mixed> ? value-of<E|array{}> : E)>' => 'ImmutableCollection<(E is iterable<mixed> ? value-of<E|array{}> : E)>',
 			'Collection<R>' => 'ImmutableCollection<R>',
 			'Collection<mixed>' => 'ImmutableCollection<mixed>',
 			'Collection<T>' => 'ImmutableCollection<T>',
@@ -345,6 +349,7 @@ public static function generateWritableCollectionTransformationNarrowing(string
 			': Collection' => ': ImmutableCollection',
 			'Collection<E>' => 'ImmutableCollection<E>',
 			'Collection<(E is null ? never : E)>' => 'ImmutableCollection<(E is null ? never : E)>',
+			'Collection<(E is iterable<mixed> ? value-of<E|array{}> : E)>' => 'ImmutableCollection<(E is iterable<mixed> ? value-of<E|array{}> : E)>',
 			'Collection<R>' => 'ImmutableCollection<R>',
 			'Collection<mixed>' => 'ImmutableCollection<mixed>',
 			'Collection<T>' => 'ImmutableCollection<T>',
@@ -372,6 +377,7 @@ public static function generateWritableListTransformationNarrowing(string $colle
 			': Collection' => ': ImmutableList',
 			'Collection<E>' => 'ImmutableList<E>',
 			'Collection<(E is null ? never : E)>' => 'ImmutableList<(E is null ? never : E)>',
+			'Collection<(E is iterable<mixed> ? value-of<E|array{}> : E)>' => 'ImmutableList<(E is iterable<mixed> ? value-of<E|array{}> : E)>',
 			'Collection<R>' => 'ImmutableList<R>',
 			'Collection<mixed>' => 'ImmutableList<mixed>',
 			'Collection<T>' => 'ImmutableList<T>',
@@ -399,6 +405,7 @@ public static function generateWritableSetTransformationNarrowing(string $collec
 			': Collection' => ': ImmutableSet',
 			'Collection<E>' => 'ImmutableSet<E>',
 			'Collection<(E is null ? never : E)>' => 'ImmutableSet<(E is null ? never : E)>',
+			'Collection<(E is iterable<mixed> ? value-of<E|array{}> : E)>' => 'ImmutableSet<(E is iterable<mixed> ? value-of<E|array{}> : E)>',
 			'Collection<R>' => 'ImmutableSet<R>',
 			'Collection<mixed>' => 'ImmutableSet<mixed>',
 			'Collection<T>' => 'ImmutableSet<T>',
@@ -450,6 +457,7 @@ public static function generateImmutableListNarrowing(string $immutableCollectio
 			': ImmutableCollection' => ': ImmutableList',
 			'ImmutableCollection<E>' => 'ImmutableList<E>',
 			'ImmutableCollection<(E is null ? never : E)>' => 'ImmutableList<(E is null ? never : E)>',
+			'ImmutableCollection<(E is iterable<mixed> ? value-of<E|array{}> : E)>' => 'ImmutableList<(E is iterable<mixed> ? value-of<E|array{}> : E)>',
 			'ImmutableCollection<E|NE>' => 'ImmutableList<E|NE>',
 			'ImmutableCollection<R>' => 'ImmutableList<R>',
 			'ImmutableCollection<mixed>' => 'ImmutableList<mixed>',

docs/collection/api/collection.md

@@ -101,7 +101,7 @@ count(): int
 Returns the number of elements in the collection.
 
 ```php
-countWhere(Closure $predicate): int
+countWhere(Closure $predicate): int<0, max>
 ```
 Returns the number of elements matching the predicate `(E, int): bool`.
 
@@ -135,7 +135,7 @@ Reduce, or `null` if empty.
 ```php
 sum(?Closure $selector = null): int|float
 ```
-Sum of all elements, or values returned by the selector `(E, int): int|float`.
+Sum of all elements, or values returned by the selector `(E, int): int|float`. The return type narrows to `int` when every summed value is an `int` — a `Collection<int>`, or a selector declared to return `int` — and stays `int|float` otherwise.
 
 ```php
 avg(?Closure $selector = null): float
@@ -168,22 +168,22 @@ maxOrNull(?Closure $selector = null): E|null
 Maximum element, or `null` if empty. Optional selector `(E, int): mixed`.
 
 ```php
-minOf(Closure $selector): mixed
+minOf(Closure $selector): R
 ```
-Returns the minimum value produced by the selector `(E, int): mixed`. Unlike `min()`, returns the **selector value** itself, not the element. Throws `NoSuchElementException` if empty.
+Returns the minimum value produced by the selector `(E, int): R`. Unlike `min()`, returns the **selector value** itself, not the element. The return type follows the selector — one declared `: int` yields `int`. Throws `NoSuchElementException` if empty.
 
 ```php
-minOfOrNull(Closure $selector): mixed
+minOfOrNull(Closure $selector): R|null
 ```
 Returns the minimum selector value, or `null` if empty.
 
 ```php
-maxOf(Closure $selector): mixed
+maxOf(Closure $selector): R
 ```
-Returns the maximum value produced by the selector `(E, int): mixed`. Unlike `max()`, returns the **selector value** itself, not the element. Throws `NoSuchElementException` if empty.
+Returns the maximum value produced by the selector `(E, int): R`. Unlike `max()`, returns the **selector value** itself, not the element. The return type follows the selector — one declared `: int` yields `int`. Throws `NoSuchElementException` if empty.
 
 ```php
-maxOfOrNull(Closure $selector): mixed
+maxOfOrNull(Closure $selector): R|null
 ```
 Returns the maximum selector value, or `null` if empty.
 
@@ -216,7 +216,7 @@ Filter by predicate `(E, int): bool`. Returns `ImmutableList` for lists, `Immuta
 ```php
 filterNotNull(): Collection<E>
 ```
-Filter out `null` elements.
+Filter out `null` elements. The element type narrows to exclude `null` — `Collection<string|null>` becomes `Collection<string>`.
 
 ```php
 filterInstanceOf(string $type): Collection<T>
@@ -239,9 +239,9 @@ flatMap(Closure $transform): Collection<R>
 Transform and flatten. Closure: `(E, int): iterable<R>`.
 
 ```php
-flatten(): Collection<mixed>
+flatten(): Collection<V>
 ```
-Flatten a collection of iterables.
+Flatten a collection of iterables, one level deep. Iterable elements contribute their own values (`V` is the element type of `E`); non-iterable elements are kept as-is. So `Collection<ImmutableList<int>>` becomes `Collection<int>`, `Collection<array<int>|string>` becomes `Collection<int|string>`, and `Collection<string>` stays `Collection<string>`. Only one level is removed — flattening `Collection<ImmutableList<ImmutableList<int>>>` yields `Collection<ImmutableList<int>>`.
 
 ```php
 takeFirst(int $n = 1): Collection<E>
@@ -333,19 +333,19 @@ groupBy(Closure $keySelector, ?Closure $valueTransform = null): Map<K, Collectio
 Group elements by key selector `(E, int): K`. When a `$valueTransform` `(E, int): V` is provided, each element is transformed before being added to its group — the result is `Map<K, ImmutableList<V>>`.
 
 ```php
-intersect(iterable $other): ImmutableSet<E>
+intersect(iterable<V> $other): ImmutableSet<E&V>
 ```
-Elements present in both this collection and the iterable. Returns a set (duplicates removed).
+Elements present in both this collection and the iterable. Returns a set (duplicates removed). The element type narrows to `E&V` — only values that can belong to both sides.
 
 ```php
-union(iterable $other): ImmutableSet<E>
+union(iterable<NE> $other): ImmutableSet<E|NE>
 ```
-All elements from both this collection and the iterable. Returns a set (duplicates removed).
+All elements from both this collection and the iterable. Returns a set (duplicates removed). The element type widens to `E|NE`, like `add()`.
 
 ```php
-subtract(iterable $other): ImmutableSet<E>
+subtract(iterable<mixed> $other): ImmutableSet<E>
 ```
-Elements present in this collection but not in the iterable. Returns a set (duplicates removed).
+Elements present in this collection but not in the iterable. Returns a set (duplicates removed). The element type is always `E` — any iterable may be subtracted.
 
 ## Ordering
 

docs/collection/api/map.md

@@ -99,7 +99,7 @@ count(): int
 Returns the number of entries in the map.
 
 ```php
-countWhere(Closure $predicate): int
+countWhere(Closure $predicate): int<0, max>
 ```
 Returns the number of entries matching the predicate `(V, K): bool`.
 
@@ -135,7 +135,7 @@ Filter by value predicate `(V): bool`.
 ```php
 filterValuesNotNull(): ImmutableMap<K,V>
 ```
-Exclude entries with `null` values.
+Exclude entries with `null` values. The value type narrows to exclude `null` — `Map<string, int|null>` becomes `Map<string, int>`. Keys are preserved.
 
 ```php
 filterValuesInstanceOf(string $type): ImmutableMap<K,T>
@@ -235,9 +235,9 @@ flatMap(Closure $transform): ImmutableList<R>
 Transform each entry with `(V, K): iterable<R>` and flatten all results into a single list.
 
 ```php
-toArray(KeyCollisionStrategy $onCollision = KeyCollisionStrategy::Throw): array
+toArray(KeyCollisionStrategy $onCollision = KeyCollisionStrategy::Throw): array<K,V>
 ```
-Convert to PHP array. Only works with scalar keys. Throws `ConversionException` for object keys or key collisions.
+Convert to PHP array. Only works with scalar keys. Throws `ConversionException` for object keys or key collisions. The key type is preserved when `K` is a valid array key — a `Map<string, int>` yields `array<string, int>`; a map with keys PHP cannot use natively falls back to `array<array-key, V>`.
 
 ```php
 toPairs(): list<array{0:K, 1:V}>

phpstan.neon

@@ -38,6 +38,15 @@ parameters:
 				- src/Set/Set.php
 				- src/Set/ImmutableSet.php
 				- src/Set/WritableSet.php
+		# flatten()'s conditional return type cannot be evaluated in classes with a
+		# concrete E (the subject is already substituted), so the trait vs ancestor
+		# comparison sees structurally different but semantically equal conditionals.
+		-
+			message: '#::flatten\(\)#'
+			identifier: method.childReturnType
+			paths:
+				- src/List/ListLogic.php
+				- src/Set/SetLogic.php
 		# classes which implement ImmutableMap<string,...>. The trait's put()/putFirst()
 		# accepts string|int|bool|float|object but the store expects string.
 		-

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;
 
@@ -292,35 +293,39 @@ public function maxOrNull(?Closure $selector = null): mixed;
 	 * Returns the minimum value produced by the selector.
 	 * Throws if the collection is empty.
 	 *
-	 * @param Closure(E, int):mixed $selector
-	 * @return mixed
+	 * @template R of mixed
+	 * @param Closure(E, int):R $selector
+	 * @return R
 	 * @throws NoSuchElementException
 	 */
 	public function minOf(Closure $selector): mixed;
 
 	/**
 	 * Returns the minimum value produced by the selector, or null if empty.
 	 *
-	 * @param Closure(E, int):mixed $selector
-	 * @return mixed
+	 * @template R of mixed
+	 * @param Closure(E, int):R $selector
+	 * @return R|null
 	 */
 	public function minOfOrNull(Closure $selector): mixed;
 
 	/**
 	 * Returns the maximum value produced by the selector.
 	 * Throws if the collection is empty.
 	 *
-	 * @param Closure(E, int):mixed $selector
-	 * @return mixed
+	 * @template R of mixed
+	 * @param Closure(E, int):R $selector
+	 * @return R
 	 * @throws NoSuchElementException
 	 */
 	public function maxOf(Closure $selector): mixed;
 
 	/**
 	 * Returns the maximum value produced by the selector, or null if empty.
 	 *
-	 * @param Closure(E, int):mixed $selector
-	 * @return mixed
+	 * @template R of mixed
+	 * @param Closure(E, int):R $selector
+	 * @return R|null
 	 */
 	public function maxOfOrNull(Closure $selector): mixed;
 
@@ -409,8 +414,10 @@ public function flatMap(Closure $transform): Collection;
 
 	/**
 	 * Flatten a collection of iterables into a single collection.
+	 * Iterable elements are flattened one level; non-iterable elements are kept as-is.
+	 * The array{} in value-of keeps the type resolvable when E is never (empty collections).
 	 *
-	 * @return Collection<mixed>
+	 * @return Collection<(E is iterable<mixed> ? value-of<E|array{}> : E)>
 	 */
 	#[NoDiscard]
 	public function flatten(): Collection;
@@ -582,25 +589,27 @@ public function groupBy(Closure $keySelector, ?Closure $valueTransform = null):
 	/**
 	 * Returns a set containing only elements present in both this collection and the given iterable.
 	 *
-	 * @param iterable<E> $other
-	 * @return Set<E>
+	 * @template V
+	 * @param iterable<V> $other
+	 * @return Set<E&V>
 	 */
 	#[NoDiscard]
 	public function intersect(iterable $other): Set;
 
 	/**
 	 * Returns a set containing all elements from both this collection and the given iterable.
 	 *
-	 * @param iterable<E> $other
-	 * @return Set<E>
+	 * @template NE
+	 * @param iterable<NE> $other
+	 * @return Set<E|NE>
 	 */
 	#[NoDiscard]
 	public function union(iterable $other): Set;
 
 	/**
 	 * Returns a set containing elements present in this collection but not in the given iterable.
 	 *
-	 * @param iterable<E> $other
+	 * @param iterable<mixed> $other
 	 * @return Set<E>
 	 */
 	#[NoDiscard]

src/CollectionLogic.php

@@ -957,7 +957,9 @@ public function groupBy(Closure $keySelector, ?Closure $valueTransform = null):
 	/**
 	 * {@inheritDoc}
 	 *
-	 * @return ImmutableSet<E>
+	 * @template U
+	 * @param iterable<U> $other
+	 * @return ImmutableSet<E&U>
 	 */
 	#[NoDiscard]
 	public function intersect(iterable $other): ImmutableSet
@@ -968,7 +970,9 @@ public function intersect(iterable $other): ImmutableSet
 	/**
 	 * {@inheritDoc}
 	 *
-	 * @return ImmutableSet<E>
+	 * @template NE
+	 * @param iterable<NE> $other
+	 * @return ImmutableSet<E|NE>
 	 */
 	#[NoDiscard]
 	public function union(iterable $other): ImmutableSet
@@ -979,6 +983,7 @@ public function union(iterable $other): ImmutableSet
 	/**
 	 * {@inheritDoc}
 	 *
+	 * @param iterable<mixed> $other
 	 * @return ImmutableSet<E>
 	 */
 	#[NoDiscard]

src/ImmutableCollection.php

@@ -192,8 +192,10 @@ public function flatMap(Closure $transform): ImmutableCollection;
 
 	/**
 	 * Flatten a collection of iterables into a single collection.
+	 * Iterable elements are flattened one level; non-iterable elements are kept as-is.
+	 * The array{} in value-of keeps the type resolvable when E is never (empty collections).
 	 *
-	 * @return ImmutableCollection<mixed>
+	 * @return ImmutableCollection<(E is iterable<mixed> ? value-of<E|array{}> : E)>
 	 */
 	#[NoDiscard]
 	public function flatten(): ImmutableCollection;

src/List/ImmutableList.php

@@ -252,8 +252,10 @@ public function flatMap(Closure $transform): ImmutableList;
 
 	/**
 	 * Flatten a collection of iterables into a single collection.
+	 * Iterable elements are flattened one level; non-iterable elements are kept as-is.
+	 * The array{} in value-of keeps the type resolvable when E is never (empty collections).
 	 *
-	 * @return ImmutableList<mixed>
+	 * @return ImmutableList<(E is iterable<mixed> ? value-of<E|array{}> : E)>
 	 */
 	#[NoDiscard]
 	public function flatten(): ImmutableList;

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.
 	 *
@@ -170,8 +180,10 @@ public function flatMap(Closure $transform): ListInterface;
 
 	/**
 	 * Flatten a collection of iterables into a single collection.
+	 * Iterable elements are flattened one level; non-iterable elements are kept as-is.
+	 * The array{} in value-of keeps the type resolvable when E is never (empty collections).
 	 *
-	 * @return ListInterface<mixed>
+	 * @return ListInterface<(E is iterable<mixed> ? value-of<E|array{}> : E)>
 	 */
 	#[NoDiscard]
 	public function flatten(): ListInterface;

src/List/ListLogic.php

@@ -239,9 +239,9 @@ public function flatMap(Closure $transform): ImmutableList
 	/**
 	 * {@inheritDoc}
 	 *
-	 * @return ImmutableList<mixed>
+	 * @return ImmutableList<(E is iterable<mixed> ? value-of<E|array{}> : E)>
 	 */
-	#[NoDiscard]
+	#[NoDiscard] // @phpstan-ignore conditionalType.subjectNotFound, return.unresolvableType (in classes with a concrete E the conditional subject is already substituted and stays unevaluated)
 	public function flatten(): ImmutableList
 	{
 		return $this->newCollectionOf(new FlattenOperation($this->store)->items());