@zeix/cause-effect 0.15.1 → 0.16.0

package/README.md

@@ -1,6 +1,6 @@
 # Cause & Effect
 
-Version 0.15.1
+Version 0.16.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.
 
@@ -10,10 +10,10 @@ Version 0.15.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()`
+- **State signals**: Hold values that can be directly modified: `createState()`
+- **Store signals**: Hold objects of nested reactive properties: `createStore()`
+- **Computed signals**: Derive memoized values from other signals: `createComputed()`
+- **Effects**: Run side effects when signals change: `createEffect()`
 
 ## Key Features
 
@@ -28,16 +28,16 @@ Version 0.15.1
 ## Quick Start
 
 ```js
-import { state, computed, effect } from '@zeix/cause-effect'
+import { createState, createComputed, createEffect } from '@zeix/cause-effect'
 
 // 1. Create state
-const user = state({ name: 'Alice', age: 30 })
+const user = createState({ name: 'Alice', age: 30 })
 
 // 2. Create computed values
-const greeting = computed(() => `Hello ${user.get().name}!`)
+const greeting = createComputed(() => `Hello ${user.get().name}!`)
 
 // 3. React to changes
-effect(() => {
+createEffect(() => {
   console.log(`${greeting.get()} You are ${user.get().age} years old`)
 })
 
@@ -59,13 +59,13 @@ bun add @zeix/cause-effect
 
 ### State Signals
 
-`state()` creates a mutable signal. Every signal has a `.get()` method to access its current value. State signals also provide `.set()` to directly assign a new value and `.update()` to modify the value with a function.
+`createState()` creates a mutable signal. Every signal has a `.get()` method to access its current value. State signals also provide `.set()` to directly assign a new value and `.update()` to modify the value with a function.
 
 ```js
-import { state, effect } from '@zeix/cause-effect'
+import { createState, createEffect } from '@zeix/cause-effect'
 
-const count = state(42)
-effect(() => {
+const count = createState(42)
+createEffect(() => {
   console.log(count.get()) // logs '42'
 })
 count.set(24) // logs '24'
@@ -77,12 +77,12 @@ document.querySelector('.increment').addEventListener('click', () => {
 
 ### 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.
+`createStore()` 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'
+import { createStore, createEffect } from '@zeix/cause-effect'
 
-const user = store({
+const user = createStore({
   name: 'Alice',
   age: 30,
   preferences: {
@@ -92,12 +92,12 @@ const user = store({
 })
 
 // Individual properties are reactive
-effect(() => {
+createEffect(() => {
   console.log(`${user.name.get()} is ${user.age.get()} years old`)
 })
 
 // Nested properties work the same way
-effect(() => {
+createEffect(() => {
   console.log(`Theme: ${user.preferences.theme.get()}`)
 })
 
@@ -106,17 +106,24 @@ 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(() => {
+createEffect(() => {
   console.log('User data:', user.get()) // Triggers on any nested change
 })
 ```
 
+#### When to Use
+
+**When to use stores vs states:**
+
+- **Use `createStore()`** for objects with properties that you want to access and modify individually.
+- **Use `createState()`** for primitive values (numbers, strings, booleans) or objects you access and replace entirely.
+
 #### 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'
+import { createStore, createEffect } from '@zeix/cause-effect'
 
 const settings = store({ autoSave: true })
 
@@ -140,61 +147,102 @@ The `add()` and `remove()` methods are optimized for performance:
 - They're perfect for frequent single-property additions/removals
 - They trigger the same events and reactivity as other store operations
 
-#### Store Events
+#### Array-like Stores
+
+Stores created from arrays behave like arrays with reactive properties. They support duck-typing with length property, single-parameter `add()`, and efficient sorting:
+
+```js
+import { createStore, createEffect } from '@zeix/cause-effect'
+
+const items = createStore(['banana', 'apple', 'cherry'])
+
+// Duck-typing: behaves like an array
+console.log(items.length) // 3
+console.log(typeof items.length) // 'number'
+
+// Individual items are reactive
+createEffect(() => {
+  console.log(`First item: ${items[0].get()}`)
+})
+
+// Single-parameter add() appends to end
+items.add('date') // Adds at index 3
+console.log(items.get()) // ['banana', 'apple', 'cherry', 'date']
+
+// Efficient sorting preserves signal references
+items.sort() // Default: string comparison
+console.log(items.get()) // ['apple', 'banana', 'cherry', 'date']
+
+// Custom sorting
+items.sort((a, b) => b.localeCompare(a)) // Reverse alphabetical
+console.log(items.get()) // ['date', 'cherry', 'banana', 'apple']
+```
+
+#### Store Change Notifications
 
-Stores emit events when properties are added, changed, or removed. You can listen to these events using standard `addEventListener()`:
+Stores emit notifications (sort of light-weight events) when properties are added, changed, or removed. You can listen to these notications using the `.on()` method:
 
 ```js
-import { store } from '@zeix/cause-effect'
+import { createStore } from '@zeix/cause-effect'
 
-const user = store({ name: 'Alice', age: 30 })
+const user = createStore({ name: 'Alice', age: 30 })
 
 // Listen for property additions
-user.addEventListener('store-add', (event) => {
-  console.log('Added properties:', event.detail)
+const offAdd = user.on('add', (added) => {
+  console.log('Added properties:', added)
 })
 
 // Listen for property changes
-user.addEventListener('store-change', (event) => {
-  console.log('Changed properties:', event.detail)
+const offChange = user.on('change', (changed) => {
+  console.log('Changed properties:', changed)
 })
 
 // Listen for property removals
-user.addEventListener('store-remove', (event) => {
-  console.log('Removed properties:', event.detail)
+const offRemove = user.on('remove', (removed) => {
+  console.log('Removed properties:', removed)
 })
 
-// These will trigger the respective events:
+// These will trigger the respective notifications:
 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 }"
+
+// Listen for sort notifications (useful for UI animations)
+const items = createStore(['banana', 'apple', 'cherry'])
+items.sort((a, b) => b.localeCompare(a)) // Reverse alphabetical
+const offSort = items.on('sort', (newOrder) => {
+  console.log('Items reordered:', newOrder) // ['2', '1', '0']
+})
 ```
 
-Events are also fired when using `set()` or `update()` methods on the entire store:
+Notifications are also fired when using `set()` or `update()` methods on the entire store:
 
 ```js
-// This will fire multiple events based on what changed
+// This will fire multiple notifications 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
+To stop listening to notifications, call the returned cleanup function:
 
-### Computed Signals vs. Functions
+```js
+offAdd() // Stops listening to add notifications
+offChange() // Stops listening to change notifications
+offRemove() // Stops listening to remove notifications
+offSort() // Stops listening to sort notifications
+```
 
-#### When to Use Computed Signals
+### Computed Signals
 
-`computed()` creates a memoized read-only signal that automatically tracks dependencies and updates only when those dependencies change.
+`createComputed()` creates a memoized read-only signal that automatically tracks dependencies and updates only when those dependencies change.
 
 ```js
-import { state, computed, effect } from '@zeix/cause-effect'
+import { createState, createComputed, createEffect } from '@zeix/cause-effect'
 
-const count = state(42)
-const isEven = computed(() => !(count.get() % 2))
-effect(() => console.log(isEven.get())) // logs 'true'
+const count = createState(42)
+const isEven = createComputed(() => !(count.get() % 2))
+createEffect(() => console.log(isEven.get())) // logs 'true'
 count.set(24) // logs nothing because 24 is also an even number
 document.querySelector('button.increment').addEventListener('click', () => {
   count.update(v => ++v)
@@ -202,7 +250,7 @@ document.querySelector('button.increment').addEventListener('click', () => {
 // Click on button logs 'false', 'true', and so on
 ```
 
-#### When to Use Functions
+#### When to Use
 
 **Performance tip**: For simple derivations, plain functions often outperform computed signals:
 
@@ -213,16 +261,53 @@ const isEven = () => !(count.get() % 2)
 
 **When to use which approach:**
 
-- **Use functions when**: The calculation is simple, inexpensive, or called infrequently
-- **Use computed() when**:
+- **Use functions when**: The calculation is simple, inexpensive, or called infrequently.
+- **Use createComputed() when**:
   - The calculation is expensive
   - You need to share the result between multiple consumers
   - You're working with asynchronous operations
   - You need to track specific error states
+  
+#### Reducer-like Capabilities
+
+`createComputed()` supports reducer-like patterns by accepting an initial value and providing access to the previous value in the callback:
+
+```js
+import { createState, createComputed, createEffect } from '@zeix/cause-effect'
+
+const actions = createState('increment')
+const counter = createComputed((prev, abort) => {
+  const action = actions.get()
+  switch (action) {
+    case 'increment':
+      return prev + 1
+    case 'decrement':
+      return prev - 1
+    case 'reset':
+      return 0
+    default:
+      return prev
+  }
+}, 0) // Initial value of 0
+
+createEffect(() => console.log('Counter:', counter.get()))
+
+// Dispatch actions
+actions.set('increment') // Counter: 1
+actions.set('increment') // Counter: 2
+actions.set('decrement') // Counter: 1
+actions.set('reset')     // Counter: 0
+```
+
+This pattern is particularly useful for:
+- State machines with transitions based on current state
+- Accumulating values over time
+- Complex state updates that depend on previous state
+- Building reactive reducers similar to Redux patterns
 
 #### Asynchronous Computations with Automatic Cancellation
 
-`computed()` seamlessly handles asynchronous operations with built-in cancellation support. When used with an async function, it:
+`createComputed()` seamlessly handles asynchronous operations with built-in cancellation support. When used with an async function, it:
 
 1. Provides an `abort` signal parameter you can pass to fetch or other cancelable APIs
 2. Automatically cancels pending operations when dependencies change
@@ -230,10 +315,10 @@ const isEven = () => !(count.get() % 2)
 4. Properly handles errors from failed requests
 
 ```js
-import { state, computed, effect, resolve, match } from '@zeix/cause-effect'
+import { createState, createComputed, createEffect, resolve, match } from '@zeix/cause-effect'
 
-const id = state(42)
-const data = computed(async abort => {
+const id = createState(42)
+const data = createComputed(async (_, abort) => {
   // The abort signal is automatically managed by the computed signal
   const response = await fetch(`/api/entries/${id.get()}`, { signal: abort })
   if (!response.ok) throw new Error(`Failed to fetch data: ${response.statusText}`)
@@ -241,7 +326,7 @@ const data = computed(async abort => {
 })
 
 // Handle all possible states using resolve and match helpers
-effect(() => {
+createEffect(() => {
   match(resolve({ data }), {
     ok: ({ data: json }) => console.log('Data loaded:', json),
     nil: () => console.log('Loading...'),
@@ -255,19 +340,19 @@ document.querySelector('button.next').addEventListener('click', () => {
 })
 ```
 
-**Note**: Always use `computed()` (not plain functions) for async operations to benefit from automatic cancellation, memoization, and state management.
+**Note**: Always use `createComputed()` (not plain functions) for async operations to benefit from automatic cancellation and memoization.
 
 ## Effects and Error Handling
 
-The `effect()` function supports both synchronous and asynchronous callbacks:
+The `createEffect()` function supports both synchronous and asynchronous callbacks:
 
 ### Synchronous Effects
 
 ```js
-import { state, effect } from '@zeix/cause-effect'
+import { createState, createEffect } from '@zeix/cause-effect'
 
-const count = state(42)
-effect(() => {
+const count = createState(42)
+createEffect(() => {
   console.log('Count changed:', count.get())
 })
 ```
@@ -277,10 +362,10 @@ effect(() => {
 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'
+import { createState, createEffect } from '@zeix/cause-effect'
 
-const userId = state(1)
-effect(async (abort) => {
+const userId = createState(1)
+createEffect(async (abort) => {
   try {
     const response = await fetch(`/api/users/${userId.get()}`, { signal: abort })
     const user = await response.json()
@@ -298,16 +383,16 @@ effect(async (abort) => {
 For more sophisticated error handling, use the `resolve()` and `match()` helper functions:
 
 ```js
-import { state, computed, effect, resolve, match } from '@zeix/cause-effect'
+import { createState, createEffect, resolve, match } from '@zeix/cause-effect'
 
-const userId = state(1)
-const userData = computed(async (abort) => {
+const userId = createState(1)
+const userData = createEffect(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(() => {
+createEffect(() => {
   match(resolve({ userData }), {
     ok: ({ userData: user }) => console.log('User loaded:', user),
     nil: () => console.log('Loading user...'),
@@ -318,90 +403,6 @@ effect(() => {
 
 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
-
-The `enqueue()` function allows you to schedule DOM updates to be executed on the next animation frame. It returns a `Promise`, which makes it easy to track when updates are applied or handle errors.
-
-```js
-import { enqueue } from '@zeix/cause-effect'
-
-// Schedule a DOM update
-enqueue(() => {
-  document.getElementById('myElement').textContent = 'Updated content'
-})
-  .then(() => console.log('Update applied successfully'))
-  .catch(error => console.error('Update failed:', error))
-```
-
-### Deduplication with Symbols
-
-A powerful feature of `enqueue()` is deduplication, which ensures that only the most recent update for a specific operation is applied when multiple updates occur within a single animation frame. This is particularly useful for high-frequency events like typing, dragging, or scrolling.
-
-Deduplication is controlled using JavaScript Symbols:
-
-```js
-import { state, effect, enqueue } from '@zeix/cause-effect'
-
-// Define a signal and update it in an event handler
-const name = state('')
-document.querySelector('input[name="name"]').addEventListener('input', e => {
-  name.set(e.target.value) // Triggers an update on every keystroke
-})
-
-// Define an effect to react to signal changes
-effect(text => {
-  // Create a Symbol for a specific update operation
-  const NAME_UPDATE = Symbol('name-update')
-  const text = name.get()
-  const nameSpan = document.querySelector('.greeting .name')
-  enqueue(() => {
-    nameSpan.textContent = text
-    return text
-  }, NAME_UPDATE) // Using the Symbol for deduplication
-    .then(result => console.log(`Name was updated to ${result}`))
-    .catch(error => console.error('Failed to update name:', error))
-})
-```
-
-In this example, as the user types "Jane" quickly, the intermediate values ('J', 'Ja', 'Jan') are deduplicated, and only the final value 'Jane' is applied to the DOM. Only the Promise for the final update is resolved.
-
-### How Deduplication Works
-
-When multiple `enqueue` calls use the same Symbol before the next animation frame:
-
-1. Only the last call will be executed
-2. Previous calls are superseded
-3. Only the Promise of the last call will be resolved
-
-This "last-write-wins" behavior optimizes DOM updates and prevents unnecessary work when many updates happen rapidly.
-
-### Optional Deduplication
-
-The deduplication Symbol is optional. When not provided, a unique Symbol is created automatically, ensuring the update is always executed:
-
-```js
-// No deduplication - always executed
-enqueue(() => document.title = 'New Page Title')
-
-// Create symbols for different types of updates
-const COLOR_UPDATE = Symbol('color-update')
-const SIZE_UPDATE = Symbol('size-update')
-
-// These won't interfere with each other (different symbols)
-enqueue(() => element.style.color = 'red', COLOR_UPDATE)
-enqueue(() => element.style.fontSize = '16px', SIZE_UPDATE)
-
-// This will replace the previous color update (same symbol)
-enqueue(() => element.style.color = 'blue', COLOR_UPDATE)
-```
-
-Using Symbols for deduplication provides:
-
-- Clear semantic meaning for update operations
-- Type safety in TypeScript
-- Simple mechanism to control which updates should overwrite each other
-- Flexibility to run every update when needed
-
 ## Advanced Usage
 
 ### Batching Updates
@@ -409,13 +410,20 @@ 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, resolve, match } from '@zeix/cause-effect'
-
-// State: define an array of State<number>
-const signals = [state(2), state(3), state(5)]
+import {
+  createState,
+  createComputed,
+  createEffect,
+  batch,
+  resolve,
+  match
+} from '@zeix/cause-effect'
+
+// State: define an Array<State<number>>
+const signals = [createState(2), createState(3), createState(5)]
 
 // Compute the sum of all signals
-const sum = computed(() => {
+const sum = createComputed(() => {
   const v = signals.reduce((total, signal) => total + signal.get(), 0)
   // Validate the result
   if (!Number.isFinite(v)) throw new Error('Invalid value')
@@ -423,7 +431,7 @@ const sum = computed(() => {
 })
 
 // Effect: handle the result with error handling
-effect(() => {
+createEffect(() => {
   match(resolve({ sum }), {
     ok: ({ sum: v }) => console.log('Sum:', v),
     err: errors => console.error('Error:', errors[0])
@@ -450,11 +458,11 @@ signals[0].set(NaN)
 Effects return a cleanup function. When executed, it will unsubscribe from signals and run cleanup functions returned by effect callbacks, for example to remove event listeners.
 
 ```js
-import { state, computed, effect } from '@zeix/cause-effect'
+import { createState, createComputed, createEffect } from '@zeix/cause-effect'
 
-const user = state({ name: 'Alice', age: 30 })
+const user = createState({ name: 'Alice', age: 30 })
 const greeting = () => `Hello ${user.get().name}!`
-const cleanup = effect(() => {
+const cleanup = createEffect(() => {
 	console.log(`${greeting()} You are ${user.get().age} years old`)
 	return () => console.log('Cleanup') // Cleanup function
 })
@@ -472,10 +480,10 @@ user.set({ name: 'Bob', age: 28 }) // Won't trigger the effect anymore
 The `resolve()` function extracts values from multiple signals and returns a discriminated union result:
 
 ```js
-import { state, computed, resolve } from '@zeix/cause-effect'
+import { createState, createComputed, resolve } from '@zeix/cause-effect'
 
-const name = state('Alice')
-const age = computed(() => 30)
+const name = createState('Alice')
+const age = createComputed(() => 30)
 const result = resolve({ name, age })
 
 if (result.ok) {

package/eslint.config.js

@@ -1,5 +1,5 @@
-import globals from 'globals'
 import pluginJs from '@eslint/js'
+import globals from 'globals'
 import tseslint from 'typescript-eslint'
 
 /** @type {import('eslint').Linter.Config[]} */