slang-ts 0.0.7 → 0.0.9

package/dist/index.d.ts

@@ -1,5 +1,658 @@
+//#region src/result.d.ts
+declare const __result__: unique symbol;
+export type Ok<T> = {
+  type: "Ok";
+  value: T;
+  readonly isOk: true;
+  readonly isErr: false;
+  readonly [__result__]: true;
+};
+export type Err<E> = {
+  type: "Err";
+  error: E;
+  readonly isOk: false;
+  readonly isErr: true;
+  readonly [__result__]: true;
+};
+/** Discriminated union: mutually exclusive Ok or Err */
+type Result<T, E> = (Ok<T> | Err<E>) & ResultMethods<T>;
+/** Methods available on a Result */
+interface ResultMethods<T> {
+  /**
+   * Unwraps the value, throwing for Err.
+   * @example maybeFail().expect("must succeed")
+   */
+  expect(msg?: string): T;
+  /**
+   * Returns an unwrap chain that throws if no else is provided.
+   * Use `.else(valueOrFn)` to supply a fallback for Err.
+   * - If `Ok`, `.else(...)` returns the inner value and ignores fallback.
+   * - If `Err`, `.else(...)` returns the fallback; if a function, it receives the error.
+   */
+  unwrap(): {
+    /**
+     * Fallback value or function to recover from Err.
+     * If a function is provided, it is called with the Err's error.
+     * Returns the unwrapped value (Ok) or the provided fallback (Err).
+     */
+    else(fallback: T | ((error: any) => T)): T;
+  };
+  /**
+   * Transforms the inner value if `Ok`, returns same `Err` if `Err`.
+   * - If fn returns `undefined`, returns original Result (no new allocation).
+   * - If fn throws, returns `Err(message)`.
+   * - Supports async functions, returning `Promise<Result<U, string>>`.
+   * @example
+   * Ok(5).andThen(x => x * 2);             // Ok(10)
+   * Err("fail").andThen(x => x * 2);       // Err("fail")
+   * Ok(5).andThen(x => undefined);         // Ok(5) - original
+   * await Ok(5).andThen(async x => x);     // Ok(5)
+   */
+  andThen<U>(fn: (value: T) => U | Promise<U>): Result<U, string> | Promise<Result<U, string>>;
+}
 /**
- * Slang - Functional programming utilities for TypeScript
- * Re-exports all types and functions from the modular src folder.
+ * Creates a new, successful result.
+ * @param value Value of the result
+ * @example
+ * const a = Ok("hello");
+ * typeof a; // Ok<"hello">
  */
