@zeix/cause-effect 0.11.0 → 0.12.1

package/lib/scheduler.ts

@@ -0,0 +1,127 @@
+/* === Types === */
+
+export type EnqueueDedupe = [Element, string]
+
+export type Watcher = () => void
+export type Updater = <T>() => T
+
+/* === Internal === */
+
+// Currently active watcher
+let active: Watcher | undefined
+
+// Pending queue for batched change notifications
+const pending = new Set<Watcher>()
+let batchDepth = 0
+
+// Map of DOM elements to update functions
+const updateMap = new Map<Element, Map<string, () => void>>()
+let requestId: number | undefined
+
+const updateDOM = () => {
+	requestId = undefined
+	for (const elementMap of updateMap.values()) {
+		for (const fn of elementMap.values()) {
+			fn()
+		}
+		elementMap.clear()
+	}
+}
+
+const requestTick = () => {
+    if (requestId) cancelAnimationFrame(requestId)
+    requestId = requestAnimationFrame(updateDOM)
+}
+
+// Initial render when the call stack is empty
+queueMicrotask(updateDOM)
+
+/* === Exported Functions === */
+
+/**
+ * Add active watcher to the array of watchers
+ * 
+ * @param {Watcher[]} watchers - watchers of the signal
+ */
+export const subscribe = (watchers: Watcher[]) => {
+	// if (!active) console.warn('Calling .get() outside of a reactive context')
+	if (active && !watchers.includes(active)) {
+		watchers.push(active)
+	}
+}
+
+/**
+ * Add watchers to the pending set of change notifications
+ * 
+ * @param {Watcher[]} watchers - watchers of the signal
+ */
+export const notify = (watchers: Watcher[]) => {
+	for (const mark of watchers) {
+        batchDepth ? pending.add(mark) : mark()
+    }
+}
+
+/**
+ * Flush all pending changes to notify watchers
+ */
+export const flush = () => {
+    while (pending.size) {
+        const watchers = Array.from(pending)
+        pending.clear()
+        for (const mark of watchers) {
+            mark()
+        }
+    }
+}
+
+/**
+ * Batch multiple changes in a single signal graph and DOM update cycle
+ * 
+ * @param {() => void} fn - function with multiple signal writes to be batched
+ */
+export const batch = (fn: () => void) => {
+	batchDepth++
+    fn()
+	flush()
+	batchDepth--
+}
+
+/**
+ * Run a function in a reactive context
+ * 
+ * @param {() => void} run - function to run the computation or effect
+ * @param {Watcher} mark - function to be called when the state changes
+ */
+export const watch = (run: () => void, mark: Watcher): void => {
+	const prev = active
+	active = mark
+	run()
+	active = prev
+}
+
+/**
+ * Enqueue a function to be executed on the next animation frame
+ * 
+ * @param callback 
+ * @param dedupe 
+ * @returns 
+ */
+export const enqueue = <T>(
+    update: Updater,
+    dedupe?: EnqueueDedupe
+) => new Promise<T>((resolve, reject) => {
+    const wrappedCallback = () => {
+        try {
+            resolve(update())
+        } catch (error) {
+            reject(error)
+        }
+    }
+    if (dedupe) {
+        const [el, op] = dedupe
+        if (!updateMap.has(el)) updateMap.set(el, new Map())
+        const elementMap = updateMap.get(el)!
+        elementMap.set(op, wrappedCallback)
+    }
+    requestTick()
+})

package/lib/signal.d.ts

@@ -1,9 +1,25 @@
 import { type State } from "./state";
 import { type Computed } from "./computed";
 type Signal<T extends {}> = State<T> | Computed<T>;
