@nlozgachev/pipelined 0.17.0 → 0.18.0

package/README.md

@@ -21,13 +21,13 @@ compose with `pipe` and `flow`.
 
 ### pipelined/core
 
-- **`Option<A>`** — a value that may not exist; propagates absence without null checks.
+- **`Maybe<A>`** — a value that may not exist; propagates absence without null checks.
 - **`Result<E, A>`** — an operation that succeeds or fails with a typed error.
 - **`Validation<E, A>`** — like `Result`, but accumulates every failure instead of stopping at the
   first.
 - **`Task<A>`** — a lazy, infallible async operation; nothing runs until called.
 - **`TaskResult<E, A>`** — a lazy async operation that can fail with a typed error.
-- **`TaskOption<A>`** — a lazy async operation that may produce nothing.
+- **`TaskMaybe<A>`** — a lazy async operation that may produce nothing.
 - **`TaskValidation<E, A>`** — a lazy async operation that accumulates validation errors.
 - **`These<E, A>`** — an inclusive OR: holds an error, a value, or both at once.
 - **`RemoteData<E, A>`** — the four states of a data fetch: `NotAsked`, `Loading`, `Failure`,
@@ -43,8 +43,8 @@ compose with `pipe` and `flow`.
 
 Everyday utilities for built-in JS types.
 
-- **`Arr`** — array utilities, data-last, returning `Option` instead of `undefined`.
-- **`Rec`** — record/object utilities, data-last, with `Option`-returning key lookup.
+- **`Arr`** — array utilities, data-last, returning `Maybe` instead of `undefined`.
+- **`Rec`** — record/object utilities, data-last, with `Maybe`-returning key lookup.
 - **`Num`** — number utilities: `range`, `clamp`, `between`, safe `parse`, and curried arithmetic.
 - **`Str`** — string utilities: `split`, `trim`, `words`, `lines`, and safe `parse.int` / `parse.float`.
 
@@ -61,25 +61,43 @@ Everyday utilities for built-in JS types.
 ## Example
 
 ```ts
-import { Option, Result } from "@nlozgachev/pipelined/core";
+import { TaskResult } from "@nlozgachev/pipelined/core";
 import { pipe } from "@nlozgachev/pipelined/composition";
 
-// Chain nullable lookups without nested null checks
-const city = pipe(
-  getUser(userId), // User | null
-  Option.fromNullable, // Option<User>
-  Option.chain((u) => Option.fromNullable(u.address)), // Option<Address>
-  Option.chain((a) => Option.fromNullable(a.city)), // Option<string>
-  Option.map((c) => c.toUpperCase()), // Option<string>
-  Option.getOrElse("UNKNOWN"), // string
-);
-
-// Parse input and look up a record — both steps can fail
-const record = pipe(
-  parseId(rawInput), // Result<ParseError, number>
-  Result.chain((id) => db.find(id)), // Result<ParseError | NotFoundError, Record>
-  Result.map((r) => r.name), // Result<ParseError | NotFoundError, string>
-);
+// Typed errors. Lazy. Composable.
+const getUser = (id: string): TaskResult<string, User> =>
+  pipe(
+    TaskResult.tryCatch(
+      () => fetch(`/users/${id}`).then((r) => r.json() as Promise<User>),
+      (e) => `fetch failed: ${e}`,
+    ),
+    TaskResult.timeout(5_000, () => "request timed out"),
+    TaskResult.retry({ attempts: 3, backoff: (n) => n * 1_000 }),
+  );
+
+// Poll until a background job finishes — stop immediately on failure
+const waitForExport = (jobId: string): TaskResult<string, ExportResult> =>
+  pipe(
+    TaskResult.tryCatch(
+      () => fetch(`/exports/${jobId}`).then((r) => r.json() as Promise<Job>),
+      String,
+    ),
+    TaskResult.pollUntil({
+      when: (job) => job.status === "done",
+      delay: (n) => n * 500,  // 500 ms, 1 s, 1.5 s, ...
+    }),
+    TaskResult.map((job) => job.result),
+  );
+
+// Compose the two — nothing runs until the final call
+const message = await pipe(
+  getUser("abc"),
+  TaskResult.chain((user) => waitForExport(user.exportId)),
+  TaskResult.match({
+    ok:  (r) => `Export ready: ${r.url}`,
+    err: (e) => `Failed: ${e}`,
+  }),
+)();
 ```
 
 ## Documentation

package/dist/{Task-Bd3gXPRQ.d.mts → Task-DBW4nOZR.d.mts}

