@zeix/cause-effect 0.11.0 → 0.12.0

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,8 +1,9 @@
 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;
+type UnknownSignal = Signal<{}>;
+type MaybeSignal<T extends {}> = Signal<T> | T | (() => T);
+type SignalValue<T> = T extends Signal<infer U> ? U : never;
 export declare const UNSET: any;
 /**
  * Check whether a value is a Signal or not
@@ -22,28 +23,16 @@ declare const isSignal: <T extends {}>(value: any) => value is Signal<T>;
  */
 declare const toSignal: <T extends {}>(value: MaybeSignal<T>) => Signal<T>;
 /**
- * Add notify function of active watchers to the set of watchers
+ * Resolve signals and apply callbacks based on the results
  *
- * @param {Watcher[]} watchers - set of current watchers
+ * @since 0.12.0
+ * @param {U} signals - dependency signals
+ * @param {Record<string, (...args) => T | Promise<T> | Error | void>} callbacks - ok, nil, err callbacks
+ * @returns {T | Promise<T> | Error | void} - 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 resolveSignals: <T extends {}, U extends UnknownSignal[]>(signals: U, callbacks: {
+    ok: (...values: { [K in keyof U]: SignalValue<U[K]>; }) => T | Promise<T> | Error | void;
+    nil?: () => T | Promise<T> | Error | void;
+    err?: (...errors: Error[]) => T | Promise<T> | Error | void;
+}) => T | Promise<T> | Error | void;
+export { type Signal, type UnknownSignal, type SignalValue, type MaybeSignal, isSignal, toSignal, resolveSignals, };

package/lib/signal.ts

@@ -1,40 +1,14 @@
 import { type State, isState, state } from "./state"
 import { computed, type Computed, isComputed } from "./computed"
-import { isComputeFunction } from "./util"
+import { isComputeFunction, toError } from "./util"
 
 /* === Types === */
 
 type Signal<T extends {}> = State<T> | Computed<T>
