@zeix/cause-effect 0.15.2 → 0.16.0

package/index.ts

@@ -1,13 +1,13 @@
 /**
  * @name Cause & Effect
- * @version 0.15.1
+ * @version 0.16.0
  * @author Esther Brunner
  */
 
 export {
 	type Computed,
 	type ComputedCallback,
-	computed,
+	createComputed,
 	isComputed,
 	isComputedCallback,
 	TYPE_COMPUTED,
@@ -20,9 +20,14 @@ export {
 	type UnknownRecord,
 	type UnknownRecordOrArray,
 } from './src/diff'
-export { type EffectCallback, effect, type MaybeCleanup } from './src/effect'
+export {
+	createEffect,
+	type EffectCallback,
+	type MaybeCleanup,
+} from './src/effect'
 export {
 	CircularDependencyError,
+	InvalidCallbackError,
 	InvalidSignalValueError,
 	NullishSignalValueError,
 	StoreKeyExistsError,
@@ -31,18 +36,6 @@ export {
 } from './src/errors'
 export { type MatchHandlers, match } from './src/match'
 export { type ResolveResult, resolve } from './src/resolve'
-export {
-	batch,
-	type Cleanup,
-	enqueue,
-	flush,
-	notify,
-	observe,
-	subscribe,
-	type Updater,
-	type Watcher,
-	watch,
-} from './src/scheduler'
 export {
 	isMutableSignal,
 	isSignal,
@@ -51,18 +44,24 @@ export {
 	toSignal,
 	type UnknownSignalRecord,
 } from './src/signal'
-export { isState, type State, state, TYPE_STATE } from './src/state'
+export { createState, isState, type State, TYPE_STATE } from './src/state'
 export {
+	createStore,
 	isStore,
 	type Store,
-	type StoreAddEvent,
-	type StoreChangeEvent,
-	type StoreEventMap,
-	type StoreRemoveEvent,
-	type StoreSortEvent,
-	store,
+	type StoreChanges,
 	TYPE_STORE,
 } from './src/store'
+export {
+	batch,
+	type Cleanup,
+	createWatcher,
+	flush,
+	notify,
+	observe,
+	subscribe,
+	type Watcher,
+} from './src/system'
 export {
 	isAbortError,
 	isAsyncFunction,
@@ -74,4 +73,5 @@ export {
 	isSymbol,
 	toError,
 	UNSET,
+	valueString,
 } from './src/util'

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@zeix/cause-effect",
-	"version": "0.15.2",
+	"version": "0.16.0",
 	"author": "Esther Brunner",
 	"main": "index.js",
 	"module": "index.ts",

package/src/computed.ts

@@ -1,13 +1,17 @@
 import { isEqual } from './diff'
-import { CircularDependencyError } from './errors'
 import {
+	CircularDependencyError,
+	InvalidCallbackError,
+	NullishSignalValueError,
+} from './errors'
+import {
+	createWatcher,
 	flush,
 	notify,
 	observe,
 	subscribe,
 	type Watcher,
-	watch,
-} from './scheduler'
+} from './system'
 import {
 	isAbortError,
 	isAsyncFunction,
@@ -15,17 +19,18 @@ import {
 	isObjectOfType,
 	toError,
 	UNSET,
+	valueString,
 } from './util'
 
 /* === Types === */
 
 type Computed<T extends {}> = {
-	[Symbol.toStringTag]: 'Computed'
+	readonly [Symbol.toStringTag]: 'Computed'
 	get(): T
 }
 type ComputedCallback<T extends {} & { then?: undefined }> =
-	| ((abort: AbortSignal) => Promise<T>)
-	| (() => T)
+	| ((oldValue: T, abort: AbortSignal) => Promise<T>)
+	| ((oldValue: T) => T)
 
 /* === Constants === */
 
@@ -37,14 +42,21 @@ const TYPE_COMPUTED = 'Computed'
  * Create a derived signal from existing signals
  *
  * @since 0.9.0
- * @param {ComputedCallback<T>} fn - computation callback function
+ * @param {ComputedCallback<T>} callback - Computation callback function
  * @returns {Computed<T>} - Computed signal
  */
-const computed = <T extends {}>(fn: ComputedCallback<T>): Computed<T> => {
+const createComputed = <T extends {}>(
+	callback: ComputedCallback<T>,
+	initialValue: T = UNSET,
+): Computed<T> => {
+	if (!isComputedCallback(callback))
+		throw new InvalidCallbackError('computed', valueString(callback))
+	if (initialValue == null) throw new NullishSignalValueError('computed')
+
 	const watchers: Set<Watcher> = new Set()
 
 	// Internal state
-	let value: T = UNSET
+	let value: T = initialValue
 	let error: Error | undefined
 	let controller: AbortController | undefined
 	let dirty = true
@@ -75,22 +87,22 @@ const computed = <T extends {}>(fn: ComputedCallback<T>): Computed<T> => {
 		error = newError
 	}
 	const settle =
-		<T>(settleFn: (arg: T) => void) =>
+		<T>(fn: (arg: T) => void) =>
 		(arg: T) => {
 			computing = false
 			controller = undefined
-			settleFn(arg)
+			fn(arg)
 			if (changed) notify(watchers)
 		}
 
 	// Own watcher: called when notified from sources (push)
-	const mark = watch(() => {
+	const watcher = createWatcher(() => {
 		dirty = true
 		controller?.abort()
 		if (watchers.size) notify(watchers)
-		else mark.cleanup()
+		else watcher.cleanup()
 	})
-	mark.off(() => {
+	watcher.unwatch(() => {
 		controller?.abort()
 	})
 
@@ -99,7 +111,7 @@ const computed = <T extends {}>(fn: ComputedCallback<T>): Computed<T> => {
 		observe(() => {
 			if (computing) throw new CircularDependencyError('computed')
 			changed = false
-			if (isAsyncFunction(fn)) {
+			if (isAsyncFunction(callback)) {
 				// Return current value until promise resolves
 				if (controller) return value
 				controller = new AbortController()
@@ -108,9 +120,7 @@ const computed = <T extends {}>(fn: ComputedCallback<T>): Computed<T> => {
 					() => {
 						computing = false
 						controller = undefined
-
-						// Retry computation with updated state
-						compute()
+						compute() // Retry computation with updated state
 					},
 					{
 						once: true,
@@ -120,7 +130,9 @@ const computed = <T extends {}>(fn: ComputedCallback<T>): Computed<T> => {
 			let result: T | Promise<T>
 			computing = true
 			try {
-				result = controller ? fn(controller.signal) : (fn as () => T)()
+				result = controller
+					? callback(value, controller.signal)
+					: (callback as (oldValue: T) => T)(value)
 			} catch (e) {
 				if (isAbortError(e)) nil()
 				else err(e)
@@ -131,16 +143,16 @@ const computed = <T extends {}>(fn: ComputedCallback<T>): Computed<T> => {
 			else if (null == result || UNSET === result) nil()
 			else ok(result)
 			computing = false
-		}, mark)
+		}, watcher)
 
-	const c: Computed<T> = {
+	return {
 		[Symbol.toStringTag]: TYPE_COMPUTED,
 
 		/**
 		 * Get the current value of the computed
 		 *
 		 * @since 0.9.0
-		 * @returns {T} - current value of the computed
+		 * @returns {T} - Current value of the computed
 		 */
 		get: (): T => {
 			subscribe(watchers)
@@ -150,15 +162,14 @@ const computed = <T extends {}>(fn: ComputedCallback<T>): Computed<T> => {
 			return value
 		},
 	}
-	return c
 }
 
 /**
- * Check if a value is a computed state
+ * Check if a value is a computed signal
  *
  * @since 0.9.0
- * @param {unknown} value - value to check
- * @returns {boolean} - true if value is a computed state, false otherwise
+ * @param {unknown} value - Value to check
+ * @returns {boolean} - true if value is a computed signal, false otherwise
  */
 const isComputed = /*#__PURE__*/ <T extends {}>(
 	value: unknown,
@@ -168,18 +179,18 @@ const isComputed = /*#__PURE__*/ <T extends {}>(
  * 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
+ * @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 is ComputedCallback<T> => isFunction(value) && value.length < 3
 
 /* === Exports === */
 
 export {
 	TYPE_COMPUTED,
-	computed,
+	createComputed,
 	isComputed,
 	isComputedCallback,
 	type Computed,

package/src/effect.ts

@@ -1,6 +1,6 @@
-import { CircularDependencyError } from './errors'
-import { type Cleanup, observe, watch } from './scheduler'
-import { isAbortError, isAsyncFunction, isFunction } from './util'
+import { CircularDependencyError, InvalidCallbackError } from './errors'
+import { type Cleanup, createWatcher, observe } from './system'
+import { isAbortError, isAsyncFunction, isFunction, valueString } from './util'
 
 /* === Types === */
 
@@ -24,12 +24,15 @@ type EffectCallback =
  * @param {EffectCallback} callback - Synchronous or asynchronous effect callback
  * @returns {Cleanup} - Cleanup function for the effect
  */
-const effect = (callback: EffectCallback): Cleanup => {
-	const isAsync = isAsyncFunction<MaybeCleanup>(callback)
+const createEffect = (callback: EffectCallback): Cleanup => {
+	if (!isFunction(callback) || callback.length > 1)
+		throw new InvalidCallbackError('effect', valueString(callback))
+
+	const isAsync = isAsyncFunction(callback)
 	let running = false
 	let controller: AbortController | undefined
 
-	const run = watch(() =>
+	const watcher = createWatcher(() =>
 		observe(() => {
 			if (running) throw new CircularDependencyError('effect')
 			running = true
@@ -52,7 +55,7 @@ const effect = (callback: EffectCallback): Cleanup => {
 								isFunction(cleanup) &&
 								controller === currentController
 							)
-								run.off(cleanup)
+								watcher.unwatch(cleanup)
 						})
 						.catch(error => {
 							if (!isAbortError(error))
@@ -60,7 +63,7 @@ const effect = (callback: EffectCallback): Cleanup => {
 						})
 				} else {
 					cleanup = (callback as () => MaybeCleanup)()
-					if (isFunction(cleanup)) run.off(cleanup)
+					if (isFunction(cleanup)) watcher.unwatch(cleanup)
 				}
 			} catch (error) {
 				if (!isAbortError(error))
@@ -68,16 +71,16 @@ const effect = (callback: EffectCallback): Cleanup => {
 			}
 
 			running = false
-		}, run),
+		}, watcher),
 	)
 
-	run()
+	watcher()
 	return () => {
 		controller?.abort()
-		run.cleanup()
+		watcher.cleanup()
 	}
 }
 
 /* === Exports === */
 
-export { type MaybeCleanup, type EffectCallback, effect }
+export { type MaybeCleanup, type EffectCallback, createEffect }

package/src/errors.ts

@@ -5,6 +5,13 @@ class CircularDependencyError extends Error {
 	}
 }
 
+class InvalidCallbackError extends TypeError {
+	constructor(where: string, value: string) {
+		super(`Invalid ${where} callback ${value}`)
+		this.name = 'InvalidCallbackError'
+	}
+}
+
 class InvalidSignalValueError extends TypeError {
 	constructor(where: string, value: string) {
 		super(`Invalid signal value ${value} in ${where}`)
@@ -48,6 +55,7 @@ class StoreKeyReadonlyError extends Error {
 
 export {
 	CircularDependencyError,
+	InvalidCallbackError,
 	InvalidSignalValueError,
 	NullishSignalValueError,
 	StoreKeyExistsError,

package/src/signal.ts

@@ -1,12 +1,12 @@
 import {
 	type Computed,
 	type ComputedCallback,
-	computed,
+	createComputed,
 	isComputed,
 	isComputedCallback,
 } from './computed'
-import { isState, type State, state } from './state'
-import { isStore, type Store, store } from './store'
+import { createState, isState, type State } from './state'
+import { createStore, isStore, type Store } from './store'
 import { isRecord } from './util'
 
 /* === Types === */
@@ -71,9 +71,9 @@ function toSignal<T extends {}>(
 							: State<T>
 function toSignal<T extends {}>(value: T) {
 	if (isSignal<T>(value)) return value
-	if (isComputedCallback(value)) return computed(value)
-	if (Array.isArray(value) || isRecord(value)) return store(value)
-	return state(value)
+	if (isComputedCallback(value)) return createComputed(value)
+	if (Array.isArray(value) || isRecord(value)) return createStore(value)
+	return createState(value)
 }
 
 /* === Exports === */

package/src/state.ts

@@ -1,15 +1,15 @@
 import { isEqual } from './diff'
-import { NullishSignalValueError } from './errors'
-import { notify, subscribe, type Watcher } from './scheduler'
-import { isObjectOfType, UNSET } from './util'
+import { InvalidCallbackError, NullishSignalValueError } from './errors'
+import { notify, subscribe, type Watcher } from './system'
+import { isFunction, isObjectOfType, UNSET, valueString } from './util'
 
 /* === Types === */
 
 type State<T extends {}> = {
-	[Symbol.toStringTag]: 'State'
+	readonly [Symbol.toStringTag]: 'State'
 	get(): T
-	set(v: T): void
-	update(fn: (v: T) => T): void
+	set(newValue: T): void
+	update(updater: (oldValue: T) => T): void
 }
 
 /* === Constants === */
@@ -25,18 +25,20 @@ const TYPE_STATE = 'State'
  * @param {T} initialValue - initial value of the state
  * @returns {State<T>} - new state signal
  */
-const state = /*#__PURE__*/ <T extends {}>(initialValue: T): State<T> => {
+const createState = /*#__PURE__*/ <T extends {}>(initialValue: T): State<T> => {
+	if (initialValue == null) throw new NullishSignalValueError('state')
+
 	const watchers: Set<Watcher> = new Set()
 	let value: T = initialValue
 
-	const s: State<T> = {
+	const state: State<T> = {
 		[Symbol.toStringTag]: TYPE_STATE,
 
 		/**
 		 * Get the current value of the state
 		 *
 		 * @since 0.9.0
-		 * @returns {T} - current value of the state
+		 * @returns {T} - Current value of the state
 		 */
 		get: (): T => {
 			subscribe(watchers)
@@ -47,13 +49,13 @@ const state = /*#__PURE__*/ <T extends {}>(initialValue: T): State<T> => {
 		 * Set a new value of the state
 		 *
 		 * @since 0.9.0
-		 * @param {T} v
+		 * @param {T} newValue - New value of the state
 		 * @returns {void}
 		 */
-		set: (v: T): void => {
-			if (v == null) throw new NullishSignalValueError('state')
-			if (isEqual(value, v)) return
-			value = v
+		set: (newValue: T): void => {
+			if (newValue == null) throw new NullishSignalValueError('state')
+			if (isEqual(value, newValue)) return
+			value = newValue
 			notify(watchers)
 
 			// Setting to UNSET clears the watchers so the signal can be garbage collected
@@ -64,15 +66,20 @@ const state = /*#__PURE__*/ <T extends {}>(initialValue: T): State<T> => {
 		 * 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
+		 * @param {(v: T) => T} updater - Function to update the state
+		 * @returns {void}
 		 */
-		update: (fn: (v: T) => T): void => {
-			s.set(fn(value))
+		update: (updater: (oldValue: T) => T): void => {
+			if (!isFunction(updater))
+				throw new InvalidCallbackError(
+					'state update',
+					valueString(updater),
+				)
+			state.set(updater(value))
 		},
 	}
 
-	return s
+	return state
 }
 
 /**
@@ -88,4 +95,4 @@ const isState = /*#__PURE__*/ <T extends {}>(
 
 /* === Exports === */
 
-export { TYPE_STATE, isState, state, type State }
+export { TYPE_STATE, isState, createState, type State }