gingersnap 0.22.0

package/future/future.d.ts

@@ -0,0 +1,208 @@
+import { FutureResult, InferredFutureResult } from "./result";
+import { Stream } from "../stream";
+type Resolve<T> = (value: T | PromiseLike<T> | Future<T>) => any;
+type Reject = (reason?: Error) => void;
+type Executor<T> = (resolve: Resolve<T>, reject: Reject, signal: AbortSignal) => void | Promise<T | void>;
+type FutureReturnType<T> = T extends Future<infer U> ? U : T;
+export declare const calculatePeriodValue: (period: WaitPeriod) => number;
+/**
+ * Duration to wait for something to occur
+ */
+export interface WaitPeriod {
+    minutes?: number;
+    seconds?: number;
+    milliseconds?: number;
+    hours?: number;
+}
+/**
+ * Represents an eventual result of some asynchronous operation. Futures are quite similar to Promise, and can be
+ * awaited as they are **Thenable** objects
+ */
+export declare class Future<T> {
+    private guid;
+    private signals;
+    private signalRegisteredCallback?;
+    private defaultSignal;
+    private fulfilled;
+    private isRunning;
+    private readonly executor;
+    private completedResult?;
+    private failureResult?;
+    private underLyingPromise?;
+    private processors;
+    private readonly finallyHandlers;
+    constructor(executor: Executor<T>, signal?: AbortSignal);
+    /**
+     * Creates a future that wraps the given future, and prevents it from being cancellable on the call to "cancel" method
+     * @param future
+     */
+    static shield<K>(future: Future<K>): Future<K>;
+    /**
+     * Creates a future from the value provided
+     * @param value an Executor function (callback for the new Future constructor)
+     * @param signal Abort Signal to establish the future with. If not provided, the future will only have the default
+     * signals
+     */
+    static of<K>(value: Executor<K>, signal?: AbortSignal): Future<K>;
+    /**
+     * Wraps a promise as a future
+     * @param value
+     */
+    static wrap<K>(value: Promise<K>): Future<InferredFutureResult<K>>;
+    /**
+     * Waits for the given future to complete. If not completed within the given timeframe, the given future is cancelled
+     * @param value
+     * @param timeout wait period object or the number of milliseconds to wait
+     */
+    static waitFor<K>(value: Future<K>, timeout: WaitPeriod | number): Future<K>;
+    /**
+     * Sleeps for the given period. If period is a number, then it's the sleep duration in seconds
+     * @param period
+     * @param signal
+     */
+    static sleep(period: WaitPeriod | number, signal?: AbortSignal): Future<void>;
+    /**
+     * Returns a future that completes with the given value.
+     * Important Note:
+     * Passing a Future or Stream to this function will execute it once and yield the result.
+     * @param value
+     */
+    static completed<T>(value: T): Future<T>;
+    /**
+     * Returns a future that fails with the given value
+     * @param value
+     */
+    static exceptionally(value: Error): Future<unknown>;
+    /**
+     * Returns the first completed or failed. If this is cancelled, then all futures provided will also be cancelled
+     * @param futures list of futures
+     * @param signal optinal abort signal
+     */
+    static firstCompleted<T extends Array<Future<any>>>(futures: T, signal?: AbortSignal): Future<FutureReturnType<T[number]>>;
+    /**
+     * Awaits all futures completion, and collects the results in an array. If this future is cancelled, then all provided
+     * futures will also be cancelled.
+     * @param futures list of futures
+     * @param signal optional abort signal
+     */
+    static collect<T extends Future<any>>(futures: T[], signal?: AbortSignal): Future<Array<FutureReturnType<T>>>;
+    /**
+     * Awaits futures finishing all possible executions, and returns the same list of futures. Whether each future
+     * completed or failed, the future is returned in the array
+     * @param futures
+     */
+    static collectSettled<T extends Future<any>>(futures: T[]): Future<T[]>;
+    /**
+     * Creates a future that schedules the provided functor at the given frequency intervals
+     * @param functor function to be executed at specified intervals
+     * @param frequency interval used to schedule the functor's call
+     */
+    static periodic(functor: (signal: AbortSignal) => Promise<any> | Future<any> | any, frequency: WaitPeriod): Future<unknown>;
+    /**
+     * Unique ID of the future
+     */
+    get id(): string;
+    /**
+     * Changes the future ID
+     * @param value
+     */
+    set id(value: string);
+    /**
+     * Checks if the future completed. A completed future is one that ran successfully without termination.
+     */
+    get done(): boolean;
+    /**
+     * Checks if the future failed
+     */
+    get failed(): boolean;
+    /**
+     * Retrieves the result of the future, if there is any
+     */
+    get result(): T;
+    /**
+     * Checks if the future is running
+     */
+    get running(): boolean;
+    /**
+     * Retrieves the error if any occurred
+     */
+    get error(): Error;
+    /**
+     * Convert the future to a stream
+     */
+    get stream(): Stream<T>;
+    /**
+     * Registers additional signal to the current future
+     * @param signal
+     */
+    registerSignal(signal: AbortSignal): Future<T>;
+    /**
+     * Removes the given signal from the future
+     * @param signal
+     */
+    unregisterSignal(signal: AbortSignal): Future<T>;
+    /**
+     * Runs the future in the background
+     */
+    schedule(): this;
+    /**
+     * Launches the future
+     */
+    run(): Promise<T>;
+    /**
+     * Cancels the future if it is currently running
+     */
+    cancel(): void;
+    /**
+     * Used to chain additional steps to be executed. This creates a new future
+     * @param callback
+     * @param clone whether the future should be cloned or not.Defaults to true
+     */
+    thenApply<K>(callback: (value: FutureResult<T>) => K, clone?: boolean): Future<InferredFutureResult<K>>;
+    /**
+     * Used to run callback irrespective of the future completing or failing
+     * @param callback
+     * @param clone whether the future should be cloned or not.Defaults to true
+     */
+    finally(callback: (value: Future<T>) => void, clone?: boolean): Future<T>;
+    /**
+     * Handles any error that occurs in the previous steps inside the future
+     * @param callback
+     * @param clone whether the future should be cloned or not.Defaults to true
+     */
+    catch<K>(callback: (reason: Error) => K, clone?: boolean): Future<InferredFutureResult<T | K>>;
+    /**
+     * Clones the current future
+     */
+    clone(): Future<T>;
+    /**
+     * Internal. Only to be called by the internal JS runtime during await
+     * @private
+     */
+    then(onFulfilled: (v: T) => void, onRejected: (reason: unknown) => void): Promise<T>;
+    /**
+     * Executes the future. Should only be triggered by the JS runtime via then(), or the user via run()
+     * @param onFulfilled
+     * @param onRejected
+     * @private
+     */
+    private __run__;
+    /**
+     * Fires the abort signal
+     * @param signal
+     * @private
+     */
+    private cancelWithSignal;
+    /**
+     * Checks if any handler exist to process errors
+     * @private
+     */
+    private findFailureHandler;
+    /**
+     * Nested processing of a future result
+     * @param result
+     * @private
+     */
+    private postResultProcessing;
+}
+export {};