gingersnap 0.22.0

package/stream/collector.mjs

@@ -0,0 +1,215 @@
+import { __awaiter, __asyncValues } from '../_virtual/_tslib.mjs';
+import { Future } from '../future/future.mjs';
+import 'ramda';
+import '../stream.mjs';
+import { Stack } from '../data-structures/array/Stack.mjs';
+import '../data-structures/object/WatchableObject.mjs';
+import 'object-hash';
+import 'uuid';
+import { AbortError } from '../errors/AbortError.mjs';
+import { SimpleQueue } from '../data-structures/object/SimpleQueue.mjs';
+
+class Collectors {
+    static read(functor) {
+        return (stream) => stream.forEach(functor);
+    }
+    static asList() {
+        return (stream) => {
+            return Future.of((resolve, reject, signal) => __awaiter(this, void 0, void 0, function* () {
+                var _a, e_1, _b, _c;
+                const collection = [];
+                try {
+                    for (var _d = true, stream_1 = __asyncValues(stream), stream_1_1; stream_1_1 = yield stream_1.next(), _a = stream_1_1.done, !_a;) {
+                        _c = stream_1_1.value;
+                        _d = false;
+                        try {
+                            const value = _c;
+                            collection.push(value);
+                            if (signal.aborted) {
+                                reject(new AbortError());
+                                break;
+                            }
+                        }
+                        finally {
+                            _d = true;
+                        }
+                    }
+                }
+                catch (e_1_1) { e_1 = { error: e_1_1 }; }
+                finally {
+                    try {
+                        if (!_d && !_a && (_b = stream_1.return)) yield _b.call(stream_1);
+                    }
+                    finally { if (e_1) throw e_1.error; }
+                }
+                resolve(collection);
+            }));
+        };
+    }
+    static asSet() {
+        return (stream) => {
+            return Future.of((resolve, reject, signal) => __awaiter(this, void 0, void 0, function* () {
+                var _a, e_2, _b, _c;
+                const collection = new Set();
+                try {
+                    for (var _d = true, stream_2 = __asyncValues(stream), stream_2_1; stream_2_1 = yield stream_2.next(), _a = stream_2_1.done, !_a;) {
+                        _c = stream_2_1.value;
+                        _d = false;
+                        try {
+                            const value = _c;
+                            collection.add(value);
+                            if (signal.aborted) {
+                                reject(new AbortError());
+                                break;
+                            }
+                        }
+                        finally {
+                            _d = true;
+                        }
+                    }
+                }
+                catch (e_2_1) { e_2 = { error: e_2_1 }; }
+                finally {
+                    try {
+                        if (!_d && !_a && (_b = stream_2.return)) yield _b.call(stream_2);
+                    }
+                    finally { if (e_2) throw e_2.error; }
+                }
+                resolve(collection);
+            }));
+        };
+    }
+    static joining(delimiter = "") {
+        return (stream) => {
+            return Future.of((resolve, reject, signal) => __awaiter(this, void 0, void 0, function* () {
+                let data = "";
+                let value;
+                const iterator = stream[Symbol.asyncIterator]();
+                value = yield iterator.next();
+                if (!value.done) {
+                    do {
+                        const nextValue = yield iterator.next();
+                        if (!nextValue.done) {
+                            data += value.value + delimiter;
+                            value = nextValue;
+                        }
+                        else
+                            break;
+                    } while (!signal.aborted);
+                }
+                if (signal.aborted) {
+                    reject(new AbortError());
+                    return;
+                }
+                if (value.value !== undefined && value.value !== null) {
+                    data += value.value;
+                }
+                resolve(data);
+            }));
+        };
+    }
+    static asStack(maxSize = undefined) {
+        return (stream) => {
+            return Future.of((resolve, reject, signal) => __awaiter(this, void 0, void 0, function* () {
+                var _a, e_3, _b, _c;
+                const collection = new Stack(maxSize);
+                try {
+                    for (var _d = true, stream_3 = __asyncValues(stream), stream_3_1; stream_3_1 = yield stream_3.next(), _a = stream_3_1.done, !_a;) {
+                        _c = stream_3_1.value;
+                        _d = false;
+                        try {
+                            const value = _c;
+                            collection.push(value);
+                            if (collection.full) {
+                                break;
+                            }
+                            else if (signal.aborted) {
+                                reject(new AbortError());
+                                break;
+                            }
+                        }
+                        finally {
+                            _d = true;
+                        }
+                    }
+                }
+                catch (e_3_1) { e_3 = { error: e_3_1 }; }
+                finally {
+                    try {
+                        if (!_d && !_a && (_b = stream_3.return)) yield _b.call(stream_3);
+                    }
+                    finally { if (e_3) throw e_3.error; }
+                }
+                resolve(collection);
+            }));
+        };
+    }
+    static asQueue() {
+        return (stream) => {
+            return Future.of((resolve, reject, signal) => __awaiter(this, void 0, void 0, function* () {
+                var _a, e_4, _b, _c;
+                const collection = new SimpleQueue();
+                try {
+                    for (var _d = true, stream_4 = __asyncValues(stream), stream_4_1; stream_4_1 = yield stream_4.next(), _a = stream_4_1.done, !_a;) {
+                        _c = stream_4_1.value;
+                        _d = false;
+                        try {
+                            const value = _c;
+                            collection.enqueue(value);
+                            if (signal.aborted) {
+                                reject(new AbortError());
+                                break;
+                            }
+                        }
+                        finally {
+                            _d = true;
+                        }
+                    }
+                }
+                catch (e_4_1) { e_4 = { error: e_4_1 }; }
+                finally {
+                    try {
+                        if (!_d && !_a && (_b = stream_4.return)) yield _b.call(stream_4);
+                    }
+                    finally { if (e_4) throw e_4.error; }
+                }
+                resolve(collection);
+            }));
+        };
+    }
+    static counting() {
+        return (stream) => {
+            return Future.of((resolve, reject, signal) => __awaiter(this, void 0, void 0, function* () {
+                var _a, e_5, _b, _c;
+                let total = 0;
+                try {
+                    for (var _d = true, stream_5 = __asyncValues(stream), stream_5_1; stream_5_1 = yield stream_5.next(), _a = stream_5_1.done, !_a;) {
+                        _c = stream_5_1.value;
+                        _d = false;
+                        try {
+                            const _ = _c;
+                            total++;
+                            if (signal.aborted) {
+                                reject(new AbortError());
+                                break;
+                            }
+                        }
+                        finally {
+                            _d = true;
+                        }
+                    }
+                }
+                catch (e_5_1) { e_5 = { error: e_5_1 }; }
+                finally {
+                    try {
+                        if (!_d && !_a && (_b = stream_5.return)) yield _b.call(stream_5);
+                    }
+                    finally { if (e_5) throw e_5.error; }
+                }
+                resolve(total);
+            }));
+        };
+    }
+}
+
+export { Collectors };

