t-tasks 1.2.0 → 2.0.0

package/dist/task.d.ts

@@ -1,489 +0,0 @@
-import { Maybe } from './maybe';
-import { Either } from './either';
-/**
- * Shortcut for monadic Either type, where erroneous value is of type any
- *
- * @template R underlying type
- */
-export type Rejectable<R> = Either<R, any>;
-/**
- * Shortcut for underlying task result type
- *
- * @template R underlying type
- */
-export type Cancelable<R> = Maybe<Rejectable<R>>;
-/**
- * Function returning Task
- *
- * @template A argument types
- * @template R returned task resolve type
- */
-export type TaskFunction<A extends unknown[], R> = (...args: A) => Task<R>;
-/**
- * Task generator
- *
- * @template TT yielded task type
- * @template R returned task resolve type
- *
- * @example
- * ```typescript
- * const generatorFunction = function*(): TaskGenerator<unknown, Task<string>, number> {
- *   const v = yield* someTaskFunction().generator();
- *
- *   return v.length;
- * };
- * ```
- */
-export type TaskGenerator<T, TT extends Task<T>, R> = Generator<TT, R, T>;
-/**
- * Function returning task generator (generator function)
- *
- * @template A argument types
- * @template TT yielded task type
- * @template R returned task resolve type
- *
- * @example
- * ```typescript
- * const generatorFunction: TaskGeneratorFunction<[], unknown, Task<string>, number> = function*() {
- *   const v = yield* someTaskFunction().generator();
- *
- *   return v.length;
- * };
- * ```
- */
-export type TaskGeneratorFunction<A extends unknown[], T, TT extends Task<T>, R> = (...args: A) => TaskGenerator<T, TT, R>;
-/**
- * Task monad interface
- *
- * @template R task resolve type
- */
-export interface Task<R> extends TaskBase<R> {
-    /**
-     * Invoke callback when task is resolved (and only then)
-     *
-     * @param op callback to invoke
-     * @returns self
-     */
-    tap(op: (value: R) => void): Task<R>;
-    /**
-     * Invoke callback when task is rejected (and only then)
-     *
-     * @param op callback to invoke
-     * @returns self
-     */
-    tapRejected(op: (error: any) => void): Task<R>;
-    /**
-     * Invoke callback when task is canceled (and only then)
-     *
-     * @param op callback to invoke
-     * @returns self
-     */
-    tapCanceled(op: () => void): Task<R>;
-    /**
-     * Invoke a dedicated callback according to task resolution
-     *
-     * @param op.resolved callback to invoke on success
-     * @param op.rejected callback to invoke on failure
-     * @param op.canceled callback to invoke on cancelation
-     * @returns self
-     */
-    matchTap(op: {
-        resolved: (value: R) => void;
-        rejected: (error: any) => void;
-        canceled: () => void;
-    }): Task<R>;
-    /**
-     * Invoke transformer when task is resolved (and only then) and return it's result instead
-     *
-     * @template R2 transformer return type
-     * @param op transformer to invoke
-     * @returns task returning transformer result
-     */
-    map<R2>(op: (value: R) => R2): Task<R2>;
-    /**
-     * Invoke transformer when task is rejected (and only then) and return it's result instead
-     *
-     * @template R2 fallback return type
-     * @param op transformer to invoke
-     * @returns task returning fallback result in case of failure
-     */
-    mapRejected<R2>(op: (error: any) => R2): Task<R | R2>;
-    /**
-     * Invoke transformer when task is canceled (and only then) and return it's result instead
-     *
-     * @template R2 fallback return type
-     * @param op transformer to invoke
-     * @returns task returning fallback result in case of cancelation
-     */
-    mapCanceled<R2>(op: () => R2): Task<R | R2>;
-    /**
-     * Invoke a dedicated transformer according to task resolution
-     *
-     * @template R2 success transformer return type
-     * @template R3 failure transformer return type
-     * @template R4 cancelation transformer return type
-     * @param op.resolved transformer to invoke on success
-     * @param op.rejected transformer to invoke on failure
-     * @param op.canceled transformer to invoke on cancelation
-     * @returns task resolving to a corresponding transformer result
-     */
-    matchMap<R2, R3 = R2, R4 = R3>(op: {
-        resolved: (value: R) => R2;
-        rejected: (error: any) => R3;
-        canceled: () => R4;
-    }): Task<R2 | R3 | R4>;
-    /**
-     * Invoke transformer when task is resolved (and only then) and continue execution with it's result
-     *
-     * @template R2 transformer task resolve type
-     * @param op transformer to invoke
-     * @returns task chaining to transformer result task
-     */
-    chain<R2>(op: (value: R) => Task<R2>): Task<R2>;
-    /**
-     * Invoke transformer when task is rejected (and only then) and continue execution with it's result
-     *
-     * @template R2 fallback task resolve type
-     * @param op transformer to invoke
-     * @returns task chaining to fallback task in case of failure
-     */
-    chainRejected<R2>(op: (error: any) => Task<R2>): Task<R | R2>;
-    /**
-     * Invoke transformer when task is canceled (and only then) and continue execution with it's result
-     *
-     * @template R2 fallback task resolve type
-     * @param op transformer to invoke
-     * @returns task chaining to fallback task in case of cancelation
-     */
-    chainCanceled<R2>(op: () => Task<R2>): Task<R | R2>;
-    /**
-     * Invoke a dedicated transformer according to task resolution and continue execution with it's result
-     *
-     * @template R2 success transformer resolve type
-     * @template R3 failure transformer resolve type
-     * @template R4 cancelation transformer resolve type
-     * @param op.resolved transformer to invoke on success
-     * @param op.rejected transformer to invoke on failure
-     * @param op.canceled transformer to invoke on cancelation
-     * @returns task chaining to a corresponding transformer result
-     */
-    matchChain<R2, R3 = R2, R4 = R3>(op: {
-        resolved: (value: R) => Task<R2>;
-        rejected: (error: any) => Task<R3>;
-        canceled: () => Task<R4>;
-    }): Task<R2 | R3 | R4>;
-    /**
-     * Return underlying promise in order to await result
-     *
-     * @returns underlying promise
-     */
-    resolve: () => TaskInvoke<R>;
-    /**
-     * Invoke underlying canel method without error
-     */
-    cancel: () => void;
-    /**
-     * Invoke underlying canel method with error
-     *
-     * @param error error value to be injected from outside
-     */
-    reject: (error: any) => void;
-    /**
-     * Wrap task to singleton generator
-     *
-     * Userful in order to avoid ambiguous yied types
-     *
-     * @returns generator of task wrapping the task
-     * @example
-     * ```typescript
-     * const getString = () => Task.resolved('hello');
-     * const getLength = (data: string) => Task.resolved(data.length);
-     *
-     * // ..... //
-     *
-     * Task.generate(function* () {
-     *   const data = yield getString(); // data: string | number
-     *   const length = yield getLength(data); // length: string | number
-     *
-     *   return length;
-     * });
-     *
-     * // ..... //
-     *
-     * Task.generate(function* () {
-     *   const data = yield* getString().generator(); // data: string
-     *   const length = yield* getLength(data).generator(); // length: number
-     *
-     *   return length;
-     * });
-     * ```
-     */
-    generator: TaskGeneratorFunction<[], unknown, Task<R>, R>;
-}
-export declare namespace Task {
-    /**
-     * Custom task monad constructor
-     *
-     * @template R returned task's resolve type
-     * @param invoke promise defining task execution
-     * @param cancel cancelation function
-     * @returns task resolving to resolve value of invoke
-     *
-     * @note low-level primitive for creating custom tasks, not intended for general use
-     */
-    function create<R>(invoke: TaskInvoke<R>, cancel: TaskCancel): Task<R>;
-    /**
-     * Invariant task constructor creating resolved task from plain value
-     *
-     * @template R returned task's resolve type
-     * @param value value to be returned upon awaiting
-     * @returns task resolving to specified value
-     */
-    function resolved<R>(value: R): Task<R>;
-    /**
-     * Invariant task constructor creating rejected task from error value
-     *
-     * @template R returned task's resolve type
-     * @param error error to be returned upon awaiting
-     * @returns task resolving to specified value
-     */
-    function rejected<R>(error: any): Task<R>;
-    /**
-     * Invariant task constructor creating canceled task
-     *
-     * @template R returned task's resolve type
-     * @returns task resolving to specified value
-     */
-    function canceled<R>(): Task<R>;
-    /**
-     * Lift from promise to task resolving to that promise result
-     *
-     * Userfull for converting promises to tasks
-     * If converted task is canceled or failed externally return value will be ignored without side-effects
-     * All tasks are no-trowing by default, any occured errors are returned as Left<any>
-     *
-     * @template R returned task resolve type
-     * @param promise promise to be resolved
-     * @returns task resolving to specified promise value
-     *
-     * @example
-     * ```typescript
-     * const task = Task.fromPromise(someAsyncOperation('someData')).map((result) => result.length);
-     * ```
-     */
-    function fromPromise<R>(promise: PromiseLike<R>): Task<R>;
-    /**
-     * Lift from sync function to task resolving to said function result
-     *
-     * Generally, functions are not considered tasks as they cannot be interrupted in any way
-     * However there may be cases when impure function performs actions leading to cancelling or failing the task they are called from
-     * Without such wrapper such cases would lead to ignoring said cancelation and continuilg task chain
-     * This function is mostly used internally and is not expected to be widely used except of some edge scenarios
-     *
-     * If converted task is canceled or failed externally return value will be ignored without side-effects
-     * All tasks are no-trowing by default, any occured errors are returned as Left<any>
-     *
-     * @template R returned task resolve type
-     * @param producer function to be wrapped to a task
-     * @param cancelRef reference object allowing to set cancelation function prior to invoking function
-     * @returns task resolving to the specified function's result
-     *
-     * @example
-     * ```typescript
-     * const cancelRef = { cancel: () => {} };
-     *
-     * const task = Task.fromFunction(() => someFunction('someData'), cancelRef).map((result) => result.length);
-     * ```
-     */
-    function fromFunction<R>(producer: () => R, cancelRef: {
-        cancel: TaskCancel;
-    }): Task<R>;
-    /**
-     * Convinience shortcut for yielding async functions as tasks
-     *
-     * @template R returned generator resolve type
-     * @param promise promise to be resolved
-     * @returns generator to be be used with yield*
-     */
-    function promiseGenerator<R>(promise: PromiseLike<R>): TaskGenerator<unknown, Task<R>, R>;
-    /**
-     * Convinience shortcut for yielding timers
-     *
-     * @template R returned generator resolve type
-     * @param promise promise to be resolved
-     * @returns generator to be be used with yield*
-     */
-    function timeoutGenerator(delay: number): TaskGenerator<unknown, Task<void>, void>;
-    /**
-     * Lift from function returning value/promise to function returning task resolving to that value
-     *
-     * Userfull for converting exising async functions to task functions for further use
-     *
-     * @template A returned function's argument types
-     * @template R returned function's result task's resolve type
-     * @param promiseFunction function returning promise or plain value to be resolved
-     * @returns task function wrapping specified promise function
-     * @see Task.fromPromise
-     *
-     * @example
-     * ```typescript
-     * const taskFunction = liftPromiseFunction(someAsyncOperation);
-     *
-     * const task = taskFunction('someData').map((result) => result.length);
-     * ```
-     */
-    function lift<A extends unknown[], R>(promiseFunction: (...args: A) => PromiseLike<R>): TaskFunction<A, R>;
-    /**
-     * Create compound task from generator function
-     *
-     * Applying yield to task within the generator function awaits the task and returns underlying value in case of success
-     * However the convinient option for typescript is to use ```yield* task.generator()``` as othervise one may have to deal with union types
-     *
-     * In case of failure an error is thrown and may be caught by try-catch
-     *
-     * If error is not caught the task is interrupted and returns 'just left error' immediately. In case of cancelation the task is interrupted and returns 'nothing' immediately
-     *
-     * @template TT yielded task type
-     * @template R returned task resolve type
-     * @param taskGeneratorFunction task generator function
-     * @returns task resolving to generator's return type
-     *
-     * @note compound task execution is interrupted only at yield statements, so despite returning immediately any promise-based chains would continue running until the first yield
-     * @note due to type unpredictability you HAVE to use ```.generator()``` together with yield* to avoid type issues, despite the fact that task may be yielded directly
-     *
-     * @example
-     * ```typescript
-     * const task = Task.generate(function*() {
-     *   try {
-     *     const value1 = yield* delayedValueTask('data', 400).generator();
-     *
-     *     const value2 = yield* delayedValueTask(value1.length, 300).generator();
-     *
-     *     return value2;
-     *   } catch (e) {
-     *     return -1;
-     *   }
-     * });
-     * ```
-     */
-    function generate<T, TT extends Task<T>, R>(taskGeneratorFunction: TaskGeneratorFunction<[], T, TT, R>): Task<R>;
-    /**
-     * Task function generator
-     *
-     * Simplifies wrighting functions returning generated tasks
-     *
-     * @template Args generator arguments
-     * @template TT yielded task type
-     * @template R returned task resolve type
-     * @param taskGeneratorFunction function* (...args) task generator function
-     * @returns task resolving to generator's return type
-     */
-    function generateFunction<A extends any[], T, TT extends Task<T>, R>(taskGeneratorFunction: TaskGeneratorFunction<A, T, TT, R>): TaskFunction<A, R>;
-    /**
-     * Generic timeout task
-     *
-     * Usefull for creating delays in task chains or implementing limiting tasks
-     *
-     * @param delay duration in ms after that the task resolves to void
-     * @returns task resolving to void (undefined) after specified delay
-     *
-     * @example
-     * ```typescript
-     * const delayedValueTask = <T>(value: T, delay: number) => Task.timeout(delay).map(() => value);
-     * // ... //
-     * const value = yield* delayedValueTask(42, 1000).generator();
-     *
-     * console.log("It's past 1 second and here's a value:", value)
-     * ```
-     */
-    function timeout(delay: number): Task<void>;
-    /**
-     * Generic callback task
-     *
-     * Usefull for creating custom tasks from success and error callbacks and cancelaton function. Synchronous callbacks are not supported, @see fromFuction
-     *
-     * @param create task body with success and error callbacks
-     * @param cancel cancelation function intended for stopping task execution
-     * @returns task resolving to success value
-     *
-     * @example
-     * ```typescript
-     * export function timeout(delay: number) {
-     *   return fromCallback<NodeJS.Timeout, void>((resolve) => setTimeout(() => resolve(), delay), clearTimeout);
-     * }
-     * ```
-     */
-    function fromCallback<H, R>(create: (resolve: (result: R) => void, reject: (error: any) => void, cancel: () => void) => H, onCancel: (handler: H) => void): Task<R>;
-    /**
-     * Start multiple tasks one after another
-     *
-     * @param taskFunctions list of task functions (without arguments)
-     * @returns composite task invoring every task in order and resolving to the list of results
-     */
-    function sequence<T>(taskFunctions: Iterable<TaskFunction<[], T>>): Task<T[]>;
-    /**
-     * Execute all tasks in parallel and return list of results
-     *
-     * Resulting task resolves when all tasks are resolved, returning list of tasks results maintaining result order
-     * In case of failure (external or internal) resulting task is immediately immediately rejected with that error and all pending tasks are canceled
-     * In case of cancelation resulting task is immediately immediately canceled together with all pending tasks
-     *
-     * @note direct equivalent of Promise.all
-     *
-     * @template T underlying task type
-     * @param tasks iterable of tasks to execute
-     * @retuirns task resolving to the list of results
-     */
-    function all<T>(tasks: Iterable<Task<T>>): Task<T[]>;
-    /**
-     * Execute all tasks in parallel and return the result of the first successful one
-     *
-     * Resulting task resolves when the first tasks is successfuly resolved, returning it's result
-     * In case of external task rejecttion all tasks are rejected with that error and resulting task is rejected with an array of errors
-     * In case of internal task rejection the execution is continued untill fthe first task resolves succesfully or all the tasks are rejected this way resulting task is rejected with an array of errors
-     * In case of cancelation resulting task is immediately immediately canceled together with all pending tasks
-     *
-     * @note direct equivalent of Promise.any
-     *
-     * @template T underlying task type
-     * @param tasks iterable of tasks to execute
-     * @retuirns task resolving to the result of first successfull task
-     */
-    function any<T>(tasks: Iterable<Task<T>>): Task<T>;
-    /**
-     * Limit task execution based on another task
-     *
-     * If the second task resolves sooner than the first, resulting task is canceled
-     * Otherwise the resulting task resolves together with the first one
-     *
-     * @param task task to limit
-     * @param limitTask limiting task
-     * @returns task limites according to limitTask
-     */
-    function limit<T>(task: Task<T>, limitTask: Task<void>): Task<T>;
-    /**
-     * Repeat task untill successful
-     *
-     * Given task is re-generated in case of failure (both external and internal)
-     * Resulting task is still cancelable by standard means
-     *
-     * @param taskFunction task preoducing function
-     */
-    function repeat<T>(taskFunction: TaskFunction<[], T>): Task<T>;
-}
-type TaskInvoke<R> = Promise<Cancelable<R>>;
-type TaskCancel = (error: Maybe<any>) => void;
-/**
- * @hidden
- */
-interface TaskBase<R> {
-    /**
-     * @hidden
-     */
-    readonly _invoke: TaskInvoke<R>;
-    /**
-     * @hidden
-     */
-    readonly _cancel: TaskCancel;
-}
-export {};