-type MaybeSignal<T extends {}> = State<T> | Computed<T> | T | ((old?: T) => T);
-type Watcher = () => void;
-export declare const UNSET: any;
+type MaybeSignal<T extends {}> = Signal<T> | T | (() => T | Promise<T>);
+type InferMaybeSignalType<T> = T extends Signal<infer U> ? U : T extends (() => infer U) ? U : T;
+type OkCallback<T, U extends MaybeSignal<{}>[]> = (...values: {
+    [K in keyof U]: InferMaybeSignalType<U[K]>;
+}) => T | Promise<T> | Error;
+type NilCallback<T> = () => T | Promise<T> | Error;
+type ErrCallback<T> = (...errors: Error[]) => T | Promise<T> | Error;
+type ComputedCallbacks<T extends {}, U extends MaybeSignal<{}>[]> = OkCallback<T, U> | {
+    ok: OkCallback<T, U>;
+    nil?: NilCallback<T>;
+    err?: ErrCallback<T>;
+};
+type EffectCallbacks<U extends MaybeSignal<{}>[]> = OkCallback<void, U> | {
+    ok: OkCallback<void, U>;
+    nil?: NilCallback<void>;
+    err?: ErrCallback<void>;
+};
+type CallbackReturnType<T> = T | Promise<T> | Error | void;
+declare const UNSET: any;
 /**
  * Check whether a value is a Signal or not
  *
@@ -20,30 +36,18 @@ declare const isSignal: <T extends {}>(value: any) => value is Signal<T>;
  * @param memo
  * @returns {Signal<T>} - converted Signal
  */
-declare const toSignal: <T extends {}>(value: MaybeSignal<T>) => Signal<T>;
+declare const toSignal: <T extends {}>(value: MaybeSignal<T> | ComputedCallbacks<T, []>) => Signal<T>;
 /**
- * Add notify function of active watchers to the set of watchers
+ * Resolve signals or functions using signals and apply callbacks based on the results
  *
- * @param {Watcher[]} watchers - set of current watchers
+ * @since 0.12.0
+ * @param {U} maybeSignals - dependency signals (or functions using signals)
+ * @param {Record<string, (...args) => CallbackReturnType<T>} cb - object of ok, nil, err callbacks or just ok callback
+ * @returns {CallbackReturnType<T>} - result of chosen callback
  */
-declare const subscribe: (watchers: Watcher[]) => void;
-/**
- * Notify all subscribers of the state change or add to the pending set if batching is enabled
- *
- * @param {Watcher[]} watchers
- */
-declare const notify: (watchers: Watcher[]) => void;
-/**
- * Run a function in a reactive context
- *
- * @param {() => void} run - function to run the computation or effect
- * @param {Watcher} mark - function to be called when the state changes
- */
-declare const watch: (run: () => void, mark: Watcher) => void;
-/**
- * Batch multiple state changes into a single update
- *
- * @param {() => void} run - function to run the batch of state changes
- */
-declare const batch: (run: () => void) => void;
-export { type Signal, type MaybeSignal, type Watcher, isSignal, toSignal, subscribe, notify, watch, batch };
+declare const resolve: <T, U extends MaybeSignal<{}>[]>(maybeSignals: U, cb: OkCallback<T | Promise<T>, U> | {
+    ok: OkCallback<T | Promise<T>, U>;
+    nil?: NilCallback<T>;
+    err?: ErrCallback<T>;
+}) => CallbackReturnType<T>;
+export { type Signal, type MaybeSignal, type InferMaybeSignalType, type EffectCallbacks, type ComputedCallbacks, type CallbackReturnType, UNSET, isSignal, toSignal, resolve, };

package/lib/signal.ts

@@ -1,44 +1,44 @@
 import { type State, isState, state } from "./state"
-import { computed, type Computed, isComputed } from "./computed"
-import { isComputeFunction } from "./util"
+import { type Computed, computed, isComputed } from "./computed"
+import { isFunction, toError } from "./util"
 
 /* === Types === */
 
 type Signal<T extends {}> = State<T> | Computed<T>
+type MaybeSignal<T extends {}> = Signal<T> | T | (() => T | Promise<T>)
+type InferMaybeSignalType<T> = T extends Signal<infer U> ? U :
+	T extends (() => infer U) ? U :
+	T
+
+type OkCallback<T, U extends MaybeSignal<{}>[]> = (...values: {
+	[K in keyof U]: InferMaybeSignalType<U[K]>
+}) => T | Promise<T> | Error
+type NilCallback<T> = () => T | Promise<T> | Error
+type ErrCallback<T> = (...errors: Error[]) => T | Promise<T> | Error
+
+type ComputedCallbacks<T extends {}, U extends MaybeSignal<{}>[]> = OkCallback<T, U> | {
+	ok: OkCallback<T, U>,
+    nil?: NilCallback<T>,
+    err?: ErrCallback<T>
+}
 
