Skip to content

Latest commit

 

History

History
513 lines (352 loc) · 8.35 KB

API.md

File metadata and controls

513 lines (352 loc) · 8.35 KB

API Reference

All functions live in the Stann\Stream namespace.

use function Stann\Stream\{filter, map, take, toArray};

Every transformation follows the same pattern: takes configuration, returns a Closure that accepts an iterable. The pipe operator does the wiring.

data |> transform(config) |> transform(config) |> terminator(config)

Transformations

All transformations return Closure(iterable): iterable. They are lazy (Generator-based) unless noted as blocking.

map

map(callable $fn): Closure

Applies $fn to each element. Receives ($value, $key). Preserves keys.

[1, 2, 3] |> map(fn(int $n) => $n * 10) |> toArray();
// [10, 20, 30]

['a' => 1, 'b' => 2] |> map(fn(int $v, string $k) => "{$k}:{$v}") |> toArray();
// ['a' => 'a:1', 'b' => 'b:2']

filter

filter(?callable $fn = null): Closure

Keeps elements where $fn returns true. Receives ($value, $key). Without callback, removes falsy values (null, false, 0, "", []) — like array_filter().

[1, 2, 3, 4, 5] |> filter(fn(int $n) => $n > 3) |> toArray();
// [4, 5]

[1, 0, null, '', false, 2] |> filter() |> toArray();
// [1, 2]

flatMap

flatMap(callable $fn): Closure

Maps each element then flattens one level. $fn must return an iterable.

[[1, 2], [3, 4]] |> flatMap(fn(array $a) => $a) |> toArray();
// [1, 2, 3, 4]

[1, 2, 3] |> flatMap(fn(int $n) => [$n, $n * 10]) |> toArray();
// [1, 10, 2, 20, 3, 30]

flatten

flatten(): Closure

Flattens one level of nested iterables. Scalars pass through untouched.

[[1, 2], [3], 4] |> flatten() |> toArray();
// [1, 2, 3, 4]

take

take(int $n): Closure

Takes the first $n elements. Lazy — stops consuming the source after $n.

[1, 2, 3, 4, 5] |> take(3) |> toArray();
// [1, 2, 3]

takeWhile

takeWhile(callable $fn): Closure

Takes elements as long as the predicate returns true. Stops at the first failure.

[1, 2, 3, 4, 5] |> takeWhile(fn(int $n) => $n < 4) |> toArray();
// [1, 2, 3]

skip

skip(int $n): Closure

Skips the first $n elements.

[1, 2, 3, 4, 5] |> skip(2) |> toArray();
// [3, 4, 5]

skipWhile

skipWhile(callable $fn): Closure

Skips elements as long as the predicate returns true. Yields all remaining once it fails.

[1, 2, 3, 4, 5] |> skipWhile(fn(int $n) => $n < 3) |> toArray();
// [3, 4, 5]

chunk

chunk(int $size): Closure

Splits into chunks of the given size. Yields arrays.

[1, 2, 3, 4, 5] |> chunk(2) |> toArray();
// [[1, 2], [3, 4], [5]]

groupBy

groupBy(callable $fn): Closure

Groups elements by the return value of $fn. Returns an associative array.

Blocking — must consume all elements.

$users |> groupBy(fn(User $u) => $u->country);
// ['FR' => [User, User], 'US' => [User]]

sortBy

sortBy(callable $fn, string $direction = 'asc'): Closure

Sorts elements by the return value of $fn.

Blocking — must consume all elements.

[3, 1, 4, 1, 5] |> sortBy(fn(int $n) => $n);
// [1, 1, 3, 4, 5]

[3, 1, 5] |> sortBy(fn(int $n) => $n, 'desc');
// [5, 3, 1]

unique

unique(?callable $fn = null): Closure

Removes duplicates. Optionally deduplicates by a key function.

[1, 2, 2, 3, 3] |> unique() |> toArray();
// [1, 2, 3]

$users |> unique(fn(User $u) => $u->email) |> toArray();

zip

zip(iterable $other): Closure

Combines two iterables element-by-element into [$a, $b] pairs. Stops at the shorter one.

[1, 2, 3] |> zip(['a', 'b', 'c']) |> toArray();
// [[1, 'a'], [2, 'b'], [3, 'c']]

concat

concat(iterable $other): Closure

Appends another iterable after the current one.

[1, 2, 3] |> concat([4, 5, 6]) |> toArray();
// [1, 2, 3, 4, 5, 6]

