@pumped-fn/lite 1.3.1 → 1.4.1

package/README.md

@@ -4,531 +4,228 @@ A lightweight effect system for TypeScript with managed lifecycles and minimal r
 
 **Zero dependencies** · **<17KB bundle** · **Full TypeScript support**
 
-## What is an Effect System?
-
-An effect system manages **how** and **when** computations run, handling:
-- **Resource lifecycle** - acquire, use, release
-- **Computation ordering** - what depends on what
-- **Side effect isolation** - controlled execution boundaries
-- **State transitions** - idle → resolving → resolved → failed
-
-## Installation
-
-```bash
-npm install @pumped-fn/lite
-# or
-pnpm add @pumped-fn/lite
-# or
-yarn add @pumped-fn/lite
-```
-
-## Quick Start
-
-```typescript
-import { atom, flow, createScope, tag, tags, controller } from '@pumped-fn/lite'
-
-// 1. Define atoms (long-lived, cached dependencies)
-const configAtom = atom({
-  factory: () => ({ apiUrl: 'https://api.example.com', timeout: 5000 })
-})
-
-const apiClientAtom = atom({
-  deps: { config: configAtom },
-  factory: (ctx, { config }) => {
-    const client = new ApiClient(config.apiUrl, config.timeout)
-    ctx.cleanup(() => client.disconnect())
-    return client
-  }
-})
-
-// 2. Define flows (short-lived request handlers)
-const fetchUserFlow = flow({
-  deps: { api: apiClientAtom },
-  factory: async (ctx, { api }) => {
-    const userId = ctx.input as string
-    return api.getUser(userId)
-  }
-})
-
-// 3. Create scope and execute
-const scope = createScope()
-await scope.ready
-
-const context = scope.createContext()
-const user = await context.exec({ flow: fetchUserFlow, input: 'user-123' })
-await context.close()
-
-// 4. Cleanup when done
-await scope.dispose()
-```
-
-## Core Concepts
-
-| Concept | Purpose |
-|---------|---------|
-| **Scope** | Long-lived boundary that manages atom lifecycles |
-| **Atom** | A managed effect with lifecycle (create, cache, cleanup, recreate) |
-| **Flow** | Template for short-lived operations with input/output |
-| **ExecutionContext** | Short-lived context for running flows with input and tags |
-| **Controller** | Handle for observing and controlling an atom's state |
-| **Tag** | Contextual value passed through execution |
-
-## Atoms
-
-Atoms are long-lived dependencies that are cached within a scope.
+## How It Works
 
 ```mermaid
-flowchart TB
-    subgraph Scope
-        Config["configAtom"] --> API["apiClientAtom"]
-        DB["dbAtom"] --> Repo["userRepoAtom"]
-        API --> Service["userServiceAtom"]
-        Repo --> Service
+sequenceDiagram
+    participant User
+    participant Scope
+    participant Atom
+
+    User->>Scope: createScope(options?)
+    Scope-->>User: scope
+    User->>Scope: await scope.ready
+
+    User->>Scope: scope.resolve(atom)
+    alt preset exists
+        Scope-->>User: preset value (factory skipped)
+    else no preset
+        Scope->>Atom: factory(ctx, deps)
+        Atom-->>Scope: value (cached)
+        Scope-->>User: value
     end
-```
 
-### Basic Atom
-
-```typescript
-const dbAtom = atom({
-  factory: async (ctx) => {
-    const connection = await createConnection()
-    ctx.cleanup(() => connection.close())
-    return connection
-  }
-})
-```
-
-**`ctx.cleanup()` lifecycle:** Runs on every `invalidate()` (before re-resolution) and on `release()`. Cleanups execute in LIFO order. For resources that should survive invalidation, use `ctx.data` instead.
-
-### Atom with Dependencies
-
-```typescript
-const userRepoAtom = atom({
-  deps: { db: dbAtom },
-  factory: (ctx, { db }) => new UserRepository(db)
-})
+    User->>Scope: scope.dispose()
+    Scope->>Atom: run cleanups, release all
 ```
 
