@rimbu/stream
Version:
Efficient structure representing a sequence of elements, with powerful operations for TypeScript
194 lines (193 loc) • 10.5 kB
text/typescript
import { CollectFun, Eq } from '@rimbu/common';
import { Reducer, type StreamSource } from '@rimbu/stream';
/**
* A Reducer that produces instances of `StreamSource`.
* @typeparam T - the input element type
* @typeparam R - the result stream element type
*/
export type Transformer<T, R = T> = Reducer<T, StreamSource<R>>;
export declare namespace Transformer {
/**
* A Reducer that produces instances of `StreamSource.NonEmpty`.
* @typeparam T - the input element type
* @typeparam R - the result stream element type
*/
type NonEmpty<T, R = T> = Reducer<T, StreamSource.NonEmpty<R>>;
/**
* Returns a transformer that produces windows/collections of `windowSize` size, each
* window starting `skipAmount` of elements after the previous, and optionally collected
* by a custom reducer.
* @typeparam T - the input element type
* @typeparam R - the window type
* @param windowSize - the amount of elements for each window
* @param options - (optional) object specifying the following properties<br/>
* - skipAmount - (default: `windowSize`) the amount of elements between the start of each window
* - collector - (default: Reducer.toArray()) the reducer to use to convert elements to windows
* @example
* ```ts
* Stream.of(1, 2, 3, 4, 5, 6)
* .transform(Transformer.window(3))
* .toArray()
* // => [[1, 2, 3], [4, 5, 6]]
* ```
*/
const window: {
<T, R>(windowSize: number, options: {
skipAmount?: number | undefined;
collector: Reducer<T, R>;
}): Transformer<T, R>;
<T>(windowSize: number, options?: {
skipAmount?: number | undefined;
collector?: undefined;
}): Transformer<T, T[]>;
};
/**
* Returns a transformer that returns only those elements from the input that are different to previous element
* according to the optionally given `eq` function.
* @param options:
* - eq - (default: `Eq.objectIs`) the equality testing function
* - negate: (default: false) when true will negate the given predicate<br/>
* @example
* ```ts
* Stream.of(1, 1, 2, 3, 2, 2)
* .transform(Transformer.distinctPrevious())
* .toArray()
* // => [1, 2, 3, 2]
* ```
*/
function distinctPrevious<T>(options?: {
eq?: Eq<T> | undefined;
negate?: boolean | undefined;
}): Transformer<T>;
/**
* Returns a transformer that applies the given flatMap function to each element of the input stream,
* and concatenates all the resulting resulting streams into one stream.
* @typeparam T - the input element type
* @typeparam T2 - the output element type
* @param flatMapFun - a function that maps each input element to an `StreamSource` or a promise
* resolving to a `StreamSource`. The function receives three parameters:<br/>
* - `value`: the current element being processed<br/>
* - `index`: the index of the current element in the input stream<br/>
* - `halt`: a function that can be called to halt further processing of the input stream<br/>
*/
function flatMap<T, T2>(flatMapFun: (value: T, index: number, halt: () => void) => StreamSource<T2>): Transformer<T, T2>;
/**
* Returns a transformer that applies the given flatMap function to each element of the input stream,
* and concatenates all the resulting resulting streams into one stream, where each resulting element is tupled
* with the originating input element.
* @typeparam T - the input element type
* @typeparam T2 - the output element type
* @param flatMapFun - a function that maps each input element to an `StreamSource` or a promise
* resolving to an `StreamSource`. The function receives three parameters:<br/>
* - `value`: the current element being processed<br/>
* - `index`: the index of the current element in the input stream<br/>
* - `halt`: a function that can be called to halt further processing of the input stream<br/>
*/
function flatZip<T, T2>(flatMapFun: (value: T, index: number, halt: () => void) => StreamSource<T2>): Transformer<T, [T, T2]>;
/**
* Returns a transformer that filters elements from the input stream based on the provided predicate function.
* @typeparam T - the type of elements in the input stream
* @param pred - a predicate function that determines whether an element should be included in the output stream, receiving:<br/>
* - `value`: the current element being processed<br/>
* - `index`: the index of the current element in the input stream<br/>
* - `halt`: a function that can be called to halt further processing of the input stream
* @param options - (optional) object specifying the following properties:<br/>
* - negate: (default: false) if true, the predicate will be negated
* @note if the predicate is a type guard, the return type is automatically inferred
*/
const filter: {
<T, TF extends T>(pred: (value: T, index: number, halt: () => void) => value is TF, options?: {
negate?: boolean | undefined;
}): Transformer<T, TF>;
<T, TF extends T>(pred: (value: T, index: number, halt: () => void) => value is TF, options: {
negate: true;
}): Transformer<T, Exclude<T, TF>>;
<T>(pred: (value: T, index: number, halt: () => void) => boolean, options?: {
negate?: boolean | undefined;
}): Transformer<T>;
};
/**
* Returns a `Transformer` instance that converts or filters its input values using given `collectFun` before passing them to the reducer.
* @param collectFun - a function receiving the following arguments, and returns a new value or `skip` if the value should be skipped:<br/>
* - `value`: the next value<br/>
* - `index`: the value index<br/>
* - `skip`: a token that, when returned, will not add a value to the resulting collection<br/>
* - `halt`: a function that, when called, ensures no next elements are passed
* @typeparam T - the input element type
* @typeparam R - the result element type
*/
function collect<T, R>(collectFun: CollectFun<T, R>): Transformer<T, R>;
/**
* Returns a `Transfoemr` that inserts the given `sep` stream source elements between each received input element.
* @param sep - the StreamSource to insert between each received element
* @typeparam T - the input and output element type
*/
function intersperse<T>(sep: StreamSource<T>): Transformer<T>;
/**
* Returns a `Transformer` that outputs the index of each received element that satisfies the given predicate.
* @param pred - a predicate function taking an element
* @param options - (optional) object specifying the following properties<br/>
* - negate: (default: false) when true will negate the given predicate
* @typeparam T - the input element type
*/
function indicesWhere<T>(pred: (value: T) => boolean, options?: {
negate?: boolean | undefined;
}): Transformer<T, number>;
/**
* Returns a `Transformer` that outputs the index of each received element that is equal to the given `searchValue` value,
* according to the `eq` equality function.
* @param searchValue - the value to match input values to
* @param options - (optional) object specifying the following properties<br/>
* - eq - (default: `Eq.objectIs`) the equality testing function
* - negate: (default: false) when true will negate the given predicate
* @typeparam T - the input element type
*/
function indicesOf<T>(searchValue: T, options?: {
eq?: Eq<T> | undefined;
negate?: boolean | undefined;
}): Transformer<T, number>;
/**
* Returns a `Transformer` that applies the given `pred` function to each received element, and collects the received elements
* into a `collector` that will be returned as output every time the predicate returns true.
* @typeparam T - the input element type
* @typeparam R - the collector result type
* @param pred - a predicate function taking an element
* @param options - (optional) object specifying the following properties<br/>
* - negate: (default: false) when true will negate the given predicate<br/>
* - collector: (default: Reducer.toArray()) a Reducer that can accept multiple values and reduce them into a single value of type `R`.
*/
function splitWhere<T, R>(pred: (value: T, index: number) => boolean, options?: {
negate?: boolean | undefined;
collector?: Reducer<T, R> | undefined;
}): Transformer<T, R>;
/**
* Returns a `Transformer` that collects the received elements
* into a `collector` that will be returned as output every time the input matches the given `sepElem` value.
* @typeparam T - the input element type
* @typeparam R - the collector result type
* @param pred - a predicate function taking an element
* @param options - (optional) object specifying the following properties<br/>
* - eq - (default: `Eq.objectIs`) the equality testing function
* - negate: (default: false) when true will negate the given predicate<br/>
* - collector: (default: Reducer.toArray()) an AsyncReducer that can accept multiple values and reduce them into a single value of type `R`.
*/
function splitOn<T, R>(sepElem: T, options?: {
eq?: Eq<T> | undefined;
negate?: boolean | undefined;
collector?: Reducer<T, R> | undefined;
}): Transformer<T, R>;
/**
* Returns a `Transformer` that collects the received elements
* into a `collector` that will be returned as output every time the input matches the given `sepSlice` sequence of elements.
* @typeparam T - the input element type
* @typeparam R - the collector result type
* @param pred - a predicate function taking an element
* @param options - (optional) object specifying the following properties<br/>
* - eq - (default: `Eq.objectIs`) the equality testing function
* - collector: (default: Reducer.toArray()) an AsyncReducer that can accept multiple values and reduce them into a single value of type `R`.
*/
function splitOnSlice<T, R>(sepSlice: StreamSource<T>, options?: {
eq?: Eq<T> | undefined;
collector?: Reducer<T, R> | undefined;
}): Transformer<T, R>;
}