@pumped-fn/lite 1.11.3 → 2.0.0

package/CHANGELOG.md

@@ -1,5 +1,26 @@
 # @pumped-fn/lite
 
+## 2.0.0
+
+### Major Changes
+
+- e87f8c9: feat(lite): add `resource()` execution-scoped dependency primitive
+
+  BREAKING CHANGE: `wrapResolve` extension hook signature changed from `(next, atom, scope)` to `(next, event: ResolveEvent)` where `ResolveEvent` is a discriminated union (`{ kind: "atom" }` or `{ kind: "resource" }`).
+
+  New `resource({ deps, factory })` primitive for execution-level dependencies (logger, transaction, trace span). Resources are resolved fresh per execution chain, shared via seek-up within nested execs, and cleaned up with `ctx.onClose()`.
+
+  Migration: update `wrapResolve(next, atom, scope)` → `wrapResolve(next, event)`, dispatch on `event.kind`.
+
+## 1.11.4
+
+### Patch Changes
+
+- a3ae2b7: Replace text glossary with mermaid sequence diagrams in documentation
+
+  - README.md now uses visual diagrams for composition, atom lifecycle, tag resolution, type utilities, and API surface
+  - PATTERNS.md converted all usage patterns to sequence diagrams for clarity
+
 ## 1.11.3
 
 ### Patch Changes

package/MIGRATION.md