package/stream/index.d.ts

@@ -0,0 +1,257 @@
+import { AnyDataType, Flattened, InferErrorResult, InferStreamResult } from "../typing/types";
+import { Future, WaitPeriod } from "../future";
+import { ExecutorState } from "./state";
+import { Collector } from "./collector";
+declare enum ActionType {
+    TRANSFORM = 0,
+    FILTER = 1,
+    LIMIT = 2,
+    UNPACK = 3,
+    PACK = 4,
+    CATCH = 5
+}
+export declare enum State {
+    MATCHED = 0,
+    CONTINUE = 1,
+    DONE = 2
+}
+interface LimitResult<T> {
+    value?: T;
+    done: boolean;
+}
+type ActionFunctor<T> = (v: T) => T | null | Promise<T> | LimitResult<T> | Promise<LimitResult<T>> | Stream<T>;
+export type Executor = (v: AbortSignal) => Promise<any> | Future<any> | AnyDataType | ExecutorState<any> | Stream<any>;
+/**
+ * Handles a continuous supply of data that can be transformed and manipulated using a chain of actions
+ */
+export declare class Stream<T> implements AsyncGenerator<T> {
+    protected executed: boolean;
+    protected actions: Array<{
+        type: ActionType;
+        functor: ActionFunctor<T>;
+    }>;
+    protected cancelHooks: Set<() => any>;
+    protected completionHooks: Set<() => any>;
+    protected completionHookInvoked: boolean;
+    protected done: boolean;
+    protected backlog: Array<{
+        records: T[] | Stream<T>;
+        actionStream: number;
+    }>;
+    private canRunExecutor;
+    private readonly runLock;
+    /**
+     * AbortController used to cancel http request created by the callback
+     * @private
+     */
+    private controller;
+    /**
+     * Callback function that executes a network request. Function should accept an AbortSignal as argument,
+     * and return AnyDataType upon completion
+     * @private
+     */
+    protected executor: Executor;
+    private concurrencyLimit;
+    private sourceStream?;
+    constructor(executor: Executor);
+    /**
+     * Used to provide setup logic that should only be invoked once, when stream
+     * is starting. This setup logic must provide the actual data required, which
+     * can come from a Stream or Future
+     * @param supplier
+     */
+    static seed<T>(supplier: () => Stream<T> | Future<T>): Stream<T>;
+    /**
+     * Streams the next available result from a list of futures, until all future completes. If any future fails, then the
+     * stream will throw an error
+     * @param futures
+     */
+    static asCompleted(futures: Array<Future<any>>): Stream<unknown>;
+    /**
+     * Stream the next available result from the list of streams. If any stream fails, then this merged stream also fails.
+     * @param streams
+     */
+    static merge<K extends Array<Stream<any>>>(streams: K): Stream<InferStreamResult<K[number]>>;
+    /**
+     * Aggregates the results from multiple streams
+     * @param streams
+     */
+    static zip<K extends Array<Stream<any>>>(streams: K): Stream<Array<InferStreamResult<K[number]>>>;
+    /**
+     * Converts the provided value to a stream
+     * @param value
+     */
+    static of<K>(value: AsyncIterable<K> | Iterable<K> | ((v: AbortSignal) => AsyncGenerator<K, any, any>) | AsyncGenerator<K> | AsyncGeneratorFunction | Future<K> | ReadableStream<K>): Stream<K>;
+    /**
+     * Stream that never gives a result
+     */
+    static forever(): Stream<null>;
+    get isParallel(): Stream<T>;
+    /**
+     * Gets a future of the next value on the stream, if any.
+     */
+    get future(): Future<T>;
+    get readableStream(): ReadableStream<T>;
+    /**
+     * Cancel the stream on the given signal
+     * @param signal
+     */
+    cancelOnSignal(signal: AbortSignal): this;
+    parallel(concurrentlyLimit?: number): Stream<T>;
+    /**
+     * Transforms each data on the stream using the callback provided
+     * @param callback
+     */
+    map<K>(callback: (v: T) => K | Promise<K> | Future<K> | Stream<K>): Stream<InferStreamResult<K>>;
+    /**
+     * Filters data on the stream using the callback provided
+     * @param callback
+     */
+    filter(callback: (v: T) => boolean | Promise<boolean> | Future<boolean>): Stream<T>;
+    reduce<K, V>(initialData: K, functor: (v: T, prev: K | V) => V, exhaustive?: boolean): Stream<V>;
+    reduceWhile<K, V>(predicate: (v: T) => boolean, initialData: K, functor: (v: T, prev: K | V) => V, exhaustive?: boolean): Stream<V>;
+    /**
+     * Retrieves the first value from the stream as a new stream. Important Note: the original stream cannot be executed
+     * before head() is invoked, otherwise the stream returned by head() will throw an error, as the first value was
+     * already consumed elsewhere
+     */
+    head(): Stream<T>;
+    /**
+     * Returns a new stream that exhausts the original stream, yielding the last value received before the original
+     * stream ended
+     */
+    tail(): Stream<T>;
+    /**
+     * group data on the stream into separate slices
+     * E.g. Stream yielding 1,2,3,4,5,6 with chunk of 2 => [1,2], [3,4], [5,6]
+     * @param value chunk size or function that indicates when to split
+     * @param keepSplitCriteria if value provided was a function, this parameter is used to determine if the data used
+     * for the split criteria should be added to the chunk, if false then the data will be added to the next chunk
+     */
+    chunk(value: number | ((v: T) => boolean), keepSplitCriteria?: boolean): Stream<T[]>;
+    /**
+     * Clones the stream
+     * @param withSignals should the abort signals of the original stream trigger the cloned stream cancellation
+     */
+    clone(withSignals?: boolean): Stream<T>;
+    /**
+     * Register hook that is only ever called if stream was cancelled
+     * @param hook
+     */
+    onCancellation(hook: () => any): this;
+    removeCancelHook(hook: () => any): this;
+    /**
+     * Register hook that is called once the stream completes, cancelled or fails
+     * @param hook
+     */
+    onCompletion(hook: () => any): this;
+    removeCompletionHook(hook: () => any): this;
+    /**
+     * Cancels the stream
+     * @param reason
+     */
+    cancel(reason?: any): void;
+    /**
+     * Limits the number of times the stream can yield a value
+     * @param count
+     */
+    take(count: number): Stream<T>;
+    /**
+     * Process stream data while predicate is true
+     * @param predicate
+     */
+    takeWhile(predicate: (v: T) => boolean): Stream<T>;
+    /**
+     * Drop stream data until predicate is no longer true
+     * @param predicate
+     */
+    skipWhile(predicate: (v: T) => boolean): Stream<T>;
+    /**
+     * Removes duplicates from the stream based on the key extractor functor provided
+     * @param uniqKeyExtractor
+     * @param expiryPeriod
+     */
+    dropRepeats(uniqKeyExtractor: (v: T) => string, expiryPeriod?: WaitPeriod | undefined): Stream<T>;
+    /**
+     * Allows the stream to yield only 1 value
+     */
+    once(): Stream<T>;
+    /**
+     * Skips the first X records on the stream
+     * @param count
+     */
+    skip(count: number): this;
+    /**
+     * Applies rate limiting to the speed at which the data is made available on the stream
+     * @param period
+     */
+    throttleBy(period: WaitPeriod): this;
+    /**
+     * Flattens any nested structure from the data arriving on the stream
+     */
+    flatten(): Stream<Flattened<T>>;
+    /**
+     * Runs the stream in the background, collecting and buffering the results for the next chain in the stream. This
+     * allows the stream to run concurrently without waiting on single emitted values sequentially
+     * @param maxSize
+     */
+    buffer(maxSize?: number): Stream<T>;
+    /**
+     * Process stream values in the background, thereby yielding the latest value if the collector of the stream is too
+     * slow (i.e. values that are not read by collector before new value flows in the stream, will be dropped)
+     */
+    conflate(): Stream<T>;
+    /**
+     * If the stream receives an error, handle that error with the given callback. If callback doesn't throw an error,
+     * then the stream will recover and resume with the result provided by the callback
+     * @param callback
+     */
+    catch<K>(callback: (v: Error) => K | null | undefined): Stream<InferErrorResult<K, T> | T>;
+    /**
+     * Consumes the entire stream and store the data in an array. Future is immediately executed
+     */
+    collect<K>(collector: Collector<K, T>): Future<K>;
+    /**
+     * Continuously exhaust the stream until the stream ends or the limit is reached. No result will be provided at
+     * the end. Future is immediately executed
+     * @param limit
+     */
+    consume(limit?: number): Future<void>;
+    /**
+     * Iterates over the stream of values, used as a collector. Future is immediately executed
+     * @param callback
+     */
+    forEach(callback: (v: T) => void | Future<void>): Future<void>;
+    /**
+     * Runs the stream only once. After this call, the stream is closed. Future is immediately executed
+     */
+    execute(): Future<T>;
+    join(): Stream<T>;
+    [Symbol.asyncIterator](): AsyncGenerator<T, any, unknown>;
+    next(...args: [] | [unknown]): Promise<IteratorResult<T, any>>;
+    return(value: any): Promise<IteratorResult<T, any>>;
+    return(value?: any): Promise<IteratorResult<T, any>>;
+    throw(e: any): Promise<IteratorResult<T, any>>;
+    throw(e?: any): Promise<IteratorResult<T, any>>;
+    protected __execute__(preProcessor?: <T>(a: T) => T | Promise<T>): Future<{
+        state: State;
+        value?: T;
+    }>;
+    protected processor(index: number, traversableActions: Array<{
+        type: ActionType;
+        functor: ActionFunctor<T>;
+    }>, record: any, preProcessor: <T>(a: T) => T | Promise<T>, signal: AbortSignal): Future<{
+        state: State;
+        value?: T | undefined;
+    }>;
+    private internalIterator;
+    private checkBacklog;
+    private internalNext;
+    private invokeCompletionHooks;
+    private processError;
+    private findAndExecuteMostRecentPacker;
+    private yieldTrueResult;
+    private forwardExecute;
+    private collectResult;
+}
+export {};

