@zeix/cause-effect 0.17.2 → 0.18.0

package/types/src/classes/computed.d.ts

@@ -1,114 +0,0 @@
-import { type Cleanup, type HookCallback, type WatchHook } from '../system';
-type Computed<T extends {}> = {
-    readonly [Symbol.toStringTag]: 'Computed';
-    get(): T;
-};
-type MemoCallback<T extends {} & {
-    then?: undefined;
-}> = (oldValue: T) => T;
-type TaskCallback<T extends {} & {
-    then?: undefined;
-}> = (oldValue: T, abort: AbortSignal) => Promise<T>;
-declare const TYPE_COMPUTED: "Computed";
-/**
- * Create a new memoized signal for a synchronous function.
- *
- * @since 0.17.0
- */
-declare class Memo<T extends {}> {
-    #private;
-    /**
-     * Create a new memoized signal.
-     *
-     * @param {MemoCallback<T>} callback - Callback function to compute the memoized value
-     * @param {T} [initialValue = UNSET] - Initial value of the signal
-     * @throws {InvalidCallbackError} If the callback is not an sync function
-     * @throws {InvalidSignalValueError} If the initial value is not valid
-     */
-    constructor(callback: MemoCallback<T>, initialValue?: T);
-    get [Symbol.toStringTag](): 'Computed';
-    /**
-     * Return the memoized value after computing it if necessary.
-     *
-     * @returns {T}
-     * @throws {CircularDependencyError} If a circular dependency is detected
-     * @throws {Error} If an error occurs during computation
-     */
-    get(): T;
-    /**
-     * Register a callback to be called when HOOK_WATCH is triggered.
-     *
-     * @param {WatchHook} type - The type of hook to register the callback for; only HOOK_WATCH is supported
-     * @param {HookCallback} callback - The callback to register
-     * @returns {Cleanup} - A function to unregister the callback
-     */
-    on(type: WatchHook, callback: HookCallback): Cleanup;
-}
-/**
- * Create a new task signals that memoizes the result of an asynchronous function.
- *
- * @since 0.17.0
- */
-declare class Task<T extends {}> {
-    #private;
-    /**
-     * Create a new task signal for an asynchronous function.
-     *
-     * @param {TaskCallback<T>} callback - The asynchronous function to compute the memoized value
-     * @param {T} [initialValue = UNSET] - Initial value of the signal
-     * @throws {InvalidCallbackError} If the callback is not an async function
-     * @throws {InvalidSignalValueError} If the initial value is not valid
-     */
-    constructor(callback: TaskCallback<T>, initialValue?: T);
-    get [Symbol.toStringTag](): 'Computed';
-    /**
-     * Return the memoized value after executing the async function if necessary.
-     *
-     * @returns {T}
-     * @throws {CircularDependencyError} If a circular dependency is detected
-     * @throws {Error} If an error occurs during computation
-     */
-    get(): T;
-    /**
-     * Register a callback to be called when HOOK_WATCH is triggered.
-     *
-     * @param {WatchHook} type - The type of hook to register the callback for; only HOOK_WATCH is supported
-     * @param {HookCallback} callback - The callback to register
-     * @returns {Cleanup} - A function to unregister the callback
-     */
-    on(type: WatchHook, callback: HookCallback): Cleanup;
-}
-/**
- * Create a derived signal from existing signals
- *
- * @since 0.9.0
- * @param {MemoCallback<T> | TaskCallback<T>} callback - Computation callback function
- */
-declare const createComputed: <T extends {}>(callback: TaskCallback<T> | MemoCallback<T>, initialValue?: T) => Task<T> | Memo<T>;
-/**
- * Check if a value is a computed signal
- *
- * @since 0.9.0
- * @param {unknown} value - Value to check
- * @returns {boolean} - True if value is a computed signal, false otherwise
- */
-declare const isComputed: <T extends {}>(value: unknown) => value is Memo<T>;
-/**
- * Check if the provided value is a callback that may be used as input for createSignal() to derive a computed state
- *
- * @since 0.12.0
- * @param {unknown} value - Value to check
- * @returns {boolean} - True if value is a sync callback, false otherwise
- */
-declare const isMemoCallback: <T extends {} & {
-    then?: undefined;
-}>(value: unknown) => value is MemoCallback<T>;
-/**
- * Check if the provided value is a callback that may be used as input for createSignal() to derive a computed state
- *
- * @since 0.17.0
- * @param {unknown} value - Value to check
- * @returns {boolean} - True if value is an async callback, false otherwise
- */
-declare const isTaskCallback: <T extends {}>(value: unknown) => value is TaskCallback<T>;
-export { TYPE_COMPUTED, createComputed, isComputed, isMemoCallback, isTaskCallback, Memo, Task, type Computed, type MemoCallback, type TaskCallback, };

