@zeix/cause-effect 0.13.1 → 0.14.0

package/src/signal.ts

@@ -0,0 +1,69 @@
+import { isState, state } from './state'
+import {
+	type ComputedCallback,
+	isComputed,
+	computed,
+} from './computed'
+import { isFunction } from './util'
+
+/* === Types === */
+
+type Signal<T extends {}> = {
+	get(): T
+}
+type MaybeSignal<T extends {}> = T | Signal<T> | ComputedCallback<T>
+
+/* === Constants === */
+
+const UNSET: any = Symbol()
+
+/* === Exported Functions === */
+
+/**
+ * Check whether a value is a Signal or not
+ *
+ * @since 0.9.0
+ * @param {unknown} value - value to check
+ * @returns {boolean} - true if value is a Signal, false otherwise
+ */
+const isSignal = /*#__PURE__*/ <T extends {}>(
+	value: unknown,
+): value is Signal<T> => isState(value) || isComputed(value)
+
+/**
+ * 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
+ * @returns {boolean} - true if value is a callback or callbacks object, false otherwise
+ */
+const isComputedCallback = /*#__PURE__*/ <T extends {}>(
+	value: unknown,
+): value is ComputedCallback<T> => isFunction(value) && value.length < 2
+
+/**
+ * Convert a value to a Signal if it's not already a Signal
+ *
+ * @since 0.9.6
+ * @param {MaybeSignal<T>} value - value to convert to a Signal
+ * @returns {Signal<T>} - converted Signal
+ */
+const toSignal = /*#__PURE__*/ <T extends {}>(
+	value: MaybeSignal<T>,
+): Signal<T> =>
+	isSignal<T>(value)
+		? value
+		: isComputedCallback<T>(value)
+			? computed(value)
+			: state(value as T)
+
+/* === Exports === */
+
+export {
+	type Signal,
+	type MaybeSignal,
+	UNSET,
+	isSignal,
+	isComputedCallback,
+	toSignal,
+}

package/{lib → src}/state.d.ts

