Collection enhancements

[valzargaming]

This pull request includes several changes to the CollectionInterface and CollectionTrait in the Discord/Helpers directory, as well as updates to various attributes in the Channel, Message, Embed, and AuditLog classes. The primary focus is on enhancing the functionality of the collection interface and traits, and updating the return types of attributes to use CollectionInterface instead of Collection.

Collection Interface Enhancements:

• Added new methods shift(), walk(callable $callback, mixed $arg), reduce(callable $callback, $initial = null), collect(), keys(), values(), diff($items, ?callable $callback), intersect($items, ?callable $callback), and unique(int $flags = SORT_STRING) to CollectionInterface. [1] [2] [3]

Collection Trait Enhancements:

• Implemented the shift() method to remove and return the first item of the collection.
• Updated the fill() method to accept both arrays and CollectionInterface instances.
• Added methods diff(), intersect(), walk(), reduce(), unique(), collect(), keys(), and values() to the CollectionTrait. [1] [2] [3] [4] [5] [6]
• Modified the __unserialize() method to accept both arrays and CollectionInterface instances.

Attribute Return Type Updates:

• Updated the return type of various attributes from Collection to CollectionInterface in Channel, Message, Embed, and AuditLog classes. [1] [2] [3] [4] [5] [6] [7] [8] [9] [10] [11] [12] [13] [14] [15] [16]

[valzargaming]

Some sneak previews!

Before reduce() and shift():

if (! $members_array = $members->toArray()) return $message->react(":x:"); // No members to process
$promise = array_shift($members_array)->addRole($this->civ13->role_ids['Verified']);
if (! $members_array) return $promise->then(static fn() => $message->react(":thumbsup:")); // There was only one member to process
return array_reduce($members_array, fn(PromiseInterface $carry_promise, Member $member) =>
    $carry_promise->then(fn() => $member->addRole($this->civ13->role_ids['Verified'])),
    $promise)
        ->then(static fn() => $message->react(":thumbsup:"));

After reduce() and shift():

return $message->react("⏱️")
    ->then(static fn() => $members->reduce(fn(PromiseInterface $carry_promise, Member $member): PromiseInterface =>
        $carry_promise->then(fn() => $member->addRole($this->civ13->role_ids['Verified'])),
        $members->shift()->addRole($this->civ13->role_ids['Verified'])))
    ->then(static fn() => $message->react("👍"));

Before reduce() and shift():

function getHighestRole(Collection $roles): ?Role
{
    return array_reduce($roles->toArray(), fn($prev, $role) =>
        ($prev === null
            ? $role
            : ($this->comparePositionTo($role, $prev) > 0
                ? $role
                : $prev))
    );
}

After reduce() and shift():

function getHighestRole(Collection $roles): ?Role
{
    return $roles->reduce(fn($prev, $role) =>
        ($prev === null
            ? $role
            : ($this->comparePositionTo($role, $prev) > 0
                ? $role
                : $prev)))
        ->shift();
}

Before diff() and merge():

blic function setRoles(
    Member $member,
    Collection|array|Role|string|int $add_roles = [],
    Collection|array|Role|string|int $remove_roles = []
): PromiseInterface
{
    if (! $add_roles    = self::__rolesToIdArray($add_roles   )) return resolve($member);
    if (! $remove_roles = self::__rolesToIdArray($remove_roles)) return resolve($member);

    foreach ($add_roles    as &$role_id)   if (  $member->roles->has($role_id))  unset($role_id);
    foreach ($remove_roles as &$role_id)   if (! $member->roles->has($role_id))  unset($role_id);

    return ($updated_roles = 
        array_diff(
            array_merge(
                array_values(
                    $member->roles
                        ->map(fn($role) => $role->id)->toArray()
                ), $add_roles),
            $remove_roles
        )
    ) ? $member->setRoles($updated_roles);
      : resolve($member);
}

After diff() and merge():

public function setRoles(
    Member $member,
    Collection|array|Role|string|int $add_roles = [],
    Collection|array|Role|string|int $remove_roles = []
): PromiseInterface
{
    if (! $add_roles    = self::__rolesToIdArray($add_roles   )) return resolve($member);
    if (! $remove_roles = self::__rolesToIdArray($remove_roles)) return resolve($member);

    foreach ($add_roles    as &$role_id)   if (  $member->roles->has($role_id))  unset($role_id);
    foreach ($remove_roles as &$role_id)   if (! $member->roles->has($role_id))  unset($role_id);

    return ($updated_roles = $member->roles
        ->map(static fn($role) => $role->id)
        //->values()
        ->merge($add_roles)
        ->diff($remove_roles))
            ? $member->setRoles($updated_roles)
            : resolve($member);
}

[valzargaming]

I'm merging this now as this PR has been thoroughly tested.