-### Self-Invalidating Atom
-
-```typescript
-const configAtom = atom({
-  factory: async (ctx) => {
-    const config = await fetchConfig()
-
-    // Re-fetch every 60 seconds
-    const interval = setInterval(() => ctx.invalidate(), 60_000)
-    ctx.cleanup(() => clearInterval(interval))
+## Invalidation & Data Retention
 
-    return config
-  }
-})
-```
-
-**`ctx.invalidate()` behavior:** Schedules re-resolution after the current factory completes — does not interrupt execution. Use `scope.flush()` in tests to wait for pending invalidations.
-
-### Per-Atom Private Storage
+```mermaid
+sequenceDiagram
+    participant User
+    participant Controller
+    participant Atom
+    participant DataStore as ctx.data
 
-Use `ctx.data` to store data that survives invalidation:
+    Note over DataStore: persists across invalidations
 
-```typescript
-const prevDataTag = tag<Data>({ label: 'prevData' })
-
-const pollingAtom = atom({
-  factory: async (ctx) => {
-    const prev = ctx.data.get(prevDataTag)  // Data | undefined
-    const current = await fetchData()
-
-    if (prev && hasChanged(prev, current)) {
-      notifyChanges(prev, current)
-    }
-
-    ctx.data.set(prevDataTag, current)
-    setTimeout(() => ctx.invalidate(), 5000)
-    return current
-  }
-})
+    User->>Controller: ctrl.invalidate()
+    Controller->>Atom: run cleanups (LIFO)
+    Note over DataStore: retained
+    Controller->>Atom: state = resolving
+    Controller->>Atom: factory(ctx, deps)
+    Note right of Atom: ctx.data still has previous values
+    Atom-->>Controller: new value
+    Controller->>Atom: state = resolved
+    Controller-->>User: listeners notified
 ```
 
-With default values:
-
-```typescript
-const countTag = tag<number>({ label: 'count', default: 0 })
-
-const counterAtom = atom({
-  factory: (ctx) => {
-    const count = ctx.data.get(countTag)  // number (guaranteed!)
-    ctx.data.set(countTag, count + 1)
-    return count
-  }
-})
-```
+## Flow Execution
 
-Use `getOrSet()` to initialize and retrieve in one call:
-
-```typescript
-const cacheTag = tag<Map<string, Result>>({ label: 'cache' })
-
-const cachedAtom = atom({
-  factory: (ctx) => {
-    const cache = ctx.data.getOrSet(cacheTag, new Map())
-    return fetchWithCache(cache)
-  }
-})
-```
-
-**`ctx.data` lifecycle:**
-- **Persists** across `invalidate()` cycles
-- **Cleared** on `release()` or `scope.dispose()`
-- Each atom has independent storage (same tag, different atoms = separate data)
+```mermaid
+sequenceDiagram
+    participant User
+    participant Scope
+    participant Context as ExecutionContext
+    participant Flow
 
-## Flows
+    User->>Scope: scope.createContext(options?)
+    Scope-->>User: context
 
-Flows are templates for short-lived operations with input validation.
+    User->>Context: ctx.exec({ flow, input, tags? })
+    Context->>Flow: parse(input)
+    Context->>Context: resolve flow deps
+    Context->>Flow: factory(ctx, deps)
+    Flow-->>Context: output
+    Context-->>User: output
 
-```typescript
-const createUserFlow = flow({
-  name: 'createUser',
-  parse: (raw) => {
-    const obj = raw as Record<string, unknown>
-    if (typeof obj.name !== 'string') throw new Error('name required')
-    return { name: obj.name }
-  },
-  deps: { repo: userRepoAtom },
-  factory: async (ctx, { repo }) => {
-    return repo.create(ctx.input)  // ctx.input typed from parse
-  }
-})
-
-// Execute
-const context = scope.createContext()
-const user = await context.exec({
-  flow: createUserFlow,
-  input: { name: 'Alice' }
-})
-await context.close()
+    User->>Context: ctx.close()
+    Context->>Context: run onClose cleanups (LIFO)
 ```
 