@@ -236,8 +236,8 @@ const loggingExt = extension({
 // AFTER (lite) - Simplified 4-hook interface
 const loggingExt: Lite.Extension = {
   name: 'logging',
-  wrapResolve: async (next, atom, scope) => {
-    console.log('Resolving atom...')
+  wrapResolve: async (next, event) => {
+    console.log('Resolving:', event.kind, event.target)
     const result = await next()
     console.log('Resolved:', result)
     return result

package/PATTERNS.md

@@ -1,380 +1,281 @@
-# Architectural Patterns
+# Patterns
 
-Design patterns implemented by `@pumped-fn/lite` and how to compose them for application architecture.
+Usage patterns as sequences. For API details, see `packages/lite/dist/index.d.mts`.
 
-## Composite Patterns
+## A. Fundamental Usage
 
 ### Request Lifecycle
 
-**Combines:** IoC Container + Command + Composite
-
-| GoF Pattern | Primitive |
-|-------------|-----------|
-| IoC Container | `Scope` (long-lived, caches atoms) |
-| Command | `Flow` (operations within request) |
-| Composite | `ExecutionContext` (parent-child with isolated data) |
-
-**Key Insight:**
-- `Scope` = application container (atoms cached here)
-- `ExecutionContext` = request boundary (data lives here, closed at request end)
-- `Flow` / `ctx.exec` = operations within the request (share context via `seekTag`)
+Model a request boundary with cleanup and shared context.
 
 ```mermaid
 sequenceDiagram
     participant App
     participant Scope
-    participant Context as ExecutionContext
-    participant ServiceAtom as Service Atom
-    participant Flow1 as Flow (validate)
-    participant Flow2 as Flow (process)
-
-    Note over Scope: Long-lived (app lifetime)
-    App->>Scope: resolve(serviceAtom)
-    Scope-->>App: service (cached)
+    participant Ctx as ExecutionContext
+    participant Flow
 
-    Note over Context: Per-request boundary
-    App->>Scope: createContext({ tags: [requestId, userId] })
+    App->>Scope: createScope()
+    App->>Scope: scope.createContext({ tags })
     Scope-->>App: ctx
 
-    App->>Context: ctx.data.setTag(TX_TAG, beginTransaction())
-    App->>Context: ctx.onClose(() => tx.rollback())
-
-    App->>Context: ctx.exec({ flow: validateFlow, input })
-    Context->>Scope: resolve flow deps (atoms)
-    Scope-->>Context: deps (cached in scope)
-    Context->>Flow1: factory(childCtx, deps)
-    Note over Flow1: childCtx.parent = ctx
-    Flow1->>Flow1: tags.required(userIdTag) from merged tags
-    Flow1-->>Context: validated
-
-    App->>Context: ctx.exec({ flow: processFlow, input: validated })
-    Context->>Scope: resolve flow deps (atoms)
-    Scope-->>Context: deps (from cache)
-    Context->>Flow2: factory(childCtx, deps)
-    Flow2->>Flow2: childCtx.exec({ fn: service.save, params: [data] })
-    Note over Flow2: Creates grandchildCtx
-    Flow2->>ServiceAtom: service.save(grandchildCtx, data)
-    ServiceAtom->>ServiceAtom: grandchildCtx.data.seekTag(TX_TAG)
-    Note over ServiceAtom: seekTag traverses parent chain
-    ServiceAtom-->>Flow2: saved
-    Flow2-->>Context: result
-
-    App->>Context: ctx.data.getTag(TX_TAG).commit()
-    App->>Context: ctx.close()
-    Context->>Context: onClose cleanups run (rollback skipped)
-```
+    App->>Ctx: ctx.exec({ flow, input, tags })
+    Ctx->>Flow: factory(childCtx, deps)
+    Flow-->>Ctx: output
+    Ctx->>Ctx: childCtx.close(result)
+    Ctx-->>App: output
 
-**Characteristics:**
-- Scope caches atoms across requests (resolve once, use many)
-- ExecutionContext bounds request lifecycle (`onClose` for cleanup)
-- Each `exec()` creates child context with isolated `data` Map
-- `seekTag()` traverses parent chain for shared data (e.g., transaction)
-- `ctx.close()` runs all `onClose` cleanups (LIFO order)
-- On error: child context auto-closes, cleanups still run
+    App->>Ctx: ctx.onClose(result => cleanup)
+    App->>Ctx: ctx.close(result?)
+    Ctx->>Ctx: run onClose(CloseResult) LIFO
+```
 
-**Primitives:** `createScope()`, `scope.createContext()`, `ctx.exec()`, `ctx.data.setTag/seekTag()`, `ctx.onClose()`, `ctx.close()`
+### Extensions Pipeline
 
----
+Observe and wrap atoms/flows — logging, auth, tracing, transaction boundaries. Extensions register `onClose(CloseResult)` to finalize based on success or failure.
 
-### Flow Deps & Execution
+```mermaid
+sequenceDiagram
+    participant App
+    participant Scope
+    participant Ext as Extension
+    participant Atom
+    participant Ctx as ExecutionContext
+    participant Flow
 
-**Combines:** Command + Composite + Resource Management
+    App->>Scope: createScope({ extensions: [ext] })
+    Scope->>Ext: ext.init(scope)
+    App->>Scope: await scope.ready
+
+    App->>Scope: resolve(atom)
+    Scope->>Ext: wrapResolve(next, { kind: "atom", target, scope })
+    Ext->>Ext: before logic
+    Ext->>Atom: next()
+    Atom-->>Ext: value
+    Ext->>Ext: after logic
+    Ext-->>Scope: value
+
+    App->>Ctx: ctx.exec({ flow })
+    Ctx->>Ext: wrapExec(next, flow, childCtx)
+    Ext->>Ext: ctx.onClose(result => result.ok ? commit : rollback)
+    Ext->>Flow: next()
+    Flow-->>Ext: output
+    Ext-->>Ctx: output
+
+    App->>Scope: dispose()
+    Scope->>Ext: ext.dispose(scope)
+```
 
-| Concern | Primitive |
-|---------|-----------|
-| Dependency injection | `deps` (atoms from Scope, tags from context hierarchy) |
-| Service invocation | `ctx.exec({ fn, params })` (observable by extensions) |
-| Resource cleanup | `ctx.onClose()` (LIFO, runs on success or failure) |
+### Scoped Isolation + Testing
 
-**Deps Resolution:**
+Swap implementations and isolate tenants/tests.
 
 ```mermaid
-flowchart TB
-    subgraph Flow["flow({ deps, factory })"]
-        Deps["deps: { db: dbAtom, userId: tags.required(userIdTag) }"]
-    end
+sequenceDiagram
+    participant Test
+    participant Scope
+    participant Atom
 
-    subgraph Resolution
-        Deps --> AtomPath["Atom deps"]
-        Deps --> TagPath["Tag deps (TagExecutor)"]
+    Test->>Scope: createScope({ presets: [preset(dbAtom, mockDb)], tags: [tenantTag(id)] })
+    Test->>Scope: resolve(dbAtom)
+    Scope-->>Test: mockDb (not real db)
 
-        AtomPath --> Scope["Scope.resolve()"]
-        Scope --> |"cached in scope"| ResolvedAtom["db instance"]
+    Test->>Scope: createContext()
+    Scope-->>Test: ctx with tenantTag
+```
 
-        TagPath --> CtxHierarchy["ctx.data.seekTag()"]
-        CtxHierarchy --> |"traverses parent chain"| ResolvedTag["userId value"]
-    end
+## B. Advanced Client/State Usage
 
-    subgraph Factory["factory(ctx, { db, userId })"]
-        ResolvedAtom --> DepsObj["deps object"]
-        ResolvedTag --> DepsObj
-    end
-```
+### Controller Reactivity
 
-**Service Invocation:**
+Client-side state with lifecycle hooks and invalidation.
 
 ```mermaid
 sequenceDiagram
-    participant Flow
-    participant Ctx as ExecutionContext
-    participant Ext as Extension.wrapExec
-    participant Fn as service.method
-
-    Note over Flow: ❌ Direct call
-    Flow->>Fn: service.method(ctx, data)
-    Note over Fn: Extensions cannot observe
-
-    Note over Flow: ✅ Via ctx.exec
-    Flow->>Ctx: ctx.exec({ fn: service.method, params: [data] })
-    Ctx->>Ctx: create childCtx (parent = ctx)
-    Ctx->>Ext: wrapExec(next, fn, childCtx)
-    Ext->>Fn: next()
-    Fn-->>Ext: result
-    Ext-->>Ctx: result
-    Ctx->>Ctx: childCtx.close()
-    Ctx-->>Flow: result
-```
+    participant App
+    participant Scope
+    participant Ctrl as Controller
+    participant Atom
 
-**Cleanup Pattern:**
+    App->>Scope: controller(atom)
+    Scope-->>App: ctrl
 
-```mermaid
-sequenceDiagram
-    participant Flow
-    participant Ctx as ExecutionContext
-    participant Tx as Transaction
-
-    Flow->>Tx: beginTransaction()
-    Tx-->>Flow: tx
-    Flow->>Ctx: ctx.onClose(() => tx.rollback())
-
-    alt Success
-        Flow->>Flow: do work
-        Flow->>Tx: tx.commit()
-        Flow->>Ctx: return result
-        Ctx->>Ctx: close() → rollback() is no-op
-    else Error
-        Flow->>Flow: do work (throws)
-        Ctx->>Ctx: close() → rollback() executes
-        Ctx->>Tx: tx.rollback()
-    end
-```
+    App->>Ctrl: ctrl.on('resolving' | 'resolved' | '*', listener)
+    Ctrl-->>App: unsubscribe
 
-**Characteristics:**
-- Atoms resolve via `Scope.resolve()` (cached, long-lived)
-- Tag deps resolve via `ctx.data.seekTag()` (traverses parent → grandparent → scope tags)
-- `ctx.exec({ fn, params })` creates child context with isolated `data` Map
-- Extensions intercept via `wrapExec(next, target, ctx)`
-- Register pessimistic cleanup via `ctx.onClose(fn)`, neutralize on success
+    App->>Ctrl: ctrl.get()
+    Ctrl-->>App: current value
 
-**Primitives:** `flow({ deps })`, `tags.required()`, `tags.optional()`, `tags.all()`, `ctx.exec()`, `ctx.onClose()`
+    App->>Ctrl: ctrl.set(newValue)
+    Ctrl->>Ctrl: notify listeners
 
----
+    App->>Ctrl: ctrl.update(v => v + 1)
+    Ctrl->>Ctrl: notify listeners
 
-### Request Pipeline
+    App->>Ctrl: ctrl.invalidate()
+    Ctrl->>Atom: re-run factory
+    Ctrl->>Ctrl: notify listeners
+```
 
-**Combines:** Command + Interceptor + Context Object
+### Ambient Context (Tags)
 
-| GoF Pattern | Primitive |
-|-------------|-----------|
-| Command | `Flow` (encapsulates request with input/output) |
-| Interceptor | `Extension.wrapExec()` (wraps execution) |
-| Context Object | `Tag` (propagates metadata without explicit passing) |
+Propagate values without wiring parameters. Tags serve two roles: scope-level config (consumed by atoms via `tags.required()`) and per-context ambient data (requestId, locale). Use `tags.required()` in deps to declare that an atom or flow needs an ambient value (e.g., a transacted connection) — extensions or context setup provide the value, the consumer just depends on it.
 
 ```mermaid
 sequenceDiagram
-    participant Client
+    participant App
     participant Scope
-    participant Extension1 as Extension (Auth)
-    participant Extension2 as Extension (Tracing)
-    participant Flow
-    participant Context as ExecutionContext
-
-    Client->>Scope: createContext({ tags: [requestId] })
-    Scope-->>Client: ctx
-    Client->>Context: exec({ flow, input, tags: [userId] })
-
-    Context->>Context: merge tags (flow → scope → context → exec)
-    Context->>Context: create child context
-
-    Context->>Extension1: wrapExec(next, flow, childCtx)
-    Extension1->>Extension1: extract userId tag, validate
-    Extension1->>Extension2: next()
-    Extension2->>Extension2: read parent span from ctx.parent?.data
-    Extension2->>Extension2: create child span, store in ctx.data
-    Extension2->>Flow: next()
-    Flow->>Flow: factory(ctx, deps) with tags.required(userId)
-    Flow-->>Extension2: result
-    Extension2->>Extension2: end span
-    Extension2-->>Extension1: result
-    Extension1-->>Context: result
-    Context->>Context: auto-close child (run onClose cleanups)
-    Context-->>Client: result
-```
+    participant Atom
+    participant Ctx as ExecutionContext
+    participant ChildCtx
+    participant Data as ctx.data
 
-**Characteristics:**
-- Extensions wrap in registration order (outer → inner)
-- Each `exec()` creates isolated child context with own `data` Map
-- Tags merge with later sources winning (exec tags override flow tags)
-- Parent chain enables span correlation without AsyncLocalStorage
+    App->>Scope: createScope({ tags: [configTag(cfg)] })
+    App->>Scope: resolve(dbAtom)
+    Note right of Atom: deps: { config: tags.required(configTag) }
+    Scope->>Atom: factory(ctx, { config: cfg })
 
-**Primitives:** `flow()`, `Extension.wrapExec`, `tag()`, `ctx.exec()`, `ctx.parent`, `ctx.data`
+    App->>Scope: scope.createContext({ tags: [requestIdTag(rid)] })
+    Scope-->>App: ctx
 
----
+    App->>Ctx: ctx.exec({ flow, tags: [localeTag('en')] })
+    Ctx->>ChildCtx: create with merged tags
 
-### Scoped Isolation
+    ChildCtx->>Data: ctx.data.seekTag(requestIdTag)
+    Data-->>ChildCtx: rid (from parent)
 
-**Combines:** IoC Container + Strategy + Composite
+    ChildCtx->>Data: ctx.data.getTag(localeTag)
+    Data-->>ChildCtx: 'en'
+```
 
-| GoF Pattern | Primitive |
-|-------------|-----------|
-| IoC Container | `Scope` (manages atom lifecycles and resolution) |
-| Strategy | `Preset` (swap implementations at scope creation) |
-| Composite | `ExecutionContext` (parent-child isolation) |
+### Derived State (Select)
+
+Subscribe to a slice of atom state with custom equality.
 
 ```mermaid
 sequenceDiagram
     participant App
-    participant TenantScope as Scope (Tenant A)
-    participant TestScope as Scope (Test)
-    participant DbAtom as dbAtom
-    participant MockDb as mockDbAtom
-
-    Note over App: Production - Tenant A
-    App->>TenantScope: createScope({ tags: [tenantId('A')] })
-    App->>TenantScope: resolve(dbAtom)
-    TenantScope->>DbAtom: factory(ctx, deps)
-    DbAtom->>DbAtom: tags.required(tenantId) → 'A'
-    DbAtom-->>TenantScope: TenantA DB connection
-
-    Note over App: Test - Mocked DB
-    App->>TestScope: createScope({ presets: [preset(dbAtom, mockDbAtom)] })
-    App->>TestScope: resolve(dbAtom)
-    TestScope->>TestScope: check presets → found
-    TestScope->>MockDb: resolve mockDbAtom instead
-    MockDb-->>TestScope: Mock DB instance
-
-    Note over App: Parallel tenant contexts
-    par Tenant A request
-        TenantScope->>TenantScope: createContext({ tags: [requestId('r1')] })
-    and Tenant B request
-        TenantScope->>TenantScope: createContext({ tags: [requestId('r2')] })
-    end
-    Note over TenantScope: Each context isolated, same scope
-```
-
-**Characteristics:**
-- Each Scope is an isolated DI container with own cache
-- Presets swap atom implementations without changing definitions
-- Tags at scope level apply to all resolutions
-- Multiple ExecutionContexts share scope but isolate request data
-- Child contexts inherit parent tags, can override
+    participant Scope
+    participant Handle as SelectHandle
+    participant Atom
 
-**Use Cases:**
-- Multi-tenancy: scope-level tenant tag, context-level request isolation
-- Testing: preset mocks without touching production atom definitions
-- Feature flags: preset alternative implementations per environment
+    App->>Scope: select(atom, v => v.count, { eq: shallowEqual })
+    Scope-->>App: handle
 
-**Primitives:** `createScope()`, `preset()`, `tag()`, `createContext()`, scope `tags` option
+    App->>Handle: handle.get()
+    Handle-->>App: selected value
 
----
+    App->>Handle: handle.subscribe(listener)
+    Handle-->>App: unsubscribe
 
-## Foundational Patterns
+    Note over Atom,Handle: atom changes
+    Handle->>Handle: eq(prev, next)?
+    Handle->>App: notify if changed
+```
 
-### IoC Container
+### Service Pattern
 
-**GoF:** Inversion of Control / Dependency Injection Container
+Constrain atom methods to ExecutionContext-first signature. Always invoke via `ctx.exec` so a child context is created — extensions can observe the call, and cleanup is scoped.
 
 ```mermaid
-graph TB
-    Scope["Scope (Container)"]
-    AtomA["Atom A"]
-    AtomB["Atom B"]
-    AtomC["Atom C"]
-    Cache["Resolution Cache"]
-
-    Scope -->|resolve| AtomA
-    Scope -->|resolve| AtomB
-    AtomB -->|deps| AtomA
-    AtomC -->|deps| AtomA
-    AtomC -->|deps| AtomB
-    Scope --- Cache
+sequenceDiagram
+    participant App
+    participant Scope
+    participant Ctx as ExecutionContext
+    participant Child as ChildContext
+    participant Svc as Service Atom
+
+    App->>Scope: resolve(userService)
+    Scope-->>App: { getUser, updateUser }
+
+    App->>Ctx: ctx.exec({ fn: svc.getUser, params: [userId] })
+    Ctx->>Child: create child context
+    Child->>Svc: getUser(childCtx, userId)
+    Svc-->>Child: user
+    Child->>Child: close(result)
+    Child-->>App: user
 ```
 
-**Primitives:** `createScope()`, `atom()`, `deps`, `scope.resolve()`
+### Typed Flow Input
 
-**Characteristics:** Lazy resolution, automatic caching, dependency graph traversal, circular dependency detection.
-
----
-
-### Observer
-
-**GoF:** Observer Pattern with State Machine
+Type flow input without runtime parsing overhead.
 
 ```mermaid
-stateDiagram-v2
-    [*] --> idle
-    idle --> resolving: resolve()
-    resolving --> resolved: success
-    resolving --> failed: error
-    resolved --> resolving: invalidate()
-    failed --> resolving: invalidate()
-
-    note right of resolving: listeners notified
-    note right of resolved: listeners notified
+sequenceDiagram
+    participant App
+    participant Ctx as ExecutionContext
+    participant Child as ChildContext
+    participant Flow
+
+    Note over Flow: flow({ parse: typed<T>(), factory })
+    App->>Ctx: ctx.exec({ flow, input: typedInput })
+    Ctx->>Child: create child (input passed through, no parse)
+    Child->>Flow: factory(childCtx, deps) with ctx.input: T
+    Flow-->>Child: output
+    Child->>Child: close(result)
+    Child-->>App: output
 ```
 
-**Primitives:** `controller()`, `ctrl.on('resolved' | 'resolving' | '*')`, `ctrl.invalidate()`
+### Controller as Dependency
 
-**Characteristics:** State-filtered subscriptions, LIFO cleanup before re-resolution, sequential invalidation chains with loop detection.
+Receive reactive handle instead of resolved value in atom/flow deps.
 
----
+```mermaid
+sequenceDiagram
+    participant Scope
+    participant AtomA as serverAtom
+    participant Ctrl as Controller
+    participant AtomB as configAtom
+
+    Scope->>AtomA: resolve(serverAtom)
+    Note over AtomA: deps: { cfg: controller(configAtom, { resolve: true }) }
+    AtomA->>Scope: resolve configAtom first
+    Scope-->>Ctrl: ctrl (already resolved)
+    AtomA->>AtomA: factory(ctx, { cfg: ctrl })
+    AtomA->>Ctrl: ctrl.on('resolved', () => ctx.invalidate())
+    Note over AtomA: react to config changes
+```
 
-### Context Object
+### Inline Function Execution
 
-**GoF:** Context Object / Ambient Context
+Execute ad-hoc logic within context without defining a flow.
 
 ```mermaid
-graph TB
-    subgraph Sources
-        FlowTags[Flow tags]
-        ScopeTags[Scope tags]
-        CtxTags[Context tags]
-        ExecTags[Exec tags]
-    end
-
-    subgraph Merge[Tag Merge - later wins]
-        FlowTags --> Merged
-        ScopeTags --> Merged
-        CtxTags --> Merged
-        ExecTags --> Merged
-    end
+sequenceDiagram
+    participant App
+    participant Ctx as ExecutionContext
 
-    subgraph Extract
-        Merged --> Required[tags.required]
-        Merged --> Optional[tags.optional]
-        Merged --> All[tags.all]
-    end
+    App->>Ctx: ctx.exec({ name, fn, params, tags })
+    Ctx->>Ctx: create childCtx (name + tags)
+    Ctx->>Ctx: fn(childCtx, ...params)
+    Ctx->>Ctx: childCtx.close(result)
+    Ctx-->>App: output
+    Note right of Ctx: name makes sub-executions observable by extensions
 ```
 
-**Primitives:** `tag()`, `tags.required()`, `tags.optional()`, `tags.all()`, `Tagged`
+### Atom Retention (GC)
 
-**Characteristics:** Implicit propagation through execution layers, type-safe extraction, merge precedence (exec > context > scope > flow).
+Control when atoms are garbage collected or kept alive indefinitely.
 
----
+```mermaid
+sequenceDiagram
+    participant App
+    participant Scope
+    participant Atom
 
-### Strategy
+    App->>Scope: createScope({ gc: { enabled: true, graceMs: 3000 } })
 
-**GoF:** Strategy Pattern
+    App->>Scope: resolve(atom)
+    Scope-->>App: value
+    Note over Scope: no refs → start grace timer
 
-```mermaid
-graph TB
-    Scope -->|resolve| Atom
-    Atom -->|check| Presets{Preset?}
-    Presets -->|value| Direct[Return value]
-    Presets -->|atom| Redirect[Resolve other atom]
-    Presets -->|none| Factory[Run factory]
-```
-
-**Primitives:** `preset()`, `createScope({ presets })`, `isPreset()`
+    alt keepAlive: true
+        Note over Atom: never GC'd
+    else graceMs expires
+        Scope->>Atom: release()
+        Atom->>Atom: run cleanups
+    end
 
-**Characteristics:** Swap implementations at scope creation, value injection bypasses factory, atom redirection for mock substitution.
+    App->>Scope: flush()
+    Note over Scope: wait all pending
+```