Union for variadic types

[nzour]

There are a lot of situations may occur when we need to define union from several cases.
For example: need to define enum of states.

This would look like:

use Psl\Type as T;

$codec = T\shape([
    // ... rest of fields
    'state' => T\union(
        T\literal_scalar('NEW'),
        T\union(
            T\literal_scalar('APPROVED'),
            T\union(
                T\literal_scalar('REJECTED'),
                T\union(
                    T\literal_scalar('COMPLETED'),
                    T\union(
                        T\literal_scalar('FROZEN'),
                        T\literal_scalar('ERROR')
                    )
                )
            )
        )
    ),
]);

Inferred type would be:

array{id: string, state: "APPROVED"|"COMPLETED"|"ERROR"|"FROZEN"|"NEW"|"REJECTED"}

---

I guess it would be great to have better solution like:

use Psl\Type as T;

$codec = T\shape([
    'id' => T\string(),
    'state' => T\union_of(
        T\literal_scalar('NEW'),
        T\literal_scalar('APPROVED'),
        T\literal_scalar('REJECTED'),
        T\literal_scalar('COMPLETED'),
        T\literal_scalar('FROZEN'),
        T\literal_scalar('ERROR'),
    ),
]);

I do understand that Psl\Type\Internal\UnionType has only 2 branches: left and right
That's why propose just implement a function with signature:

/**
 * @template T
 *
 * @param TypeInterface<T> $left_type
 * @param TypeInterface<T> $right_type
 * @param TypeInterface<T> ...$others
 * @return TypeInterface<T>
 *
 * @no-named-arguments
 */
function union_of(
    TypeInterface $left_type,
    TypeInterface $right_type,
    TypeInterface ...$others
): TypeInterface { // actually Psl\Type\Internal\UnionType returns here
    ...
}

---

As alternatives I may guess there is more suitable name for function.
This may be named like literals or one_of or etc.

This function may also be implemented in user land, but I think it would be great to have unified solution inside core of the library.

---

Want to hear other guys thoughts.
If this would be approved, I may produce PR.
As I can see, this is very light enhancement.

[azjezz]

Hm, i think we can allowing extra arguments to Type\union and Type\intersection ( i prefer if these two provide the same API ).

This will also prevent a BC break, in v2.0 we can drop $right and $left and make both union and intersection accept variadic arguments.

[nzour]

🤔 Hmm, I kept in my that UnionType has left and right branches, therefore function union() takes two arguments to be honest with users.

I was thinking about suggestion to define extra function to prevent boilerplate when we need define union type with a lot of cases.
But, If you think it is alright to expand already existed function - it is fair enough for me

[azjezz]

we can have function union(TypeInterface $right, TypeInterface $left, TypeInterface ...$other), UnionType is an internal class, there's no reason to design the public API to match it.

[nzour]

Looks great for me.

[azjezz]

Are you up for a PR?

[nzour]

Are you up for a PR?

I'm on it

[nzour]

By the way, why you want to make union and intersection completely variadic (in v2.0)?
union(string()) - doesn't make sense for me

[azjezz]

union(string()) - doesn't make sense for me

it doesn't to me too, but that's solvable via Psl\invariant(Iter\count($types) >= 2, 'at least 2 types are required to create a union.');

[nzour]

union(string()) - doesn't make sense for me

it doesn't to me too, but that's solvable via Psl\invariant(Iter\count($types) >= 2, 'at least 2 types are required to create a union.');

Do you prefer runtime exception instead of statically analysed issue?

[azjezz]

the reason is i don't like $right, $left, $others, maybe we could just rename them to something more appropriate...

WDYT about $first, $second, ...$rest? ( renaming arguments is not BC break, we can do it now )

[nzour]

You right, first, second and rest sounds more logic, I see it now