@zeix/cause-effect 0.17.3 → 0.18.0

package/types/src/nodes/task.d.ts

@@ -0,0 +1,73 @@
+import { type ComputedOptions, type TaskCallback } from '../graph';
+/**
+ * An asynchronous reactive computation (colorless async).
+ * Automatically tracks dependencies and re-executes when they change.
+ * Provides abort semantics and pending state tracking.
+ *
+ * @template T - The type of value resolved by the task
+ */
+type Task<T extends {}> = {
+    readonly [Symbol.toStringTag]: 'Task';
+    /**
+     * Gets the current value of the task.
+     * Returns the last resolved value, even while a new computation is pending.
+     * When called inside another reactive context, creates a dependency.
+     * @returns The current value
+     * @throws UnsetSignalValueError If the task value is still unset when read.
+     */
+    get(): T;
+    /**
+     * Checks if the task is currently executing.
+     * @returns True if a computation is in progress
+     */
+    isPending(): boolean;
+    /**
+     * Aborts the current computation if one is running.
+     * The task's AbortSignal will be triggered.
+     */
+    abort(): void;
+};
+/**
+ * Creates an asynchronous reactive computation (colorless async).
+ * The computation automatically tracks dependencies and re-executes when they change.
+ * Provides abort semantics - in-flight computations are aborted when dependencies change.
+ *
+ * @since 0.18.0
+ * @template T - The type of value resolved by the task
+ * @param fn - The async computation function that receives the previous value and an AbortSignal
+ * @param options - Optional configuration for the task
+ * @returns A Task object with get(), isPending(), and abort() methods
+ *
+ * @example
+ * ```ts
+ * const userId = createState(1);
+ * const user = createTask(async (prev, signal) => {
+ *   const response = await fetch(`/api/users/${userId.get()}`, { signal });
+ *   return response.json();
+ * });
+ *
+ * // When userId changes, the previous fetch is aborted
+ * userId.set(2);
+ * ```
+ *
+ * @example
+ * ```ts
+ * // Check pending state
+ * if (user.isPending()) {
+ *   console.log('Loading...');
+ * }
+ * ```
+ */
+declare function createTask<T extends {}>(fn: (prev: T, signal: AbortSignal) => Promise<T>, options: ComputedOptions<T> & {
+    value: T;
+}): Task<T>;
+declare function createTask<T extends {}>(fn: TaskCallback<T>, options?: ComputedOptions<T>): Task<T>;
+/**
+ * Checks if a value is a Task signal.
+ *
+ * @since 0.18.0
+ * @param value - The value to check
+ * @returns True if the value is a Task
+ */
+declare function isTask<T extends {} = unknown & {}>(value: unknown): value is Task<T>;
+export { createTask, isTask, type Task };

package/types/src/signal.d.ts

