How to make a (lazy) strictly typed collection

[drupol]

I'm just writing here my raw ideas about how to provide a TypedCollection class.

Idea 1 (tested and working)

We could simply provide a new TypedCollection class that would decorate Collection and where the ::getIterator() method would be wrapped with a new TypedIterator such as:

<?php

/**
 * For the full copyright and license information, please view
 * the LICENSE file that was distributed with this source code.
 */

declare(strict_types=1);

namespace loophp\collection\Iterator;

use Exception;
use Generator;
use Iterator;

/**
 * @internal
 *
 * @psalm-template TKey
 * @psalm-template T
 *
 * @extends ProxyIterator<TKey, T>
 */
final class TypedIterator extends ProxyIterator
{
    /**
     * @param iterable<TKey, T> $iterable
     */
    public function __construct(Iterator $iterator)
    {
        $this->iterator = new ClosureIterator(
            static function (Iterator $iterator): Generator {
                $type = null;
                foreach ($iterator as $key => $value) {
                    yield $key => $value;

                    if ($type !== null && $type !== gettype($value)) {
                        throw new Exception('Invalid types detected.');
                    }

                    $type = gettype($value);
                }
            },
            $iterator
        );
    }
}

Idea 2 (tested and working)

Add a new operation Collection::strict(callable $callback) that would throw an exception as soon as the $callback return false.

Example of what the Strict operation could be

<?php

/**
 * For the full copyright and license information, please view
 * the LICENSE file that was distributed with this source code.
 */

declare(strict_types=1);

namespace loophp\collection\Operation;

use Closure;
use Exception;
use Generator;
use Iterator;
use Throwable;

/**
 * @psalm-template TKey
 * @psalm-template T
 *
 * phpcs:disable Generic.Files.LineLength.TooLong
 */
final class Strict extends AbstractOperation
{
    /**
     * @psalm-return Closure(string|null): Closure(Iterator<TKey, T>): Generator<TKey, T>
     */
    public function __invoke(): Closure
    {
        return
            static function (callable $callback): Closure {
                $apply = static fn(callable $callback): Closure =>
                    static function ($value, $key, Iterator $iterator) use ($callback): bool {
                        if (false === $callback($value, $key, $iterator)) {
                            throw new Exception('Invalid type detected.');
                        }

                        return true;
                    };

                return Apply::of()($apply($callback));
            };
    }
}

[AlexandruGG]

I like both ideas, I think they are both valid in terms of enforcing a typed collection at runtime.

From a static analysis point of view I think something closer to "Idea 1" is more feasible, because it's likely that a separate class with different type hints for its interfaces would be needed. For example, for Appendable the type of elements that can be appended cannot be mixed, and must be the same type T as the elements already contained in the collection.

[drupol]

Actually, that's not true.

We actually could add any type in the collection, but it would be only when iterating that it would throw an exception if the type/callback doesn't match. This is why it's lazy :)

[AlexandruGG]

I understand that technically it's possible to do it because of using the iterators, but I'm not sure that's desirable behaviour.

If I am using a typed collection and I accidentally add an element that's of a different type I want the static analysis to scream at me 😄. Not allow me to do it and then fail later when I don't expect it.

[drupol]

Then it's not lazy anymore...

[AlexandruGG]

Could you clarify what you mean by that?

I'm not proposing to change the lazy behaviour of the collection. What I am referring to is what the user should be allowed to do with a typed collection. In other languages the compiler will stop you from doing something like mixing the types, but in PHP we have to rely on static analysis for that.

[drupol]

I meant that the action you're doing is not evaluated ASAP, it's delayed.

But I think you're right, we should first start to list the features we want :)