@zeix/cause-effect 0.9.7

package/.editorconfig

@@ -0,0 +1,7 @@
+root = true
+
+[*]
+indent_style = tab
+indent_size = 4
+end_of_line = lf
+charset = utf-8

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 - 2025 Zeix AG
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,122 @@
+# Cause & Effect
+
+Version 0.9.7
+
+**Cause & Effect** - efficient state management with signals that sync instantly and reactively across your application.
+
+## Key Features
+
+* **Efficient State Management**: Use lightweight signals for state updates that automatically notify dependents when needed.
+* **Support for Asynchronous Operations**: Handle state updates smoothly, even when dealing with network requests or Promise-based libraries, without disrupting reactivity.
+* **Memoized Computed Signals**: Optionally create derived values that are cached and automatically recalculated when source data changes.
+
+## Installation
+
+```bash
+# with npm
+npm install @zeix/cause-effect
+
+# or with bun
+bun add @zeix/cause-effect
+```
+
+## Basic Usage
+
+### Single State Signal
+
+`state()` creates a new state signal. To access the current value of the signal use the `.get()` method. To update the value of the signal use the `.set()` method with a new value or an updater function of the form `(v: T) => T`.
+
+```js
+import { state, effect } from '@zeix/cause-effect'
+
+const count = state(42)
+effect(() => console.log(count.get())) // logs '42'
+count.set(24) // logs '24'
+document.querySelector('button.increment')
+    .addEventListener('click', () => count.set(v => ++v))
+// Click on button logs '25', '26', and so on
+```
+
+### Sync Computed Signal
+
+`computed()` creates a new computed signal. Computed signals are read-only and you can access the current resulting value using the `.get()` method.
+
+```js
+import { state, computed, effect } from '@zeix/cause-effect'
+
+const count = state(42)
+const isOdd = computed(() => count.get() % 2)
+effect(() => console.log(isOdd.get())) // logs 'false'
+count.set(24) // logs nothing because 24 is also an even number
+document.querySelector('button.increment')
+    .addEventListener('click', () => count.set(v => ++v))
+// Click on button logs 'true', 'false', and so on
+```
+
+If you want to derive a computed signal from a single other signal you can use the `.map()` method on either `State` or `Computed`. This does the same as the snippet above:
+
+```js
+import { state, effect } from '@zeix/cause-effect'
+
+const count = state(42)
+const isOdd = count.map(v => v % 2)
+effect(() => console.log(isOdd.get())) // logs 'false'
+count.set(24) // logs nothing because 24 is also an even number
+document.querySelector('button.increment')
+    .addEventListener('click', () => count.set(v => ++v))
+// Click on button logs 'true', 'false', and so on
+```
+
+### Async Computed Signal
+
+Async computed signals are as straight forward as their sync counterparts. Just create the computed signal with an async function.
+
+**Caution**: You can't use the `.map()` method to create an async computed signal. And async computed signals will return `undefined` until the Promise is resolved.
+
+```js
+import { state, computed, effect } from '@zeix/cause-effect'
+
+const entryId = state(42)
+const entryData = computed(async () => {
+    const response = await fetch(`/api/entry/${entryId.get()}`)
+    if (!response.ok) return new Error(`Failed to fetch data: ${response.statusText}`)
+    return response.json()
+})
+effect(() => {
+    let data
+    try {
+        data = entryData.get()
+    } catch (error) {
+        console.error(error.message) // logs the error message if an error ocurred
+        return
+    }
+    if (null == data) return // doesn't do anything while we are still waiting for the data
+    document.querySelector('.entry h2').textContent = data.title
+    document.querySelector('.entry p').textContent = data.description
+})
+// Updates h1 and p of the entry as soon as fetched data for entry becomes available
+document.querySelector('button.next')
+    .addEventListener('click', () => entryId.set(v => ++v))
+// Click on button updates h1 and p of the entry as soon as fetched data for the next entry is loaded
+```
+
+### Effects and Batching
+
+Effects run synchronously as soon as source signals update. If you need to set multiple signals you can batch them together to ensure dependents are executed only once.
+
+```js
+import { state, computed, effect, batch } from '@zeix/cause-effect'
+
+const a = state(3)
+const b = state(4)
+const sum = computed(() => a.get() + b.get())
+effect(() => console.log(sum.get())) // logs '7'
+document.querySelector('button.double-all')
+    .addEventListener('click', () =>
+        batch(() => {
+            a.set(v => v * 2)
+            b.set(v => v * 2)
+        }
+    ))
+// Click on button logs '14' only once (instead of first '10' and then '14' without batch)
+```

package/index.d.ts