package/stream/observable.cjs

@@ -0,0 +1,110 @@
+'use strict';
+
+var stream = require('../stream.cjs');
+var future = require('../future/future.cjs');
+require('ramda');
+require('../data-structures/object/WatchableObject.cjs');
+require('object-hash');
+require('uuid');
+var Queue = require('../data-structures/object/Queue.cjs');
+var signal = require('../data/signal.cjs');
+
+/**
+ * Provides a Publisher-Subscriber service around an event stream
+ */
+class Observable {
+    signal(topic) {
+        return new signal.Signal(this.subscribe(topic).map((v) => v.data));
+    }
+    /**
+     * Pull data off a stream and publishes it
+     * @param topic topic used to dispatch data to subscribers
+     * @param stream any data stream
+     */
+    publishFromStream(topic, stream) {
+        return stream
+            .map((data) => this.publish(topic, data))
+            .consume()
+            .schedule();
+    }
+    /**
+     * Provides a Request-Reply model by sending data over the given topic, and
+     * await a response over the second topic provided.
+     * @param reqTopic
+     * @param replyTopic
+     * @param data
+     * @param timeout how long to wait for a response, defaults to 15 seconds
+     */
+    request(reqTopic, replyTopic, data, timeout = { seconds: 15 }) {
+        this.publish(reqTopic, data);
+        return future.Future.waitFor(this.subscribe(replyTopic, 2).future, timeout).thenApply(({ value }) => value.data);
+    }
+}
+/**
+ * Provides Publisher-Subscriber service around an EventTarget
+ */
+class ObservableEventTarget extends Observable {
+    constructor() {
+        super();
+        this.__internal__ = new EventTarget();
+    }
+    publish(topic, data) {
+        this.__internal__.dispatchEvent(new CustomEvent(topic, { detail: { topic, data } }));
+        this.__internal__.dispatchEvent(new CustomEvent("*", { detail: { topic, data } }));
+    }
+    subscribe(topic, bufferSize = undefined, expiryPeriod = undefined) {
+        const queue = new Queue.Queue(bufferSize, expiryPeriod);
+        const listener = typeof topic === "string"
+            ? (evt) => queue.enqueue(evt.detail)
+            : (evt) => {
+                if (topic.test(evt.detail.topic)) {
+                    queue.enqueue(evt.detail);
+                }
+            };
+        const listeningTopic = typeof topic === "string" ? topic : "*";
+        return stream.Stream.seed(() => {
+            this.__internal__.addEventListener(listeningTopic, listener);
+            return queue.streamEntries;
+        }).onCompletion(() => {
+            this.__internal__.removeEventListener(listeningTopic, listener);
+            queue.clear();
+        });
+    }
+}
+/**
+ * Provides Publisher-Subscriber service around a MessagePort
+ */
+class ObservableMessagePort extends Observable {
+    constructor(messagePort) {
+        super();
+        this.messagePort = messagePort;
+    }
+    publish(topic, data) {
+        this.messagePort.postMessage({ topic, data });
+    }
+    subscribe(topic, bufferSize = undefined, expiryPeriod = undefined) {
+        const queue = new Queue.Queue(bufferSize, expiryPeriod);
+        const listener = typeof topic === "string"
+            ? (evt) => {
+                if (topic === "*" || evt.data.topic === topic) {
+                    queue.enqueue(evt.data);
+                }
+            }
+            : (evt) => {
+                if (topic.test(evt.data.topic)) {
+                    queue.enqueue(evt.data);
+                }
+            };
+        return stream.Stream.seed(() => {
+            this.messagePort.addEventListener("message", listener);
+            return queue.streamEntries;
+        }).onCompletion(() => {
+            this.messagePort.removeEventListener("message", listener);
+            queue.clear();
+        });
+    }
+}
+
+exports.Observable = Observable;
+exports.ObservableEventTarget = ObservableEventTarget;
+exports.ObservableMessagePort = ObservableMessagePort;

