@adbl/cells 0.0.21 → 0.0.23

package/README.md

@@ -3,240 +3,402 @@
 [![npm version](https://badge.fury.io/js/%40adbl%2Fcells.svg)](https://badge.fury.io/js/%40adbl%2Fcells)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
-Cells is a powerful yet lightweight library for reactive state management in JavaScript applications. It offers an intuitive API that simplifies the complexities of managing and propagating state changes throughout your application.
+A lightweight, type-safe library for reactive state management. Cells simplifies complex state propagation with an intuitive API that handles synchronous updates, asynchronous data fetching, and race conditions automatically.
+
+## Table of Contents
+
+- [Features](#features)
+- [Installation](#installation)
+- [Quick Start](#quick-start)
+- [Guide](#guide)
+  - [Core Concepts](#1-core-concepts)
+  - [Asynchronous State](#2-asynchronous-state)
+  - [Advanced Patterns](#3-advanced-patterns)
+- [API Reference](#api-reference)
+- [TypeScript Support](#typescript-support)
+- [Contributing](#contributing)
+- [License](#license)
 
 ## Features
 
-- **Simple API**: Easy to learn and use, even for developers new to reactive programming.
-- **Lightweight**: No external dependencies, keeping your project lean.
-- **Flexible**: Works seamlessly with any JavaScript framework or vanilla JS.
-- **Type-safe**: Built with TypeScript, providing excellent type inference and checking.
-- **Performant**: Optimized for efficiency, with features like batched updates to minimize unnecessary computations.
+- **Fine-grained Reactivity** - Updates only what changes, avoiding unnecessary re-renders
+- **Async Primitives** - First-class support for async state with built-in loading and error tracking
+- **Race Condition Handling** - Automatically cancels stale async requests via `AbortSignal`
+- **Glitch-free** - Guarantees consistency across derived values with topological update ordering
+- **Type-safe** - Full TypeScript support with inferred types
+- **Zero Dependencies** - Keeps your bundle small (~3KB minified)
 
 ## Installation
 
-Get started with Cells in your project:
-
 ```bash
 npm install @adbl/cells
 ```
 
-Or if you prefer Yarn:
-
 ```bash
 yarn add @adbl/cells
 ```
 
-## Core Concepts
-
-### 1. Source Cells
+```bash
+pnpm add @adbl/cells
+```
 
-Source cells are the building blocks of your reactive state. They hold values that can change over time, automatically notifying dependents when updates occur.
+## Quick Start
 
 ```javascript
 import { Cell } from '@adbl/cells';
 
-const count = Cell.source(0);
-console.log(count.get()); // Output: 0
+// 1. Create a source cell
+const name = Cell.source('World');
 
-count.set(5);
-console.log(count.get()); // Output: 5
+// 2. Create a derived cell (updates automatically)
+const greeting = Cell.derived(() => `Hello, ${name.get()}!`);
+
+// 3. Listen for changes
+greeting.listen((msg) => console.log(msg));
+
+// 4. Update the source
+name.set('Cells'); // Console: "Hello, Cells!"
 ```
 
-### 2. Derived Cells
+---
+
+## Guide
 
-Derived cells allow you to create computed values based on other cells. They update automatically when their dependencies change, ensuring your derived state is always in sync.
+### 1. Core Concepts
+
+#### Source Cells
+
+The root of your state graph. You can read, subscribe to, and modify them.
 
 ```javascript
 const count = Cell.source(0);
-const doubledCount = Cell.derived(() => count.get() * 2);
-
-console.log(doubledCount.get()); // Output: 0
 
-count.set(5);
-console.log(doubledCount.get()); // Output: 10
+count.set(1);
+console.log(count.get()); // 1
 ```
 
-### 3. Reactive Effects
+#### Derived Cells
 
-Easily set up listeners to react to changes in cell values, allowing you to create side effects or update your UI in response to state changes.
+Computed values that update automatically when dependencies change. They are eager and always kept in sync.
 
 ```javascript
-const count = Cell.source(0);
+const count = Cell.source(1);
+const double = Cell.derived(() => count.get() * 2);
 
-count.listen((newValue) => {
-  console.log(`Count changed to: ${newValue}`);
-});
+console.log(double.get()); // 2
 
-count.set(3); // Output: "Count changed to: 3"
-count.set(7); // Output: "Count changed to: 7"
+count.set(5);
+console.log(double.get()); // 10
 ```
 
-### 5. Batch Updates
+#### Effects (`listen`)
 
-When you need to perform multiple updates but only want to trigger effects once, you can use batch updates to optimize performance:
+Run side effects when a cell changes.
 
 ```javascript
-const cell1 = Cell.source(0);
-const cell2 = Cell.source(0);
+const count = Cell.source(0);
 
-const callback = () => {
-  console.log('Update occurred');
-};
+// Runs only on updates
+const unsubscribe = count.listen((val) => console.log(val));
 
-cell1.listen(callback);
-cell2.listen(callback);
+// Runs immediately, then on updates
+count.runAndListen((val) => console.log('Current:', val));
 
-Cell.batch(() => {
-  cell1.set(1);
-  cell2.set(2);
-});
-// Output: "Update occurred" (only once)
+// Cleanup when done
+unsubscribe();
 ```
 
-### 6. Async Operations
+---
+
+### 2. Asynchronous State
+
+Cells shines when handling async operations, replacing manual promise handling with declarative primitives.
 
-Cells provides utilities for handling asynchronous operations, making it easy to manage loading states, data, and errors:
+#### Async Derived Cells
+
+Use `Cell.derivedAsync` for data fetching or heavy computations. It automatically exposes `pending` and `error` states.
 
 ```javascript
-const fetchUser = Cell.async(async (userId) => {
-  const response = await fetch(`https://api.example.com/users/${userId}`);
-  return response.json();
-});
+const userId = Cell.source(1);
 
-const { pending, data, error, run } = fetchUser;
+const user = Cell.derivedAsync(async (get, signal) => {
+  // 'get' tracks dependencies
+  const id = get(userId);
 
-pending.listen((isPending) => {
-  console.log(isPending ? 'Loading...' : 'Done!');
+  // 'signal' handles cancellation automatically if userId changes
+  const res = await fetch(`/api/users/${id}`, { signal });
+  return res.json();
 });
 
-data.listen((userData) => {
-  if (userData) {
-    console.log('User data:', userData);
-  }
-});
+// Built-in status tracking
+user.pending.listen((isLoading) => console.log(isLoading ? 'Loading...' : 'Done'));
+user.error.listen((err) => err && console.error(err));
 
-run(123); // Triggers the async operation
+// Access the data
+const data = await user.get();
 ```
 
-#### Automatic Abort of Previous Operations
-
-When you call `run()` multiple times on the same async cell, any previous ongoing async operations are automatically aborted. This prevents race conditions and ensures that only the result of the latest `run()` call is applied.
+#### Task Cells
 
-Additionally, the getter function receives an `AbortSignal` via `this.signal`, which you can use to cancel long-running operations or check for abortion:
+Use `Cell.task` for user-triggered actions (e.g., form submissions). Unlike derived cells, these only execute when triggered with `runWith`.
 
 ```javascript
-const fetchUser = Cell.async(async function (userId) {
-  const response = await fetch(`https://api.example.com/users/${userId}`, {
-    signal: this.signal, // Pass the abort signal to fetch
+const login = Cell.task(async (creds, signal) => {
+  const res = await fetch('/api/login', {
+    method: 'POST',
+    body: JSON.stringify(creds),
+    signal,
   });
-  return response.json();
+  return res.json();
+});
+
+// Trigger the task
+const result = await login.runWith({ user: 'admin', pass: '1234' });
+
+// Track status
+login.pending.listen((isPending) => {
+  submitButton.disabled = isPending;
 });
+```
 
-const { data, run } = fetchUser;
+#### Composite Cells
 
-// Start first request
-run(123);
+Group multiple async cells into a synchronized unit. Useful for preventing partial updates or ensuring "all-or-nothing" behavior.
 
-// Start second request - this aborts the first
-run(456);
+```javascript
+const profile = Cell.derivedAsync(fetchProfile);
+const posts = Cell.derivedAsync(fetchPosts);
+
+// Waits for BOTH to finish before updating
+const dashboard = Cell.composite({ profile, posts });
+
+dashboard.pending.listen((isPending) => showSpinner(isPending));
+dashboard.error.listen((err) => err && showError(err));
 
-// Only the result of the second request (user 456) will be applied
+dashboard.loaded.listen(async (ready) => {
+  if (ready) {
+    const profileData = await dashboard.values.profile.get();
+    const postsData = await dashboard.values.posts.get();
+    renderDashboard(profileData, postsData);
+  }
+});
 ```
 
-### 7. Flattening
+---
+
+### 3. Advanced Patterns
 
-Cells offers utility functions to work with nested cell structures, making it easier to handle complex state shapes:
+#### Batch Updates
+
+Group multiple updates into a single notification to avoid unnecessary re-computations.
 
 ```javascript
-const nestedCell = Cell.source(Cell.source(5));
-const flattenedValue = Cell.flatten(nestedCell);
-console.log(flattenedValue); // Output: 5
+Cell.batch(() => {
+  firstName.set('John');
+  lastName.set('Doe');
+  // Effects run once here, after the block finishes
+});
+```
+
+#### Peeking
 
-const arrayOfCells = [Cell.source(1), Cell.source(2), Cell.source(3)];
-const flattenedArray = Cell.flattenArray(arrayOfCells);
-console.log(flattenedArray); // Output: [1, 2, 3]
+Read a value *without* subscribing to it.
 
-const objectWithCells = { a: Cell.source(1), b: Cell.source(2) };
-const flattenedObject = Cell.flattenObject(objectWithCells);
-console.log(flattenedObject); // Output: { a: 1, b: 2 }
+```javascript
+const sum = Cell.derived(() => {
+  // Re-runs if 'a' changes, but NOT if 'b' changes
+  return a.get() + b.peek();
+});
 ```
 
-### 8. Custom Equality Checks
+#### Custom Equality
 
-For more complex objects, you can provide custom equality functions to determine when a cell's value has truly changed:
+Customize how cells detect changes.
 
 ```javascript
-const userCell = Cell.source(
-  { name: 'Alice', age: 30 },
+const user = Cell.source(
+  { id: 1, name: 'Alice' },
   {
-    equals: (a, b) => a.name === b.name && a.age === b.age,
+    equals: (a, b) => a.id === b.id, // Only update if ID changes
   }
 );
 ```
 
-### 9. Named Effects
+#### Memory Management (Contexts)
 
-To aid in debugging, you can name your effects, making it easier to track and manage them:
+For high-performance scenarios involving many dynamically created cells, use `LocalContext` for manual disposal.
 
 ```javascript
-const count = Cell.source(0);
+const ctx = Cell.context();
 
-count.listen((value) => console.log(`Count is now: ${value}`), {
-  name: 'countLogger',
+Cell.runWithContext(ctx, () => {
+  // All listeners and derived cells created here are bound to 'ctx'
+  source.listen(handler);
+  const derived = Cell.derived(() => source.get() * 2);
 });
 
-console.log(count.isListeningTo('countLogger')); // Output: true
-
-count.stopListeningTo('countLogger');
+// Clean up everything at once
+ctx.destroy();
 ```
 
-## Advanced Features and API Details
+---
 
-### Cell Options
+## API Reference
 
-When creating a source cell, you have fine-grained control over its behavior:
+### `Cell` Static Methods
 
-```javascript
-const cell = Cell.source(initialValue, {
-  immutable: boolean, // If true, the cell will not allow updates
-  deep: boolean, // By default, the cell only reacts to changes at the top level of objects. Setting deep to true will proxy the cell to all nested properties and trigger updates when they change as well.
-  equals: (oldValue, newValue) => boolean, // Custom equality function
-});
-```
+| Method | Description |
+|--------|-------------|
+| `source(value, options?)` | Creates a mutable source cell. |
+| `derived(fn)` | Creates a computed cell from other cells. |
+| `derivedAsync(fn)` | Creates an async computed cell with cancellation support. |
+| `task(fn)` | Creates a triggerable async task. |
+| `composite(map)` | Combines multiple cells into a synchronized object. |
+| `batch(fn)` | Batches updates to prevent multiple effect triggers. |
+| `context()` | Creates a new `LocalContext` for scoped memory management. |
+| `runWithContext(ctx, fn)` | Executes a function within a specific `LocalContext`. |
+| `isCell(value)` | Returns `true` if the value is a Cell. |
+
+### Cell Instance Methods
+
+| Method | Description |
+|--------|-------------|
+| `get()` | Returns the value. Registers dependency if in a derivation. |
+| `peek()` | Returns the value without registering a dependency. |
+| `listen(callback, options?)` | Subscribes to changes. Returns an unsubscribe function. |
+| `runAndListen(callback, options?)` | Runs callback immediately, then subscribes to future changes. |
+| `ignore(callback)` | Removes a previously registered listener. |
+| `valueOf()` | Returns the raw value (for implicit coercion). |
+| `toString()` | Returns the stringified value. |
+
+### `SourceCell` Methods
+
+| Method | Description |
+|--------|-------------|
+| `set(value)` | Updates the cell's value and notifies listeners. |
+
+### `AsyncCell` Properties and Methods
+
+Available on `AsyncDerivedCell` and `AsyncTaskCell`:
+
+| Property/Method | Description |
+|-----------------|-------------|
+| `pending` | A `Cell<boolean>` indicating loading state. |
+| `error` | A `Cell<Error \| null>` holding the last error. |
+| `get()` | Returns a `Promise` that resolves to the value. |
+| `peek()` | Returns a `Promise` without registering dependencies. |
+
+### `AsyncDerivedCell` Methods
+
+| Method | Description |
+|--------|-------------|
+| `revalidate()` | Forces a refresh of the async computation. |
+
+### `AsyncTaskCell` Methods
+
+| Method | Description |
+|--------|-------------|
+| `runWith(input)` | Executes the task with the given input. Returns a `Promise`. |
+
+### `Composite` Object
+
+Returned by `Cell.composite()`:
+
+| Property | Description |
+|----------|-------------|
+| `values` | Object containing synchronized async cells for each input key. |
+| `pending` | A `Cell<boolean>` that is `true` while any input is pending. |
+| `error` | A `Cell<Error \| null>` with the first error from any input. |
+| `loaded` | A `Cell<boolean>` that becomes `true` after initial load completes. |
+
+### `LocalContext` Methods
+
+| Method | Description |
+|--------|-------------|
+| `destroy()` | Disposes all listeners and derived cells bound to this context. |
 
 ### Effect Options
 
-When setting up listeners or effects, you can customize their behavior:
+Options for `listen()` and `runAndListen()`:
 
-```javascript
-cell.listen(callback, {
-  once: boolean, // If true, the effect will only run once
-  signal: AbortSignal, // An AbortSignal to cancel the effect
-  name: string, // A name for the effect (useful for debugging)
-  priority: number, // The priority of the effect (higher priority effects run first)
+| Option | Type | Description |
+|--------|------|-------------|
+| `once` | `boolean` | Remove the listener after it fires once. |
+| `signal` | `AbortSignal` | Automatically remove listener when signal aborts. |
+| `weak` | `boolean` | Use a weak reference (listener may be garbage collected). |
+| `priority` | `number` | Execution order (higher runs first, default: 0). |
+
+### Cell Options
+
+Options for `Cell.source()`:
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `equals` | `(a, b) => boolean` | Custom equality function for change detection. |
+
+---
+
+## TypeScript Support
+
+Cells is written in JavaScript with comprehensive JSDoc annotations and ships with TypeScript declaration files.
+
+```typescript
+import { Cell, SourceCell, DerivedCell, AsyncDerivedCell } from '@adbl/cells';
+
+// Types are inferred automatically
+const count: SourceCell<number> = Cell.source(0);
+const doubled: DerivedCell<number> = Cell.derived(() => count.get() * 2);
+
+// Async cells with proper typing
+const user: AsyncDerivedCell<User> = Cell.derivedAsync(async (get) => {
+  const id = get(userId);
+  const res = await fetch(`/api/users/${id}`);
+  return res.json() as User;
+});
+
+// Task cells with input/output types
+const submitForm = Cell.task(async (data: FormData, signal: AbortSignal) => {
+  const res = await fetch('/api/submit', { method: 'POST', body: data, signal });
+  return res.json() as SubmitResult;
 });
 ```
 
-### Explicit Disposal (Contexts)
+---
 
-By default, Cells uses `WeakRef` and Garbage Collection to manage memory. This is easy to use but can lead to "ghost computations", where listeners and derived cells keep running for a short time after they are no longer needed.
+## Contributing
 
-For high-performance scenarios, you can use a `LocalContext` to group dependencies and kill them synchronously.
+Contributions are welcome! Here's how to get started:
 
-```javascript
-const ctx = Cell.context();
-const source = Cell.source(1);
+### Development Setup
 
-Cell.runWithContext(ctx, () => {
-  // This listener is now bound to 'ctx' (Strong Reference)
-  source.listen((val) => console.log(val));
-});
+```bash
+# Clone the repository
+git clone https://github.com/adebola-io/signals.git
+cd signals
 
-source.set(2); // Logs: 2
+# Install dependencies
+npm install
 
-// Synchronously remove all listeners created in that block
-ctx.destroy();
+# Run tests in watch mode
+npm test
+
+# Run tests once
+npm run test-once
+
+# Build the project
+npm run build
+```
 
-source.set(3); // Nothing happens
+### Running Tests
+
+```bash
+npm test
 ```
+
+The test suite uses [Vitest](https://vitest.dev/) and covers all core functionality including async behavior and race conditions.
+
+---
+
+## License
+
+MIT © [Sefunmi Adebola Akomolafe](https://github.com/adebola-io)