package/types/src/classes/list.d.ts

@@ -1,41 +0,0 @@
-import { type UnknownArray } from '../diff';
-import { type Cleanup, type Hook, type HookCallback } from '../system';
-import { DerivedCollection } from './collection';
-import { State } from './state';
-type ArrayToRecord<T extends UnknownArray> = {
-    [key: string]: T extends Array<infer U extends {}> ? U : never;
-};
-type KeyConfig<T> = string | ((item: T) => string);
-declare const TYPE_LIST: "List";
-declare class List<T extends {}> {
-    #private;
-    constructor(initialValue: T[], keyConfig?: KeyConfig<T>);
-    get [Symbol.toStringTag](): 'List';
-    get [Symbol.isConcatSpreadable](): true;
-    [Symbol.iterator](): IterableIterator<State<T>>;
-    get length(): number;
-    get(): T[];
-    set(newValue: T[]): void;
-    update(fn: (oldValue: T[]) => T[]): void;
-    at(index: number): State<T> | undefined;
-    keys(): IterableIterator<string>;
-    byKey(key: string): State<T> | undefined;
-    keyAt(index: number): string | undefined;
-    indexOfKey(key: string): number;
-    add(value: T): string;
-    remove(keyOrIndex: string | number): void;
-    sort(compareFn?: (a: T, b: T) => number): void;
-    splice(start: number, deleteCount?: number, ...items: T[]): T[];
-    on(type: Hook, callback: HookCallback): Cleanup;
-    deriveCollection<R extends {}>(callback: (sourceValue: T) => R): DerivedCollection<R, T>;
-    deriveCollection<R extends {}>(callback: (sourceValue: T, abort: AbortSignal) => Promise<R>): DerivedCollection<R, T>;
-}
-/**
- * Check if the provided value is a List instance
- *
- * @since 0.15.0
- * @param {unknown} value - Value to check
- * @returns {boolean} - True if the value is a List instance, false otherwise
- */
-declare const isList: <T extends {}>(value: unknown) => value is List<T>;
-export { isList, List, TYPE_LIST, type ArrayToRecord, type KeyConfig };

package/types/src/classes/ref.d.ts

@@ -1,48 +0,0 @@
-import { type Guard } from '../errors';
-import { type Cleanup, type HookCallback, type WatchHook } from '../system';
-declare const TYPE_REF = "Ref";
-/**
- * Create a new ref signal.
- *
- * @since 0.17.1
- */
-declare class Ref<T extends {}> {
-    #private;
-    /**
-     * Create a new ref signal.
-     *
-     * @param {T} value - Reference to external object
-     * @param {Guard<T>} guard - Optional guard function to validate the value
-     * @throws {NullishSignalValueError} - If the value is null or undefined
-     * @throws {InvalidSignalValueError} - If the value is invalid
-     */
-    constructor(value: T, guard?: Guard<T>);
-    get [Symbol.toStringTag](): string;
-    /**
-     * Get the value of the ref signal.
-     *
-     * @returns {T} - Object reference
-     */
-    get(): T;
-    /**
-     * Notify watchers of relevant changes in the external reference.
-     */
-    notify(): void;
-    /**
-     * Register a callback to be called when HOOK_WATCH is triggered.
-     *
-     * @param {WatchHook} type - The type of hook to register the callback for; only HOOK_WATCH is supported
-     * @param {HookCallback} callback - The callback to register
-     * @returns {Cleanup} - A function to unregister the callback
-     */
-    on(type: WatchHook, callback: HookCallback): Cleanup;
-}
-/**
- * Check if the provided value is a Ref instance
- *
- * @since 0.17.1
- * @param {unknown} value - Value to check
- * @returns {boolean} - True if the value is a Ref instance, false otherwise
- */
-declare const isRef: <T extends {}>(value: unknown) => value is Ref<T>;
-export { TYPE_REF, Ref, isRef };

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

