@zeix/cause-effect 0.17.3 → 0.18.1

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

@@ -0,0 +1,81 @@
+import { type Cleanup, type SignalOptions } from '../graph';
+/**
+ * A read-only signal that tracks external input and updates a state value as long as it is active.
+ *
+ * @template T - The type of value produced by the sensor
+ */
+type Sensor<T extends {}> = {
+    readonly [Symbol.toStringTag]: 'Sensor';
+    /**
+     * Gets the current value of the sensor.
+     * When called inside another reactive context, creates a dependency.
+     * @returns The sensor value
+     * @throws UnsetSignalValueError If the sensor value is still unset when read.
+     */
+    get(): T;
+};
+/**
+ * A callback function for sensors when the sensor starts being watched.
+ *
+ * @template T - The type of value observed
+ * @param set - A function to set the observed value
+ * @returns A cleanup function when the sensor stops being watched
+ */
+type SensorOptions<T extends {}> = SignalOptions<T> & {
+    /**
+     * Optional initial value. Avoids `UnsetSignalValueError` on first read
+     * before the watched callback fires.
+     */
+    value?: T;
+};
+type SensorCallback<T extends {}> = (set: (next: T) => void) => Cleanup;
+/**
+ * Creates a sensor that tracks external input and updates a state value as long as it is active.
+ * Sensors get activated when they are first accessed by an effect and deactivated when they are
+ * no longer watched. This lazy activation pattern ensures resources are only consumed when needed.
+ *
+ * @since 0.18.0
+ * @template T - The type of value produced by the sensor
+ * @param watched - The callback invoked when the sensor starts being watched, receives a `set` function and returns a cleanup function.
+ * @param options - Optional configuration for the sensor.
+ * @param options.value - Optional initial value. Avoids `UnsetSignalValueError` on first read
+ *   before the watched callback fires. Essential for the mutable-object observation pattern.
+ * @param options.equals - Optional equality function. Defaults to strict equality (`===`). Use `SKIP_EQUALITY`
+ *   for mutable objects where the reference stays the same but internal state changes.
+ * @param options.guard - Optional type guard to validate values.
+ * @returns A read-only sensor signal.
+ *
+ * @example Tracking external values
+ * ```ts
+ * const mousePos = createSensor<{ x: number; y: number }>((set) => {
+ *   const handler = (e: MouseEvent) => {
+ *     set({ x: e.clientX, y: e.clientY });
+ *   };
+ *   window.addEventListener('mousemove', handler);
+ *   return () => window.removeEventListener('mousemove', handler);
+ * });
+ * ```
+ *
+ * @example Observing a mutable object
+ * ```ts
+ * import { createSensor, SKIP_EQUALITY } from 'cause-effect';
+ *
+ * const el = createSensor<HTMLElement>((set) => {
+ *   const node = document.getElementById('box')!;
+ *   set(node);
+ *   const obs = new MutationObserver(() => set(node));
+ *   obs.observe(node, { attributes: true });
+ *   return () => obs.disconnect();
+ * }, { value: node, equals: SKIP_EQUALITY });
+ * ```
+ */
+declare function createSensor<T extends {}>(watched: SensorCallback<T>, options?: SensorOptions<T>): Sensor<T>;
+/**
+ * Checks if a value is a Sensor signal.
+ *
+ * @since 0.18.0
+ * @param value - The value to check
+ * @returns True if the value is a Sensor
+ */
+declare function isSensor<T extends {} = unknown & {}>(value: unknown): value is Sensor<T>;
+export { createSensor, isSensor, type Sensor, type SensorCallback, type SensorOptions, };

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