-Parse runs before factory. On failure, throws `ParseError`.
-
-## Controllers
-
-Controllers provide reactive access to atom state.
+## Tag Inheritance
 
 ```mermaid
-flowchart LR
-    subgraph Controller
-        State["state: idle|resolving|resolved|failed"]
-        Get["get()"]
-        Inv["invalidate()"]
+flowchart TD
+    subgraph Scope["Scope: tags=[tenantId('t1')]"]
+        subgraph Context["Context: tags=[requestId('r1')]"]
+            subgraph Flow["Flow deps:"]
+                T1["tags.required(tenantId) → 't1'"]
+                T2["tags.required(requestId) → 'r1'"]
+            end
+        end
     end
 
-    App -->|subscribe| Controller
-    Controller -->|on 'resolved'| App
-    Controller -->|on 'resolving'| App
+    Note["Inner inherits from outer. Override by passing same tag at inner level."]
 ```
 
-### Basic Usage
+## Controller Reactivity
 
-```typescript
-const ctrl = scope.controller(configAtom)
+```mermaid
+sequenceDiagram
+    participant User
+    participant Controller
+    participant Atom
 
-ctrl.state              // 'idle' | 'resolving' | 'resolved' | 'failed'
-ctrl.get()              // value (throws if not resolved)
-await ctrl.resolve()    // resolve and wait
-ctrl.invalidate()       // trigger re-resolution
-```
+    User->>Controller: scope.controller(atom)
+    User->>Controller: ctrl.on('resolved', listener)
+    Controller-->>User: unsubscribe fn
 
-**Stale reads:** During `'resolving'` state, `ctrl.get()` returns the previous value. This enables optimistic UI patterns.
+    Note over Controller: atom invalidated elsewhere
 
-### Subscribing to Changes
+    Controller->>Atom: state = resolving
+    Controller-->>User: 'resolving' listeners fire
+    Atom-->>Controller: new value
+    Controller->>Atom: state = resolved
+    Controller-->>User: 'resolved' listeners fire
 
-```typescript
-ctrl.on('resolved', () => console.log('Updated:', ctrl.get()))
-ctrl.on('resolving', () => console.log('Refreshing...'))
-ctrl.on('*', () => console.log('State:', ctrl.state))
+    User->>Controller: ctrl.get()
+    Controller-->>User: current value
 ```
 
-### Controller as Dependency
+## Primitives
 
-Use `controller()` when you need reactive access to an atom's state, not just its value.
+### Scope
 
-**Key difference:**
-- Regular dep `{ x: atom }` — auto-resolved, you receive the value
-- Controller dep `{ x: controller(atom) }` — **unresolved**, you receive a reactive handle
+Entry point. Manages atom lifecycles, caching, and cleanup orchestration.
 
-```typescript
-const appAtom = atom({
-  deps: { config: controller(configAtom) },
-  factory: async (ctx, { config }) => {
-    await config.resolve()  // Must resolve manually
-
-    // Subscribe to upstream changes
-    const unsub = config.on('resolved', () => ctx.invalidate())
-    ctx.cleanup(unsub)
-
-    return new App(config.get())
-  }
-})
-```
+- `createScope(options?)` — create with optional extensions, presets, tags
+- `scope.ready` — wait for extension initialization
+- `scope.resolve(atom)` — resolve and cache
+- `scope.controller(atom)` — get reactive handle
+- `scope.release(atom)` — run cleanups, remove from cache
+- `scope.dispose()` — release all, cleanup extensions
+- `scope.createContext(options?)` — create execution context for flows
+- `scope.select(atom, selector)` — fine-grained reactivity
+- `scope.flush()` — wait for pending invalidations
 
-**When to use:** React to upstream invalidations, conditional/lazy resolution, access atom state.
+### Atom
 
-### Fine-Grained Reactivity
+Long-lived cached dependency with lifecycle.
 
-Use `select()` to subscribe only when a derived value changes:
+- Dependencies on other atoms via `deps`
+- `ctx.cleanup(fn)` — runs on invalidate and release (LIFO order)
+- `ctx.invalidate()` — schedule re-resolution
+- `ctx.data` — storage that survives invalidation (cleared on release)
+- `ctx.data.getOrSet(tag, defaultValue)` — initialize and retrieve in one call
 
-```typescript
-const portSelect = scope.select(configAtom, (c) => c.port)
-portSelect.subscribe(() => console.log('Port changed:', portSelect.get()))
-```
+### Flow
 
-## Tags
+Short-lived operation with input/output.
 
-Tags pass contextual values through execution without explicit wiring.
+- `parse` — validate/transform input before factory (throws `ParseError` on failure)
+- `typed<T>()` — type marker without runtime parsing
+- Dependencies on atoms via `deps`
+- `ctx.input` — typed input access
+- `ctx.onClose(fn)` — cleanup when context closes
 
-```mermaid
-flowchart LR
-    subgraph Definition
-        T["tag({ label: 'tenantId' })"]
-    end
+### Tag
 