@@ -1,61 +0,0 @@
-import { type Cleanup, type HookCallback, type WatchHook } from '../system';
-declare const TYPE_STATE: "State";
-/**
- * Create a new state signal.
- *
- * @since 0.17.0
- */
-declare class State<T extends {}> {
-    #private;
-    /**
-     * Create a new state signal.
-     *
-     * @param {T} initialValue - Initial value of the state
-     * @throws {NullishSignalValueError} - If the initial value is null or undefined
-     * @throws {InvalidSignalValueError} - If the initial value is invalid
-     */
-    constructor(initialValue: T);
-    get [Symbol.toStringTag](): string;
-    /**
-     * Get the current value of the state signal.
-     *
-     * @returns {T} - Current value of the state
-     */
-    get(): T;
-    /**
-     * Set the value of the state signal.
-     *
-     * @param {T} newValue - New value of the state
-     * @returns {void}
-     * @throws {NullishSignalValueError} - If the initial value is null or undefined
-     * @throws {InvalidSignalValueError} - If the initial value is invalid
-     */
-    set(newValue: T): void;
-    /**
-     * Update the value of the state signal.
-     *
-     * @param {Function} updater - Function that takes the current value and returns the new value
-     * @returns {void}
-     * @throws {InvalidCallbackError} - If the updater function is not a function
-     * @throws {NullishSignalValueError} - If the initial value is null or undefined
-     * @throws {InvalidSignalValueError} - If the initial value is invalid
-     */
-    update(updater: (oldValue: T) => T): void;
-    /**
-     * Register a callback to be called when HOOK_WATCH is triggered.
-     *
-     * @param {WatchHook} type - The type of hook to register the callback for; only HOOK_WATCH is supported
-     * @param {HookCallback} callback - The callback to register
-     * @returns {Cleanup} - A function to unregister the callback
-     */
-    on(type: WatchHook, callback: HookCallback): Cleanup;
-}
-/**
- * Check if the provided value is a State instance
- *
- * @since 0.9.0
- * @param {unknown} value - Value to check
- * @returns {boolean} - True if the value is a State instance, false otherwise
- */
-declare const isState: <T extends {}>(value: unknown) => value is State<T>;
-export { TYPE_STATE, isState, State };

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

@@ -1,51 +0,0 @@
-import { type UnknownRecord } from '../diff';
-import { type MutableSignal } from '../signal';
-import { type Cleanup, type Hook, type HookCallback } from '../system';
-import type { List } from './list';
-import type { State } from './state';
-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]> : State<T[K] & {}>;
-};
-declare const TYPE_STORE: "Store";
-declare class BaseStore<T extends UnknownRecord> {
-    #private;
-    /**
-     * Create a new store with the given initial value.
-     *
-     * @param {T} initialValue - The initial value of the store
-     * @throws {NullishSignalValueError} - If the initial value is null or undefined
-     * @throws {InvalidSignalValueError} - If the initial value is not an object
-     */
-    constructor(initialValue: T);
-    get [Symbol.toStringTag](): 'Store';
-    get [Symbol.isConcatSpreadable](): boolean;
-    [Symbol.iterator](): IterableIterator<[
-        string,
-        MutableSignal<T[keyof T] & {}>
-    ]>;
-    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(newValue: T): void;
-    update(fn: (oldValue: T) => T): void;
-    add<K extends keyof T & string>(key: K, value: T[K]): K;
-    remove(key: string): void;
-    on(type: Hook, callback: HookCallback): Cleanup;
-}
-/**
- * Create a new store with deeply nested reactive properties
- *
- * @since 0.15.0
- * @param {T} initialValue - Initial object or array value of the store
- * @returns {Store<T>} - New store with reactive properties that preserves the original type T
- */
-declare const createStore: <T extends UnknownRecord>(initialValue: T) => Store<T>;
-/**
- * Check if the provided value is a Store instance
- *
- * @since 0.15.0
- * @param {unknown} value - Value to check
- * @returns {boolean} - True if the value is a Store instance, false otherwise
- */
-declare const isStore: <T extends UnknownRecord>(value: unknown) => value is BaseStore<T>;
-export { createStore, isStore, BaseStore, TYPE_STORE, type Store };

