@zeix/cause-effect 0.14.1 → 0.15.0

package/README.md

@@ -1,6 +1,6 @@
 # Cause & Effect
 
-Version 0.14.1
+Version 0.15.0
 
 **Cause & Effect** is a lightweight, reactive state management library for JavaScript applications. It uses fine-grained reactivity with signals to create predictable and efficient data flow in your app.
 
@@ -11,6 +11,7 @@ Version 0.14.1
 ### Core Concepts
 
 - **State signals**: Hold values that can be directly modified: `state()`
+- **Store signals**: Hold objects of nested reactive properties: `store()`
 - **Computed signals**: Derive memoized values from other signals: `computed()`
 - **Effects**: Run side effects when signals change: `effect()`
 
@@ -19,9 +20,10 @@ Version 0.14.1
 - ⚡ **Reactive States**: Automatic updates when dependencies change
 - 🧩 **Composable**: Create a complex signal graph with a minimal API
 - ⏱️ **Async Ready**: Built-in `Promise` and `AbortController` support
-- 🛡️ **Error Handling**: Declare handlers for errors and unset states in effects
+- 🛡️ **Error Handling**: Built-in helper functions for declarative error handling
+- 🔧 **Helper Functions**: `resolve()` and `match()` for type-safe value extraction and pattern matching for suspense and error boundaries
 - 🚀 **Performance**: Batching and efficient dependency tracking
-- 📦 **Tiny**: Around 1kB gzipped, zero dependencies
+- 📦 **Tiny**: Less than 3kB gzipped, zero dependencies
 
 ## Quick Start
 
