@zeix/cause-effect 0.13.1 → 0.14.0

package/lib/computed.ts

@@ -1,206 +0,0 @@
-import { type Signal, type ComputedCallback, match, UNSET } from './signal'
-import { CircularDependencyError, isAbortError, isAsyncFunction, isFunction, isObjectOfType, isPromise, toError } from './util'
-import { type Watcher, flush, notify, subscribe, watch } from './scheduler'
-import { type TapMatcher, type EffectMatcher, effect } from './effect'
-
-/* === Types === */
-
-export type ComputedMatcher<S extends Signal<{}>[], R extends {}> = {
-	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?: () => R | Promise<R>
-}
-
-export type Computed<T extends {}> = {
-    [Symbol.toStringTag]: 'Computed'
-    get(): T
-    map<U extends {}>(fn: (v: T) => U | Promise<U>): Computed<U>
-	tap(matcher: TapMatcher<T> | ((v: T) => void | (() => void))): () => void
-}
-
-/* === Constants === */
-
-const TYPE_COMPUTED = 'Computed'
-
-/* === Private Functions === */
-
-const isEquivalentError = /*#__PURE__*/ (
-	error1: Error,
-	error2: Error | undefined
-): boolean => {
-    if (!error2) return false
-    return error1.name === error2.name && error1.message === error2.message
-}
-
-/* === Computed Factory === */
-
-/**
- * Create a derived signal from existing signals
- * 
- * @since 0.9.0
- * @param {ComputedMatcher<S, T> | ComputedCallback<T>} matcher - computed matcher or callback
- * @returns {Computed<T>} - Computed signal
- */
-export const computed = <T extends {}, S extends Signal<{}>[] = []>(
-	matcher: ComputedMatcher<S, T> | ComputedCallback<T>,
-): Computed<T> => {
-	const watchers: Set<Watcher> = new Set()
-	const m = isFunction(matcher) ? undefined : {
-			nil: () => UNSET,
-			err: (...errors: Error[]) => {
-				if (errors.length > 1) throw new AggregateError(errors)
-				else throw errors[0]
-			},
-			...matcher,
-		} as Required<ComputedMatcher<S, T>>
-	const fn = (m ? m.ok : matcher) as ComputedCallback<T>
-
-	// 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 = !isEquivalentError(newError, error)
-		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) {
-			if (changed) notify(watchers)
-		} else {
-			mark.cleanups.forEach((fn: () => void) => fn())
-			mark.cleanups.clear()
-		}
-	}) as Watcher
-	mark.cleanups = new Set()
-
-	// Called when requested by dependencies (pull)
-	const compute = () => watch(() => {
-		if (computing) throw new CircularDependencyError('computed')
-		changed = false
-		if (isAsyncFunction(fn)) {
-			if (controller) return value // return current value until promise resolves
-			controller = new AbortController()
-			if (m) m.abort = m.abort instanceof AbortSignal
-			? AbortSignal.any([m.abort, controller.signal])
-			: controller.signal
-			controller.signal.addEventListener('abort', abort, { once: true })
-		}
-		let result: T | Promise<T>
-		computing = true
-		try {
-			result = m && m.signals.length
-				? match<S, T>(m)
-				: fn(controller?.signal)
-		} catch (e) {
-			isAbortError(e) ? nil() : 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
-		 * 
-		 * @since 0.9.0
-		 * @returns {T} - current value of the computed
-		 */
-		get: (): T => {
-			subscribe(watchers)
-			flush()
-			if (dirty) compute()
-			if (error) throw error
-			return value
-		},
-
-		/**
-		 * Create a computed signal from the current computed 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: [c],
-				ok: fn
-			}),
-
-		/** 
-		 * Case matching for the computed 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: [c],
-				...(isFunction(matcher) ? { ok: matcher } : matcher)
-			} as EffectMatcher<[Computed<T>]>)
-	}
-	return c
-}
-
-/* === Helper Functions === */
-
-/**
- * Check if a value is a computed state
- * 
- * @since 0.9.0
- * @param {unknown} value - value to check
- * @returns {boolean} - true if value is a computed state, false otherwise
- */
-export const isComputed = /*#__PURE__*/ <T extends {}>(value: unknown): value is Computed<T> =>
-	isObjectOfType(value, TYPE_COMPUTED)

package/lib/effect.d.ts

@@ -1,22 +0,0 @@
-import { type Signal } from './signal';
-export type TapMatcher<T extends {}> = {
-    ok: (value: T) => void | (() => void);
-    err?: (error: Error) => void | (() => void);
-    nil?: () => void | (() => void);
-};
-export type EffectMatcher<S extends Signal<{}>[]> = {
-    signals: S;
-    ok: (...values: {
-        [K in keyof S]: S[K] extends Signal<infer T> ? T : never;
-    }) => void | (() => void);
-    err?: (...errors: Error[]) => void | (() => void);
-    nil?: () => void | (() => void);
-};
-/**
- * Define what happens when a reactive state changes
- *
- * @since 0.1.0
- * @param {EffectMatcher<S> | (() => void | (() => void))} matcher - effect matcher or callback
- * @returns {() => void} - cleanup function for the effect
- */
-export declare function effect<S extends Signal<{}>[]>(matcher: EffectMatcher<S> | (() => void | (() => void))): () => void;

package/lib/effect.ts

@@ -1,61 +0,0 @@
-import { type Signal, match } from './signal'
-import { CircularDependencyError, isFunction, toError } from './util'
-import { watch, type Watcher } from './scheduler'
-
-/* === Types === */
-
-export type TapMatcher<T extends {}> = {
-	ok: (value: T) => void | (() => void)
-	err?: (error: Error) => void | (() => void)
-	nil?: () => void | (() => void)
-}
-
-export type EffectMatcher<S extends Signal<{}>[]> = {
-	signals: S
-	ok: (...values: {
-		[K in keyof S]: S[K] extends Signal<infer T> ? T : never
-	}) => void | (() => void)
-	err?: (...errors: Error[]) => void | (() => void)
-	nil?: () => void | (() => void)
-}
-
-/* === Exported Functions === */
-
-/**
- * Define what happens when a reactive state changes
- * 
- * @since 0.1.0
- * @param {EffectMatcher<S> | (() => void | (() => void))} matcher - effect matcher or callback
- * @returns {() => void} - cleanup function for the effect
- */
-export function effect<S extends Signal<{}>[]>(
-	matcher: EffectMatcher<S> | (() => void | (() => void))
-): () => void {
-	const {
-		signals,
-		ok,
-		err = console.error,
-		nil = () => {}
-	} = isFunction(matcher)
-		? { signals: [] as unknown as S, ok: matcher }
-		: matcher
-	let running = false
-	const run = (() => watch(() => {
-		if (running) throw new CircularDependencyError('effect')
-		running = true
-		let cleanup: void | (() => void) = undefined
-		try {
-			cleanup = match<S, void | (() => void)>({ signals, ok, err, nil }) as void | (() => void)
-		} catch (e) {
-			err(toError(e))
-		}
-		if (isFunction(cleanup)) run.cleanups.add(cleanup)
-		running = false
-    }, run)) as Watcher
-	run.cleanups = new Set()
-	run()
-	return () => {
-		run.cleanups.forEach((fn: () => void) => fn())
-		run.cleanups.clear()
-	}
-}

package/lib/signal.d.ts

@@ -1,45 +0,0 @@
-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>;
-declare const UNSET: any;
-/**
- * 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
- */
-declare const isSignal: <T extends {}>(value: any) => value is Signal<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
- * @returns {boolean} - true if value is a callback or callbacks object, false otherwise
- */
-declare const isComputedCallback: <T extends {}>(value: unknown) => value is ComputedCallback<T>;
-/**
- * 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
- */
-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, };

package/lib/signal.ts

@@ -1,102 +0,0 @@
-import { type State, isState, state } from "./state"
-import { type Computed, computed, isComputed } from "./computed"
-import { isAbortError, isFunction, toError } 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>
-
-/* === 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: any): 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)
-
-
-/**
- * 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)
-	}
-}
-
-export {
-	type Signal, type MaybeSignal, type ComputedCallback,
-    UNSET, isSignal, isComputedCallback, toSignal, match,
-}

package/lib/state.ts

@@ -1,118 +0,0 @@
-import { UNSET } from './signal'
-import { type Computed, computed } from './computed'
-import { isFunction, isObjectOfType } from './util'
-import { type Watcher, notify, subscribe } from './scheduler'
-import { type TapMatcher, type EffectMatcher, effect } from './effect'
-
-/* === Types === */
-
-export 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 === */
-
-/**
- * Create a new state signal
- * 
- * @since 0.9.0
- * @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 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))
-        },
-
-		/**
-		 * 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
-}
-
-/**
- * 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
- */
-export const isState = /*#__PURE__*/ <T extends {}>(value: unknown): value is State<T> =>
-	isObjectOfType(value, TYPE_STATE)