package/types/src/diff.d.ts

@@ -1,28 +0,0 @@
-type UnknownRecord = Record<string, unknown>;
-type UnknownArray = ReadonlyArray<unknown & {}>;
-type DiffResult = {
-    changed: boolean;
-    add: UnknownRecord;
-    change: UnknownRecord;
-    remove: UnknownRecord;
-};
-/**
- * Checks if two values are equal with cycle detection
- *
- * @since 0.15.0
- * @param {T} a - First value to compare
- * @param {T} b - Second value to compare
- * @param {WeakSet<object>} visited - Set to track visited objects for cycle detection
- * @returns {boolean} Whether the two values are equal
- */
-declare const isEqual: <T>(a: T, b: T, visited?: WeakSet<object>) => boolean;
-/**
- * Compares two records and returns a result object containing the differences.
- *
- * @since 0.15.0
- * @param {T} oldObj - The old record to compare
- * @param {T} newObj - The new record to compare
- * @returns {DiffResult} The result of the comparison
- */
-declare const diff: <T extends UnknownRecord>(oldObj: T, newObj: T) => DiffResult;
-export { type DiffResult, diff, isEqual, type UnknownRecord, type UnknownArray };

package/types/src/effect.d.ts

@@ -1,15 +0,0 @@
-import { type Cleanup, type MaybeCleanup } from './system';
-type EffectCallback = (() => MaybeCleanup) | ((abort: AbortSignal) => Promise<MaybeCleanup>);
-/**
- * Define what happens when a reactive state changes
- *
- * The callback can be synchronous or asynchronous. Async callbacks receive
- * an AbortSignal parameter, which is automatically aborted when the effect
- * re-runs or is cleaned up, preventing stale async operations.
- *
- * @since 0.1.0
- * @param {EffectCallback} callback - Synchronous or asynchronous effect callback
- * @returns {Cleanup} - Cleanup function for the effect
- */
-declare const createEffect: (callback: EffectCallback) => Cleanup;
-export { type MaybeCleanup, type EffectCallback, createEffect };

package/types/src/match.d.ts

@@ -1,21 +0,0 @@
-import type { ResolveResult } from './resolve';
-import type { SignalValues, UnknownSignalRecord } from './signal';
-type MatchHandlers<S extends UnknownSignalRecord> = {
-    ok: (values: SignalValues<S>) => void;
-    err?: (errors: readonly Error[]) => void;
-    nil?: () => void;
-};
-/**
- * Match on resolve result and call appropriate handler for side effects
- *
- * This is a utility function for those who prefer the handler pattern.
- * All handlers are for side effects only and return void. If you need
- * cleanup logic, use a hoisted let variable in your effect.
- *
- * @since 0.15.0
- * @param {ResolveResult<S>} result - Result from resolve()
- * @param {MatchHandlers<S>} handlers - Handlers for different states (side effects only)
- * @returns {void} - Always returns void
- */
-declare function match<S extends UnknownSignalRecord>(result: ResolveResult<S>, handlers: MatchHandlers<S>): void;
-export { match, type MatchHandlers };

package/types/src/resolve.d.ts

@@ -1,29 +0,0 @@
-import type { SignalValues, UnknownSignalRecord } from './signal';
-type ResolveResult<S extends UnknownSignalRecord> = {
-    ok: true;
-    values: SignalValues<S>;
-    errors?: never;
-    pending?: never;
-} | {
-    ok: false;
-    errors: readonly Error[];
-    values?: never;
-    pending?: never;
-} | {
-    ok: false;
-    pending: true;
-    values?: never;
-    errors?: never;
-};
-/**
- * Resolve signal values with perfect type inference
- *
- * Always returns a discriminated union result, regardless of whether
- * handlers are provided or not. This ensures a predictable API.
- *
- * @since 0.15.0
- * @param {S} signals - Signals to resolve
- * @returns {ResolveResult<S>} - Discriminated union result
- */
-declare function resolve<S extends UnknownSignalRecord>(signals: S): ResolveResult<S>;
-export { resolve, type ResolveResult };