@@ -73,6 +75,114 @@ document.querySelector('.increment').addEventListener('click', () => {
 // Click on button logs '25', '26', and so on
 ```
 
+### Store Signals
+
+`store()` creates a mutable signal that holds an object with nested reactive properties. Each property automatically becomes its own signal with `.get()`, `.set()`, and `.update()` methods. Nested objects recursively become nested stores.
+
+```js
+import { store, effect } from '@zeix/cause-effect'
+
+const user = store({
+  name: 'Alice',
+  age: 30,
+  preferences: {
+    theme: 'dark',
+    notifications: true
+  }
+})
+
+// Individual properties are reactive
+effect(() => {
+  console.log(`${user.name.get()} is ${user.age.get()} years old`)
+})
+
+// Nested properties work the same way
+effect(() => {
+  console.log(`Theme: ${user.preferences.theme.get()}`)
+})
+
+// Update individual properties
+user.age.update(v => v + 1) // Logs: "Alice is 31 years old"
+user.preferences.theme.set('light') // Logs: "Theme: light"
+
+// Watch the entire store
+effect(() => {
+  console.log('User data:', user.get()) // Triggers on any nested change
+})
+```
+
+#### Dynamic Properties
+
+Stores support dynamic property addition and removal at runtime using the `add()` and `remove()` methods:
+
+```js
+import { store, effect } from '@zeix/cause-effect'
+
+const settings = store({ autoSave: true })
+
+// Add new properties at runtime
+settings.add('timeout', 5000)
+console.log(settings.timeout.get()) // 5000
+
+// Adding an existing property has no effect
+settings.add('autoSave', false) // Ignored - autoSave remains true
+
+// Remove properties
+settings.remove('timeout')
+console.log(settings.timeout) // undefined
+
+// Removing non-existent properties has no effect
+settings.remove('nonExistent') // Safe - no error thrown
+```
+
+The `add()` and `remove()` methods are optimized for performance:
+- They bypass the full reconciliation process used by `set()` and `update()`
+- They're perfect for frequent single-property additions/removals
+- They trigger the same events and reactivity as other store operations
+
+#### Store Events
+
+Stores emit events when properties are added, changed, or removed. You can listen to these events using standard `addEventListener()`:
+
+```js
+import { store } from '@zeix/cause-effect'
+
+const user = store({ name: 'Alice', age: 30 })
+
+// Listen for property additions
+user.addEventListener('store-add', (event) => {
+  console.log('Added properties:', event.detail)
+})
+
+// Listen for property changes
+user.addEventListener('store-change', (event) => {
+  console.log('Changed properties:', event.detail)
+})
+
+// Listen for property removals
+user.addEventListener('store-remove', (event) => {
+  console.log('Removed properties:', event.detail)
+})
+
+// These will trigger the respective events:
+user.add('email', 'alice@example.com') // Logs: "Added properties: { email: 'alice@example.com' }"
+user.age.set(31)                       // Logs: "Changed properties: { age: 31 }"
+user.remove('email')                   // Logs: "Removed properties: { email: UNSET }"
+```
+
+Events are also fired when using `set()` or `update()` methods on the entire store:
+
+```js
+// This will fire multiple events based on what changed
+user.update(u => ({ ...u, name: 'Bob', city: 'New York' }))
+// Logs: "Changed properties: { name: 'Bob' }"
+// Logs: "Added properties: { city: 'New York' }"
+```
+
+**When to use stores vs state:**
+- **Use `store()`** for objects with reactive properties that you want to access individually
+- **Use `state()`** for primitive values or objects you replace entirely
+
 ### Computed Signals vs. Functions
 
 #### When to Use Computed Signals
@@ -120,7 +230,7 @@ const isEven = () => !(count.get() % 2)
 4. Properly handles errors from failed requests
 
 ```js
-import { state, computed, effect } from '@zeix/cause-effect'
+import { state, computed, effect, resolve, match } from '@zeix/cause-effect'
 
 const id = state(42)
 const data = computed(async abort => {
@@ -130,12 +240,13 @@ const data = computed(async abort => {
   return response.json()
 })
 
-// Handle all possible states
-effect({
-  signals: [data],
-  ok: json => console.log('Data loaded:', json),
-  nil: () => console.log('Loading...'),
-  err: error => console.error('Error:', error)
+// Handle all possible states using resolve and match helpers
+effect(() => {
+  match(resolve({ data }), {
+    ok: ({ data: json }) => console.log('Data loaded:', json),
+    nil: () => console.log('Loading...'),
+    err: errors => console.error('Error:', errors[0])
+  })
 })
 
 // When id changes, the previous request is automatically canceled
@@ -148,24 +259,64 @@ document.querySelector('button.next').addEventListener('click', () => {
 
 ## Effects and Error Handling
 
-Cause & Effect provides a robust way to handle side effects and errors through the `effect()` function, with three distinct paths:
+The `effect()` function supports both synchronous and asynchronous callbacks:
 
-1. **Ok**: When values are available
-2. **Nil**: For loading/unset states (with async tasks)
-3. **Err**: When errors occur during computation
+### Synchronous Effects
 
-This allows for declarative handling of all possible states:
+```js
+import { state, effect } from '@zeix/cause-effect'
+
+const count = state(42)
+effect(() => {
+  console.log('Count changed:', count.get())
+})
+```
+
+### Asynchronous Effects with AbortSignal
+
+Async effect callbacks receive an `AbortSignal` parameter that automatically cancels when the effect re-runs or is cleaned up:
+
+```js
+import { state, effect } from '@zeix/cause-effect'
+
+const userId = state(1)
+effect(async (abort) => {
+  try {
+    const response = await fetch(`/api/users/${userId.get()}`, { signal: abort })
+    const user = await response.json()
+    console.log('User loaded:', user)
+  } catch (error) {
+    if (!abort.aborted) {
+      console.error('Failed to load user:', error)
+    }
+  }
+})
+```
+
+### Error Handling with Helper Functions
+
+For more sophisticated error handling, use the `resolve()` and `match()` helper functions:
 
 ```js
-effect({
-  signals: [data],
-  ok: (value) => /* update UI when data is available */,
-  nil: () => /* show loading state while pending */,
-  err: (error) => /* show error message when computation fails */
+import { state, computed, effect, resolve, match } from '@zeix/cause-effect'
+
+const userId = state(1)
+const userData = computed(async (abort) => {
+  const response = await fetch(`/api/users/${userId.get()}`, { signal: abort })
+  if (!response.ok) throw new Error(`HTTP ${response.status}`)
+  return response.json()
+})
+
+effect(() => {
+  match(resolve({ userData }), {
+    ok: ({ userData: user }) => console.log('User loaded:', user),
+    nil: () => console.log('Loading user...'),
+    err: errors => console.error('Error loading user:', errors[0])
+  })
 })
 ```
 
-Instead of using a single callback function, you can provide an object with an `ok` handler (required), plus optional `err` and `nil` handlers. Cause & Effect will automatically route to the appropriate handler based on the state of the signals. If not provided, Cause & Effect will assume `console.error` for `err` and a no-op for `nil`.
+The `resolve()` function extracts values from signals and returns a discriminated union result, while `match()` provides pattern matching for handling different states declaratively.
 
 ## DOM Updates
 
@@ -258,7 +409,7 @@ Using Symbols for deduplication provides:
 Use `batch()` to group multiple signal updates, ensuring effects run only once after all changes are applied:
 
 ```js
-import { state, computed, effect, batch } from '@zeix/cause-effect'
+import { state, computed, effect, batch, resolve, match } from '@zeix/cause-effect'
 
 // State: define an array of State<number>
 const signals = [state(2), state(3), state(5)]
@@ -271,11 +422,12 @@ const sum = computed(() => {
   return v
 })
 
-// Effect: handle the result
-effect({
-  signals: [sum],
-  ok: v => console.log('Sum:', v),
-  err: error => console.error('Error:', error)
+// Effect: handle the result with error handling
+effect(() => {
+  match(resolve({ sum }), {
+    ok: ({ sum: v }) => console.log('Sum:', v),
+    err: errors => console.error('Error:', errors[0])
+  })
 })
 
 // Batch: apply changes to all signals in a single transaction
@@ -321,6 +473,83 @@ cleanup() // Logs: 'Cleanup' and unsubscribes from signal `user`
 user.set({ name: 'Bob', age: 28 }) // Won't trigger the effect anymore
 ```
 
+## Helper Functions
+
+### `resolve()` - Extract Signal Values
+
+The `resolve()` function extracts values from multiple signals and returns a discriminated union result:
+
+```js
+import { state, computed, resolve } from '@zeix/cause-effect'
+
+const name = state('Alice')
+const age = computed(() => 30)
+const result = resolve({ name, age })
+
+if (result.ok) {
+  console.log(result.values.name, result.values.age) // Type-safe access
+} else if (result.pending) {
+  console.log('Loading...')
+} else {
+  console.error('Errors:', result.errors)
+}
+```
+
+### `match()` - Pattern Matching for Side Effects
+
+The `match()` function provides pattern matching on resolve results for side effects:
+
+```js
+import { resolve, match } from '@zeix/cause-effect'
+
+match(resolve({ name, age }), {
+  ok: ({ name, age }) => document.title = `${name} (${age})`,
+  nil: () => document.title = 'Loading...',
+  err: errors => document.title = `Error: ${errors[0].message}`
+})
+```
+
+### `diff()` - Compare Object Changes
+
+The `diff()` function compares two objects and returns detailed information about what changed:
+
+```js
+import { diff } from '@zeix/cause-effect'
+
+const oldUser = { name: 'Alice', age: 30, city: 'Boston' }
+const newUser = { name: 'Alice', age: 31, email: 'alice@example.com' }
+
+const changes = diff(oldUser, newUser)
+console.log(changes.changed)  // true - something changed
+console.log(changes.add)      // { email: 'alice@example.com' }
+console.log(changes.change)   // { age: 31 }
+console.log(changes.remove)   // { city: UNSET }
+```
+
+This function is used internally by stores to efficiently determine what changed and emit appropriate events.
+
+### `isEqual()` - Deep Equality Comparison
+
+The `isEqual()` function performs deep equality comparison with circular reference detection:
+
+```js
+import { isEqual } from '@zeix/cause-effect'
+
+const obj1 = { name: 'Alice', preferences: { theme: 'dark' } }
+const obj2 = { name: 'Alice', preferences: { theme: 'dark' } }
+const obj3 = { name: 'Bob', preferences: { theme: 'dark' } }
+
+console.log(isEqual(obj1, obj2)) // true - deep equality
+console.log(isEqual(obj1, obj3)) // false - names differ
+
+// Handles arrays, primitives, and complex nested structures
+console.log(isEqual([1, 2, 3], [1, 2, 3]))           // true
+console.log(isEqual('hello', 'hello'))               // true
+console.log(isEqual({ a: [1, 2] }, { a: [1, 2] }))   // true
+```
+
+Both `diff()` and `isEqual()` include built-in protection against circular references and will throw a `CircularDependencyError` if cycles are detected.
+
 ## Contributing & License
 
 Feel free to contribute, report issues, or suggest improvements.

package/biome.json

@@ -0,0 +1,35 @@
+{
+	"$schema": "https://biomejs.dev/schemas/2.1.4/schema.json",
+	"vcs": {
+		"enabled": false,
+		"clientKind": "git",
+		"useIgnoreFile": false
+	},
+	"files": {
+		"ignoreUnknown": false,
+		"includes": ["**", "!index.js", "!index.dev.js", "!**/*.d.ts"]
+	},
+	"formatter": {
+		"enabled": true,
+		"indentStyle": "tab"
+	},
+	"linter": {
+		"enabled": true,
+		"rules": {
+			"recommended": true
+		}
+	},
+	"javascript": {
+		"formatter": {
+			"quoteStyle": "double"
+		}
+	},
+	"assist": {
+		"enabled": true,
+		"actions": {
+			"source": {
+				"organizeImports": "on"
+			}
+		}
+	}
+}

package/index.d.ts

@@ -1,11 +1,36 @@
 /**
  * @name Cause & Effect
- * @version 0.14.1
+ * @version 0.14.2
  * @author Esther Brunner
  */
-export { isFunction, CircularDependencyError } from './src/util';
-export { type Signal, type MaybeSignal, type SignalValues, UNSET, isSignal, isComputedCallback, toSignal, } from './src/signal';
-export { type State, TYPE_STATE, state, isState } from './src/state';
-export { type Computed, type ComputedCallback, TYPE_COMPUTED, computed, isComputed, } from './src/computed';
-export { type EffectMatcher, effect } from './src/effect';
-export { type Watcher, type Cleanup, type Updater, watch, subscribe, notify, flush, batch, observe, enqueue, } from './src/scheduler';
+export {
+	type Computed,
+	type ComputedCallback,
+	computed,
+	isComputed,
+	TYPE_COMPUTED,
+} from './src/computed'
+export { type EffectMatcher, type MaybeCleanup, effect } from './src/effect'
+export {
+	batch,
+	type Cleanup,
+	enqueue,
+	flush,
+	notify,
+	observe,
+	subscribe,
+	type Updater,
+	type Watcher,
+	watch,
+} from './src/scheduler'
+export {
+	isComputedCallback,
+	isSignal,
+	type MaybeSignal,
+	type Signal,
+	type SignalValues,
+	toSignal,
+	UNSET,
+} from './src/signal'
+export { isState, type State, state, TYPE_STATE } from './src/state'
+export { CircularDependencyError, isFunction } from './src/util'