@@ -0,0 +1,78 @@
+import { type SignalOptions } from '../graph';
+/**
+ * A callback function for states that updates a value based on the previous value.
+ *
+ * @template T - The type of value
+ * @param prev - The previous state value
+ * @returns The new state value
+ */
+type UpdateCallback<T extends {}> = (prev: T) => T;
+/**
+ * A mutable reactive state container.
+ * Changes to the state will automatically propagate to dependent computations and effects.
+ *
+ * @template T - The type of value stored in the state
+ */
+type State<T extends {}> = {
+    readonly [Symbol.toStringTag]: 'State';
+    /**
+     * Gets the current value of the state.
+     * When called inside a memo, task, or effect, creates a dependency.
+     * @returns The current value
+     */
+    get(): T;
+    /**
+     * Sets a new value for the state.
+     * If the new value is different (according to the equality function), all dependents will be notified.
+     * @param next - The new value to set
+     */
+    set(next: T): void;
+    /**
+     * Updates the state with a new value computed by a callback function.
+     * The callback receives the current value as an argument.
+     * @param fn - The callback function to compute the new value
+     */
+    update(fn: UpdateCallback<T>): void;
+};
+/**
+ * Creates a mutable reactive state container.
+ *
+ * @since 0.9.0
+ * @template T - The type of value stored in the state
+ * @param value - The initial value
+ * @param options - Optional configuration for the state
+ * @returns A State object with get() and set() methods
+ *
+ * @example
+ * ```ts
+ * const count = createState(0);
+ * count.set(1);
+ * console.log(count.get()); // 1
+ * ```
+ *
+ * @example
+ * ```ts
+ * // With type guard
+ * const count = createState(0, {
+ *   guard: (v): v is number => typeof v === 'number'
+ * });
+ * ```
+ */
+declare function createState<T extends {}>(value: T, options?: SignalOptions<T>): State<T>;
+/**
+ * Checks if a value is a State signal.
+ *
+ * @since 0.9.0
+ * @param value - The value to check
+ * @returns True if the value is a State
+ *
+ * @example
+ * ```ts
+ * const state = createState(0);
+ * if (isState(state)) {
+ *   state.set(1); // TypeScript knows state has set()
+ * }
+ * ```
+ */
+declare function isState<T extends {} = unknown & {}>(value: unknown): value is State<T>;
+export { createState, isState, type State, type UpdateCallback };

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

@@ -0,0 +1,51 @@
+import { type Cleanup, TYPE_STORE } from '../graph';
+import { type List, type UnknownRecord } from './list';
+import { type State } from './state';
+type StoreOptions = {
+    watched?: () => Cleanup;
+};
+type BaseStore<T extends UnknownRecord> = {
+    readonly [Symbol.toStringTag]: 'Store';
+    readonly [Symbol.isConcatSpreadable]: false;
+    [Symbol.iterator](): IterableIterator<[
+        string,
+        State<T[keyof T] & {}> | Store<UnknownRecord> | List<unknown & {}>
+    ]>;
+    keys(): IterableIterator<string>;
+    byKey<K extends keyof T & string>(key: K): T[K] extends readonly (infer U extends {})[] ? List<U> : T[K] extends UnknownRecord ? Store<T[K]> : T[K] extends unknown & {} ? State<T[K] & {}> : State<T[K] & {}> | undefined;
+    get(): T;
+    set(next: T): void;
+    update(fn: (prev: T) => T): void;
+    add<K extends keyof T & string>(key: K, value: T[K]): K;
+    remove(key: string): void;
+};
+type Store<T extends UnknownRecord> = BaseStore<T> & {
+    [K in keyof T]: T[K] extends readonly (infer U extends {})[] ? List<U> : T[K] extends UnknownRecord ? Store<T[K]> : T[K] extends unknown & {} ? State<T[K] & {}> : State<T[K] & {}> | undefined;
+};
+/**
+ * Creates a reactive store with deeply nested reactive properties.
+ * Each property becomes its own signal (State for primitives, nested Store for objects, List for arrays).
+ * Properties are accessible directly via proxy.
+ *
+ * @since 0.15.0
+ * @param value - Initial object value of the store
+ * @param options - Optional configuration for watch lifecycle
+ * @returns A Store with reactive properties
+ *
+ * @example
+ * ```ts
+ * const user = createStore({ name: 'Alice', age: 30 });
+ * user.name.set('Bob'); // Only name subscribers react
+ * console.log(user.get()); // { name: 'Bob', age: 30 }
+ * ```
+ */
+declare function createStore<T extends UnknownRecord>(value: T, options?: StoreOptions): Store<T>;
+/**
+ * Checks if a value is a Store signal.
+ *
+ * @since 0.15.0
+ * @param value - The value to check
+ * @returns True if the value is a Store
+ */
+declare function isStore<T extends UnknownRecord>(value: unknown): value is Store<T>;
+export { createStore, isStore, type Store, type StoreOptions, TYPE_STORE };

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

@@ -0,0 +1,79 @@
+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
+ * @param options.value - Optional initial value for reducer patterns
+ * @param options.equals - Optional equality function. Defaults to strict equality (`===`)
+ * @param options.guard - Optional type guard to validate values
+ * @param options.watched - Optional callback invoked when the task is first watched by an effect.
+ *   Receives an `invalidate` function to mark the task dirty and trigger re-execution.
+ *   Must return a cleanup function called when no effects are watching.
+ * @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, };