@zeix/cause-effect 0.17.0 → 0.17.2

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

@@ -1,3 +1,4 @@
+import { type Cleanup, type HookCallback, type WatchHook } from '../system';
 type Computed<T extends {}> = {
     readonly [Symbol.toStringTag]: 'Computed';
     get(): T;
@@ -34,6 +35,14 @@ declare class Memo<T extends {}> {
      * @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.
@@ -60,6 +69,14 @@ declare class Task<T extends {}> {
      * @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

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

@@ -1,6 +1,6 @@
 import { type UnknownArray } from '../diff';
-import { type Cleanup, type Listener, type Notifications } from '../system';
-import { Collection } from './collection';
+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;
@@ -11,7 +11,7 @@ declare class List<T extends {}> {
     #private;
     constructor(initialValue: T[], keyConfig?: KeyConfig<T>);
     get [Symbol.toStringTag](): 'List';
-    get [Symbol.isConcatSpreadable](): boolean;
+    get [Symbol.isConcatSpreadable](): true;
     [Symbol.iterator](): IterableIterator<State<T>>;
     get length(): number;
     get(): T[];
@@ -26,9 +26,9 @@ declare class List<T extends {}> {
     remove(keyOrIndex: string | number): void;
     sort(compareFn?: (a: T, b: T) => number): void;
     splice(start: number, deleteCount?: number, ...items: T[]): T[];
-    on<K extends keyof Notifications>(type: K, listener: Listener<K>): Cleanup;
-    deriveCollection<R extends {}>(callback: (sourceValue: T) => R): Collection<R, T>;
-    deriveCollection<R extends {}>(callback: (sourceValue: T, abort: AbortSignal) => Promise<R>): Collection<R, 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

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

@@ -0,0 +1,48 @@
+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,3 +1,4 @@
+import { type Cleanup, type HookCallback, type WatchHook } from '../system';
 declare const TYPE_STATE: "State";
 /**
  * Create a new state signal.
@@ -40,6 +41,14 @@ declare class State<T extends {}> {
      * @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

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

@@ -1,6 +1,6 @@
 import { type UnknownRecord } from '../diff';
 import { type MutableSignal } from '../signal';
-import { type Cleanup, type Listener, type Listeners } from '../system';
+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> & {
@@ -23,14 +23,14 @@ declare class BaseStore<T extends UnknownRecord> {
         string,
         MutableSignal<T[keyof T] & {}>
     ]>;
-    get(): T;
-    set(newValue: T): void;
     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<K extends keyof Omit<Listeners, 'sort'>>(type: K, listener: Listener<K>): Cleanup;
+    on(type: Hook, callback: HookCallback): Cleanup;
 }
 /**
  * Create a new store with deeply nested reactive properties

package/types/src/effect.d.ts

@@ -1,5 +1,4 @@
-import { type Cleanup } from './system';
-type MaybeCleanup = Cleanup | undefined | void;
+import { type Cleanup, type MaybeCleanup } from './system';
 type EffectCallback = (() => MaybeCleanup) | ((abort: AbortSignal) => Promise<MaybeCleanup>);
 /**
  * Define what happens when a reactive state changes

package/types/src/errors.d.ts

@@ -1,4 +1,5 @@
 import { type MutableSignal } from './signal';
+type Guard<T> = (value: unknown) => value is T;
 declare class CircularDependencyError extends Error {
     constructor(where: string);
 }
@@ -8,6 +9,12 @@ declare class DuplicateKeyError extends Error {
 declare class InvalidCallbackError extends TypeError {
     constructor(where: string, value: unknown);
 }
+declare class InvalidCollectionSourceError extends TypeError {
+    constructor(where: string, value: unknown);
+}
+declare class InvalidHookError extends TypeError {
+    constructor(where: string, type: string);
+}
 declare class InvalidSignalValueError extends TypeError {
     constructor(where: string, value: unknown);
 }
@@ -17,7 +24,8 @@ declare class NullishSignalValueError extends TypeError {
 declare class ReadonlySignalError extends Error {
     constructor(what: string, value: unknown);
 }
+declare const createError: (reason: unknown) => Error;
 declare const validateCallback: (where: string, value: unknown, guard?: (value: unknown) => boolean) => void;
 declare const validateSignalValue: (where: string, value: unknown, guard?: (value: unknown) => boolean) => void;
 declare const guardMutableSignal: <T extends {}>(what: string, value: unknown, signal: unknown) => signal is MutableSignal<T>;
-export { CircularDependencyError, DuplicateKeyError, InvalidCallbackError, InvalidSignalValueError, NullishSignalValueError, ReadonlySignalError, validateCallback, validateSignalValue, guardMutableSignal, };
+export { type Guard, CircularDependencyError, DuplicateKeyError, InvalidCallbackError, InvalidCollectionSourceError, InvalidHookError, InvalidSignalValueError, NullishSignalValueError, ReadonlySignalError, createError, validateCallback, validateSignalValue, guardMutableSignal, };

package/types/src/system.d.ts

@@ -1,21 +1,26 @@
 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;
-    onCleanup(cleanup: Cleanup): void;
+    on(type: CleanupHook, cleanup: Cleanup): void;
     stop(): void;
 };
-type Notifications = {
-    add: readonly string[];
-    change: readonly string[];
-    remove: readonly string[];
-    sort: readonly string[];
-};
-type Listener<K extends keyof Notifications> = (payload: Notifications[K]) => void;
-type Listeners = {
-    [K in keyof Notifications]: Set<Listener<K>>;
-};
+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 that can be used to observe changes to a signal
+ * Create a watcher to observe changes to a signal.
  *
  * A watcher is a reaction function with onCleanup and stop methods
  *
@@ -25,29 +30,31 @@ type Listeners = {
  */
 declare const createWatcher: (react: () => void) => Watcher;
 /**
- * Subscribe by adding active watcher to the Set of watchers of a signal
+ * 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>) => void;
+declare const subscribeActiveWatcher: (watchers: Set<Watcher>, watchHookCallbacks?: Set<HookCallback>) => void;
 /**
- * Notify watchers of a signal change
+ * 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>) => void;
+declare const notifyWatchers: (watchers: Set<Watcher>) => boolean;
 /**
- * Flush all pending reactions of enqueued watchers
+ * Flush all pending reactions of enqueued watchers.
  */
 declare const flushPendingReactions: () => void;
 /**
- * Batch multiple signal writes
+ * 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)
+ * 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
@@ -56,10 +63,19 @@ declare const batchSignalWrites: (callback: () => void) => void;
  */
 declare const trackSignalReads: (watcher: Watcher | false, run: () => void) => void;
 /**
- * Emit a notification to listeners
+ * 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 {Set<Listener>} listeners - Listeners to be notified
- * @param {Notifications[K]} payload - Payload to be sent to listeners
+ * @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 emitNotification: <T extends keyof Notifications>(listeners: Set<Listener<T>>, payload: Notifications[T]) => void;
-export { type Cleanup, type Watcher, type Notifications, type Listener, type Listeners, createWatcher, subscribeActiveWatcher, notifyWatchers, flushPendingReactions, batchSignalWrites, trackSignalReads, emitNotification, };
+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, };

package/types/src/util.d.ts

@@ -1,4 +1,3 @@
-declare const UNSET: any;
 declare const isString: (value: unknown) => value is string;
 declare const isNumber: (value: unknown) => value is number;
 declare const isSymbol: (value: unknown) => value is symbol;
@@ -14,6 +13,5 @@ declare const isRecordOrArray: <T extends Record<string | number, unknown> | Rea
 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 toError: (reason: unknown) => Error;
 declare const valueString: (value: unknown) => string;
-export { UNSET, isString, isNumber, isSymbol, isFunction, isAsyncFunction, isSyncFunction, isNonNullObject, isObjectOfType, isRecord, isRecordOrArray, isUniformArray, hasMethod, isAbortError, toError, valueString, };
+export { isString, isNumber, isSymbol, isFunction, isAsyncFunction, isSyncFunction, isNonNullObject, isObjectOfType, isRecord, isRecordOrArray, isUniformArray, hasMethod, isAbortError, valueString, };