-    subgraph Usage
-        R["tags.required(tag)"] --> |"throws if missing"| V1["string"]
-        O["tags.optional(tag)"] --> |"undefined if missing"| V2["string | undefined"]
-        A["tags.all(tag)"] --> |"collects all"| V3["string[]"]
-    end
-```
+Contextual value passed through execution without explicit wiring.
 
-### Creating Tags
+- `tag({ label, default?, parse? })` — define with optional default and validation
+- `tags.required(tag)` — dependency that throws if missing
+- `tags.optional(tag)` — dependency that returns undefined if missing
+- `tags.all(tag)` — collects all values from inheritance chain
+- Tags inherit: Scope → Context → exec call
 
-```typescript
-const tenantIdTag = tag<string>({ label: 'tenantId' })
-const userRolesTag = tag<string[]>({ label: 'userRoles', default: [] })
-
-// With parse validation
-const userId = tag({
-  label: 'userId',
-  parse: (raw) => {
-    if (typeof raw !== 'string') throw new Error('Must be string')
-    return raw
-  }
-})
-
-userId('abc-123')  // OK
-userId(123)        // Throws ParseError
-```
+### Controller
 
-### Using Tags as Dependencies
+Reactive handle for observing and controlling atom state.
 
-```typescript
-// Required - throws if not found
-const tenantAtom = atom({
-  deps: { tenantId: tags.required(tenantIdTag) },
-  factory: (ctx, { tenantId }) => loadTenantData(tenantId)
-})
-
-// Optional - undefined if not found
-const optionalAtom = atom({
-  deps: { tenantId: tags.optional(tenantIdTag) },
-  factory: (ctx, { tenantId }) => {
-    if (tenantId) {
-      return loadTenantData(tenantId)
-    }
-    return loadDefaultData()
-  }
-})
-
-// Collect all - returns array of all matching tags
-const multiAtom = atom({
-  deps: { roles: tags.all(userRolesTag) },
-  factory: (ctx, { roles }) => roles.flat()  // string[][]
-})
-```
+- `ctrl.state` — sync access: `'idle' | 'resolving' | 'resolved' | 'failed'`
+- `ctrl.get()` — sync value access (throws if not resolved, returns stale during resolving)
+- `ctrl.resolve()` — async resolution
+- `ctrl.invalidate()` — trigger re-resolution (runs factory)
+- `ctrl.set(value)` — replace value directly (skips factory)
+- `ctrl.update(fn)` — transform value: `fn(currentValue) → newValue` (skips factory)
+- `ctrl.on(event, listener)` — subscribe to `'resolved' | 'resolving' | '*'`
+- Use `controller(atom)` in deps for reactive dependency (unresolved, you control timing)
 
-### Passing Tags
+### Preset
 
-Tags can be passed at different levels, with inner levels inheriting from outer:
+Value injection for testing. Bypasses factory entirely.
 
-```mermaid
-flowchart LR
-    subgraph Scope["createScope()"]
-        ST["tenantId: 'tenant-123'"]
-        subgraph Context["createContext()"]
-            CT["userRoles: ['admin']"]
-            subgraph Exec["exec()"]
-                ET["requestId: 'req-456'"]
-            end
-        end
-    end
+- `preset(atom, value)` — inject direct value
+- `preset(atom, otherAtom)` — redirect to another atom's factory
+- Pass via `createScope({ presets: [...] })`
 