-type MaybeSignal<T extends {}> = State<T> | Computed<T> | T | ((old?: T) => T)
-
-type Watcher = () => void
-
-/* === Internals === */
-
-// Currently active watcher
-let active: () => void | undefined
-
-// Batching state
-let batchDepth = 0
+type EffectCallbacks<U extends MaybeSignal<{}>[]> = OkCallback<void, U> | {
+	ok: OkCallback<void, U>,
+	nil?: NilCallback<void>,
+	err?: ErrCallback<void>
+}
 
-// Pending notifications
-const markQueue: Set<Watcher> = new Set()
+type CallbackReturnType<T> = T | Promise<T> | Error | void
 
-// Pending runs
-const runQueue: Set<() => void> = new Set()
+/* === Constants === */
 
-/**
- * Flush pending notifications and runs
- */
-const flush = () => {
-	while (markQueue.size || runQueue.size) {
-		markQueue.forEach(mark => mark())
-		markQueue.clear()
-		runQueue.forEach(run => run())
-		runQueue.clear()
-	}
-}
+const UNSET: any = Symbol()
 
-/* === Constants === */
+/* === Private Functions === */
 
-export const UNSET: any = Symbol()
+const isComputedCallbacks = /*#__PURE__*/ <T extends {}>(value: unknown): value is ComputedCallbacks<T, []> =>
+	(isFunction(value) && !value.length)
+		|| (typeof value === 'object' && value !== null && 'ok' in value && isFunction(value.ok))
 
 /* === Exported Functions === */
 
@@ -61,56 +61,67 @@ const isSignal = /*#__PURE__*/ <T extends {}>(value: any): value is Signal<T> =>
  * @returns {Signal<T>} - converted Signal
  */
 const toSignal = /*#__PURE__*/ <T extends {}>(
-	value: MaybeSignal<T>
+	value: MaybeSignal<T> | ComputedCallbacks<T, []>
 ): Signal<T> =>
 	isSignal<T>(value) ? value
-		: isComputeFunction<T>(value) ? computed(value)
-		: state(value)
-
-/**
- * Add notify function of active watchers to the set of watchers
- * 
- * @param {Watcher[]} watchers - set of current watchers
- */
-const subscribe = (watchers: Watcher[]) => {
-	if (active && !watchers.includes(active)) watchers.push(active)
-}
-
-/**
- * Notify all subscribers of the state change or add to the pending set if batching is enabled
- * 
- * @param {Watcher[]} watchers 
- */
-const notify = (watchers: Watcher[]) => {
-	watchers.forEach(mark => batchDepth ? markQueue.add(mark) : mark())
-}
+		: isComputedCallbacks<T>(value) ? computed(value)
+		: state(value as T)
 
-/**
- * Run a function in a reactive context
- * 
- * @param {() => void} run - function to run the computation or effect
- * @param {Watcher} mark - function to be called when the state changes
- */
-const watch = (run: () => void, mark: Watcher): void => {
-	const prev = active
-	active = mark
-	run()
-	active = prev
-}
 
 /**
- * Batch multiple state changes into a single update
+ * Resolve signals or functions using signals and apply callbacks based on the results
  * 
- * @param {() => void} run - function to run the batch of state changes
+ * @since 0.12.0
+ * @param {U} maybeSignals - dependency signals (or functions using signals)
+ * @param {Record<string, (...args) => CallbackReturnType<T>} cb - object of ok, nil, err callbacks or just ok callback
+ * @returns {CallbackReturnType<T>} - result of chosen callback
  */
