@zeix/cause-effect 0.15.2 → 0.16.0

package/test/util/dependency-graph.ts

@@ -1,6 +1,6 @@
+import { Random } from 'random'
 import type { TestConfig } from './framework-types'
 import type { Computed, ReactiveFramework, Signal } from './reactive-framework'
-import { Random } from 'random'
 
 export interface Graph {
 	sources: Signal<number>[]

package/types/index.d.ts

@@ -1,16 +1,16 @@
 /**
  * @name Cause & Effect
- * @version 0.15.1
+ * @version 0.16.0
  * @author Esther Brunner
  */
-export { type Computed, type ComputedCallback, computed, isComputed, isComputedCallback, TYPE_COMPUTED, } from './src/computed';
+export { type Computed, type ComputedCallback, createComputed, isComputed, isComputedCallback, TYPE_COMPUTED, } from './src/computed';
 export { type DiffResult, diff, isEqual, type UnknownArray, type UnknownRecord, type UnknownRecordOrArray, } from './src/diff';
-export { type EffectCallback, effect, type MaybeCleanup } from './src/effect';
-export { CircularDependencyError, InvalidSignalValueError, NullishSignalValueError, StoreKeyExistsError, StoreKeyRangeError, StoreKeyReadonlyError, } from './src/errors';
+export { createEffect, type EffectCallback, type MaybeCleanup, } from './src/effect';
+export { CircularDependencyError, InvalidCallbackError, InvalidSignalValueError, NullishSignalValueError, StoreKeyExistsError, StoreKeyRangeError, StoreKeyReadonlyError, } from './src/errors';
 export { type MatchHandlers, match } from './src/match';
 export { type ResolveResult, resolve } from './src/resolve';
-export { batch, type Cleanup, enqueue, flush, notify, observe, subscribe, type Updater, type Watcher, watch, } from './src/scheduler';
 export { isMutableSignal, isSignal, type Signal, type SignalValues, toSignal, type UnknownSignalRecord, } from './src/signal';
-export { isState, type State, state, TYPE_STATE } from './src/state';
-export { isStore, type Store, type StoreAddEvent, type StoreChangeEvent, type StoreEventMap, type StoreRemoveEvent, type StoreSortEvent, store, TYPE_STORE, } from './src/store';
-export { isAbortError, isAsyncFunction, isFunction, isNumber, isRecord, isRecordOrArray, isString, isSymbol, toError, UNSET, } from './src/util';
+export { createState, isState, type State, TYPE_STATE } from './src/state';
+export { createStore, isStore, type Store, type StoreChanges, TYPE_STORE, } from './src/store';
+export { batch, type Cleanup, createWatcher, flush, notify, observe, subscribe, type Watcher, } from './src/system';
+export { isAbortError, isAsyncFunction, isFunction, isNumber, isRecord, isRecordOrArray, isString, isSymbol, toError, UNSET, valueString, } from './src/util';

package/types/src/collection.d.ts

@@ -0,0 +1,26 @@
+import type { UnknownArray } from './diff';
+import { type Store, type StoreChanges } from './store';
+import { type Cleanup } from './system';
+type Collection<T extends UnknownArray> = {
+    readonly [Symbol.toStringTag]: 'Collection';
+    get(): T;
+    on<K extends keyof StoreChanges<T>>(type: K, listener: (change: StoreChanges<T>[K]) => void): Cleanup;
+};
+type CollectionCallback<T extends UnknownArray> = (store: Store<T>) => T;
+declare const TYPE_COLLECTION = "Collection";
+/**
+ * Create a collection signal
+ *
+ * @param {CollectionCallback<T>} fn - callback function to create the collection
+ * @returns {Collection<T>} - collection signal
+ */
+declare const createCollection: <T extends UnknownArray>(fn: CollectionCallback<T>) => Collection<T>;
+/**
+ * Check if a value is a collection signal
+ *
+ * @since 0.16.0
+ * @param {unknown} value - value to check
+ * @returns {boolean} - true if value is a computed state, false otherwise
+ */
+declare const isCollection: <T extends UnknownArray>(value: unknown) => value is Collection<T>;
+export { TYPE_COLLECTION, createCollection, isCollection, type Collection };

package/types/src/computed.d.ts

@@ -1,33 +1,33 @@
 type Computed<T extends {}> = {
-    [Symbol.toStringTag]: 'Computed';
+    readonly [Symbol.toStringTag]: 'Computed';
     get(): T;
 };
 type ComputedCallback<T extends {} & {
     then?: undefined;
-}> = ((abort: AbortSignal) => Promise<T>) | (() => T);
+}> = ((oldValue: T, abort: AbortSignal) => Promise<T>) | ((oldValue: T) => T);
 declare const TYPE_COMPUTED = "Computed";
 /**
  * Create a derived signal from existing signals
  *
  * @since 0.9.0
- * @param {ComputedCallback<T>} fn - computation callback function
+ * @param {ComputedCallback<T>} callback - Computation callback function
  * @returns {Computed<T>} - Computed signal
  */