@@ -1,12 +1,8 @@
-import { type Computed } from './computed';
-import { type TapMatcher } from './effect';
-export type State<T extends {}> = {
+type State<T extends {}> = {
     [Symbol.toStringTag]: 'State';
     get(): T;
     set(v: T): void;
     update(fn: (v: T) => T): void;
-    map<U extends {}>(fn: (v: T) => U | Promise<U>): Computed<U>;
-    tap(matcher: TapMatcher<T> | ((v: T) => void | (() => void))): () => void;
 };
 /**
  * Create a new state signal
@@ -15,7 +11,7 @@ export type State<T extends {}> = {
  * @param {T} initialValue - initial value of the state
  * @returns {State<T>} - new state signal
  */
-export declare const state: <T extends {}>(initialValue: T) => State<T>;
+declare const state: <T extends {}>(initialValue: T) => State<T>;
 /**
  * Check if the provided value is a State instance
  *
@@ -23,4 +19,5 @@ export declare const state: <T extends {}>(initialValue: T) => State<T>;
  * @param {unknown} value - value to check
  * @returns {boolean} - true if the value is a State instance, false otherwise
  */
-export declare const isState: <T extends {}>(value: unknown) => value is State<T>;
+declare const isState: <T extends {}>(value: unknown) => value is State<T>;
+export { type State, state, isState };

package/src/state.ts

@@ -0,0 +1,89 @@
+import { UNSET } from './signal'
+import { isObjectOfType } from './util'
+import { type Watcher, notify, subscribe } from './scheduler'
+
+/* === Types === */
+
+type State<T extends {}> = {
+	[Symbol.toStringTag]: 'State'
+	get(): T
+	set(v: T): void
+	update(fn: (v: T) => T): void
+}
+
+/* === Constants === */
+
+const TYPE_STATE = 'State'
+
+/* === Functions === */
+
+/**
+ * Create a new state signal
+ *
+ * @since 0.9.0
+ * @param {T} initialValue - initial value of the state
+ * @returns {State<T>} - new state signal
+ */
+const state = /*#__PURE__*/ <T extends {}>(initialValue: T): State<T> => {
+	const watchers: Set<Watcher> = new Set()
+	let value: T = initialValue
+
+	const s: State<T> = {
+		[Symbol.toStringTag]: TYPE_STATE,
+
+		/**
+		 * 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
+		 * @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) watchers.clear()
+		},
+
+		/**
+		 * 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))
+		},
+	}
+
+	return s
+}
+
+/**
+ * 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
+ */
+const isState = /*#__PURE__*/ <T extends {}>(
+	value: unknown,
+): value is State<T> => isObjectOfType(value, TYPE_STATE)
+
+/* === Exports === */
+
+export { type State, state, isState }

package/src/task.d.ts

@@ -0,0 +1,17 @@
+import { type Computed } from './computed';
+/**
+ * Callback for async computation tasks
+ * This explicitly returns a Promise<T> to differentiate from MemoCallback
+ *
+ * @since 0.14.0
+ */
+type TaskCallback<T extends {}> = (abort: AbortSignal) => Promise<T>;
+/**
+ * Create a derived signal that supports asynchronous computations
+ *
+ * @since 0.14.0
+ * @param {TaskCallback<T>} fn - async computation callback
+ * @returns {Computed<T>} - Computed signal
+ */
+declare const task: <T extends {}>(fn: TaskCallback<T>) => Computed<T>;
+export { type TaskCallback, task };

package/src/task.ts

@@ -0,0 +1,153 @@
+import { UNSET } from './signal'
+import {
+	CircularDependencyError,
+	isAbortError,
+	isPromise,
+	toError,
+} from './util'
+import {
+	type Cleanup,
+	type Watcher,
+	flush,
+	notify,
+	subscribe,
+	watch,
+} from './scheduler'
+import {
+	type Computed,
+	TYPE_COMPUTED,
+} from './computed'
+
+/* === Types === */
+
+/**
+ * Callback for async computation tasks
+ * This explicitly returns a Promise<T> to differentiate from MemoCallback
+ * 
+ * @since 0.14.0
+ */
+type TaskCallback<T extends {}> = (abort: AbortSignal) => Promise<T>
+
+/* === Function === */
+
+/**
+ * Create a derived signal that supports asynchronous computations
+ *
+ * @since 0.14.0
+ * @param {TaskCallback<T>} fn - async computation callback
+ * @returns {Computed<T>} - Computed signal
+ */
+const task = <T extends {}>(fn: TaskCallback<T>): Computed<T> => {
+	const watchers: Set<Watcher> = new Set()
+
+	// Internal state
+	let value: T = UNSET
+	let error: Error | undefined
+	let dirty = true
+	let changed = false
+	let computing = false
+	let controller: AbortController | undefined
+
+	// Functions to update internal state
+	const ok = (v: T) => {
+		if (!Object.is(v, value)) {
+			value = v
+			dirty = false
+			error = undefined
+			changed = true
+		}
+	}
+	const nil = () => {
+		changed = UNSET !== value
+		value = UNSET
+		error = undefined
+	}
+	const err = (e: unknown) => {
+		const newError = toError(e)
+		changed = !(
+			error &&
+			newError.name === error.name &&
+			newError.message === error.message
+		)
+		value = UNSET
+		error = newError
+	}
+	const resolve = (v: T) => {
+		computing = false
+		controller = undefined
+		ok(v)
+		if (changed) notify(watchers)
+	}
+	const reject = (e: unknown) => {
+		computing = false
+		controller = undefined
+		err(e)
+		if (changed) notify(watchers)
+	}
+	const abort = () => {
+		computing = false
+		controller = undefined
+		compute() // retry
+	}
+
+	// Called when notified from sources (push)
+	const mark = (() => {
+		dirty = true
+		controller?.abort('Aborted because source signal changed')
+		if (watchers.size) {
+			notify(watchers)
+		} else {
+			mark.cleanups.forEach(fn => fn())
+			mark.cleanups.clear()
+		}
+	}) as Watcher
+	mark.cleanups = new Set<Cleanup>()
+
+	// Called when requested by dependencies (pull)
+	const compute = () =>
+		watch(() => {
+			if (computing) throw new CircularDependencyError('task')
+			changed = false
+			controller = new AbortController()
+			controller.signal.addEventListener('abort', abort, {
+				once: true,
+			})
+
+			let result: T | Promise<T>
+			computing = true
+			try {
+				result = fn(controller.signal)
+			} catch (e) {
+				if (isAbortError(e)) nil()
+				else err(e)
+				computing = false
+				return
+			}
+			if (isPromise(result)) result.then(resolve, reject)
+			else if (null == result || UNSET === result) nil()
+			else ok(result)
+			computing = false
+		}, mark)
+
+	const c: Computed<T> = {
+		[Symbol.toStringTag]: TYPE_COMPUTED,
+
+		/**
+		 * Get the current value of the computed
+		 *
+		 * @returns {T} - current value of the computed
+		 */
+		get: (): T => {
+			subscribe(watchers)
+			flush()
+			if (dirty) compute()
+			if (error) throw error
+			return value
+		},
+	}
+	return c
+}
+
+/* === Exports === */
+
+export { type TaskCallback, task }

package/{lib → src}/util.d.ts

@@ -8,4 +8,4 @@ declare const toError: (reason: unknown) => Error;
 declare class CircularDependencyError extends Error {
     constructor(where: string);
 }
-export { isFunction, isAsyncFunction, isObjectOfType, isError, isAbortError, isPromise, toError, CircularDependencyError };
+export { isFunction, isAsyncFunction, isObjectOfType, isError, isAbortError, isPromise, toError, CircularDependencyError, };

package/{lib → src}/util.ts

@@ -1,13 +1,18 @@
 /* === Utility Functions === */
 
-const isFunction = /*#__PURE__*/ <T>(value: unknown): value is (...args: unknown[]) => T =>
-    typeof value === 'function'
+const isFunction = /*#__PURE__*/ <T>(
+	value: unknown,
+): value is (...args: unknown[]) => T => typeof value === 'function'
 
-const isAsyncFunction = /*#__PURE__*/ <T>(value: unknown): value is (...args: unknown[]) => Promise<T> =>
+const isAsyncFunction = /*#__PURE__*/ <T>(
+	value: unknown,
+): value is (...args: unknown[]) => Promise<T> =>
 	isFunction(value) && value.constructor.name === 'AsyncFunction'
 
-const isObjectOfType = /*#__PURE__*/ <T>(value: unknown, type: string): value is T =>
-	Object.prototype.toString.call(value) === `[object ${type}]`
+const isObjectOfType = /*#__PURE__*/ <T>(
+	value: unknown,
+	type: string,
+): value is T => Object.prototype.toString.call(value) === `[object ${type}]`
 
 const isError = /*#__PURE__*/ (value: unknown): value is Error =>
 	value instanceof Error
@@ -20,13 +25,20 @@ const toError = (reason: unknown): Error =>
 
 class CircularDependencyError extends Error {
 	constructor(where: string) {
-        super(`Circular dependency in ${where} detected`)
+		super(`Circular dependency in ${where} detected`)
 		return this
-    }
+	}
 }
 
+/* === Exports === */
+
 export {
-	isFunction, isAsyncFunction,
-	isObjectOfType, isError, isAbortError, isPromise, toError,
-	CircularDependencyError
-}
+	isFunction,
+	isAsyncFunction,
+	isObjectOfType,
+	isError,
+	isAbortError,
+	isPromise,
+	toError,
+	CircularDependencyError,
+}

package/test/batch.test.ts

@@ -1,20 +1,15 @@
 import { describe, test, expect } from 'bun:test'
-import { state, computed, effect, batch } from '../'
-
-/* === Utility Functions === */
-
-const wait = (ms: number) => new Promise(resolve => setTimeout(resolve, ms))
+import { state, memo, batch, effect } from '../'
 
 /* === Tests === */
 
 describe('Batch', function () {
-
-	test('should be triggered only once after repeated state change', function() {
+	test('should be triggered only once after repeated state change', function () {
 		const cause = state(0)
 		let result = 0
 		let count = 0
-		cause.tap(res => {
-			result = res
+		effect(() => {
+			result = cause.get()
 			count++
 		})
 		batch(() => {
@@ -23,17 +18,18 @@ describe('Batch', function () {
 			}
 		})
 		expect(result).toBe(10)
-		expect(count).toBe(2); // + 1 for effect initialization
+		expect(count).toBe(2) // + 1 for effect initialization
 	})
 
-	test('should be triggered only once when multiple signals are set', function() {
+	test('should be triggered only once when multiple signals are set', function () {
 		const a = state(3)
 		const b = state(4)
 		const c = state(5)
-		const sum = computed(() => a.get() + b.get() + c.get())
+		const sum = memo(() => a.get() + b.get() + c.get())
 		let result = 0
 		let count = 0
-		sum.tap({
+		effect({
+			signals: [sum],
 			ok: res => {
 				result = res
 				count++
@@ -46,27 +42,27 @@ describe('Batch', function () {
 			c.set(10)
 		})
 		expect(result).toBe(24)
-		expect(count).toBe(2); // + 1 for effect initialization
+		expect(count).toBe(2) // + 1 for effect initialization
 	})
 
-	test('should prove example from README works', function() {
-
+	test('should prove example from README works', function () {
 		// State: define an array of Signal<number>
 		const signals = [state(2), state(3), state(5)]
 
 		// Computed: derive a calculation ...
-		const sum = computed(() => signals.reduce((total, v) => total + v.get(), 0))
-			.map(v => { // ... perform validation and handle errors
-				if (!Number.isFinite(v)) throw new Error('Invalid value')
-				return v
-			})
+		const sum = memo(() => {
+			const v = signals.reduce((total, v) => total + v.get(), 0)
+			if (!Number.isFinite(v)) throw new Error('Invalid value')
+			return v
+		})
 
 		let result = 0
 		let okCount = 0
 		let errCount = 0
-		
+
 		// Effect: switch cases for the result
-		sum.tap({
+		effect({
+			signals: [sum],
 			ok: v => {
 				result = v
 				okCount++
@@ -75,7 +71,7 @@ describe('Batch', function () {
 			err: _error => {
 				errCount++
 				// console.error('Error:', error)
-			}
+			},
 		})
 
 		expect(okCount).toBe(1)
@@ -92,9 +88,8 @@ describe('Batch', function () {
 		// Provoke an error
 		signals[0].set(NaN)
 
-        expect(errCount).toBe(1)
-		expect(okCount).toBe(2); // should not have changed due to error
-        expect(result).toBe(20); // should not have changed due to error
+		expect(errCount).toBe(1)
+		expect(okCount).toBe(2) // should not have changed due to error
+		expect(result).toBe(20) // should not have changed due to error
 	})
-
 })