-export * from "./src";
+export declare function Ok<T>(value: T): Ok<T> & ResultMethods<T>;
+/**
+ * Creates a new, failed result with a string error message.
+ * @param error Error message (must be a string)
+ * @example
+ * const a = Err("something went wrong");
+ * typeof a; // Err<string>
+ */
+export declare function Err(error: string): Err<string> & ResultMethods<never>;
+//#endregion
+//#region src/atom.d.ts
+/** Unique symbol to brand atoms */
+declare const __atom__: unique symbol;
+/** Atom type carrying the original name for hover/type info */
+type Atom<T extends string = string> = symbol & {
+  readonly [__atom__]: T;
+};
+/** Methods available on an Atom */
+interface AtomMethods<T extends string> {
+  /** Returns the same atom */
+  to(target: "atom"): Atom<T>;
+  /**
+   * Returns `Option<string>` using the atom description.
+   * @example atom("ready").to("option") // Some("ready")
+   */
+  to(target: "option"): Option<string>;
+  /**
+   * Returns `Ok<string>` using the atom description.
+   * @example atom("ready").to("result") // Ok("ready")
+   */
+  to(target: "result"): Result<string, string>;
+  /**
+   * Transforms the atom description, returns new Atom.
+   * - If fn returns `undefined`, returns original Atom (no new allocation).
+   * - If fn returns non-string, panics.
+   * - If fn throws, panics.
+   * - Sync only (no async support for Atom).
+   * @example
+   * atom("hello").andThen(s => s.toUpperCase());  // Atom("HELLO")
+   * atom("test").andThen(s => undefined);         // Atom("test") - original
+   */
+  andThen<U extends string>(fn: (value: T) => U | undefined): Atom<U> & AtomMethods<U>;
+}
+/**
+ * Creates a new, unique atom (non-interned).
+ * - Atoms are symbols with additional methods for type-safe conversions.
+ * @param name - Name of the atom (used for hover/description).
+ * @returns `Atom<T>` with chainable `to()` method for conversions.
+ * @example
+ * const ready = atom("ready");
+ * ready.to("option"); // Some("ready")
+ * ready.to("result"); // Ok("ready")
+ */
+export declare function atom<const T extends string>(name: T): Atom<T> & AtomMethods<T>;
+//#endregion
+//#region src/option.d.ts
+declare const __option__: unique symbol;
+type Some<T> = {
+  type: "Some";
+  value: T;
+  readonly isSome: true;
+  readonly isNone: false;
+  readonly [__option__]: true;
+};
+type None = {
+  type: "None";
+  readonly isSome: false;
+  readonly isNone: true;
+  readonly [__option__]: true;
+};
+type Option<T> = (Some<T> | None) & OptionMethods<T>;
+/** Values treated as falsy by Option */
+type NonTruthy = null | undefined | "";
+/** Methods available on an Option */
+interface OptionMethods<T> {
+  /** Returns the same option */
+  to(target: "option"): Option<T>;
+  /** Converts `Some<string>` to `Atom<string>`; throws for `None` or non-string */
+  to(target: "atom"): Atom<T & string>;
+  /** Converts to `Result<T, string>`; `None` becomes `Err("Value is None")` */
+  to(target: "result"): Result<T | (T extends string ? never : Atom<string>), string>;
+  /**
+   * Unwraps the option, throwing if `None`.
+   * @throws Error with provided message or default.
+   * @example
+   * option(42).expect(); // 42
+   * option("").expect("must be present"); // throws
+   */
+  expect(msg?: string): T;
+  /**
+   * Returns an unwrap chain that MUST be completed with `.else(...)`.
+   * If `.else(...)` is not chained, an error is thrown ("Expected else").
+   * - If `Some`, `.else(...)` is required but ignored for outcome; returns the inner value.
+   * - If `None`, `.else(...)` provides fallback; if a function, it is called with `undefined`.
+   * - Fallback result must be truthy; otherwise, throws ("Fallback must be truthy").
+   */
+  unwrap(): {
+    /**
+     * Fallback value or transformer to recover from `None`.
+     * - Function form receives `undefined` and must return a truthy value.
+     * - Direct value must be truthy.
+     * Returns the inner value for `Some`, or the validated fallback for `None`.
+     */
+    else(fallback: T | ((value: T | undefined) => T)): T;
+  };
+  /**
+   * Transforms the inner value if `Some`, returns `None` if `None`.
+   * - If fn returns `undefined`, returns original Option (no new allocation).
+   * - If fn throws, returns `None`.
+   * - Supports async functions, returning `Promise<Option<U>>`.
+   * @example
+   * option(5).andThen(x => x * 2);           // Some(10)
+   * option(null).andThen(x => x * 2);        // None
+   * option(5).andThen(x => undefined);       // Some(5) - original
+   * await option(5).andThen(async x => x);   // Some(5)
+   */
+  andThen<U>(fn: (value: T) => U | Promise<U>): Option<U> | Promise<Option<U>>;
+}
+/**
+ * Checks if a value is falsy for Option purposes.
+ * Falsy: null, undefined, empty string, NaN, Infinity, -Infinity
+ */
+export declare const isFalsy: (value: any) => boolean;
+/**
+ * Creates a new truthy option.
+ * @param value - the value of the option
+ * @throws Error if value is falsy
+ * @example
+ * const a = Some("hello");
+ * typeof a; // Some<"hello">
+ */
+declare function Some<T>(value: T): Some<T>;
+/** Singleton None value */
+declare const None: None;
+/**
+ * Creates a new option type from a value.
+ * - Truthy values become `Some<T>`; `null|undefined|""` become `None`.
+ * - Provides chainable `.to()`, `.expect()`, and `.unwrap()` helpers.
+ * @example
+ * option("hi").expect(); // "hi"
+ * option("").expect("cannot be empty"); // throws Error("cannot be empty")
+ * option("state").to("atom"); // Atom<"state">
+ * option(null).to("result"); // Err("Value is None")
+ */
+export declare function option<T>(value: T | NonTruthy): Option<T> & OptionMethods<T>;
+//#endregion
+//#region src/internals.d.ts
+/**
+ * Schedules a microtask; falls back to Promise if unavailable.
+ * Used internally for deferred error handling in unwrap chains.
+ */
+export declare const scheduleMicrotask: (fn: () => void) => void;
+//#endregion
+//#region src/println.d.ts
+type EnvironmentMode = "development" | "production" | "dev" | "prod";
+type PrintFn = (line: string) => void;
+type EnvironmentOptions = {
+  printFn?: PrintFn | null;
+};
+/**
+ * Sets the runtime environment for dev-only utilities.
+ * Idempotent — safe to call any number of times, in any order; the last call wins.
+ * Accepts a mode (full words or short forms: "development"/"dev", "production"/"prod")
+ * or options `{ printFn }` to route println through an existing logger instead of
+ * the console — useful in production, where logs go somewhere real.
+ * Pass `{ printFn: null }` to switch back to the console.
+ */
+export declare const setEnvironment: (next: EnvironmentMode | EnvironmentOptions) => void;
+/**
+ * Prints a line to the console — args joined with spaces, newline appended.
+ * When a custom printFn is set, the line goes to it instead, in every mode.
+ * Otherwise production mode is silent, so dev chatter never leaks to prod logs.
+ */
+export declare const println: (...args: unknown[]) => void;
+//#endregion
+//#region src/panic.d.ts
+/**
+ * Throws an error immediately.
+ * Use for unrecoverable failures or guard clauses.
+ * @param message - Error message
+ * @example
+ * panic("Critical!");
+ *
+ * // Guard clause pattern
+ * if (!config.apiKey) panic("API key required");
+ */
+export declare function panic(message: string): never;
+//#endregion
+//#region src/options.d.ts
+/**
+ * Resolves the usable inner type of a value.
+ * - `Some<U>` / `Ok<U>` contribute `U`.
+ * - `None`, `Err`, null, undefined, and empty string contribute nothing.
+ * - Raw values contribute themselves.
+ */
+type OptionsValue<T> = T extends {
+  isErr: true;
+} | {
+  isNone: true;
+} | null | undefined | "" ? never : T extends {
+  isSome: true;
+  value: infer U;
+} | {
+  isOk: true;
+  value: infer U;
+} ? U : T;
+/**
+ * Returns the first usable value from a list as an `Ok`, or the fallback
+ * `Err` if none is usable.
+ *
+ * Normalizes heterogeneous values — raw values, `Option`s, and `Result`s
+ * from different sources — when all you care about is whether any of them
+ * is usable. A value is usable when its unwrapped inner value is truthy;
+ * `None`, `Err`, null, undefined, `""`, NaN, and Infinity are skipped.
+ * Note that `0` and `false` are usable, matching `option()` semantics.
+ *
+ * @param values - Values to inspect in order; first usable one wins.
+ * @param fallback - `Err` returned when no value is usable (default `Err("No value!")`).
+ * @returns `Ok` of the first usable inner value, or the fallback.
+ * @example
+ * const a = null;
+ * const b = option(undefined);
+ * const c = Ok(true);
+ * const d = Err("nope!");
+ * Options([a, b, c, d]); // Ok(true) - c is usable
+ *
+ * const nothing = Options([a, option(null), Err("nope!")]); // Err("No value!")
+ */
+export declare function Options<T extends readonly unknown[]>(values: T, fallback?: Err<string> & ResultMethods<never>): Result<OptionsValue<T[number]>, string>;
+//#endregion
+//#region src/to.d.ts
+/**
+ * Converts between Slang types.
+ * - `option`: Wraps primitive or symbol description into `Option`
+ * - `atom`: Converts `Some<string>` to `Atom` or returns symbol Atom
+ * - `result`: Wraps values into `Ok`, `None` into `Err`
+ */
+export declare function _to<T>(value: Option<T>, target: "option"): Option<T>;
+export declare function _to<T extends string>(value: Option<T>, target: "atom"): Atom<T>;
+export declare function _to<T extends string>(value: Atom<T>, target: "option"): Option<string>;
+export declare function _to<T extends string>(value: Atom<T>, target: "atom"): Atom<T>;
+export declare function _to<T, E = string>(value: Option<T>, target: "result"): Result<T, E>;
+export declare function _to<E = string>(value: Atom<any>, target: "result"): Result<string, E>;
+//#endregion
+//#region src/match.d.ts
+/**
+ * Pattern matching for `Result` and `Option` — exhaustiveness enforced.
+ *
+ * Returns the value returned by the selected handler. If all handlers return
+ * `Result` or `Option`, TypeScript will infer that automatically.
+ */
+export declare function match<T, E, R>(value: Result<T, E> | (Result<any, any> & ResultMethods<any>), patterns: {
+  Ok: ((v: Ok<T>) => R) | (() => R);
+  Err: ((e: Err<E>) => R) | (() => R);
+}): R;
+export declare function match<T, R>(value: Some<T> | None, patterns: {
+  Some: ((v: Some<T>) => R) | (() => R);
+  None: ((v: None) => R) | (() => R);
+}): R;
+/**
+ * Allowed keys in matchAll patterns.
+ * - Strings, numbers, and Atom descriptions.
+ * - Booleans are represented as "true" | "false" strings
+ */
+type MatchKey = string | number | symbol;
+/**
+ * Type-safe pattern object: must always have `_` fallback.
+ */
+type MatchPatterns<V> = { [K in MatchKey]?: (v: V) => unknown; } & {
+  _: () => unknown;
+};
+/**
+ * Extracts return types from all handlers in a patterns object as a union.
+ * Allows each arm to return a different type.
+ */
+type InferReturnTypes<P> = { [K in keyof P]: P[K] extends ((...args: any[]) => infer R) ? R : never; }[keyof P];
+/**
+ * Matches a value against literal or Atom cases by *semantic name*.
+ * - Supports string, number, booleans and Atom (symbol) values.
+ * - Unsupported will throw an error. (objects, arrays, functions, etc)
+ * - For Atoms, uses their description as a key (e.g. atom("ready") → "ready").
+ * - Requires a `_` default handler.
+ *
+ * @example
+ * matchAll(ready, {
+ *   1: () => println("One"),
+ *   2: () => println("Two"),
+ *   0: () => println("Zero"),
+ *   true: () => println("True"),
+ *   false: () => println("False"),
+ *   ready: () => println("Ready!"),
+ *   failed: () => println("Failed!"),
+ *   _: () => println("Unknown!"),
+ * });
+ */
+export declare function matchAll<T extends MatchKey | boolean, P extends MatchPatterns<T>>(value: T, patterns: P): InferReturnTypes<P>;
+//#endregion
+//#region src/zip.d.ts
+/**
+ * Combines multiple collections element-wise into tuples.
+ * - All inputs must be the same type (all arrays, all Sets, or all objects).
+ * - By default, only arrays are allowed; set `includeValues: true` to extract values from Sets/Objects.
+ * - Stops at shortest collection by default; use `fillValue` to extend to longest.
+ * - Transforms columns into rows for parallel iteration.
+ * @param inputs Collections of the same type to combine
+ * @param options Configuration: `fillValue` extends to longest, `includeValues` extracts values from Sets/Objects (default: false)
+ * @returns Array of tuples, one per index position
+ * @example
+ * zip([[1, 2], ['a', 'b']]); // [[1, 'a'], [2, 'b']]
+ * zip([[1, 2], ['a']], { fillValue: 'x' }); // [[1, 'a'], [2, 'x']]
+ * const s1 = new Set([1, 2]); const s2 = new Set([3, 4]);
+ * zip([s1, s2], { includeValues: true }); // [[1, 3], [2, 4]]
+ */
+export declare function zip<T extends readonly any[]>(inputs: { [K in keyof T]: Iterable<T[K]> | {
+  [key: string]: T[K];
+}; }, options?: {
+  fillValue?: T[number];
+  includeValues?: boolean;
+}): T[number][][];
+/**
+ * Combines multiple collections element-wise and transforms each tuple.
+ * - All inputs must be the same type (all arrays, all Sets, or all objects).
+ * - By default, only arrays are allowed; set `includeValues: true` to extract values from Sets/Objects.
+ * - Applies a function to each set of corresponding elements.
+ * - Useful for aggregating, computing, or transforming aligned data.
+ * @param inputs Collections of the same type to combine
+ * @param fn Transform function applied to each tuple
+ * @param options Configuration: `fillValue` extends to longest, `includeValues` extracts values from Sets/Objects (default: false)
+ * @returns Array of transformed results
+ * @example
+ * zipWith([[1, 2], [3, 4]], (t) => t[0] + t[1]); // [4, 6]
+ * zipWith([[1, 2], [10]], (t) => t.reduce((a, b) => a + b, 0), { fillValue: 0 }); // [11, 2]
+ */
+export declare function zipWith<T extends readonly any[], R>(inputs: { [K in keyof T]: Iterable<T[K]> | {
+  [key: string]: T[K];
+}; }, fn: (tuple: T[number][]) => R, options?: {
+  fillValue?: T[number];
+  includeValues?: boolean;
+}): R[];
+/**
+ * Unzips an array of tuples back into separate arrays.
+ * - Reverses the zip operation: transforms rows to columns.
+ * - Useful for separating previously combined collections.
+ * @param zipped Array of tuples (rows) to transpose
+ * @returns Array of arrays (columns), one per tuple position
+ * @example
+ * const zipped = [[1, 'a'], [2, 'b'], [3, 'c']];
+ * unzip(zipped); // [[1, 2, 3], ['a', 'b', 'c']]
+ */
+export declare function unzip<T>(zipped: T[][]): T[][];
+//#endregion
+//#region src/safe-try.d.ts
+/** Terminal success value after resolving supported Slang wrappers. */
+type SafeTryValue<T> = T extends Atom<infer Name> ? Name : T extends Ok<infer Value> ? SafeTryValue<Value> : T extends Some<infer Value> ? SafeTryValue<Value> : T extends Err<infer _Error> ? never : T extends None ? never : T;
+/** Options for safeTry behavior */
+type SafeTryOptions = {
+  /** If true, re-throws thrown errors instead of capturing them. */
+  throw?: boolean;
+};
+/**
+ * Captures failures and resolves nested Slang wrappers into one Result.
+ * - Awaits the callback, then iteratively unwraps Result, Option, and Atom values.
+ * - Returns the first Err or None as Err; cycles also return Err.
+ * - Leaves object properties, array elements, and wrapped Promise values intact.
+ * - `{ throw: true }` re-throws thrown errors; returned failures remain Err.
+ *
+ * @param fn - Function to execute (sync or async)
+ * @param options - `{ throw?: boolean }`
+ * @returns Promise of one Result containing the terminal success value or error text
+ *
+ * @example
+ * const result = await safeTry(() => Ok(Ok("Hello")));
+ * if (result.isOk) println(result.value); // "Hello"
+ *
+ * @example
+ * const result = await safeTry(() => {
+ *   throw new Error("Oops!");
+ * });
+ * if (result.isErr) println(result.error);
+ */
+export declare function safeTry<T>(fn: () => T | Promise<T>, options?: SafeTryOptions): Promise<Result<SafeTryValue<Awaited<T>>, string>>;
+//#endregion
+//#region src/pipe.d.ts
+/** Function that transforms one Result into another */
+type PipeFn<T = any, E = any> = (input: Result<T, E>) => Result<any, any> | Promise<Result<any, any>>;
+/** Context passed to onEach callback */
+type PipeEachContext = {
+  prevResult: Result<any, any>;
+  currentFn: string;
+  nextFn: string | undefined;
+};
+/** Options for pipeline execution */
+type PipeRunOptions = {
+  /** Called after each function executes */
+  onEach?: (ctx: PipeEachContext) => void;
+  /** Called when pipeline completes successfully */
+  onSuccess?: (value: any) => void;
+  /** Called when pipeline encounters an error (only when allowErrors is false) */
+  onError?: (error: Error) => void;
+  /** If true, continues pipeline even when a function returns Err */
+  allowErrors?: boolean;
+};
+/** Pipeline object returned by pipe() */
+type Pipeline<T, E> = {
+  run: (options?: PipeRunOptions) => Promise<Result<T, E>>;
+};
+/**
+ * Creates a pipeline for sequential function composition.
+ * Each function receives the previous Result and returns a new Result.
+ *
+ * @param initial - Starting value (plain value, Option, Result, or Atom)
+ * @param fns - Pipeline functions that transform Results
+ * @returns Pipeline object with `.run()` method
+ *
+ * @example
+ * const add = (x: number) => (res: Result<number, string>) =>
+ *   res.isOk ? Ok(res.value + x) : res;
+ *
+ * const result = await pipe(5, add(3), add(2)).run();
+ * // result.value === 10
+ *
+ * @example
+ * const result = await pipe(option(5), add(3)).run({
+ *   onEach: ({ currentFn, prevResult }) => console.log(currentFn, prevResult),
+ *   onSuccess: (value) => console.log("Done:", value),
+ *   allowErrors: false,
+ * });
+ */
+export declare function pipe<T, E = string>(initial: T, ...fns: PipeFn[]): Pipeline<any, E>;
+//#endregion
+//#region src/super-promise.d.ts
+/** The operation itself. Receives the attempt's AbortSignal. */
+type Executor<T> = (signal: AbortSignal) => T | Promise<T> | Result<T, string> | Promise<Result<T, string>>;
+/** Stop signal for `retryUntil`. */
+type RetryUntilOptions = {
+  /** When this fires, retrying ends — mid-attempt firings cancel the in-flight attempt. */
+  signal: AbortSignal;
+  /** Wait between attempts. No wait applies before the first attempt. */
+  delay?: number;
+};
+/** Execution policies, configured at construction time. */
+type SuperPromiseOptions = {
+  /** Do not execute until this signal fires (accepts SuperPromise signals and AbortSignal). */
+  defer?: AbortSignal;
+  /** Wait before initial execution; normal retries also wait this long. */
+  delay?: number;
+  /** Abort the operation after this many milliseconds. Timeouts are never retried. */
+  timeout?: number;
+  /** `n` retries after the first attempt — `n + 1` attempts total. Aborts and timeouts are never retried. */
+  retry?: number;
+  /** Keep retrying until the stop signal fires. Overrides `retry` and `delay`. */
+  retryUntil?: RetryUntilOptions;
+};
+/** A single async operation with lifecycle ergonomics. Promise-compatible. */
+type SuperPromise<T> = {
+  /** Lifecycle signal: fires once when the task reaches a terminal state. */
+  done: AbortSignal;
+  /** Cancels the operation; settles with `Err("Aborted")` when not yet settled. */
+  abort(): void;
+  /** Manually settles an externally controlled task with a value. First settlement wins. */
+  resolve(value: T): void;
+  /** Manually settles an externally controlled task with a failure. First settlement wins. */
+  reject(error: unknown): void;
+  /** Observes a successful value without transforming it. Callback throws settle as `Err`. */
+  tap(fn: (value: T) => unknown | Promise<unknown>): SuperPromise<T>;
+  /** Promise-compatible. The callback receives the settled `Result`; the task never rejects. */
+  then<TR1 = Result<T, string>, TR2 = never>(onfulfilled?: ((value: Result<T, string>) => TR1 | PromiseLike<TR1>) | null, onrejected?: ((reason: unknown) => TR2 | PromiseLike<TR2>) | null): Promise<TR1 | TR2>;
+  /** Promise-compatible. Effectively dead — failures are captured into `Err`, never rejections. */
+  catch<TR = never>(onrejected?: ((reason: unknown) => TR | PromiseLike<TR>) | null): Promise<Result<T, string> | TR>;
+  /** Promise-compatible. Native behavior. */
+  finally(onfinally?: (() => void) | null): Promise<Result<T, string>>;
+};
+/**
+ * Creates a SuperPromise — one async operation plus lifecycle/execution ergonomics.
+ *
+ * Lazy activation: the executor starts on first consumption (`await`/`.then()`,
+ * or a runner's `start()`), not at creation. Defer chains activate recursively,
+ * so awaiting a deferred task runs its dependency first.
+ *
+ * @example
+ * const task = superPromise(async signal => {
+ *   const response = await fetch(url, { signal });
+ *   return response.json();
+ * });
+ *
+ * const result = await task; // Result<T, string>
+ */
+export declare function superPromise<T>(fn: Executor<T>, options?: SuperPromiseOptions): SuperPromise<T>;
+/** Creates an externally controlled SuperPromise, settled via `resolve`/`reject`. */
+export declare function superPromise<T>(fn?: undefined, options?: SuperPromiseOptions): SuperPromise<T>;
+//#endregion
+//#region src/super-runner.d.ts
+/** Sequence result: positional tuple of the runners' Ok values. */
+type TupleValues<R extends readonly SuperPromise<unknown>[]> = { -readonly [K in keyof R]: R[K] extends SuperPromise<infer T> ? T : never; };
+/** all/race result: named object of the runners' Ok values. */
+type NamedValues<R extends Record<string, SuperPromise<unknown>>> = { [K in keyof R]: R[K] extends SuperPromise<infer T> ? T : never; };
+/** race(count: 1) result: union of single-winner objects. */
+type RaceValues<C extends number, R extends Record<string, SuperPromise<unknown>>> = C extends 1 ? { [K in keyof R]: { [P in K]: R[K] extends SuperPromise<infer T> ? T : never; }; }[keyof R] : Partial<NamedValues<R>>;
+/** Orchestrates multiple already-created SuperPromises. */
+type SuperRunner<Value> = {
+  /** Lifecycle signal: fires once when the runner reaches a terminal state. */
+  done: AbortSignal;
+  /** Starts execution. Idempotent: repeated calls return the same result without re-executing children. */
+  start(): Promise<Result<Value, string>>;
+  /** Cancels the runner and all active children; settles with `Err("Aborted")`. */
+  abort(): void;
+};
+/** Runs runners in order; stops at the first failure. */
+export declare function superRunner<const R extends readonly SuperPromise<unknown>[]>(config: {
+  type: "sequence";
+  runners: R;
+}): SuperRunner<TupleValues<R>>;
+/** Runs runners concurrently; fails fast on the first failure, aborting remaining children. */
+export declare function superRunner<const R extends Record<string, SuperPromise<unknown>>>(config: {
+  type: "all";
+  runners: R;
+}): SuperRunner<NamedValues<R>>;
+/** Runs runners concurrently; first `count` successful completions win, remaining children are aborted. */
+export declare function superRunner<const C extends number, const R extends Record<string, SuperPromise<unknown>>>(config: {
+  type: "race";
+  count: C;
+  runners: R;
+}): SuperRunner<RaceValues<C, R>>;
+//#endregion
+//#region src/channel.d.ts
+/** Event published on a Channel. */
+type ChannelEvent = {
+  topic: string;
+  data: unknown;
+};
+/** Subscriber handler receiving published events. */
+type ChannelSubscriber = (event: ChannelEvent) => void;
+/** Event communication between independent parts of an application. */
+type Channel = {
+  /** Immediately publishes an event to subscribers of its topic. */
+  send(event: ChannelEvent): void;
+  /**
+   * Subscribes to events of a specific topic.
+   * Returns an unsubscribe function; after calling it, no further events are received.
+   */
+  subscribe(filter: {
+    topic: string;
+  }, handler: ChannelSubscriber): () => void;
+  /** Publishes an event when a signal fires. Accepts any compatible lifecycle signal. */
+  when(config: {
+    signal: AbortSignal;
+    topic: string;
+    data: unknown;
+  }): void;
+};
+/**
+ * Creates a Channel — completely independent of SuperPromise/SuperRunner.
+ *
+ * @example
+ * const channel = createChannel();
+ *
+ * const unsubscribe = channel.subscribe({ topic: "user.created" }, event => {
+ *   println(event.data);
+ * });
+ *
+ * channel.send({ topic: "user.created", data: user });
+ * unsubscribe(); // stop receiving events
+ */
+export declare function createChannel(): Channel;
+//#endregion
+//#region src/signal.d.ts
+/**
+ * A lifecycle Signal — a trigger that fires once and stays fired.
+ *
+ * Abort-compatible: structurally an `AbortSignal` plus a `fire()` method,
+ * so it can be passed anywhere a native `AbortSignal` is expected
+ * (and vice-versa). Wraps AbortController semantics.
+ *
+ * Consumed by `defer`, `retryUntil`, `channel.when`, and `task.done`.
+ */
+type Signal = AbortSignal & {
+  /** Fires the signal once. Subsequent calls are no-ops. */
+  fire(): void;
+};
+/**
+ * Creates a lifecycle signal.
+ *
+ * ```ts
+ * const signal = createSignal();
+ *
+ * signal.addEventListener("abort", () => {
+ *   println("fired");
+ * });
+ *
+ * signal.fire(); // "fired"
+ * signal.aborted; // true
+ * ```
+ *
+ * Listeners are NOT replayed after firing — consumers must check
+ * `signal.aborted` synchronously to detect an already-fired signal.
+ */
+export declare function createSignal(): Signal;
+//#endregion
+export type { Atom, AtomMethods, Channel, ChannelEvent, ChannelSubscriber, EnvironmentMode, EnvironmentOptions, Err as ErrType, Executor, NonTruthy, None, Ok as OkType, Option, OptionMethods, OptionsValue, PipeEachContext, PipeFn, PipeRunOptions, Pipeline, PrintFn, Result, ResultMethods, RetryUntilOptions, Signal, Some, SuperPromise, SuperPromiseOptions, SuperRunner };