-const batch = (run: () => void): void => {
-    batchDepth++
-    run()
-    batchDepth--
-	if (!batchDepth) flush()
+const resolve = <T, U extends MaybeSignal<{}>[]>(
+	maybeSignals: U,
+	cb: OkCallback<T | Promise<T>, U> | {
+		ok: OkCallback<T | Promise<T>, U>
+		nil?: NilCallback<T>
+		err?: ErrCallback<T>
+	}
+): CallbackReturnType<T> => {
+	const { ok, nil, err } = isFunction(cb)
+		? { ok: cb }
+		: cb as {
+			ok: OkCallback<T | Promise<T>, U>
+			nil?: NilCallback<T>
+			err?: ErrCallback<T>
+		}
+	const values = [] as {
+		[K in keyof U]: InferMaybeSignalType<U[K]>
+	}
+    const errors: Error[] = []
+    let hasUnset = false
+
+    for (let i = 0; i < maybeSignals.length; i++) {
+		const s = maybeSignals[i]
+		try {
+			const value = isSignal(s) ? s.get() : isFunction(s) ? s() : s
+			if (value === UNSET) hasUnset = true
+			values[i] = value as InferMaybeSignalType<typeof s>
+		} catch (e) {
+			errors.push(toError(e))
+		}
+    }
+
+	let result: CallbackReturnType<T> = undefined
+    try {
+		if (hasUnset && nil) result = nil()
+		else if (errors.length) result = err ? err(...errors) : errors[0]
+		else if (!hasUnset) result = ok(...values) as CallbackReturnType<T>
+    } catch (e) {
+		result = toError(e)
+		if (err) result = err(result)
+    }
+	return result
 }
 
 export {
-	type Signal, type MaybeSignal, type Watcher,
-    isSignal, toSignal, subscribe, notify, watch, batch
+	type Signal, type MaybeSignal, type InferMaybeSignalType,
+	type EffectCallbacks, type ComputedCallbacks, type CallbackReturnType,
+    UNSET, isSignal, toSignal, resolve,
 }

package/lib/state.d.ts

@@ -1,58 +1,21 @@
-import { type Computed } from "./computed";
-/**
- * Define a reactive state
- *
- * @since 0.9.0
- * @class State
- */
-export declare class State<T extends {}> {
-    private value;
-    private watchers;
-    constructor(value: T);
-    /**
-     * Get the current value of the state
-     *
-     * @since 0.9.0
-     * @method of State<T>
-     * @returns {T} - current value of the state
-     */
+import { type ComputedCallbacks, type EffectCallbacks } from './signal';
+import { type Computed } from './computed';
+export type State<T extends {}> = {
+    [Symbol.toStringTag]: 'State';
     get(): T;
-    /**
-     * Set a new value of the state
-     *
-     * @since 0.9.0
-     * @method of State<T>
-     * @param {T} value
-     * @returns {void}
-     */
-    set(value: T): void;
-    /**
-     * Update the state with a new value using a function
-     *
-     * @since 0.10.0
-     * @method of State<T>
-     * @param {(value: T) => T} fn
-     * @returns {void} - updates the state with the result of the function
-     */
-    update(fn: (value: T) => T): void;
-    /**
-     * Create a derived state from an existing state
-     *
-     * @since 0.9.0
-     * @method of State<T>
-     * @param {(value: T) => U} fn
-     * @returns {Computed<U>} - derived state
-     */
-    map<U extends {}>(fn: (value: T) => U): Computed<U>;
-}
+    set(v: T): void;
+    update(fn: (v: T) => T): void;
+    map<U extends {}>(cb: ComputedCallbacks<U, [State<T>]>): Computed<U>;
+    match: (cb: EffectCallbacks<[State<T>]>) => void;
+};
 /**
  * Create a new state signal
  *
  * @since 0.9.0
- * @param {T} value - initial value of the state
+ * @param {T} initialValue - initial value of the state
  * @returns {State<T>} - new state signal
  */
-export declare const state: <T extends {}>(value: T) => State<T>;
+export declare const state: <T extends {}>(initialValue: T) => State<T>;
 /**
  * Check if the provided value is a State instance
  *

package/lib/state.ts

@@ -1,84 +1,104 @@
-import { type Watcher, subscribe, notify, UNSET } from "./signal"
-import { type Computed, computed } from "./computed"
+import { UNSET, type ComputedCallbacks, type EffectCallbacks } from './signal'
+import { type Computed, computed } from './computed'
+import { isObjectOfType } from './util';
+import { type Watcher, notify, subscribe } from './scheduler'
+import { effect } from './effect';
 
-/* === Class State === */
+/* === Types === */
+
+export type State<T extends {}> = {
+    [Symbol.toStringTag]: 'State';
+    get(): T;
+    set(v: T): void;
+    update(fn: (v: T) => T): void;
+    map<U extends {}>(cb: ComputedCallbacks<U, [State<T>]>): Computed<U>;
+	match: (cb: EffectCallbacks<[State<T>]>) => void
+}
+
+/* === Constants === */
+
+const TYPE_STATE = 'State'
+
+/* === State Factory === */
 
 /**
- * Define a reactive state
+ * Create a new state signal
  * 
  * @since 0.9.0
- * @class State
+ * @param {T} initialValue - initial value of the state
+ * @returns {State<T>} - new state signal
  */
-export class State<T extends {}> {
-    private watchers: Watcher[] = []
+export const state = /*#__PURE__*/ <T extends {}>(initialValue: T): State<T> => {
+	const watchers: Watcher[] = []
+	let value: T = initialValue
 
-    constructor(private value: T) {}
+	const s: State<T> = {
+		[Symbol.toStringTag]: TYPE_STATE,
 
-	/**
-	 * Get the current value of the state
-	 * 
-	 * @since 0.9.0
-	 * @method of State<T>
-	 * @returns {T} - current value of the state
-	 */
-    get(): T {
-        subscribe(this.watchers)
-        return this.value
-    }
+		/**
+		 * Get the current value of the state
+		 * 
+		 * @since 0.9.0
+		 * @returns {T} - current value of the state
+		 */
+        get: (): T => {
+			subscribe(watchers)
+        	return value
+		},
 
-	/**
-	 * Set a new value of the state
-	 * 
-	 * @since 0.9.0
-	 * @method of State<T>
-	 * @param {T} value
-	 * @returns {void}
-	 */
-    set(value: T): void {
-		if (Object.is(this.value, value)) return
-		this.value = value
-		notify(this.watchers)
+		/**
+		 * Set a new value of the state
+		 * 
+		 * @since 0.9.0
+		 * @param {T} v
+		 * @returns {void}
+		 */
+        set: (v: T): void => {
+            if (Object.is(value, v)) return
+            value = v
+            notify(watchers)
 
-		// Setting to UNSET clears the watchers so the signal can be garbage collected
-		if (UNSET === value) this.watchers = []
-    }
+            // Setting to UNSET clears the watchers so the signal can be garbage collected
+            if (UNSET === value) watchers.length = 0 // head = tail = undefined
+        },
 
-	/**
-	 * Update the state with a new value using a function
-	 * 
-	 * @since 0.10.0
-	 * @method of State<T>
-	 * @param {(value: T) => T} fn
-	 * @returns {void} - updates the state with the result of the function
-	 */
-	update(fn: (value: T) => T): void {
-		this.set(fn(this.value))
-    }
+		/**
+		 * Update the state with a new value using a function
+		 * 
+		 * @since 0.10.0
+		 * @param {(v: T) => T} fn - function to update the state
+		 * @returns {void} - updates the state with the result of the function
+		 */
+        update: (fn: (v: T) => T): void => {
+            s.set(fn(value))
+        },
 
-	/**
-	 * Create a derived state from an existing state
-	 * 
-	 * @since 0.9.0
-	 * @method of State<T>
-	 * @param {(value: T) => U} fn
-	 * @returns {Computed<U>} - derived state
-	 */
-    map<U extends {}>(fn: (value: T) => U): Computed<U> {
-        return computed<U>(() => fn(this.get()))
-    }
-}
+		/**
+		 * Create a computed signal from the current state signal
+		 * 
+		 * @since 0.9.0
+		 * @param {ComputedCallbacks<U, [State<T>]>} cb - compute callback or object of ok, nil, err callbacks to map this value to new computed
+		 * @returns {Computed<U>} - computed signal
+		 */
+        map: <U extends {}>(cb: ComputedCallbacks<U, [State<T>]>): Computed<U> =>
+            computed(cb, s),
 
-/* === Helper Functions === */
+		/**
+		 * Case matching for the state signal with effect callbacks
+		 * 
+		 * @since 0.12.0
+		 * @method of State<T>
+		 * @param {EffectCallbacks<[State<T>]>} cb - effect callback or object of ok, nil, err callbacks to be executed when the state changes
+		 * @returns {State<T>} - self, for chaining effect callbacks
+		 */
+		match: (cb: EffectCallbacks<[State<T>]>): State<T> => {
+			effect(cb, s)
+			return s
+		}
+	}
 
-/**
- * Create a new state signal
- * 
- * @since 0.9.0
- * @param {T} value - initial value of the state
- * @returns {State<T>} - new state signal
- */
-export const state = /*#__PURE__*/ <T extends {}>(value: T): State<T> =>
-	new State(value)
+	return s
+}
 
 /**
  * Check if the provided value is a State instance
@@ -88,4 +108,4 @@ export const state = /*#__PURE__*/ <T extends {}>(value: T): State<T> =>
  * @returns {boolean} - true if the value is a State instance, false otherwise
  */
 export const isState = /*#__PURE__*/ <T extends {}>(value: unknown): value is State<T> =>
-	value instanceof State
+	isObjectOfType(value, TYPE_STATE)

package/lib/util.d.ts

@@ -1,8 +1,8 @@
 declare const isFunction: <T>(value: unknown) => value is (...args: unknown[]) => T;
 declare const isAsyncFunction: <T>(value: unknown) => value is (...args: unknown[]) => Promise<T> | PromiseLike<T>;
-declare const isComputeFunction: <T>(value: unknown) => value is ((old?: T) => T);
+declare const isObjectOfType: <T>(value: unknown, type: string) => value is T;
 declare const isInstanceOf: <T>(type: new (...args: any[]) => T) => (value: unknown) => value is T;
 declare const isError: (value: unknown) => value is Error;
 declare const isPromise: (value: unknown) => value is Promise<unknown>;
 declare const toError: (value: unknown) => Error;
-export { isFunction, isAsyncFunction, isComputeFunction, isInstanceOf, isError, isPromise, toError };
+export { isFunction, isAsyncFunction, isObjectOfType, isInstanceOf, isError, isPromise, toError };

package/lib/util.ts

@@ -6,8 +6,8 @@ const isFunction = /*#__PURE__*/ <T>(value: unknown): value is (...args: unknown
 const isAsyncFunction = /*#__PURE__*/ <T>(value: unknown): value is (...args: unknown[]) => Promise<T> | PromiseLike<T> =>
 	isFunction(value) && /^async\s+/.test(value.toString())
 
-const isComputeFunction = /*#__PURE__*/ <T>(value: unknown): value is ((old?: T) => T) =>
-	isFunction(value) && value.length < 2
+const isObjectOfType = /*#__PURE__*/ <T>(value: unknown, type: string): value is T =>
+	Object.prototype.toString.call(value) === `[object ${type}]`
 
 const isInstanceOf = /*#__PURE__*/ <T>(type: new (...args: any[]) => T) =>
 	(value: unknown): value is T =>
@@ -20,6 +20,6 @@ const toError = (value: unknown): Error =>
 	isError(value) ? value : new Error(String(value))
 
 export {
-	isFunction, isAsyncFunction, isComputeFunction,
-	isInstanceOf, isError, isPromise, toError
+	isFunction, isAsyncFunction,
+	isObjectOfType, isInstanceOf, isError, isPromise, toError
 }

package/package.json

@@ -1,11 +1,12 @@
 {
   "name": "@zeix/cause-effect",
-  "version": "0.11.0",
+  "version": "0.12.1",
   "author": "Esther Brunner",
   "main": "index.js",
   "module": "index.ts",
   "devDependencies": {
-    "@types/bun": "latest"
+    "@types/bun": "latest",
+    "random": "^5.3.0"
   },
   "peerDependencies": {
     "typescript": "^5.6.3"