-declare const computed: <T extends {}>(fn: ComputedCallback<T>) => Computed<T>;
+declare const createComputed: <T extends {}>(callback: ComputedCallback<T>, initialValue?: T) => Computed<T>;
 /**
- * Check if a value is a computed state
+ * 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 state, false otherwise
+ * @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 Computed<T>;
 /**
  * Check if the provided value is a callback that may be used as input for toSignal() to derive a computed state
  *
  * @since 0.12.0
- * @param {unknown} value - value to check
+ * @param {unknown} value - Value to check
  * @returns {boolean} - true if value is a callback or callbacks object, false otherwise
  */
 declare const isComputedCallback: <T extends {}>(value: unknown) => value is ComputedCallback<T>;
-export { TYPE_COMPUTED, computed, isComputed, isComputedCallback, type Computed, type ComputedCallback, };
+export { TYPE_COMPUTED, createComputed, isComputed, isComputedCallback, type Computed, type ComputedCallback, };

package/types/src/effect.d.ts

@@ -1,4 +1,4 @@
-import { type Cleanup } from './scheduler';
+import { type Cleanup } from './system';
 type MaybeCleanup = Cleanup | undefined | void;
 type EffectCallback = (() => MaybeCleanup) | ((abort: AbortSignal) => Promise<MaybeCleanup>);
 /**
@@ -12,5 +12,5 @@ type EffectCallback = (() => MaybeCleanup) | ((abort: AbortSignal) => Promise<Ma
  * @param {EffectCallback} callback - Synchronous or asynchronous effect callback
  * @returns {Cleanup} - Cleanup function for the effect
  */
-declare const effect: (callback: EffectCallback) => Cleanup;
-export { type MaybeCleanup, type EffectCallback, effect };
+declare const createEffect: (callback: EffectCallback) => Cleanup;
+export { type MaybeCleanup, type EffectCallback, createEffect };

package/types/src/errors.d.ts

@@ -1,6 +1,9 @@
 declare class CircularDependencyError extends Error {
     constructor(where: string);
 }
+declare class InvalidCallbackError extends TypeError {
+    constructor(where: string, value: string);
+}
 declare class InvalidSignalValueError extends TypeError {
     constructor(where: string, value: string);
 }