-    ST -.->|inherited| CT
-    CT -.->|inherited| ET
-```
+### Extension
 
-All three tag levels are available during flow execution.
+AOP-style middleware for cross-cutting concerns.
 
-## Presets
+- `init(scope)` — setup when scope created
+- `wrapResolve(next, atom, scope)` — intercept atom resolution
+- `wrapExec(next, target, ctx)` — intercept flow execution
+- `dispose(scope)` — cleanup when scope disposed
+- Pass via `createScope({ extensions: [...] })`
 
-Presets inject or redirect atom values, useful for testing.
+## Full API
 
-```mermaid
-flowchart LR
-    subgraph Normal["Normal Resolution"]
-        A1[resolve dbAtom] --> F1[factory]
-        F1 --> V1[real connection]
-    end
+See [`dist/index.d.mts`](./dist/index.d.mts) for complete type definitions.
 
-    subgraph Preset["With Preset"]
-        A2[resolve dbAtom] --> P[preset check]
-        P -->|value| V2[mockDb]
-        P -->|atom| F2[testAtom.factory]
-    end
-```
+All types available under the `Lite` namespace:
 
-**Value injection** bypasses the factory entirely:
 ```typescript
-const scope = createScope({
-  presets: [preset(dbAtom, mockDb)]
-})
+import type { Lite } from '@pumped-fn/lite'
 ```
 
-**Atom redirection** uses another atom's factory:
-```typescript
-const scope = createScope({
-  presets: [preset(configAtom, testConfigAtom)]
-})
-```
+## Edge Cases
 
-## Extensions
+### Controller.set() / update()
 
-Extensions wrap atom resolution and flow execution (AOP-style middleware).
+| State | Behavior |
+|-------|----------|
+| `idle` | Throws "Atom not resolved" |
+| `resolving` | Queues, applies after resolution completes |
+| `resolved` | Queues normally |
+| `failed` | Throws the stored error |
 
-```typescript
-const timingExtension: Lite.Extension = {
-  name: 'timing',
-  wrapResolve: async (next, atom, scope) => {
-    const start = performance.now()
-    const result = await next()
-    console.log(`Resolved in ${performance.now() - start}ms`)
-    return result
-  }
-}
-
-const scope = createScope({ extensions: [timingExtension] })
-```
-
-Interface: `{ name, init?, wrapResolve?, wrapExec?, dispose? }`
-
-## Lifecycle
+Both run cleanups before applying the new value.
 
-```mermaid
-stateDiagram-v2
-    [*] --> idle
-    idle --> resolving: resolve()
-    resolving --> resolved: success
-    resolving --> failed: error
-    resolved --> resolving: invalidate()
-    failed --> resolving: invalidate()
-    resolved --> idle: release()
-    failed --> idle: release()
-```
+### DataStore.get()
 
-**Invalidation sequence:**
-1. `invalidate()` → queued (microtask batched)
-2. Cleanups run (LIFO)
-3. State = resolving → factory()
-4. State = resolved → listeners notified
-
-## API Reference
-
-### Factory Functions
-
-| Function | Description |
-|----------|-------------|
-| `createScope(options?)` | Create DI container (returns Scope with `ready` promise) |
-| `atom(config)` | Define long-lived cached dependency |
-| `flow(config)` | Define short-lived operation template (optional `name`, `parse`) |
-| `tag(config)` | Define contextual value (optional `parse` for validation) |
-| `controller(atom)` | Create controller dependency helper |
-| `preset(atom, value)` | Create value injection preset |
-
-### Scope Methods
-
-| Method | Description |
-|--------|-------------|
-| `scope.ready` | Promise that resolves when extensions are initialized |
-| `scope.resolve(atom)` | Resolve atom and return cached value |
-| `scope.controller(atom)` | Get Controller for atom |
-| `scope.select(atom, selector, options?)` | Create fine-grained subscription |
-| `scope.release(atom)` | Release atom (run cleanups, remove from cache) |
-| `scope.dispose()` | Dispose scope (release all atoms, cleanup extensions) |
-| `scope.createContext(options?)` | Create ExecutionContext for flows |
-| `scope.on(event, atom, listener)` | Subscribe to atom state changes |
-| `scope.flush()` | Wait for pending invalidation queue to process |
-
-### Controller Methods
-
-| Method | Description |
-|--------|-------------|
-| `ctrl.state` | Current state: `'idle'` \| `'resolving'` \| `'resolved'` \| `'failed'` |
-| `ctrl.get()` | Get resolved value (throws if not resolved) |
-| `ctrl.resolve()` | Resolve and return value |
-| `ctrl.release()` | Release atom |
-| `ctrl.invalidate()` | Trigger re-resolution |
-| `ctrl.on(event, listener)` | Subscribe: `'resolved'` \| `'resolving'` \| `'*'` |
-
-### ExecutionContext Methods
-
-| Method | Description |
-|--------|-------------|
-| `ctx.input` | Current execution input |
-| `ctx.scope` | Parent scope |
-| `ctx.exec(options)` | Execute flow or function |
-| `ctx.onClose(fn)` | Register cleanup for context close |
-| `ctx.close()` | Close context and run cleanups |
-
-### ResolveContext Methods
-
-| Method | Description |
-|--------|-------------|
-| `ctx.cleanup(fn)` | Register cleanup for atom invalidation/release |
-| `ctx.invalidate()` | Schedule self-invalidation |
-| `ctx.scope` | Parent scope |
-| `ctx.data` | Per-atom DataStore (survives invalidation) |
-
-### Type Guards
-
-| Function | Description |
-|----------|-------------|
-| `isAtom(value)` | Check if value is Atom |
-| `isFlow(value)` | Check if value is Flow |
-| `isTag(value)` | Check if value is Tag |
-| `isTagged(value)` | Check if value is Tagged |
-| `isPreset(value)` | Check if value is Preset |
-| `isControllerDep(value)` | Check if value is ControllerDep |
-
-### Types
-
-All types are available under the `Lite` namespace:
+`ctx.data.get(tag)` always returns `T | undefined` (Map-like semantics). Use `getOrSet(tag)` when you need the tag's default value.
 
 ```typescript
-import type { Lite } from '@pumped-fn/lite'
+const countTag = tag<number>({ label: 'count', default: 0 })
 
-const myAtom: Lite.Atom<Config> = atom({ factory: () => loadConfig() })
-const myController: Lite.Controller<Config> = scope.controller(myAtom)
-const myTag: Lite.Tag<string> = tag({ label: 'myTag' })
+ctx.data.get(countTag)       // undefined (not stored)
+ctx.data.getOrSet(countTag)  // 0 (uses default, now stored)
+ctx.data.get(countTag)       // 0 (now stored)
 ```
 
-## Design Principles
-
-1. **Minimal API** - Every export is expensive to learn
-2. **Zero dependencies** - No runtime dependencies
-3. **Explicit lifecycle** - No magic, clear state transitions
-4. **Composable** - Effects compose through deps
-5. **Type-safe** - Full TypeScript inference
-
 ## License
 
 MIT