enumerate

enumerate(): Closure

Pairs each element with its zero-based index. Yields [index, value] tuples.

['a', 'b', 'c'] |> enumerate() |> toArray();
// [[0, 'a'], [1, 'b'], [2, 'c']]

scan

scan(callable $fn, mixed $initial): Closure

Like reduce, but yields each intermediate accumulator value. Also called "running fold".

[1, 2, 3, 4] |> scan(fn(int $acc, int $v) => $acc + $v, 0) |> toArray();
// [1, 3, 6, 10]

reverse

reverse(): Closure

Reverses elements.

Blocking — must consume all elements.

[1, 2, 3] |> reverse();
// [3, 2, 1]

keys

keys(): Closure

Yields keys from the iterable.

['a' => 1, 'b' => 2] |> keys() |> toArray();
// ['a', 'b']

values

values(): Closure

Yields values, discarding keys.

['a' => 1, 'b' => 2] |> values() |> toArray();
// [1, 2]

pluck

pluck(string|int $key): Closure

Extracts a single property/key from each element. Works with arrays, ArrayAccess, and objects.

$users |> pluck('name') |> toArray();
// ['Alice', 'Bob', 'Charlie']

tap

tap(callable $fn): Closure

Executes a side effect on each element without altering the stream. Lazy — nothing happens until consumed by a terminator.

$users
    |> tap(fn(User $u) => $logger->info($u->name))
    |> map(fn(User $u) => $u->email)
    |> toArray();

Terminators

Terminators consume the iterable and return a final value (or void). They trigger evaluation of the entire lazy chain.

toArray

toArray(): Closure

Converts the iterable to an array. Preserves string keys, re-indexes integer keys.

[1, 2, 3] |> map(fn(int $n) => $n * 2) |> toArray();
// [2, 4, 6]

reduce

reduce(callable $fn, mixed $initial = null): Closure

Reduces to a single value. $fn receives ($accumulator, $value).

[1, 2, 3, 4] |> reduce(fn(int $acc, int $v) => $acc + $v, 0);
// 10

first

first(?callable $predicate = null): Closure

Returns the first element, optionally matching a predicate. Returns null if empty.

[1, 2, 3] |> first();
// 1

[1, 2, 3, 4] |> first(fn(int $n) => $n > 2);
// 3

last

last(?callable $predicate = null): Closure

Returns the last element, optionally matching a predicate. Returns null if empty.

[1, 2, 3] |> last();
// 3

count

count(): Closure

Counts elements.

[1, 2, 3] |> count();
// 3

sum

sum(?callable $fn = null): Closure

Sums elements, optionally extracting a numeric value.

[1, 2, 3] |> sum();
// 6

$orders |> sum(fn(Order $o) => $o->total);
// 1250.50

min

min(?callable $fn = null): Closure

Returns the minimum element, optionally by a key function. Returns null on empty.

[3, 1, 4, 1, 5] |> min();
// 1

$users |> min(fn(User $u) => $u->age);
// User with lowest age

max

max(?callable $fn = null): Closure

Returns the maximum element, optionally by a key function. Returns null on empty.

[3, 1, 4, 1, 5] |> max();
// 5

join

join(string $separator = ', '): Closure

Joins elements into a string.

['a', 'b', 'c'] |> join(' - ');
// 'a - b - c'

contains

contains(mixed $needle): Closure

Checks if the collection contains a value (strict comparison).

[1, 2, 3] |> contains(2);
// true

every

every(callable $fn): Closure

Returns true if all elements satisfy the predicate. Short-circuits on first failure.

[2, 4, 6] |> every(fn(int $n) => $n % 2 === 0);
// true

some

some(callable $fn): Closure

Returns true if at least one element satisfies the predicate. Short-circuits on first match.

[1, 2, 3] |> some(fn(int $n) => $n === 2);
// true

partition

partition(callable $fn): Closure

Splits elements into two arrays based on a predicate. Returns [matching, notMatching].

[$even, $odd] = [1, 2, 3, 4, 5] |> partition(fn(int $n) => $n % 2 === 0);
// $even = [2, 4], $odd = [1, 3, 5]

each

each(callable $fn): Closure

Consumes the iterable, executing $fn on each element. Triggers evaluation of the entire lazy chain. Returns void.

$notifications
    |> filter(fn(Notif $n) => !$n->isSent())
    |> each(fn(Notif $n) => $mailer->send($n));