@@ -1,51 +1,65 @@
-import { type Computed } from './classes/computed';
-import { List } from './classes/list';
-import { State } from './classes/state';
-import { type Store } from './classes/store';
-import type { UnknownRecord } from './diff';
-type Signal<T extends {}> = {
+import { type ComputedOptions, type MemoCallback, type Signal, type TaskCallback } from './graph';
+import { type List, type UnknownRecord } from './nodes/list';
+import { type Memo } from './nodes/memo';
+import { type State } from './nodes/state';
+import { type Store } from './nodes/store';
+import { type Task } from './nodes/task';
+type MutableSignal<T extends {}> = {
     get(): T;
-};
-type UnknownSignal = Signal<unknown & {}>;
-type MutableSignal<T extends {}> = T extends readonly (infer U extends {})[] ? List<U> : T extends UnknownRecord ? Store<T> : State<T>;
-type ReadonlySignal<T extends {}> = Computed<T>;
-type UnknownSignalRecord = Record<string, UnknownSignal>;
-type SignalValues<S extends UnknownSignalRecord> = {
-    [K in keyof S]: S[K] extends Signal<infer T> ? T : never;
+    set(value: T): void;
+    update(callback: (value: T) => T): void;
 };
 /**
- * Check whether a value is a Signal
+ * Create a derived signal from existing signals
  *
  * @since 0.9.0
- * @param {unknown} value - value to check
- * @returns {boolean} - true if value is a Signal, false otherwise
+ * @param callback - Computation callback function
+ * @param options - Optional configuration
  */
-declare const isSignal: <T extends {}>(value: unknown) => value is Signal<T>;
-/**
- * Check whether a value is a State, Store, or List
- *
- * @since 0.15.2
- * @param {unknown} value - Value to check
- * @returns {boolean} - True if value is a State, Store, or List, false otherwise
- */
-declare const isMutableSignal: (value: unknown) => value is MutableSignal<unknown & {}>;
+declare function createComputed<T extends {}>(callback: TaskCallback<T>, options?: ComputedOptions<T>): Task<T>;
+declare function createComputed<T extends {}>(callback: MemoCallback<T>, options?: ComputedOptions<T>): Memo<T>;
 /**
  * Convert a value to a Signal.
  *
  * @since 0.9.6
  */
+declare function createSignal<T extends {}>(value: Signal<T>): Signal<T>;
 declare function createSignal<T extends {}>(value: readonly T[]): List<T>;
-declare function createSignal<T extends {}>(value: T[]): List<T>;
 declare function createSignal<T extends UnknownRecord>(value: T): Store<T>;
-declare function createSignal<T extends {}>(value: () => T): Computed<T>;
+declare function createSignal<T extends {}>(value: TaskCallback<T>): Task<T>;
+declare function createSignal<T extends {}>(value: MemoCallback<T>): Memo<T>;
 declare function createSignal<T extends {}>(value: T): State<T>;
 /**
  * Convert a value to a MutableSignal.
  *
  * @since 0.17.0
  */
+declare function createMutableSignal<T extends {}>(value: MutableSignal<T>): MutableSignal<T>;
 declare function createMutableSignal<T extends {}>(value: readonly T[]): List<T>;
-declare function createMutableSignal<T extends {}>(value: T[]): List<T>;
 declare function createMutableSignal<T extends UnknownRecord>(value: T): Store<T>;
 declare function createMutableSignal<T extends {}>(value: T): State<T>;
-export { createMutableSignal, createSignal, isMutableSignal, isSignal, type MutableSignal, type ReadonlySignal, type Signal, type SignalValues, type UnknownSignal, type UnknownSignalRecord, };
+/**
+ * Check if a value is a computed signal
+ *
+ * @since 0.9.0
+ * @param value - Value to check
+ * @returns True if value is a computed signal, false otherwise
+ */
+declare function isComputed<T extends {}>(value: unknown): value is Memo<T>;
+/**
+ * Check whether a value is a Signal
+ *
+ * @since 0.9.0
+ * @param value - Value to check
+ * @returns True if value is a Signal, false otherwise
+ */
+declare function isSignal<T extends {}>(value: unknown): value is Signal<T>;
+/**
+ * Check whether a value is a State, Store, or List
+ *
+ * @since 0.15.2
+ * @param value - Value to check
+ * @returns True if value is a State, Store, or List, false otherwise
+ */
+declare function isMutableSignal(value: unknown): value is MutableSignal<unknown & {}>;
+export { type MutableSignal, createComputed, createSignal, createMutableSignal, isComputed, isSignal, isMutableSignal, };

package/types/src/util.d.ts

@@ -1,17 +1,10 @@
-declare const isString: (value: unknown) => value is string;
-declare const isNumber: (value: unknown) => value is number;
-declare const isSymbol: (value: unknown) => value is symbol;
-declare const isFunction: <T>(fn: unknown) => fn is (...args: unknown[]) => T;
-declare const isAsyncFunction: <T>(fn: unknown) => fn is (...args: unknown[]) => Promise<T>;
-declare const isSyncFunction: <T extends unknown & {
+declare function isFunction<T>(fn: unknown): fn is (...args: unknown[]) => T;
+declare function isAsyncFunction<T>(fn: unknown): fn is (...args: unknown[]) => Promise<T>;
+declare function isSyncFunction<T extends unknown & {
     then?: undefined;
-}>(fn: unknown) => fn is (...args: unknown[]) => T;
-declare const isNonNullObject: (value: unknown) => value is NonNullable<object>;
-declare const isObjectOfType: <T>(value: unknown, type: string) => value is T;
-declare const isRecord: <T extends Record<string, unknown>>(value: unknown) => value is T;
-declare const isRecordOrArray: <T extends Record<string | number, unknown> | ReadonlyArray<unknown>>(value: unknown) => value is T;
-declare const isUniformArray: <T>(value: unknown, guard?: (item: T) => item is T & {}) => value is T[];
-declare const hasMethod: <T extends object & Record<string, (...args: unknown[]) => unknown>>(obj: T, methodName: string) => obj is T & Record<string, (...args: unknown[]) => unknown>;
-declare const isAbortError: (error: unknown) => boolean;
-declare const valueString: (value: unknown) => string;
-export { isString, isNumber, isSymbol, isFunction, isAsyncFunction, isSyncFunction, isNonNullObject, isObjectOfType, isRecord, isRecordOrArray, isUniformArray, hasMethod, isAbortError, valueString, };
+}>(fn: unknown): fn is (...args: unknown[]) => T;
+declare function isObjectOfType<T>(value: unknown, type: string): value is T;
+declare function isRecord<T extends Record<string, unknown>>(value: unknown): value is T;
+declare function isUniformArray<T>(value: unknown, guard?: (item: T) => item is T & {}): value is T[];
+declare function valueString(value: unknown): string;
+export { isFunction, isAsyncFunction, isSyncFunction, isObjectOfType, isRecord, isUniformArray, valueString, };