@zeix/cause-effect 0.13.2 → 0.14.0

package/src/signal.d.ts

@@ -1,8 +1,8 @@
-import { type State } from "./state";
-import { type Computed } from "./computed";
-type Signal<T extends {}> = State<T> | Computed<T>;
-type ComputedCallback<T extends {}> = (abort?: AbortSignal) => T | Promise<T>;
-type MaybeSignal<T extends {}> = Signal<T> | T | ComputedCallback<T>;
+import { type ComputedCallback } from './computed';
+type Signal<T extends {}> = {
+    get(): T;
+};
+type MaybeSignal<T extends {}> = T | Signal<T> | ComputedCallback<T>;
 declare const UNSET: any;
 /**
  * Check whether a value is a Signal or not
@@ -28,18 +28,4 @@ declare const isComputedCallback: <T extends {}>(value: unknown) => value is Com
  * @returns {Signal<T>} - converted Signal
  */
 declare const toSignal: <T extends {}>(value: MaybeSignal<T>) => Signal<T>;
-/**
- * Resolve signals or functions using signals and apply callbacks based on the results
- *
- * @since 0.13.0
- * @param {SignalMatcher<S, R>} matcher - SignalMatcher to match
- * @returns {R | Promise<R>} - result of the matched callback
- */
-declare const match: <S extends Signal<{}>[], R>(matcher: {
-    signals: S;
-    abort?: AbortSignal;
-    ok: ((...values: { [K in keyof S]: S[K] extends Signal<infer T> ? T : never; }) => R | Promise<R>);
-    err: ((...errors: Error[]) => R | Promise<R>);
-    nil: (abort?: AbortSignal) => R | Promise<R>;
-}) => R | Promise<R>;
-export { type Signal, type MaybeSignal, type ComputedCallback, UNSET, isSignal, isComputedCallback, toSignal, match, };
+export { type Signal, type MaybeSignal, UNSET, isSignal, isComputedCallback, toSignal, };

package/src/signal.ts

@@ -1,12 +1,17 @@
-import { type State, isState, state } from "./state"
-import { type Computed, computed, isComputed } from "./computed"
-import { isAbortError, isFunction, toError } from "./util"
+import { isState, state } from './state'
+import {
+	type ComputedCallback,
+	isComputed,
+	computed,
+} from './computed'
+import { isFunction } from './util'
 
 /* === Types === */
 
-type Signal<T extends {}> = State<T> | Computed<T>
-type ComputedCallback<T extends {}> = (abort?: AbortSignal) => T | Promise<T>
-type MaybeSignal<T extends {}> = Signal<T> | T | ComputedCallback<T>
+type Signal<T extends {}> = {
+	get(): T
+}
+type MaybeSignal<T extends {}> = T | Signal<T> | ComputedCallback<T>
 
 /* === Constants === */
 
@@ -16,87 +21,49 @@ const UNSET: any = Symbol()
 
 /**
  * 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)
+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
+	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)
-
+	value: MaybeSignal<T>,
+): Signal<T> =>
+	isSignal<T>(value)
+		? value
+		: isComputedCallback<T>(value)
+			? computed(value)
+			: state(value as T)
 
-/**
- * Resolve signals or functions using signals and apply callbacks based on the results
- * 
- * @since 0.13.0
- * @param {SignalMatcher<S, R>} matcher - SignalMatcher to match
- * @returns {R | Promise<R>} - result of the matched callback
- */
-const match = <S extends Signal<{}>[], R>(
-	matcher: {
-		signals: S,
-		abort?: AbortSignal,
-		ok: ((...values: {
-				[K in keyof S]: S[K] extends Signal<infer T> ? T : never
-			}) => R | Promise<R>),
-		err: ((...errors: Error[]) => R | Promise<R>),
-		nil: (abort?: AbortSignal) => R | Promise<R>
-	}
-): R | Promise<R> => {
-	const { signals, abort, ok, err, nil } = matcher
-
-	const errors: Error[] = []
-	let suspense = false
-	const values = signals.map(signal => {
-		try {
-			const value = signal.get()
-			if (value === UNSET) suspense = true
-			return value
-		} catch (e) {
-			if (isAbortError(e)) throw e
-			errors.push(toError(e))
-		}
-	}) as {
-		[K in keyof S]: S[K] extends Signal<infer T extends {}> ? T : never
-	}
-	
-	try {
-		return suspense ? nil(abort)
-			: errors.length ? err(...errors)
-			: ok(...values)
-	} catch (e) {
-		if (isAbortError(e)) throw e
-		const error = toError(e)
-		return err(error)
-	}
-}
+/* === Exports === */
 
 export {
-	type Signal, type MaybeSignal, type ComputedCallback,
-    UNSET, isSignal, isComputedCallback, toSignal, match,
-}
+	type Signal,
+	type MaybeSignal,
+	UNSET,
+	isSignal,
+	isComputedCallback,
+	toSignal,
+}