package/types/src/system.d.ts

@@ -1,81 +0,0 @@
-type Cleanup = () => void;
-type MaybeCleanup = Cleanup | undefined | void;
-type Hook = 'add' | 'change' | 'cleanup' | 'remove' | 'sort' | 'watch';
-type CleanupHook = 'cleanup';
-type WatchHook = 'watch';
-type HookCallback = (payload?: readonly string[]) => MaybeCleanup;
-type HookCallbacks = {
-    [K in Hook]?: Set<HookCallback>;
-};
-type Watcher = {
-    (): void;
-    on(type: CleanupHook, cleanup: Cleanup): void;
-    stop(): void;
-};
-declare const UNSET: any;
-declare const HOOK_ADD = "add";
-declare const HOOK_CHANGE = "change";
-declare const HOOK_CLEANUP = "cleanup";
-declare const HOOK_REMOVE = "remove";
-declare const HOOK_SORT = "sort";
-declare const HOOK_WATCH = "watch";
-/**
- * Create a watcher to observe changes to a signal.
- *
- * A watcher is a reaction function with onCleanup and stop methods
- *
- * @since 0.14.1
- * @param {() => void} react - Function to be called when the state changes
- * @returns {Watcher} - Watcher object with off and cleanup methods
- */
-declare const createWatcher: (react: () => void) => Watcher;
-/**
- * Subscribe by adding active watcher to the Set of watchers of a signal.
- *
- * @param {Set<Watcher>} watchers - Watchers of the signal
- * @param {Set<HookCallback>} watchHookCallbacks - HOOK_WATCH callbacks of the signal
- */
-declare const subscribeActiveWatcher: (watchers: Set<Watcher>, watchHookCallbacks?: Set<HookCallback>) => void;
-/**
- * Notify watchers of a signal change.
- *
- * @param {Set<Watcher>} watchers - Watchers of the signal
- * @returns {boolean} - Whether any watchers were notified
- */
-declare const notifyWatchers: (watchers: Set<Watcher>) => boolean;
-/**
- * Flush all pending reactions of enqueued watchers.
- */
-declare const flushPendingReactions: () => void;
-/**
- * Batch multiple signal writes.
- *
- * @param {() => void} callback - Function with multiple signal writes to be batched
- */
-declare const batchSignalWrites: (callback: () => void) => void;
-/**
- * Run a function with signal reads in a tracking context (or temporarily untrack).
- *
- * @param {Watcher | false} watcher - Watcher to be called when the signal changes
- *                                    or false for temporary untracking while inserting auto-hydrating DOM nodes
- *                                    that might read signals (e.g., Web Components)
- * @param {() => void} run - Function to run the computation or effect
- */
-declare const trackSignalReads: (watcher: Watcher | false, run: () => void) => void;
-/**
- * Trigger a hook.
- *
- * @param {Set<HookCallback> | undefined} callbacks - Callbacks to be called when the hook is triggered
- * @param {readonly string[] | undefined} payload - Payload to be sent to listeners
- * @return {Cleanup | undefined} Cleanup function to be called when the hook is unmounted
- */
-declare const triggerHook: (callbacks: Set<HookCallback> | undefined, payload?: readonly string[]) => Cleanup | undefined;
-/**
- * Check whether a hook type is handled in a signal.
- *
- * @param {Hook} type - Type of hook to check
- * @param {T} handled - List of handled hook types
- * @returns {type is T[number]} - Whether the hook type is handled
- */
-declare const isHandledHook: <T extends readonly Hook[]>(type: Hook, handled: T) => type is T[number];
-export { type Cleanup, type MaybeCleanup, type Watcher, type Hook, type CleanupHook, type WatchHook, type HookCallback, type HookCallbacks, HOOK_ADD, HOOK_CHANGE, HOOK_CLEANUP, HOOK_REMOVE, HOOK_SORT, HOOK_WATCH, UNSET, createWatcher, subscribeActiveWatcher, notifyWatchers, flushPendingReactions, batchSignalWrites, trackSignalReads, triggerHook, isHandledHook, };