t-tasks 2.0.0 → 2.1.0

package/dist/t-tasks.d.ts

@@ -60,6 +60,7 @@ export interface Just<R> {
    * Applied to 'just value' returns self without invoking transformer
    * Applied to 'nothing' returns 'just op()'
    *
+   * @template R2 transformer function's return type
    * @param op function to be invoked
    * @returns 'just value' or 'just op()'
    */
@@ -85,6 +86,18 @@ export interface Just<R> {
     just: (value: R) => R2;
     nothing: () => R3;
   }): R2 | R3;
+  /**
+   * Maybe pattern matching transformer function
+   *
+   * Applied to 'just value' returns 'just op.just(value)'
+   * Applied to 'nothing' returns 'just op.nothing()'
+   *
+   * @template R2 just transformer function's return type
+   * @template R3 nothing transformer function's return type
+   * @param op.just transformer to be invoked with underlying value in case of just
+   * @param op.nothing transformer to be invoked in case of nothing
+   * @returns 'just op.just(value)' or 'just op.nothing()'
+   */
   matchMap<R2, R3 = R2>(this: Just<R>, op: {
     just: (value: R) => R2;
     nothing: () => R3;
@@ -248,6 +261,8 @@ export interface Just<R> {
  * Absolutely Nothing
  *
  * Maybe data type specialization representing an absence of any value
+ *
+ * @template R underlying value
  */
 export interface Nothing<R> {
   /**
@@ -302,6 +317,7 @@ export interface Nothing<R> {
    * Applied to 'just value' returns self without invoking transformer
    * Applied to 'nothing' returns 'just op()'
    *
+   * @template R2 transformer function's return type
    * @param op function to be invoked
    * @returns 'just value' or 'just op()'
    */
@@ -327,6 +343,18 @@ export interface Nothing<R> {
     just: (value: R) => R2;
     nothing: () => R3;
   }): R2 | R3;
+  /**
+   * Maybe pattern matching transformer function
+   *
+   * Applied to 'just value' returns 'just op.just(value)'
+   * Applied to 'nothing' returns 'just op.nothing()'
+   *
+   * @template R2 just transformer function's return type
+   * @template R3 nothing transformer function's return type
+   * @param op.just transformer to be invoked with underlying value in case of just
+   * @param op.nothing transformer to be invoked in case of nothing
+   * @returns 'just op.just(value)' or 'just op.nothing()'
+   */
   matchMap<R2, R3 = R2>(this: Nothing<R>, op: {
     just: (value: R) => R2;
     nothing: () => R3;
@@ -508,7 +536,22 @@ export declare namespace Just {
   function just<R>(just: Just<R>): R;
 }
 export declare namespace Nothing {}
+/**
+ * Maybe generator
+ *
+ * @template T yielded underlying type
+ * @template TT yielded Maybe type
+ * @template R returned underlying type
+ */
 export type MaybeGenerator<T, TT extends Maybe<T>, R> = Generator<TT, R, T>;
+/**
+ * Function returning Maybe generator (generator function)
+ *
+ * @template A argument types
+ * @template T yielded underlying type
+ * @template TT yielded Maybe type
+ * @template R returned underlying type
+ */
 export type MaybeGeneratorFunction<A extends unknown[], T, TT extends Maybe<T>, R> = (...args: A) => MaybeGenerator<T, TT, R>;
 export declare namespace Maybe {
   /**
@@ -530,6 +573,7 @@ export declare namespace Maybe {
    *
    * Resolves to 'nothing' in case of undefined value and 'just value' otherwise
    *
+   * @template R underlying type
    * @param value possibly undefined value
    * @returns either 'just value' or 'nothing'
    */
@@ -541,7 +585,8 @@ export declare namespace Maybe {
    *
    * Resolves to 'nothing' in case of undefined or null value and 'just value' otherwise
    *
-   * @param value possibly undefined value
+   * @template R underlying type
+   * @param value possibly undefined or null value
    * @returns either 'just value' or 'nothing'
    */
   function fromNullable(value: undefined): Nothing<never>;
@@ -586,6 +631,7 @@ export declare namespace Maybe {
   /**
    * Standalone list predicate
    *
+   * @template R underlying value type
    * @param maybes a list of Maybe
    * @returns true in case every list element is Just
    */
@@ -593,6 +639,7 @@ export declare namespace Maybe {
   /**
    * Standalone list predicate
    *
+   * @template R underlying value type
    * @param maybes a list of Maybe
    * @returns true in case at least one list element is Just
    */
@@ -600,6 +647,7 @@ export declare namespace Maybe {
   /**
    * Standalone list predicate
    *
+   * @template R underlying value type
    * @param maybes a list of Maybe
    * @returns true in case every list element is Nothing
    */
@@ -607,6 +655,7 @@ export declare namespace Maybe {
   /**
    * Standalone list predicate
    *
+   * @template R underlying value type
    * @param maybes a list of Maybe
    * @returns true in case at least one list element is Nothing
    */
@@ -617,6 +666,7 @@ export declare namespace Maybe {
    * Applying yield to a Maybe within the generator function unwraps the Maybe and returns underlying value in case of success
    * However the convenient option for typescript is to use ```yield* maybe.generator()``` as otherwise one may have to deal with union types
    *
+   * @template T yielded underlying type
    * @template TT yielded Maybe type
    * @template R returned underlying type
    * @param maybeGeneratorFunction Maybe generator function
@@ -688,6 +738,7 @@ export interface Right<R, L> {
    * Applied to 'right value' returns self without invoking transformer
    * Applied to 'left error' returns 'right op(error)'
    *
+   * @template R2 transformer function's return type
    * @param op transformer to be invoked with underlying error
    * @returns 'right value' or 'right op(error)'
    */
@@ -713,6 +764,18 @@ export interface Right<R, L> {
     right: (value: R) => R2;
     left: (error: L) => R3;
   }): R2 | R3;
+  /**
+   * Either pattern matching transformer function
+   *
+   * Applied to 'right value' returns 'right op.right(value)'
+   * Applied to 'left error' returns 'right op.left(error)'
+   *
+   * @template R2 right transformer function's return type
+   * @template R3 left transformer function's return type
+   * @param op.right transformer to be invoked with underlying value in case of 'right'
+   * @param op.left transformer to be invoked with underlying error in case of 'left'
+   * @returns 'right op.right(value)' or 'right op.left(error)'
+   */
   matchMap<R2, R3 = R2>(this: Right<R, L>, op: {
     right: (value: R) => R2;
     left: (error: L) => R3;
@@ -739,7 +802,7 @@ export interface Right<R, L> {
   chain<R2, L2>(this: Either<R, L>, op: (value: R) => Left<R2, L2>): Left<never, L | L2>;
   chain<R2, L2>(this: Either<R, L>, op: (value: R) => Either<R2, L2>): Either<R2, L | L2>;
   /**
-   * Either composition function
+   * Either fallback composition function
    *
    * Applied to 'right value' returns self without invoking composition function
    * Applied to 'left error' returns 'op(error)'
@@ -767,7 +830,7 @@ export interface Right<R, L> {
    * @template L3 left transformer function result's underlying error type
    * @param op.right transformer to be invoked with underlying value in case of 'right'
    * @param op.left transformer to be invoked with underlying error in case of 'left'
-   * @returns 'op(value)' or 'op(error)'
+   * @returns 'op.right(value)' or 'op.left(error)'
    */
   matchChain<R2, L2, R3 = R2, L3 = L2>(this: Right<R, L>, op: {
     right: (value: R) => Right<R2, L2>;
@@ -938,6 +1001,7 @@ export interface Left<R, L> {
    * Applied to 'right value' returns self without invoking transformer
    * Applied to 'left error' returns 'right op(error)'
    *
+   * @template R2 transformer function's return type
    * @param op transformer to be invoked with underlying error
    * @returns 'right value' or 'right op(error)'
    */
@@ -963,6 +1027,18 @@ export interface Left<R, L> {
     right: (value: R) => R2;
     left: (error: L) => R3;
   }): R2 | R3;
+  /**
+   * Either pattern matching transformer function
+   *
+   * Applied to 'right value' returns 'right op.right(value)'
+   * Applied to 'left error' returns 'right op.left(error)'
+   *
+   * @template R2 right transformer function's return type
+   * @template R3 left transformer function's return type
+   * @param op.right transformer to be invoked with underlying value in case of 'right'
+   * @param op.left transformer to be invoked with underlying error in case of 'left'
+   * @returns 'right op.right(value)' or 'right op.left(error)'
+   */
   matchMap<R2, R3 = R2>(this: Left<R, L>, op: {
     right: (value: R) => R2;
     left: (error: L) => R3;
@@ -1017,7 +1093,7 @@ export interface Left<R, L> {
    * @template L3 left transformer function result's underlying error type
    * @param op.right transformer to be invoked with underlying value in case of 'right'
    * @param op.left transformer to be invoked with underlying error in case of 'left'
-   * @returns 'op(value)' or 'op(error)'
+   * @returns 'op.right(value)' or 'op.left(error)'
    */
   matchChain<R2, L2, R3 = R2, L3 = L2>(this: Left<R, L>, op: {
     right: (value: R) => Right<R2, L2>;
@@ -1162,7 +1238,22 @@ export declare namespace Left {
    */
   function left<R, L>(left: Left<R, L>): L;
 }
+/**
+ * Either generator
+ *
+ * @template T yielded underlying type
+ * @template TT yielded Either type
+ * @template R returned underlying type
+ */
 export type EitherGenerator<T, TT extends Either<T, any>, R> = Generator<TT, R, T>;
+/**
+ * Function returning Either generator (generator function)
+ *
+ * @template A argument types
+ * @template T yielded underlying type
+ * @template TT yielded Either type
+ * @template R returned underlying type
+ */
 export type EitherGeneratorFunction<A extends unknown[], T, TT extends Either<T, any>, R> = (...args: A) => EitherGenerator<T, TT, R>;
 export declare namespace Either {
   /**
@@ -1186,6 +1277,8 @@ export declare namespace Either {
    *
    * Resolves to 'left error' in case of undefined value and 'right value' otherwise
    *
+   * @template R underlying value type
+   * @template L underlying error type
    * @param value possibly undefined value
    * @param error error to use in case of undefined value
    * @returns either 'right value' or 'left error'
@@ -1198,8 +1291,10 @@ export declare namespace Either {
    *
    * Resolves to 'left error' in case of undefined or null value and 'right value' otherwise
    *
-   * @param value possibly undefined or nullable value
-   * @param error error to use in case of undefined or nullable value
+   * @template R underlying value type
+   * @template L underlying error type
+   * @param value possibly undefined or null value
+   * @param error error to use in case of undefined or null value
    * @returns either 'right value' or 'left error'
    */
   function fromNullable<L>(value: undefined, error: L): Left<never, L>;
@@ -1228,6 +1323,7 @@ export declare namespace Either {
    * Useful for passing as a predicate to collection transformers
    *
    * @template R underlying value type
+   * @template L underlying error type
    * @param either Either instance
    * @returns 'true' in case argument is 'right value' (and resolves type to be 'right')
    */
@@ -1238,6 +1334,7 @@ export declare namespace Either {
    * Useful for passing as a predicate to collection transformers
    *
    * @template R underlying value type
+   * @template L underlying error type
    * @param either Either instance
    * @returns 'true' in case argument is 'left error' (and resolves type to be 'left')
    */
@@ -1245,6 +1342,8 @@ export declare namespace Either {
   /**
    * Standalone list predicate
    *
+   * @template R underlying value type
+   * @template L underlying error type
    * @param eithers a list of Either
    * @returns true in case every list element is Right
    */
@@ -1252,6 +1351,8 @@ export declare namespace Either {
   /**
    * Standalone list predicate
    *
+   * @template R underlying value type
+   * @template L underlying error type
    * @param eithers a list of Either
    * @returns true in case at least one list element is Right
    */
@@ -1259,6 +1360,8 @@ export declare namespace Either {
   /**
    * Standalone list predicate
    *
+   * @template R underlying value type
+   * @template L underlying error type
    * @param eithers a list of Either
    * @returns true in case every list element is Left
    */
@@ -1266,6 +1369,8 @@ export declare namespace Either {
   /**
    * Standalone list predicate
    *
+   * @template R underlying value type
+   * @template L underlying error type
    * @param eithers a list of Either
    * @returns true in case at least one list element is Left
    */
@@ -1276,6 +1381,7 @@ export declare namespace Either {
    * Applying yield to an Either within the generator function unwraps the Either and returns underlying value in case of success
    * However the convenient option for typescript is to use ```yield* either.generator()``` as otherwise one may have to deal with union types
    *
+   * @template T yielded underlying type
    * @template TT yielded Either type
    * @template R returned underlying type
    * @param eitherGeneratorFunction Either generator function
@@ -1307,6 +1413,7 @@ export type TaskFunction<A extends unknown[], R> = (...args: A) => Task<R>;
 /**
  * Task generator
  *
+ * @template T yielded underlying type
  * @template TT yielded task type
  * @template R returned task resolve type
  *
@@ -1324,6 +1431,7 @@ export type TaskGenerator<T, TT extends Task<T>, R> = Generator<TT, R, T>;
  * Function returning task generator (generator function)
  *
  * @template A argument types
+ * @template T yielded underlying type
  * @template TT yielded task type
  * @template R returned task resolve type
  *
@@ -1457,6 +1565,11 @@ export interface Task<R> extends TaskBase<R> {
     rejected: (error: any) => Task<R3>;
     canceled: () => Task<R4>;
   }): Task<R2 | R3 | R4>;
+  /**
+   * Read the settled result when the task has already finished
+   *
+   * @returns settled result, or null when the task is still pending
+   */
   resolved: () => Cancelable<R> | null;
   /**
    * Return underlying promise in order to await result
@@ -1465,13 +1578,16 @@ export interface Task<R> extends TaskBase<R> {
    */
   resolve: () => TaskInvoke<R>;
   /**
-   * Invoke underlying canel method without error
+   * Invoke underlying cancel method without error
+   *
+   * @returns 'true' when the task was still pending and cancelation was applied
    */
   cancel: () => boolean;
   /**
-   * Invoke underlying canel method with error
+   * Invoke underlying cancel method with error
    *
    * @param error error value to be injected from outside
+   * @returns 'true' when the task was still pending and the error was applied
    */
   reject: (error: any) => boolean;
   /**
@@ -1531,14 +1647,14 @@ export declare namespace Task {
    *
    * @template R returned task's resolve type
    * @param error error to be returned upon awaiting
-   * @returns task resolving to specified value
+   * @returns task rejected with the specified error
    */
   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
+   * @returns canceled task
    */
   function canceled<R>(): Task<R>;
   /**
@@ -1587,10 +1703,12 @@ export declare namespace Task {
   /**
    * Generic callback task
    *
-   * Usefull for creating custom tasks from success and error callbacks and cancelaton function. Synchronous callbacks are not supported, @see fromFuction
+   * Usefull for creating custom tasks from success and error callbacks and cancelaton function. Synchronous callbacks are not supported, @see fromFunction
    *
+   * @template H cancelation handler type
+   * @template R returned task resolve type
    * @param create task body with success and error callbacks
-   * @param cancel cancelation function intended for stopping task execution
+   * @param onCancel cancelation function intended for stopping task execution
    * @returns task resolving to success value
    *
    * @example
@@ -1632,9 +1750,8 @@ export declare namespace Task {
   /**
    * 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*
+   * @param delay duration in ms after that the generator resolves
+   * @returns generator to be used with yield*
    */
   function timeoutGenerator(delay: number): TaskGenerator<unknown, Task<void>, void>;
   /**
@@ -1666,6 +1783,7 @@ export declare namespace Task {
    *
    * 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 T yielded underlying type
    * @template TT yielded task type
    * @template R returned task resolve type
    * @param taskGeneratorFunction task generator function
@@ -1695,11 +1813,12 @@ export declare namespace Task {
    *
    * Simplifies wrighting functions returning generated tasks
    *
-   * @template Args generator arguments
+   * @template A generator arguments
+   * @template T yielded underlying type
    * @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
+   * @returns task function 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>;
   /**
@@ -1723,6 +1842,7 @@ export declare namespace Task {
   /**
    * Start multiple tasks one after another
    *
+   * @template T underlying task type
    * @param taskFunctions list of task functions (without arguments)
    * @returns composite task invoring every task in order and resolving to the list of results
    */
@@ -1738,7 +1858,7 @@ export declare namespace Task {
    *
    * @template T underlying task type
    * @param tasks iterable of tasks to execute
-   * @retuirns task resolving to the list of results
+   * @returns task resolving to the list of results
    */
   function all<T>(tasks: Iterable<Task<T>>): Task<T[]>;
   /**
@@ -1753,7 +1873,7 @@ export declare namespace Task {
    *
    * @template T underlying task type
    * @param tasks iterable of tasks to execute
-   * @retuirns task resolving to the result of first successfull task
+   * @returns task resolving to the result of first successfull task
    */
   function any<T>(tasks: Iterable<Task<T>>): Task<unknown>;
   /**
@@ -1762,6 +1882,7 @@ export declare namespace Task {
    * If the second task resolves sooner than the first, resulting task is canceled
    * Otherwise the resulting task resolves together with the first one
    *
+   * @template T underlying task type
    * @param task task to limit
    * @param limitTask limiting task
    * @returns task limites according to limitTask
@@ -1773,7 +1894,9 @@ export declare namespace Task {
    * Given task is re-generated in case of failure (both external and internal)
    * Resulting task is still cancelable by standard means
    *
+   * @template T underlying task type
    * @param taskFunction task preoducing function
+   * @returns task that retries until the produced task resolves
    */
   function repeat<T>(taskFunction: TaskFunction<[], T>): Task<T>;
 }

package/dist/t-tasks.esm.js

@@ -612,29 +612,52 @@ function chainTaskMaybe(parent, op) {
 		else return false;
 	});
 }
-function chainTaskEither(_task, op) {
-	return chainTaskMaybe(_task, (maybe) => maybe.map(op).orMap(Task.canceled).just);
+function mapTaskMaybe(parent, op) {
+	const cell = settleCell();
+	let state = { phase: "parent" };
+	parent._invoke((result) => {
+		state = {
+			phase: "transform",
+			error: null
+		};
+		let value = null;
+		try {
+			value = op(result);
+		} catch (e) {
+			cell.resolve(Maybe.just(Either.left(e)));
+			state = { phase: "closed" };
+			return;
+		}
+		const transformError = state.phase === "transform" ? state.error : null;
+		if (transformError) cell.resolve(transformError.map(Either.left));
+		else cell.resolve(value);
+		state = { phase: "closed" };
+	});
+	return Task.create(cell.promise, (error) => {
+		if (cell.settled()) return false;
+		if (state.phase === "parent") return parent._cancel(error);
+		else if (state.phase === "transform") {
+			state.error = error;
+			return true;
+		} else return false;
+	});
 }
-function mapTaskMaybe(_task, op) {
-	return chainTaskMaybe(_task, (maybe) => {
-		return op(maybe).match({
-			just: (either) => either.match({
-				right: Task.resolved,
-				left: Task.rejected
-			}),
-			nothing: Task.canceled
-		});
+function tapTaskMaybe(parent, op) {
+	parent._invoke((result) => {
+		try {
+			op(result);
+		} catch (e) {
+			reportError(e);
+		}
 	});
+	return parent;
+}
+function chainTaskEither(_task, op) {
+	return chainTaskMaybe(_task, (maybe) => maybe.map(op).orMap(Task.canceled).just);
 }
 function mapTaskEither(_task, op) {
 	return mapTaskMaybe(_task, (maybe) => maybe.map(op));
 }
-function tapTaskMaybe(_task, op) {
-	return mapTaskMaybe(_task, (value) => {
-		op(value);
-		return value;
-	});
-}
 function tapTaskEither(_task, op) {
 	return tapTaskMaybe(_task, (maybe) => maybe.tap(op));
 }
@@ -746,6 +769,9 @@ var TaskClass = class {
 		});
 	}
 };
+function reportError(error) {
+	if (typeof globalThis.reportError === "function") globalThis.reportError(error);
+}
 //#endregion
 export { Either, Just, Left, Maybe, Right, Task };