@@ -0,0 +1,9 @@
+/**
+ * @name Cause & Effect
+ * @version 0.9.7
+ * @author Esther Brunner
+ */
+export { UNSET, State, state, isState } from './lib/state';
+export { type Computed, computed, isComputed } from './lib/computed';
+export { type Signal, isSignal, toSignal, batch } from './lib/signal';
+export { effect } from './lib/effect';

package/index.js

@@ -0,0 +1 @@
+var A=(y)=>typeof y==="function",D=(y)=>A(y)&&/^async\s+/.test(y.toString()),G=(y)=>(x)=>x instanceof y,X=G(Error),O=G(Promise);var R="Computed",q=(y,x)=>{x=x??D(y);let j=[],Q,B=null,W=!0,S=()=>{if(W=!0,x)I(j)},Y={[Symbol.toStringTag]:R,get:()=>{if(x)H(j);if(!x||W)J(()=>{let F=(L)=>{Q=L,W=!1,B=null},C=(L)=>{B=X(L)?L:new Error(`Computed function failed: ${L}`)};try{let L=y(Q);O(L)?L.then(F).catch(C):F(L)}catch(L){C(L)}},S);if(X(B))throw B;return Q},map:(F)=>q(()=>F(Y.get()))};return Y},Z=(y)=>!!y&&typeof y==="object"&&y[Symbol.toStringTag]===R;var z,$=!1,N=[],P=(y)=>M(y)||Z(y),U=(y,x=!1)=>P(y)?y:A(y)?q(y,x):k(y),H=(y)=>{if(z&&!y.includes(z))y.push(z)},I=(y)=>y.forEach((x)=>$?N.push(x):x()),J=(y,x)=>{let j=z;z=x,y(),z=j},T=(y)=>{$=!0,y(),$=!1,N.forEach((x)=>x()),N.length=0};var V=Symbol();class K{y;watchers=[];constructor(y){this.value=y}get(){return H(this.watchers),this.value}set(y){if(V!==y){let x=A(y)?y(this.value):y;if(Object.is(this.value,x))return;this.value=x}if(I(this.watchers),V===y)this.watchers=[]}map(y){return q(()=>y(this.get()))}}var k=(y)=>new K(y),M=G(K);var p=(y)=>{let x=()=>J(()=>{try{y()}catch(j){console.error(j)}},x);x()};export{U as toSignal,k as state,M as isState,P as isSignal,Z as isComputed,p as effect,q as computed,T as batch,V as UNSET,K as State};

package/index.ts

@@ -0,0 +1,9 @@
+/**
+ * @name Cause & Effect
+ * @version 0.9.7
+ * @author Esther Brunner
+ */
+export { UNSET, State, state, isState } from './lib/state'
+export { type Computed, computed, isComputed } from './lib/computed'
+export { type Signal, isSignal, toSignal, batch } from './lib/signal'
+export { effect } from './lib/effect'

package/lib/computed.d.ts

@@ -0,0 +1,14 @@
+export type Computed<T> = {
+    [Symbol.toStringTag]: "Computed";
+    get: () => T;
+    map: <U>(fn: (value: T) => U) => Computed<U>;
+};
+/**
+ * Create a derived state from existing states
+ *
+ * @since 0.9.0
+ * @param {() => T} fn - compute function to derive state
+ * @returns {Computed<T>} result of derived state
+ */
+export declare const computed: <T>(fn: (v?: T) => T | Promise<T>, memo?: boolean) => Computed<T>;
+export declare const isComputed: <T>(value: unknown) => value is Computed<T>;

package/lib/computed.ts

@@ -0,0 +1,75 @@
+import { type Watcher, subscribe, notify, watch } from "./signal"
+import { isAsyncFunction, isError, isPromise } from "./util"
+
+/* === Types === */
+
+export type Computed<T> = {
+    [Symbol.toStringTag]: "Computed"
+    get: () => T
+    map: <U>(fn: (value: T) => U) => Computed<U>
+}
+
+/* === Constants === */
+
+const TYPE_COMPUTED = 'Computed'
+
+/* === Namespace Computed === */
+
+/**
+ * Create a derived state from existing states
+ * 
+ * @since 0.9.0
+ * @param {() => T} fn - compute function to derive state
+ * @returns {Computed<T>} result of derived state
+ */
+export const computed =  /*#__PURE__*/ <T>(
+	fn: (v?: T) => T | Promise<T>,
+	memo?: boolean
+): Computed<T> => {
+	memo = memo ?? isAsyncFunction(fn)
+	const watchers: Watcher[] = []
+	let value: T
+	let error: Error | null = null
+	let stale = true
+
+	const mark: Watcher = () => {
+		stale = true
+		if (memo) notify(watchers)
+	}
+
+	const c: Computed<T> = {
+		[Symbol.toStringTag]: TYPE_COMPUTED,
+		get: () => {
+			if (memo) subscribe(watchers)
+			if (!memo || stale) watch(() => {
+				const handleOk = (v: T) => {
+					value = v
+					stale = false
+					error = null
+				}
+				const handleErr = (e: unknown) => {
+					error = isError(e)
+						? e
+						: new Error(`Computed function failed: ${e}`)
+				}
+				try {
+					const res = fn(value)
+					isPromise(res)
+						? res.then(handleOk).catch(handleErr)
+						: handleOk(res)
+				} catch (e) {
+					handleErr(e)
+				}
+			}, mark)
+			if (isError(error)) throw error
+			return value
+		},
+		map: <U>(fn: (value: T) => U): Computed<U> =>
+			computed(() => fn(c.get())),
+	}
+	return c
+}
+
+export const isComputed = /*#__PURE__*/ <T>(value: unknown): value is Computed<T> =>
+	!!value && typeof value === 'object'
+		&& (value as { [key in typeof Symbol.toStringTag]: string })[Symbol.toStringTag] === TYPE_COMPUTED