package/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

@@ -1,25 +1,21 @@
 import { UNSET } from './signal'
-import { type Computed, computed } from './computed'
-import { isFunction, isObjectOfType } from './util'
+import { isObjectOfType } from './util'
 import { type Watcher, notify, subscribe } from './scheduler'
-import { type TapMatcher, type EffectMatcher, effect } from './effect'
 
 /* === Types === */
 
-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
 }
 
 /* === Constants === */
 
 const TYPE_STATE = 'State'
 
-/* === State Factory === */
+/* === Functions === */
 
 /**
  * Create a new state signal
@@ -28,9 +24,7 @@ const TYPE_STATE = 'State'
  * @param {T} initialValue - initial value of the state
  * @returns {State<T>} - new state signal
  */
-export const state = /*#__PURE__*/ <T extends {}>(
-	initialValue: T,
-): State<T> => {
+const state = /*#__PURE__*/ <T extends {}>(initialValue: T): State<T> => {
 	const watchers: Set<Watcher> = new Set()
 	let value: T = initialValue
 
@@ -74,34 +68,6 @@ export const state = /*#__PURE__*/ <T extends {}>(
 		update: (fn: (v: T) => T): void => {
 			s.set(fn(value))
 		},
-
-		/**
-		 * Create a computed signal from the current state signal
-		 *
-		 * @since 0.9.0
-		 * @param {(v: T) => U | Promise<U>} fn - computed callback
-		 * @returns {Computed<U>} - computed signal
-		 */
-		map: <U extends {}>(fn: (v: T) => U | Promise<U>): Computed<U> =>
-			computed({
-				signals: [s],
-				ok: fn,
-			}),
-
-		/**
-		 * Case matching for the state signal with effect callbacks
-		 *
-		 * @since 0.13.0
-		 * @param {TapMatcher<T> | ((v: T) => void | (() => void))} matcher - tap matcher or effect callback
-		 * @returns {() => void} - cleanup function for the effect
-		 */
-		tap: (
-			matcher: TapMatcher<T> | ((v: T) => void | (() => void)),
-		): (() => void) =>
-			effect({
-				signals: [s],
-				...(isFunction(matcher) ? { ok: matcher } : matcher),
-			} as EffectMatcher<[State<T>]>),
 	}
 
 	return s
@@ -114,6 +80,10 @@ export const state = /*#__PURE__*/ <T extends {}>(
  * @param {unknown} value - value to check
  * @returns {boolean} - true if the value is a State instance, false otherwise
  */
-export const isState = /*#__PURE__*/ <T extends {}>(
+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/src/util.ts

@@ -30,6 +30,8 @@ class CircularDependencyError extends Error {
 	}
 }
 
+/* === Exports === */
+
 export {
 	isFunction,
 	isAsyncFunction,

package/test/batch.test.ts

@@ -1,9 +1,5 @@
 import { describe, test, expect } from 'bun:test'
-import { state, computed, batch } from '../'
-
-/* === Utility Functions === */
-
-const wait = (ms: number) => new Promise(resolve => setTimeout(resolve, ms))
+import { state, memo, batch, effect } from '../'
 
 /* === Tests === */
 
@@ -12,8 +8,8 @@ describe('Batch', function () {
 		const cause = state(0)
 		let result = 0
 		let count = 0
-		cause.tap(res => {
-			result = res
+		effect(() => {
+			result = cause.get()
 			count++
 		})
 		batch(() => {
@@ -29,10 +25,11 @@ describe('Batch', 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++
@@ -53,10 +50,8 @@ describe('Batch', function () {
 		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
+		const sum = memo(() => {
+			const v = signals.reduce((total, v) => total + v.get(), 0)
 			if (!Number.isFinite(v)) throw new Error('Invalid value')
 			return v
 		})
@@ -66,7 +61,8 @@ describe('Batch', function () {
 		let errCount = 0
 
 		// Effect: switch cases for the result
-		sum.tap({
+		effect({
+			signals: [sum],
 			ok: v => {
 				result = v
 				okCount++