@@ -16,4 +19,4 @@ declare class StoreKeyRangeError extends RangeError {
 declare class StoreKeyReadonlyError extends Error {
     constructor(key: string, value: string);
 }
-export { CircularDependencyError, InvalidSignalValueError, NullishSignalValueError, StoreKeyExistsError, StoreKeyRangeError, StoreKeyReadonlyError, };
+export { CircularDependencyError, InvalidCallbackError, InvalidSignalValueError, NullishSignalValueError, StoreKeyExistsError, StoreKeyRangeError, StoreKeyReadonlyError, };

package/types/src/state.d.ts

@@ -1,8 +1,8 @@
 type State<T extends {}> = {
-    [Symbol.toStringTag]: 'State';
+    readonly [Symbol.toStringTag]: 'State';
     get(): T;
-    set(v: T): void;
-    update(fn: (v: T) => T): void;
+    set(newValue: T): void;
+    update(updater: (oldValue: T) => T): void;
 };
 declare const TYPE_STATE = "State";
 /**
@@ -12,7 +12,7 @@ declare const TYPE_STATE = "State";
  * @param {T} initialValue - initial value of the state
  * @returns {State<T>} - new state signal
  */
-declare const state: <T extends {}>(initialValue: T) => State<T>;
+declare const createState: <T extends {}>(initialValue: T) => State<T>;
 /**
  * Check if the provided value is a State instance
  *
@@ -21,4 +21,4 @@ declare const state: <T extends {}>(initialValue: T) => State<T>;
  * @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, type State };
+export { TYPE_STATE, isState, createState, type State };

package/types/src/store.d.ts

@@ -1,60 +1,46 @@
 import { type UnknownArray, type UnknownRecord, type UnknownRecordOrArray } from './diff';
 import { type State } from './state';
+import { type Cleanup } from './system';
 type ArrayItem<T> = T extends readonly (infer U extends {})[] ? U : never;
-type StoreEventMap<T extends UnknownRecord | UnknownArray> = {
-    'store-add': StoreAddEvent<T>;
-    'store-change': StoreChangeEvent<T>;
-    'store-remove': StoreRemoveEvent<T>;
-    'store-sort': StoreSortEvent;
+type StoreChanges<T> = {
+    add: Partial<T>;
+    change: Partial<T>;
+    remove: Partial<T>;
+    sort: string[];
 };
-interface StoreEventTarget<T extends UnknownRecord | UnknownArray> extends EventTarget {
-    addEventListener<K extends keyof StoreEventMap<T>>(type: K, listener: (event: StoreEventMap<T>[K]) => void, options?: boolean | AddEventListenerOptions): void;
-    removeEventListener<K extends keyof StoreEventMap<T>>(type: K, listener: (event: StoreEventMap<T>[K]) => void, options?: boolean | EventListenerOptions): void;
-    dispatchEvent(event: Event): boolean;
-}
-interface BaseStore<T extends UnknownRecord | UnknownArray> extends StoreEventTarget<T> {
+interface BaseStore {
     readonly [Symbol.toStringTag]: 'Store';
-    get(): T;
-    set(value: T): void;
-    update(fn: (value: T) => T): void;
-    sort<U = T extends UnknownArray ? ArrayItem<T> : T[Extract<keyof T, string>]>(compareFn?: (a: U, b: U) => number): void;
     readonly size: State<number>;
 }
-type RecordStore<T extends UnknownRecord> = BaseStore<T> & {
+type RecordStore<T extends UnknownRecord> = BaseStore & {
     [K in keyof T]: T[K] extends readonly unknown[] | Record<string, unknown> ? Store<T[K]> : State<T[K]>;
 } & {
-    add<K extends Extract<keyof T, string>>(key: K, value: T[K]): void;
-    remove<K extends Extract<keyof T, string>>(key: K): void;
     [Symbol.iterator](): IterableIterator<[
         Extract<keyof T, string>,
         T[Extract<keyof T, string>] extends readonly unknown[] | Record<string, unknown> ? Store<T[Extract<keyof T, string>]> : State<T[Extract<keyof T, string>]>
     ]>;
+    add<K extends Extract<keyof T, string>>(key: K, value: T[K]): void;
+    get(): T;
+    set(value: T): void;
+    update(fn: (value: T) => T): void;
+    sort<U = T[Extract<keyof T, string>]>(compareFn?: (a: U, b: U) => number): void;
+    on<K extends keyof StoreChanges<T>>(type: K, listener: (change: StoreChanges<T>[K]) => void): Cleanup;
+    remove<K extends Extract<keyof T, string>>(key: K): void;
 };
-type ArrayStore<T extends UnknownArray> = BaseStore<T> & {
-    readonly length: number;
+type ArrayStore<T extends UnknownArray> = BaseStore & {
+    [Symbol.iterator](): IterableIterator<ArrayItem<T> extends readonly unknown[] | Record<string, unknown> ? Store<ArrayItem<T>> : State<ArrayItem<T>>>;
+    readonly [Symbol.isConcatSpreadable]: boolean;
     [n: number]: ArrayItem<T> extends readonly unknown[] | Record<string, unknown> ? Store<ArrayItem<T>> : State<ArrayItem<T>>;
     add(value: ArrayItem<T>): void;
+    get(): T;
+    set(value: T): void;
+    update(fn: (value: T) => T): void;
+    sort<U = ArrayItem<T>>(compareFn?: (a: U, b: U) => number): void;
+    on<K extends keyof StoreChanges<T>>(type: K, listener: (change: StoreChanges<T>[K]) => void): Cleanup;
     remove(index: number): void;
-    [Symbol.iterator](): IterableIterator<ArrayItem<T> extends readonly unknown[] | Record<string, unknown> ? Store<ArrayItem<T>> : State<ArrayItem<T>>>;
-    readonly [Symbol.isConcatSpreadable]: boolean;
+    readonly length: number;
 };
-interface StoreAddEvent<T extends UnknownRecord | UnknownArray> extends CustomEvent {
-    type: 'store-add';
-    detail: Partial<T>;
-}
-interface StoreChangeEvent<T extends UnknownRecord | UnknownArray> extends CustomEvent {
-    type: 'store-change';
-    detail: Partial<T>;
-}
-interface StoreRemoveEvent<T extends UnknownRecord | UnknownArray> extends CustomEvent {
-    type: 'store-remove';
-    detail: Partial<T>;
-}
-interface StoreSortEvent extends CustomEvent {
-    type: 'store-sort';
-    detail: string[];
-}
-type Store<T> = T extends UnknownRecord ? RecordStore<T> : T extends UnknownArray ? ArrayStore<T> : never;
+type Store<T extends UnknownRecord | UnknownArray> = T extends UnknownRecord ? RecordStore<T> : T extends UnknownArray ? ArrayStore<T> : never;
 declare const TYPE_STORE = "Store";
 /**
  * Create a new store with deeply nested reactive properties
@@ -68,7 +54,7 @@ declare const TYPE_STORE = "Store";
  * @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 store: <T extends UnknownRecord | UnknownArray>(initialValue: T) => Store<T>;
+declare const createStore: <T extends UnknownRecord | UnknownArray>(initialValue: T) => Store<T>;
 /**
  * Check if the provided value is a Store instance
  *
@@ -77,4 +63,4 @@ declare const store: <T extends UnknownRecord | UnknownArray>(initialValue: T) =
  * @returns {boolean} - true if the value is a Store instance, false otherwise
  */
 declare const isStore: <T extends UnknownRecordOrArray>(value: unknown) => value is Store<T>;
-export { TYPE_STORE, isStore, store, type Store, type StoreAddEvent, type StoreChangeEvent, type StoreRemoveEvent, type StoreSortEvent, type StoreEventMap, };
+export { TYPE_STORE, isStore, createStore, type Store, type StoreChanges };

package/types/src/system.d.ts

@@ -0,0 +1,44 @@
+type Cleanup = () => void;
+type Watcher = {
+    (): void;
+    unwatch(cleanup: Cleanup): void;
+    cleanup(): void;
+};
+/**
+ * Create a watcher that can be used to observe changes to a signal
+ *
+ * @since 0.14.1
+ * @param {() => void} watch - Function to be called when the state changes
+ * @returns {Watcher} - Watcher object with off and cleanup methods
+ */
+declare const createWatcher: (watch: () => void) => Watcher;
+/**
+ * Add active watcher to the Set of watchers
+ *
+ * @param {Set<Watcher>} watchers - watchers of the signal
+ */
+declare const subscribe: (watchers: Set<Watcher>) => void;
+/**
+ * Add watchers to the pending set of change notifications
+ *
+ * @param {Set<Watcher>} watchers - watchers of the signal
+ */
+declare const notify: (watchers: Set<Watcher>) => void;
+/**
+ * Flush all pending changes to notify watchers
+ */
+declare const flush: () => void;
+/**
+ * Batch multiple changes in a single signal graph and DOM update cycle
+ *
+ * @param {() => void} fn - function with multiple signal writes to be batched
+ */
+declare const batch: (fn: () => void) => void;
+/**
+ * Run a function in a reactive context
+ *
+ * @param {() => void} run - function to run the computation or effect
+ * @param {Watcher} watcher - function to be called when the state changes or undefined for temporary unwatching while inserting auto-hydrating DOM nodes that might read signals (e.g., web components)
+ */
+declare const observe: (run: () => void, watcher?: Watcher) => void;
+export { type Cleanup, type Watcher, subscribe, notify, flush, batch, createWatcher, observe, };

package/types/src/util.d.ts

@@ -4,7 +4,6 @@ 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 isDefinedObject: (value: unknown) => value is Record<string, unknown>;
 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;
@@ -14,4 +13,4 @@ declare const toError: (reason: unknown) => Error;
 declare const arrayToRecord: <T>(array: T[]) => Record<string, T>;
 declare const recordToArray: <T>(record: Record<string | number, T>) => Record<string, T> | T[];
 declare const valueString: (value: unknown) => string;
-export { UNSET, isString, isNumber, isSymbol, isFunction, isAsyncFunction, isDefinedObject, isObjectOfType, isRecord, isRecordOrArray, hasMethod, isAbortError, toError, arrayToRecord, recordToArray, valueString, };
+export { UNSET, isString, isNumber, isSymbol, isFunction, isAsyncFunction, isObjectOfType, isRecord, isRecordOrArray, hasMethod, isAbortError, toError, arrayToRecord, recordToArray, valueString, };

package/src/scheduler.ts

@@ -1,172 +0,0 @@
-/* === Types === */
-
-type Cleanup = () => void
-
-type Watcher = {
-	(): void
-	off(cleanup: Cleanup): void
-	cleanup(): void
-}
-
-type Updater = <T>() => T | boolean | undefined
-
-/* === Internal === */
-
-// Currently active watcher
-let active: Watcher | undefined
-
-// Pending queue for batched change notifications
-const pending = new Set<Watcher>()
-let batchDepth = 0
-
-// Map of deduplication symbols to update functions (using Symbol keys prevents unintended overwrites)
-const updateMap = new Map<symbol, Updater>()
-let requestId: number | undefined
-
-const updateDOM = () => {
-	requestId = undefined
-	const updates = Array.from(updateMap.values())
-	updateMap.clear()
-	for (const update of updates) {
-		update()
-	}
-}
-
-const requestTick = () => {
-	if (requestId) cancelAnimationFrame(requestId)
-	requestId = requestAnimationFrame(updateDOM)
-}
-
-// Initial render when the call stack is empty
-queueMicrotask(updateDOM)
-
-/* === Functions === */
-
-/**
- * Create a watcher that can be used to observe changes to a signal
- *
- * @since 0.14.1
- * @param {() => void} notice - function to be called when the state changes
- * @returns {Watcher} - watcher object with off and cleanup methods
- */
-const watch = (notice: () => void): Watcher => {
-	const cleanups = new Set<Cleanup>()
-	const w = notice as Partial<Watcher>
-	w.off = (on: Cleanup) => {
-		cleanups.add(on)
-	}
-	w.cleanup = () => {
-		for (const cleanup of cleanups) {
-			cleanup()
-		}
-		cleanups.clear()
-	}
-	return w as Watcher
-}
-
-/**
- * Add active watcher to the Set of watchers
- *
- * @param {Set<Watcher>} watchers - watchers of the signal
- */
-const subscribe = (watchers: Set<Watcher>) => {
-	if (active && !watchers.has(active)) {
-		const watcher = active
-		watchers.add(watcher)
-		active.off(() => {
-			watchers.delete(watcher)
-		})
-	}
-}
-
-/**
- * Add watchers to the pending set of change notifications
- *
- * @param {Set<Watcher>} watchers - watchers of the signal
- */
-const notify = (watchers: Set<Watcher>) => {
-	for (const watcher of watchers) {
-		if (batchDepth) pending.add(watcher)
-		else watcher()
-	}
-}
-
-/**
- * Flush all pending changes to notify watchers
- */
-const flush = () => {
-	while (pending.size) {
-		const watchers = Array.from(pending)
-		pending.clear()
-		for (const watcher of watchers) {
-			watcher()
-		}
-	}
-}
-
-/**
- * Batch multiple changes in a single signal graph and DOM update cycle
- *
- * @param {() => void} fn - function with multiple signal writes to be batched
- */
-const batch = (fn: () => void) => {
-	batchDepth++
-	try {
-		fn()
-	} finally {
-		flush()
-		batchDepth--
-	}
-}
-
-/**
- * Run a function in a reactive context
- *
- * @param {() => void} run - function to run the computation or effect
- * @param {Watcher} watcher - function to be called when the state changes or undefined for temporary unwatching while inserting auto-hydrating DOM nodes that might read signals (e.g., web components)
- */
-const observe = (run: () => void, watcher?: Watcher): void => {
-	const prev = active
-	active = watcher
-	try {
-		run()
-	} finally {
-		active = prev
-	}
-}
-
-/**
- * Enqueue a function to be executed on the next animation frame
- *
- * If the same Symbol is provided for multiple calls before the next animation frame,
- * only the latest call will be executed (deduplication).
- *
- * @param {Updater} fn - function to be executed on the next animation frame; can return updated value <T>, success <boolean> or void
- * @param {symbol} dedupe - Symbol for deduplication; if not provided, a unique Symbol is created ensuring the update is always executed
- */
-const enqueue = <T>(fn: Updater, dedupe?: symbol) =>
-	new Promise<T | boolean | undefined>((resolve, reject) => {
-		updateMap.set(dedupe || Symbol(), (): undefined => {
-			try {
-				resolve(fn())
-			} catch (error) {
-				reject(error)
-			}
-		})
-		requestTick()
-	})
-
-/* === Exports === */
-
-export {
-	type Cleanup,
-	type Watcher,
-	type Updater,
-	subscribe,
-	notify,
-	flush,
-	batch,
-	watch,
-	observe,
-	enqueue,
-}