@@ -224,16 +224,16 @@ declare namespace Result {
      */
     const recoverUnless: <E, A, B>(blockedErr: E, fallback: () => Result<E, B>) => (data: Result<E, A>) => Result<E, A | B>;
     /**
-     * Converts a Result to an Option.
+     * Converts a Result to an Maybe.
      * Ok becomes Some, Err becomes None (the error is discarded).
      *
      * @example
      * ```ts
-     * Result.toOption(Result.ok(42)); // Some(42)
-     * Result.toOption(Result.err("oops")); // None
+     * Result.toMaybe(Result.ok(42)); // Some(42)
+     * Result.toMaybe(Result.err("oops")); // None
      * ```
      */
-    const toOption: <E, A>(data: Result<E, A>) => Option<A>;
+    const toMaybe: <E, A>(data: Result<E, A>) => Maybe<A>;
     /**
      * Applies a function wrapped in an Result to a value wrapped in an Result.
      *
@@ -253,141 +253,141 @@ declare namespace Result {
 type Some<A> = WithKind<"Some"> & WithValue<A>;
 type None = WithKind<"None">;
 /**
- * Option represents an optional value: every Option is either Some (contains a value) or None (empty).
- * Use Option instead of null/undefined to make optionality explicit and composable.
+ * Maybe represents an optional value: every Maybe is either Some (contains a value) or None (empty).
+ * Use Maybe instead of null/undefined to make optionality explicit and composable.
  *
  * @example
  * ```ts
- * const findUser = (id: string): Option<User> =>
- *   users.has(id) ? Option.some(users.get(id)!) : Option.none();
+ * const findUser = (id: string): Maybe<User> =>
+ *   users.has(id) ? Maybe.some(users.get(id)!) : Maybe.none();
  *
  * pipe(
  *   findUser("123"),
- *   Option.map(user => user.name),
- *   Option.getOrElse(() => "Unknown")
+ *   Maybe.map(user => user.name),
+ *   Maybe.getOrElse(() => "Unknown")
  * );
  * ```
  */
-type Option<T> = Some<T> | None;
-declare namespace Option {
+type Maybe<T> = Some<T> | None;
+declare namespace Maybe {
     /**
      * Creates a Some containing the given value.
      */
     const some: <A>(value: A) => Some<A>;
     /**
-     * Type guard that checks if a Option is Some.
+     * Type guard that checks if a Maybe is Some.
      */
-    const isSome: <A>(data: Option<A>) => data is Some<A>;
+    const isSome: <A>(data: Maybe<A>) => data is Some<A>;
     /**
-     * Creates a None (empty Option).
+     * Creates a None (empty Maybe).
      */
     const none: () => None;
     /**
-     * Type guard that checks if a Option is None.
+     * Type guard that checks if a Maybe is None.
      */
-    const isNone: <A>(data: Option<A>) => data is None;
+    const isNone: <A>(data: Maybe<A>) => data is None;
     /**
-     * Creates a Option from a nullable value.
+     * Creates a Maybe from a nullable value.
      * Returns None if the value is null or undefined, Some otherwise.
      *
      * @example
      * ```ts
-     * Option.fromNullable(null); // None
-     * Option.fromNullable(42); // Some(42)
+     * Maybe.fromNullable(null); // None
+     * Maybe.fromNullable(42); // Some(42)
      * ```
      */
-    const fromNullable: <A>(value: A | null | undefined) => Option<A>;
+    const fromNullable: <A>(value: A | null | undefined) => Maybe<A>;
     /**
-     * Extracts the value from a Option, returning null if None.
+     * Extracts the value from a Maybe, returning null if None.
      */
-    const toNullable: <A>(data: Option<A>) => A | null;
+    const toNullable: <A>(data: Maybe<A>) => A | null;
     /**
-     * Extracts the value from a Option, returning undefined if None.
+     * Extracts the value from a Maybe, returning undefined if None.
      */
-    const toUndefined: <A>(data: Option<A>) => A | undefined;
+    const toUndefined: <A>(data: Maybe<A>) => A | undefined;
     /**
-     * Creates a Option from a possibly undefined value.
+     * Creates a Maybe from a possibly undefined value.
      * Returns None if undefined, Some otherwise.
      */
-    const fromUndefined: <A>(value: A | undefined) => Option<A>;
+    const fromUndefined: <A>(value: A | undefined) => Maybe<A>;
     /**
-     * Converts an Option to a Result.
+     * Converts an Maybe to a Result.
      * Some becomes Ok, None becomes Err with the provided error.
      *
      * @example
      * ```ts
      * pipe(
-     *   Option.some(42),
-     *   Option.toResult(() => "Value was missing")
+     *   Maybe.some(42),
+     *   Maybe.toResult(() => "Value was missing")
      * ); // Ok(42)
      *
      * pipe(
-     *   Option.none(),
-     *   Option.toResult(() => "Value was missing")
+     *   Maybe.none(),
+     *   Maybe.toResult(() => "Value was missing")
      * ); // Err("Value was missing")
      * ```
      */
-    const toResult: <E>(onNone: () => E) => <A>(data: Option<A>) => Result<E, A>;
+    const toResult: <E>(onNone: () => E) => <A>(data: Maybe<A>) => Result<E, A>;
     /**
-     * Creates an Option from a Result.
+     * Creates an Maybe from a Result.
      * Ok becomes Some, Err becomes None (the error is discarded).
      *
      * @example
      * ```ts
-     * Option.fromResult(Result.ok(42)); // Some(42)
-     * Option.fromResult(Result.err("oops")); // None
+     * Maybe.fromResult(Result.ok(42)); // Some(42)
+     * Maybe.fromResult(Result.err("oops")); // None
      * ```
      */
-    const fromResult: <E, A>(data: Result<E, A>) => Option<A>;
+    const fromResult: <E, A>(data: Result<E, A>) => Maybe<A>;
     /**
-     * Transforms the value inside a Option if it exists.
+     * Transforms the value inside a Maybe if it exists.
      *
      * @example
      * ```ts
-     * pipe(Option.some(5), Option.map(n => n * 2)); // Some(10)
-     * pipe(Option.none(), Option.map(n => n * 2)); // None
+     * pipe(Maybe.some(5), Maybe.map(n => n * 2)); // Some(10)
+     * pipe(Maybe.none(), Maybe.map(n => n * 2)); // None
      * ```
      */
-    const map: <A, B>(f: (a: A) => B) => (data: Option<A>) => Option<B>;
+    const map: <A, B>(f: (a: A) => B) => (data: Maybe<A>) => Maybe<B>;
     /**
-     * Chains Option computations. If the first is Some, passes the value to f.
+     * Chains Maybe computations. If the first is Some, passes the value to f.
      * If the first is None, propagates None.
      *
      * @example
      * ```ts
-     * const parseNumber = (s: string): Option<number> => {
+     * const parseNumber = (s: string): Maybe<number> => {
      *   const n = parseInt(s, 10);
-     *   return isNaN(n) ? Option.none() : Option.some(n);
+     *   return isNaN(n) ? Maybe.none() : Maybe.some(n);
      * };
      *
-     * pipe(Option.some("42"), Option.chain(parseNumber)); // Some(42)
-     * pipe(Option.some("abc"), Option.chain(parseNumber)); // None
+     * pipe(Maybe.some("42"), Maybe.chain(parseNumber)); // Some(42)
+     * pipe(Maybe.some("abc"), Maybe.chain(parseNumber)); // None
      * ```
      */
-    const chain: <A, B>(f: (a: A) => Option<B>) => (data: Option<A>) => Option<B>;
+    const chain: <A, B>(f: (a: A) => Maybe<B>) => (data: Maybe<A>) => Maybe<B>;
     /**
-     * Extracts the value from a Option by providing handlers for both cases.
+     * Extracts the value from a Maybe by providing handlers for both cases.
      *
      * @example
      * ```ts
      * pipe(
-     *   Option.some(5),
-     *   Option.fold(
+     *   Maybe.some(5),
+     *   Maybe.fold(
      *     () => "No value",
      *     n => `Value: ${n}`
      *   )
      * ); // "Value: 5"
      * ```
      */
-    const fold: <A, B>(onNone: () => B, onSome: (a: A) => B) => (data: Option<A>) => B;
+    const fold: <A, B>(onNone: () => B, onSome: (a: A) => B) => (data: Maybe<A>) => B;
     /**
-     * Pattern matches on a Option, returning the result of the matching case.
+     * Pattern matches on a Maybe, returning the result of the matching case.
      *
      * @example
      * ```ts
      * pipe(
      *   optionUser,
-     *   Option.match({
+     *   Maybe.match({
      *     some: user => `Hello, ${user.name}`,
      *     none: () => "Hello, stranger"
      *   })
@@ -397,64 +397,64 @@ declare namespace Option {
     const match: <A, B>(cases: {
         none: () => B;
         some: (a: A) => B;
-    }) => (data: Option<A>) => B;
+    }) => (data: Maybe<A>) => B;
     /**
-     * Returns the value inside an Option, or a default value if None.
-     * The default is a thunk `() => B` — evaluated only when the Option is None.
+     * Returns the value inside an Maybe, or a default value if None.
+     * The default is a thunk `() => B` — evaluated only when the Maybe is None.
      * The default can be a different type, widening the result to `A | B`.
      *
      * @example
      * ```ts
-     * pipe(Option.some(5), Option.getOrElse(() => 0)); // 5
-     * pipe(Option.none(), Option.getOrElse(() => 0)); // 0
-     * pipe(Option.none<string>(), Option.getOrElse(() => null)); // null — typed as string | null
+     * pipe(Maybe.some(5), Maybe.getOrElse(() => 0)); // 5
+     * pipe(Maybe.none(), Maybe.getOrElse(() => 0)); // 0
+     * pipe(Maybe.none<string>(), Maybe.getOrElse(() => null)); // null — typed as string | null
      * ```
      */
-    const getOrElse: <A, B>(defaultValue: () => B) => (data: Option<A>) => A | B;
+    const getOrElse: <A, B>(defaultValue: () => B) => (data: Maybe<A>) => A | B;
     /**
-     * Executes a side effect on the value without changing the Option.
+     * Executes a side effect on the value without changing the Maybe.
      * Useful for logging or debugging.
      *
      * @example
      * ```ts
      * pipe(
-     *   Option.some(5),
-     *   Option.tap(n => console.log("Value:", n)),
-     *   Option.map(n => n * 2)
+     *   Maybe.some(5),
+     *   Maybe.tap(n => console.log("Value:", n)),
+     *   Maybe.map(n => n * 2)
      * );
      * ```
      */
-    const tap: <A>(f: (a: A) => void) => (data: Option<A>) => Option<A>;
+    const tap: <A>(f: (a: A) => void) => (data: Maybe<A>) => Maybe<A>;
     /**
-     * Filters a Option based on a predicate.
-     * Returns None if the predicate returns false or if the Option is already None.
+     * Filters a Maybe based on a predicate.
+     * Returns None if the predicate returns false or if the Maybe is already None.
      *
      * @example
      * ```ts
-     * pipe(Option.some(5), Option.filter(n => n > 3)); // Some(5)
-     * pipe(Option.some(2), Option.filter(n => n > 3)); // None
+     * pipe(Maybe.some(5), Maybe.filter(n => n > 3)); // Some(5)
+     * pipe(Maybe.some(2), Maybe.filter(n => n > 3)); // None
      * ```
      */
-    const filter: <A>(predicate: (a: A) => boolean) => (data: Option<A>) => Option<A>;
+    const filter: <A>(predicate: (a: A) => boolean) => (data: Maybe<A>) => Maybe<A>;
     /**
-     * Recovers from a None by providing a fallback Option.
-     * The fallback can produce a different type, widening the result to `Option<A | B>`.
+     * Recovers from a None by providing a fallback Maybe.
+     * The fallback can produce a different type, widening the result to `Maybe<A | B>`.
      */
-    const recover: <A, B>(fallback: () => Option<B>) => (data: Option<A>) => Option<A | B>;
+    const recover: <A, B>(fallback: () => Maybe<B>) => (data: Maybe<A>) => Maybe<A | B>;
     /**
-     * Applies a function wrapped in a Option to a value wrapped in a Option.
+     * Applies a function wrapped in a Maybe to a value wrapped in a Maybe.
      *
      * @example
      * ```ts
      * const add = (a: number) => (b: number) => a + b;
      * pipe(
-     *   Option.some(add),
-     *   Option.ap(Option.some(5)),
-     *   Option.ap(Option.some(3))
+     *   Maybe.some(add),
+     *   Maybe.ap(Maybe.some(5)),
+     *   Maybe.ap(Maybe.some(3))
      * ); // Some(8)
      * ```
      */
-    const ap: <A>(arg: Option<A>) => <B>(data: Option<(a: A) => B>) => Option<B>;
+    const ap: <A>(arg: Maybe<A>) => <B>(data: Maybe<(a: A) => B>) => Maybe<B>;
 }
 
 /**
@@ -674,4 +674,4 @@ declare namespace Task {
     const timeout: <E>(ms: number, onTimeout: () => E) => <A>(task: Task<A>) => Task<Result<E, A>>;
 }
 
-export { Deferred as D, type Err as E, type None as N, type Ok as O, Result as R, type Some as S, Task as T, type WithValue as W, Option as a, type WithLog as b, type WithKind as c, type WithError as d, type WithErrors as e, type WithFirst as f, type WithSecond as g };
+export { Deferred as D, type Err as E, Maybe as M, type None as N, type Ok as O, Result as R, type Some as S, Task as T, type WithValue as W, type WithLog as a, type WithKind as b, type WithError as c, type WithErrors as d, type WithFirst as e, type WithSecond as f };