package/lib/effect.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Define what happens when a reactive state changes
+ *
+ * @since 0.1.0
+ * @param {() => void} fn - callback function to be executed when a state changes
+ */
+export declare const effect: (fn: () => void) => void;

package/lib/effect.ts

@@ -0,0 +1,21 @@
+
+import { type Watcher, watch } from "./signal"
+
+/* === Exported Function === */
+
+/**
+ * Define what happens when a reactive state changes
+ * 
+ * @since 0.1.0
+ * @param {() => void} fn - callback function to be executed when a state changes
+ */
+export const effect = (fn: () => void) => {
+	const run: Watcher = () => watch(() => {
+        try {
+            fn()
+        } catch (error) {
+            console.error(error)
+        }
+    }, run)
+	run()
+}

package/lib/signal.d.ts

@@ -0,0 +1,48 @@
+import { type State } from "./state";
+import { type Computed } from "./computed";
+type Signal<T> = State<T> | Computed<T>;
+type MaybeSignal<T> = State<T> | Computed<T> | T;
+type Watcher = () => void;
+/**
+ * Check whether a value is a Signal or not
+ *
+ * @since 0.9.0
+ * @param {any} value - value to check
+ * @returns {boolean} - true if value is a Signal, false otherwise
+ */
+declare const isSignal: <T>(value: any) => value is Signal<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
+ * @param memo
+ * @returns {Signal<T>} - converted Signal
+ */
+declare const toSignal: <T>(value: MaybeSignal<T>, memo?: boolean) => Signal<T>;
+/**
+ * Add notify function of active watchers to the set of watchers
+ *
+ * @param {Watcher[]} watchers - set of current watchers
+ */
+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 Watcher, isSignal, toSignal, subscribe, notify, watch, batch };

package/lib/signal.ts

@@ -0,0 +1,98 @@
+import { type State, isState, state } from "./state"
+import { computed, type Computed, isComputed } from "./computed"
+import { isFunction } from "./util"
+
+/* === Types === */
+
+type Signal<T> = State<T> | Computed<T>
+
+type MaybeSignal<T> = State<T> | Computed<T> | T
+
+type Watcher = () => void
+
+/* === Internals === */
+
+// Currently active watcher
+let active: () => void | undefined
+
+// Batching state
+let batching = false
+
+// Pending notifications
+const pending: Watcher[] = []
+
+/* === Exported Functions === */
+
+/**
+ * Check whether a value is a Signal or not
+ * 
+ * @since 0.9.0
+ * @param {any} value - value to check
+ * @returns {boolean} - true if value is a Signal, false otherwise
+ */
+const isSignal = /*#__PURE__*/ <T>(value: any): value is Signal<T> =>
+	isState(value) || isComputed(value)
+
+/**
+ * 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
+ * @param memo 
+ * @returns {Signal<T>} - converted Signal
+ */
+const toSignal = /*#__PURE__*/ <T>(
+	value: MaybeSignal<T>,
+	memo: boolean = false
+): Signal<T> =>
+	isSignal<T>(value) ? value
+		: isFunction(value) ? computed(value, memo)
+		: 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
+ * 
+ * @param {Watcher[]} watchers 
+ */
+const notify = (watchers: Watcher[]) =>
+	watchers.forEach(n => batching ? pending.push(n) : n())
+
+/**
+ * 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 => {
+    batching = true
+    run()
+    batching = false
+    pending.forEach(n => n())
+    pending.length = 0
+}
+
+export {
+	type Signal, type Watcher,
+    isSignal, toSignal, subscribe, notify, watch, batch
+}

package/lib/state.d.ts

@@ -0,0 +1,38 @@
+import { type Computed } from "./computed";
+export declare const UNSET: any;
+/**
+ * Define a reactive state
+ *
+ * @since 0.9.0
+ * @class State
+ */
+export declare class State<T> {
+    private value;
+    private watchers;
+    constructor(value: T);
+    /**
+     * Get the current value of the state
+     *
+     * @method of State<T>
+     * @returns {T} - current value of the state
+     */
+    get(): T;
+    /**
+     * Set a new value of the state
+     *
+     * @method of State<T>
+     * @param {T | ((v: T) => T)} value
+     * @returns {void}
+     */
+    set(value: T | ((v: T) => T)): void;
+    map<U>(fn: (value: T) => U): Computed<U>;
+}
+/**
+ * Create a new state signal
+ *
+ * @static method of State<T>
+ * @param {T} value - initial value of the state
+ * @returns {State<T>} - new state signal
+ */
+export declare const state: <T>(value: T) => State<T>;
+export declare const isState: (value: unknown) => value is State<any>;