+type UnknownSignal = Signal<{}>
+type MaybeSignal<T extends {}> = Signal<T> | T | (() => 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
-
-// Pending notifications
-const markQueue: Set<Watcher> = new Set()
-
-// Pending runs
-const runQueue: Set<() => void> = new Set()
-
-/**
- * Flush pending notifications and runs
- */
-const flush = () => {
-	while (markQueue.size || runQueue.size) {
-		markQueue.forEach(mark => mark())
-		markQueue.clear()
-		runQueue.forEach(run => run())
-		runQueue.clear()
-	}
-}
+type SignalValue<T> = T extends Signal<infer U> ? U : never
 
 /* === Constants === */
 
@@ -67,50 +41,52 @@ const toSignal = /*#__PURE__*/ <T extends {}>(
 		: 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
+ * Resolve signals and apply callbacks based on the results
  * 
- * @param {Watcher[]} watchers 
+ * @since 0.12.0
+ * @param {U} signals - dependency signals
+ * @param {Record<string, (...args) => T | Promise<T> | Error | void>} callbacks - ok, nil, err callbacks
+ * @returns {T | Promise<T> | Error | void} - result of chosen callback
  */
-const notify = (watchers: Watcher[]) => {
-	watchers.forEach(mark => batchDepth ? markQueue.add(mark) : mark())
-}
-
-/**
- * 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
- * 
- * @param {() => void} run - function to run the batch of state changes
- */
-const batch = (run: () => void): void => {
-    batchDepth++
-    run()
-    batchDepth--
-	if (!batchDepth) flush()
+const resolveSignals = <T extends {}, U extends UnknownSignal[]>(
+	signals: U,
+	callbacks: {
+		ok: (...values: { [K in keyof U]: SignalValue<U[K]> }) => T | Promise<T> | Error | void
+		nil?: () => T | Promise<T> | Error | void
+		err?: (...errors: Error[]) => T | Promise<T> | Error | void
+	}
+): T | Promise<T> | Error | void => {
+	const { ok, nil, err  } = callbacks
+	const values = [] as { [K in keyof U]: SignalValue<U[K]> }
+    const errors: Error[] = []
+    let hasUnset = false
+
+    for (const signal of signals) {
+		try {
+			const value = signal.get()
+			if (value === UNSET) hasUnset = true
+			values.push(value)
+		} catch (e) {
+			errors.push(toError(e))
+		}
+    }
+
+	let result: T | Promise<T> | Error | void = undefined
+    try {
+		if (hasUnset && nil) result = nil()
+		else if (errors.length) result = err ? err(...errors) : errors[0]
+		else if (!hasUnset) result = ok(...values)
+    } catch (e) {
+		result = toError(e)
+		if (err) result = err(result)
+    } finally {
+		return result
+	}
 }
 
 export {
-	type Signal, type MaybeSignal, type Watcher,
-    isSignal, toSignal, subscribe, notify, watch, batch
+	type Signal, type UnknownSignal, type SignalValue, type MaybeSignal,
+    isSignal, toSignal, resolveSignals,
 }

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 Computed } from './computed';
+import { type EffectCallbacks } from './effect';
+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>;
-}
+    match: (callbacks: 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 {}>(v: T) => State<T>;
 /**
  * Check if the provided value is a State instance
  *

package/lib/state.ts

@@ -1,84 +1,108 @@
-import { type Watcher, subscribe, notify, UNSET } from "./signal"
-import { type Computed, computed } from "./computed"
+import { UNSET } from './signal'
+import { type Computed, computed } from './computed'
+import { isObjectOfType } from './util';
+import { type Watcher, notify, subscribe } from './scheduler'
+import { type EffectCallbacks, effect } from './effect';
 
-/* === Class State === */
+/* === Types === */
+
+export type State<T extends {}> = {
+    [Symbol.toStringTag]: 'State';
+    get(): T;
+    set(value: T): void;
+    update(fn: (value: T) => T): void;
+    map<U extends {}>(fn: (value: T) => U): Computed<U>;
+	match: (callbacks: 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 {}>(v: T): State<T> => {
+	const watchers: Watcher[] = []
+	let value: T = v
 
-    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
+		 * @method of State<T>
+		 * @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
+		 * @method of State<T>
+		 * @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
+		 * @method of State<T>
+		 * @param {(v: T) => T} fn
+		 * @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
+		 * @method of State<T>
+		 * @param {(v: T) => R} fn
+		 * @returns {Computed<R>} - computed signal
+		 */
+        map: <R extends {}>(fn: (v: T) => R): Computed<R> =>
+            computed(() => fn(s.get())),
 
-/* === Helper Functions === */
+		/**
+		 * Case matching for the state signal with effect callbacks
+		 * 
+		 * @since 0.12.0
+		 * @method of State<T>
+		 * @param {EffectCallbacks[<T>]} callbacks 
+		 * @returns {State<T>} - self, for chaining effect callbacks
+		 */
+		match: (callbacks: EffectCallbacks<[State<T>]>): State<T> => {
+			effect(callbacks, 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 +112,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,10 @@
 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 };
+declare const isEquivalentError: (error1: Error, error2: Error | undefined) => boolean;
+export { isFunction, isAsyncFunction, isComputeFunction, isObjectOfType, isInstanceOf, isError, isPromise, toError, isEquivalentError };

package/lib/util.ts

@@ -9,6 +9,9 @@ const isAsyncFunction = /*#__PURE__*/ <T>(value: unknown): value is (...args: un
 const isComputeFunction = /*#__PURE__*/ <T>(value: unknown): value is ((old?: T) => T) =>
 	isFunction(value) && value.length < 2
 
+const isObjectOfType = <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 =>
 		value instanceof type
@@ -19,7 +22,15 @@ const isPromise = /*#__PURE__*/ isInstanceOf(Promise)
 const toError = (value: unknown): Error =>
 	isError(value) ? value : new Error(String(value))
 
+const isEquivalentError = /*#__PURE__*/ (
+	error1: Error,
+	error2: Error | undefined
+): boolean => {
+    if (!error2) return false
+    return error1.name === error2.name && error1.message === error2.message
+}
+
 export {
 	isFunction, isAsyncFunction, isComputeFunction,
-	isInstanceOf, isError, isPromise, toError
+	isObjectOfType, isInstanceOf, isError, isPromise, toError, isEquivalentError
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zeix/cause-effect",
-  "version": "0.11.0",
+  "version": "0.12.0",
   "author": "Esther Brunner",
   "main": "index.js",
   "module": "index.ts",
@@ -26,5 +26,8 @@
     "test": "bun test"
   },
   "type": "module",
-  "types": "index.d.ts"
+  "types": "index.d.ts",
+  "dependencies": {
+    "random": "^5.3.0"
+  }
 }