package/stream/observable.d.ts

@@ -0,0 +1,65 @@
+import { Stream } from "./index";
+import { Future, WaitPeriod } from "../future";
+import { Signal } from "../data/signal";
+/**
+ * Provides a Publisher-Subscriber service around an event stream
+ */
+export declare abstract class Observable<T> {
+    /**
+     * Dispatches data to all subscribers listening on the provided topic
+     * @param topic
+     * @param data
+     */
+    abstract publish(topic: string, data: T): void;
+    /**
+     * Monitor for incoming data on the provided topic. If topic is '*', then
+     * will subscribe to all incoming data
+     * @param topic
+     * @param bufferSize
+     * @param expiryPeriod
+     */
+    abstract subscribe(topic: string | RegExp, bufferSize?: number, expiryPeriod?: WaitPeriod): Stream<{
+        topic: string;
+        data: T;
+    }>;
+    signal(topic: string | RegExp): Signal<T>;
+    /**
+     * Pull data off a stream and publishes it
+     * @param topic topic used to dispatch data to subscribers
+     * @param stream any data stream
+     */
+    publishFromStream(topic: string, stream: Stream<T>): Future<void>;
+    /**
+     * Provides a Request-Reply model by sending data over the given topic, and
+     * await a response over the second topic provided.
+     * @param reqTopic
+     * @param replyTopic
+     * @param data
+     * @param timeout how long to wait for a response, defaults to 15 seconds
+     */
+    request(reqTopic: string, replyTopic: string, data: T, timeout?: WaitPeriod): Future<T>;
+}
+/**
+ * Provides Publisher-Subscriber service around an EventTarget
+ */
+export declare class ObservableEventTarget<T> extends Observable<T> {
+    private readonly __internal__;
+    constructor();
+    publish(topic: string, data: T): void;
+    subscribe(topic: string | RegExp, bufferSize?: number | undefined, expiryPeriod?: WaitPeriod | undefined): Stream<{
+        topic: string;
+        data: T;
+    }>;
+}
+/**
+ * Provides Publisher-Subscriber service around a MessagePort
+ */
+export declare class ObservableMessagePort<T> extends Observable<T> {
+    private readonly messagePort;
+    constructor(messagePort: MessagePort);
+    publish(topic: string, data: T): void;
+    subscribe(topic: string | RegExp, bufferSize?: number | undefined, expiryPeriod?: WaitPeriod | undefined): Stream<{
+        topic: string;
+        data: T;
+    }>;
+}