rexfect 0.0.7

package/dist/async/abortable.d.ts

@@ -0,0 +1,331 @@
+/**
+ * Abortable function utilities.
+ *
+ * Creates async functions with full lifecycle control:
+ * - Pause/Resume execution
+ * - Abort with cleanup
+ * - External event injection (take/send)
+ * - Status tracking
+ *
+ * Similar to saga pattern but uses async/await instead of suspense.
+ */
+import { type SafeFnWithUtils } from "./safe";
+import { abortableSymbol, isAbortable } from "./abortable-guard";
+export { abortableSymbol, isAbortable };
+export type AbortableStatus = "running" | "success" | "error" | "paused" | "waiting" | "aborted";
+/**
+ * Send function type.
+ * - When TYield is void: `() => void` (checkpoint/nudge pattern)
+ * - When TYield is object: `<K>(key: K, value: TYield[K]) => void`
+ */
+export type AbortableSend<TYield extends void | object = void> = void extends TYield ? () => void : <TKey extends keyof TYield>(key: TKey, value: TYield[TKey]) => void;
+/**
+ * Take function type.
+ * Returns a Promise that resolves when the event arrives.
+ * - When TYield is void: `() => Promise<void>` (checkpoint pattern)
+ * - When TYield is object: `<K>(key: K) => Promise<TYield[K]>`
+ */
+export type AbortableTake<TYield extends void | object = void> = void extends TYield ? () => Promise<void> : <TKey extends keyof TYield>(key: TKey) => Promise<TYield[TKey]>;
+/**
+ * Join function type for coordinating multiple abortable results.
+ * When the parent abortable is aborted, all joined results are also aborted.
+ */
+export type AbortableJoin = {
+    /** Join a single abortable result */
+    <TResult>(result: AbortableResult<TResult, any>): Promise<TResult>;
+    /** Join multiple abortable results (like Promise.all with abort propagation) */
+    <const T extends readonly AbortableResult<any, any>[]>(results: T): Promise<{
+        -readonly [K in keyof T]: Awaited<T[K]>;
+    }>;
+};
+/**
+ * Result returned when invoking an abortable function.
+ * Extends Promise for async consumption while providing control methods.
+ *
+ * @example
+ * ```ts
+ * const result = myAbortable(args);
+ *
+ * // Promise-like usage
+ * const value = await result;
+ *
+ * // Control methods
+ * result.pause();
+ * result.resume();
+ * result.abort();
+ *
+ * // Status checks
+ * result.running();  // boolean
+ * result.status();   // "running" | "success" | ...
+ *
+ * // Event sending
+ * result.send("eventKey", eventValue);
+ * ```
+ */
+export type AbortableResult<TResult, TYield extends void | object = void> = Promise<TResult> & {
+    /** Send an event to the abortable */
+    send: AbortableSend<TYield>;
+    /** Check if abortable has failed */
+    failed(): boolean;
+    /** Check if abortable has completed (success, error, or aborted) */
+    completed(): boolean;
+    /** Check if abortable is currently running */
+    running(): boolean;
+    /** Check if abortable succeeded */
+    succeeded(): boolean;
+    /** Check if abortable is paused */
+    paused(): boolean;
+    /** Check if abortable is waiting for async operation or event */
+    waiting(): boolean;
+    /** Check if abortable was aborted */
+    aborted(): boolean;
+    /** Get current status */
+    status(): AbortableStatus;
+    /** Get result if succeeded, undefined otherwise */
+    result(): Awaited<TResult> | undefined;
+    /** Get error if failed, undefined otherwise */
+    error(): Error | undefined;
+    /**
+     * Pause execution at current await point.
+     * @returns false if already paused or completed
+     */
+    pause(): boolean;
+    /**
+     * Resume execution from paused state.
+     * @returns false if not paused
+     */
+    resume(): boolean;
+    /**
+     * Abort execution.
+     * Does NOT affect parent signal - only this abortable's internal signal.
+     * @returns false if already aborted or completed
+     */
+    abort(): boolean;
+};
+/**
+ * Context passed to abortable function handlers.
+ *
+ * @example
+ * ```ts
+ * const myFn = abortable<[string], Result, { confirm: boolean }>(
+ *   async ({ signal, safe, take, aborted, abort }, id) => {
+ *     const data = await safe(fetchData, id);
+ *
+ *     if (aborted()) return null;
+ *
+ *     const confirmed = await take("confirm");
+ *     if (!confirmed) {
+ *       abort();
+ *       return null;
+ *     }
+ *
+ *     return processData(data);
+ *   }
+ * );
+ * ```
+ */
+export interface AbortableContext<TYield extends void | object = void> {
+    /**
+     * AbortSignal for this abortable instance.
+     * This is the abortable's OWN signal, not the parent's.
+     * Use this for fetch, timers, etc.
+     */
+    signal: AbortSignal;
+    /**
+     * Safe execution utility.
+     * Wraps async operations to handle abort gracefully.
+     *
+     * Includes utilities: `.all()`, `.race()`, `.any()`, `.settled()`, `.callback()`
+     */
+    safe: SafeFnWithUtils;
+    /**
+     * Wait for an external event.
+     * Returns a Promise that resolves when `send(key, value)` is called.
+     *
+     * @example
+     * ```ts
+     * // With typed events
+     * const confirmed = await take("confirm");
+     *
+     * // Checkpoint pattern (TYield = void)
+     * await take(); // Waits for send()
+     * ```
+     */
+    take: AbortableTake<TYield>;
+    /**
+     * Check if this abortable has been aborted.
+     */
+    aborted(): boolean;
+    /**
+     * Abort this abortable from inside.
+     * Does NOT affect parent signal.
+     * @returns false if already aborted
+     */
+    abort(): boolean;
+    /**
+     * Check for pause point.
+     * Call this between async operations to allow pause/resume.
+     * Throws AbortableAbortedError if aborted.
+     *
+     * @example
+     * ```ts
+     * const myFn = abortable(async (ctx) => {
+     *   const data = await fetchData();
+     *   await ctx.checkpoint(); // Allow pause here
+     *   const processed = await process(data);
+     *   await ctx.checkpoint(); // Allow pause here
+     *   return processed;
+     * });
+     * ```
+     */
+    checkpoint(): Promise<void>;
+    /**
+     * Join one or more abortable results.
+     * When this abortable is aborted, all joined results are also aborted.
+     *
+     * @example
+     * ```ts
+     * // Single result
+     * const user = await ctx.join(fetchUser(id));
+     *
+     * // Multiple results (like Promise.all)
+     * const [user, posts, comments] = await ctx.join([
+     *   fetchUser(id),
+     *   fetchPosts(id),
+     *   fetchComments(id),
+     * ]);
+     * ```
+     */
+    join: AbortableJoin;
+    /**
+     * Abort the previous invocation of this abortable function.
+     * Useful for "latest only" patterns where rapid calls should cancel in-flight operations.
+     *
+     * @param message - Optional abort message
+     *
+     * @example
+     * ```ts
+     * const search = abortable(async ({ signal, abortPrev }, query: string) => {
+     *   abortPrev(); // Cancel previous search
+     *   const res = await fetch(`/search?q=${query}`, { signal });
+     *   return res.json();
+     * });
+     *
+     * search("h");
+     * search("he");
+     * const results = await search("hello"); // Only this completes
+     * ```
+     */
+    abortPrev(message?: string): void;
+    /**
+     * Create a child context that aborts when this context aborts.
+     * Useful for sub-operations that should cancel with parent.
+     */
+    fork(): AbortableContext<TYield>;
+    /**
+     * Create an independent context that doesn't abort with parent.
+     * Useful for background operations that should continue.
+     */
+    spawn(): AbortableContext<TYield>;
+}
+/**
+ * Handler function signature for abortable.
+ */
+export type AbortableFn<TArgs extends any[], TResult, TYield extends void | object = void> = (ctx: AbortableContext<TYield>, ...args: TArgs) => Promise<TResult>;
+/**
+ * Wrapper type for use() method.
+ */
+export type AbortableWrapper<TArgs extends any[], TResult, TYield extends void | object, TNewArgs extends any[] = TArgs, TNewResult = TResult, TNewYield extends void | object = TYield> = (next: AbortableFn<TArgs, TResult, TYield>) => AbortableFn<TNewArgs, TNewResult, TNewYield>;
+/**
+ * Identity wrapper that preserves all input types including TYield.
+ */
+export type IdentityWrapper = <TArgs extends any[], TResult, TYield extends void | object = void>(next: AbortableFn<TArgs, TResult, TYield>) => AbortableFn<TArgs, TResult, TYield>;
+/**
+ * An abortable function with full lifecycle control.
+ *
+ * - Direct call: `fn(...args)` - creates new AbortController
+ * - With signal: `fn.withSignal(signal, ...args)` - links to parent signal
+ * - Chainable: `fn.use(wrapper)` - returns new Abortable with wrapper applied
+ *
+ * Signal relationship:
+ * - Abortable creates its own internal AbortController
+ * - When `withSignal(parentSignal)` is called:
+ *   - If parent aborts → this abortable aborts
+ *   - If this abortable aborts → parent NOT affected
+ */
+export interface Abortable<TArgs extends any[], TResult, TYield extends void | object = void> {
+    /** Call without signal (creates new AbortController) */
+    (...args: TArgs): AbortableResult<TResult, TYield>;
+    /**
+     * Call with parent signal.
+     * Parent abort → this aborts. This abort → parent unaffected.
+     */
+    withSignal(signal: AbortSignal | undefined, ...args: TArgs): AbortableResult<TResult, TYield>;
+    /**
+     * Apply a wrapper and return a new Abortable.
+     *
+     * @example
+     * ```ts
+     * const fetchUserWithRetry = fetchUser.use(withRetry(3));
+     * ```
+     */
+    use<TNewArgs extends any[] = TArgs, TNewResult = TResult, TNewYield extends void | object = TYield>(wrapper: AbortableWrapper<TArgs, TResult, TYield, TNewArgs, TNewResult, TNewYield>): Abortable<TNewArgs, TNewResult, TNewYield>;
+    /**
+     * Type assertion for return type.
+     */
+    as<TNewResult, TNewArgs extends any[] = TArgs, TNewYield extends void | object = TYield>(): Abortable<TNewArgs, TNewResult, TNewYield>;
+    /** Type brand for discrimination */
+    readonly [abortableSymbol]: true;
+}
+/**
+ * Error thrown when abortable is aborted.
+ */
+export declare class AbortableAbortedError extends Error {
+    readonly name = "AbortableAbortedError";
+    constructor(message?: string);
+}
+/**
+ * Create an abortable function with full lifecycle control.
+ *
+ * Features:
+ * - Pause/Resume execution
+ * - Abort with cleanup
+ * - External event injection (take/send)
+ * - Status tracking
+ * - Parent signal linkage (parent abort → this aborts, not vice versa)
+ *
+ * @example
+ * ```ts
+ * // Simple abortable
+ * const fetchUser = abortable(async ({ signal, safe }, id: string) => {
+ *   const res = await fetch(`/api/users/${id}`, { signal });
+ *   return res.json();
+ * });
+ *
+ * // With events
+ * const checkout = abortable<[Cart], Receipt, { confirm: boolean }>(
+ *   async ({ signal, safe, take }, cart) => {
+ *     const validated = await safe(validateCart, cart);
+ *
+ *     const confirmed = await take("confirm");
+ *     if (!confirmed) throw new Error("Cancelled");
+ *
+ *     return await safe(processPayment, validated);
+ *   }
+ * );
+ *
+ * // Usage
+ * const result = checkout(cart);
+ * result.send("confirm", true);
+ * const receipt = await result;
+ *
+ * // With pause/resume
+ * result.pause();
+ * result.resume();
+ *
+ * // With abort
+ * result.abort();
+ * ```
+ */
+export declare function abortable<const TArgs extends any[], TResult, TYield extends void | object = void>(fn: AbortableFn<TArgs, TResult, TYield>): Abortable<TArgs, TResult, TYield>;
+//# sourceMappingURL=abortable.d.ts.map

package/dist/async/abortable.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"abortable.d.ts","sourceRoot":"","sources":["../../src/async/abortable.ts"],"names":[],"mappings":"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"}