package/lib/state.ts

@@ -0,0 +1,67 @@
+import { isFunction, isInstanceOf } from "./util"
+import { type Watcher, subscribe, notify } from "./signal"
+import { type Computed, computed } from "./computed"
+
+/* === Constants === */
+
+export const UNSET: any = Symbol()
+
+/* === Class State === */
+
+/**
+ * Define a reactive state
+ * 
+ * @since 0.9.0
+ * @class State
+ */
+export class State<T> {
+    private watchers: Watcher[] = []
+
+    constructor(private value: T) {}
+
+	/**
+	 * Get the current value of the state
+	 * 
+	 * @method of State<T>
+	 * @returns {T} - current value of the state
+	 */
+    get(): T {
+        subscribe(this.watchers)
+        return this.value
+    }
+
+	/**
+	 * Set a new value of the state
+	 * 
+	 * @method of State<T>
+	 * @param {T | ((v: T) => T)} value
+	 * @returns {void}
+	 */
+    set(value: T | ((v: T) => T)): void {
+		if (UNSET !== value) {
+			const newValue = isFunction(value) ? value(this.value) : value
+			if (Object.is(this.value, newValue)) return
+			this.value = newValue
+		}
+		notify(this.watchers)
+
+		// Setting to null clears the watchers so the signal can be garbage collected
+		if (UNSET === value) this.watchers = []
+    }
+
+    map<U>(fn: (value: T) => U): Computed<U> {
+        return computed<U>(() => fn(this.get()))
+    }
+}
+
+/**
+ * Create a new state signal
+ * 
+ * @static method of State<T>
+ * @param {T} value - initial value of the state
+ * @returns {State<T>} - new state signal
+ */
+export const state = /*#__PURE__*/ <T>(value: T): State<T> =>
+	new State(value)
+
+export const isState = /*#__PURE__*/ isInstanceOf(State)

package/lib/util.d.ts

@@ -0,0 +1,6 @@
+declare const isFunction: (value: unknown) => value is (...args: any[]) => any;
+declare const isAsyncFunction: (value: unknown) => value is (...args: any[]) => Promise<any> | PromiseLike<any>;
+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>;
+export { isFunction, isAsyncFunction, isInstanceOf, isError, isPromise };

package/lib/util.ts

@@ -0,0 +1,16 @@
+/* === Utility Functions === */
+
+const isFunction = /*#__PURE__*/ (value: unknown): value is (...args: any[]) => any =>
+    typeof value === 'function'
+
+const isAsyncFunction = /*#__PURE__*/ (value: unknown): value is (...args: any[]) => Promise<any> | PromiseLike<any> =>
+	isFunction(value) && /^async\s+/.test(value.toString())
+
+const isInstanceOf = /*#__PURE__*/ <T>(type: new (...args: any[]) => T) =>
+	(value: unknown): value is T =>
+		value instanceof type
+
+const isError = /*#__PURE__*/ isInstanceOf(Error)
+const isPromise = /*#__PURE__*/ isInstanceOf(Promise)
+
+export { isFunction, isAsyncFunction, isInstanceOf, isError, isPromise }

package/package.json

@@ -0,0 +1,30 @@
+{
+  "name": "@zeix/cause-effect",
+  "version": "0.9.7",
+  "author": "Esther Brunner",
+  "main": "index.js",
+  "module": "index.ts",
+  "devDependencies": {
+    "@types/bun": "latest"
+  },
+  "peerDependencies": {
+    "typescript": "^5.6.3"
+  },
+  "description": "Cause & Effect - reactive state management with signals.",
+  "license": "MIT",
+  "keywords": [
+    "Cause & Effect",
+    "Reactivity",
+    "Signals",
+    "Effects"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "bun build index.ts --outdir ./ --minify && bunx tsc",
+    "test": "bun test"
+  },
+  "type": "module",
+  "types": "index.d.ts"
+}