@pumped-fn/lite 1.11.4 → 2.0.0

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # @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

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

@@ -22,17 +22,17 @@ sequenceDiagram
     App->>Ctx: ctx.exec({ flow, input, tags })
     Ctx->>Flow: factory(childCtx, deps)
     Flow-->>Ctx: output
-    Ctx->>Ctx: childCtx.close()
+    Ctx->>Ctx: childCtx.close(result)
     Ctx-->>App: output
 
-    App->>Ctx: ctx.onClose(cleanup)
-    App->>Ctx: ctx.close()
-    Ctx->>Ctx: run cleanups (LIFO)
+    App->>Ctx: ctx.onClose(result => cleanup)
+    App->>Ctx: ctx.close(result?)
+    Ctx->>Ctx: run onClose(CloseResult) LIFO
 ```
 
 ### Extensions Pipeline
 
-Observe and wrap timing for atoms/flows (logging, auth, tracing).
+Observe and wrap atoms/flows — logging, auth, tracing, transaction boundaries. Extensions register `onClose(CloseResult)` to finalize based on success or failure.
 
 ```mermaid
 sequenceDiagram
@@ -40,6 +40,7 @@ sequenceDiagram
     participant Scope
     participant Ext as Extension
     participant Atom
+    participant Ctx as ExecutionContext
     participant Flow
 
     App->>Scope: createScope({ extensions: [ext] })
@@ -47,18 +48,19 @@ sequenceDiagram
     App->>Scope: await scope.ready
 
     App->>Scope: resolve(atom)
-    Scope->>Ext: wrapResolve(next, atom, scope)
+    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->>Scope: ctx.exec({ flow })
-    Scope->>Ext: wrapExec(next, flow, ctx)
+    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-->>Scope: output
+    Ext-->>Ctx: output
 
     App->>Scope: dispose()
     Scope->>Ext: ext.dispose(scope)
@@ -117,21 +119,30 @@ sequenceDiagram
 
 ### Ambient Context (Tags)
 
-Propagate state without wiring parameters (app shell, user, locale).
+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 App
+    participant Scope
+    participant Atom
     participant Ctx as ExecutionContext
     participant ChildCtx
     participant Data as ctx.data
 
-    App->>Data: ctx.data.setTag(userTag, user)
+    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 })
+
+    App->>Scope: scope.createContext({ tags: [requestIdTag(rid)] })
+    Scope-->>App: ctx
+
     App->>Ctx: ctx.exec({ flow, tags: [localeTag('en')] })
     Ctx->>ChildCtx: create with merged tags
 
-    ChildCtx->>Data: ctx.data.seekTag(userTag)
-    Data-->>ChildCtx: user (from parent)
+    ChildCtx->>Data: ctx.data.seekTag(requestIdTag)
+    Data-->>ChildCtx: rid (from parent)
 
     ChildCtx->>Data: ctx.data.getTag(localeTag)
     Data-->>ChildCtx: 'en'
@@ -164,22 +175,25 @@ sequenceDiagram
 
 ### Service Pattern
 
-Constrain atom methods to ExecutionContext-first signature for tracing/auth.
+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
 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: svc.getUser(ctx, userId)
-    Ctx->>Svc: traced execution
-    Svc-->>Ctx: user
-    Ctx-->>App: user
+    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
 ```
 
 ### Typed Flow Input
@@ -189,14 +203,17 @@ Type flow input without runtime parsing overhead.
 ```mermaid
 sequenceDiagram
     participant App
+    participant Ctx as ExecutionContext
+    participant Child as ChildContext
     participant Flow
-    participant Ctx
 
     Note over Flow: flow({ parse: typed<T>(), factory })
-    App->>Flow: ctx.exec({ flow, input: typedInput })
-    Flow->>Flow: skip parse (type-only)
-    Flow->>Ctx: factory(ctx) with ctx.input: T
-    Ctx-->>App: output
+    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
 ```
 
 ### Controller as Dependency
@@ -228,11 +245,12 @@ sequenceDiagram
     participant App
     participant Ctx as ExecutionContext
 
-    App->>Ctx: ctx.exec({ fn: (ctx, a, b) => a + b, params: [1, 2], tags })
-    Ctx->>Ctx: create childCtx with tags
-    Ctx->>Ctx: fn(childCtx, 1, 2)
-    Ctx->>Ctx: childCtx.close()
-    Ctx-->>App: 3
+    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
 ```
 
 ### Atom Retention (GC)

package/README.md

@@ -1,8 +1,22 @@
 # @pumped-fn/lite
 
-Lightweight effect system for TypeScript: scoped lifecycles, tagged context, and opt‑in reactivity.
+![Coverage: 97%+ statements](https://img.shields.io/badge/coverage-97%25%2B_statements-brightgreen) ![Coverage: 100% functions](https://img.shields.io/badge/coverage-100%25_functions-brightgreen) ![Tests: 263 passed](https://img.shields.io/badge/tests-263_passed-brightgreen)
 
-Docs: `packages/lite/PATTERNS.md` for usage patterns, `packages/lite/dist/index.d.mts` for API details.
+**Scoped Ambient State** for TypeScript — a scope-local atom graph with explicit dependencies and opt-in reactivity.
+
+State lives in the scope, not in the component tree. Handlers and components observe — they don't own or construct dependencies. The same graph works across React, server handlers, background jobs, and tests.
+
+**Frontend** — atoms form a reactive dependency graph (`homeData <- auth`). UI subscribes via controllers; auth changes cascade to dependents automatically. Components are projections of state, not owners.
+
+**Backend** — atoms are infrastructure singletons (db pool, cache). Runtime config enters the scope as tags; atoms consume it via `tags.required()`. Contexts bound per request carry tags (tenantId, traceId) without parameter drilling. Extensions wrap every resolve/exec for logging, tracing, auth. Cleanup is guaranteed.
+
+**Both** — presets swap any atom/flow for testing or multi-tenant isolation. Tags carry runtime config; presets replace implementations. No mocks, no test-only code paths.
+
+```
+npx @pumped-fn/lite              # CLI reference
+npx @pumped-fn/lite primitives   # API
+npx @pumped-fn/lite diagrams     # mermaid source
+```
 
 ## How It Works
 
@@ -11,220 +25,157 @@ sequenceDiagram
     participant App
     participant Scope
     participant Ext as Extension
-    participant Ctx as ExecutionContext
     participant Atom
+    participant Ctx as ExecutionContext
+    participant Child as ChildContext
     participant Flow
     participant Ctrl as Controller
 
-    App->>Scope: createScope({ extensions, presets, tags })
-    Scope-->>App: scope (ready)
+    Note over App,Ctrl: (*) stable ref — same identity until released
 
-    App->>Scope: resolve(atom)
-    Scope->>Ext: wrapResolve(next, atom)
-    Ext->>Atom: factory(ctx, deps)
-    Atom-->>Scope: value (cached)
-
-    App->>Scope: createContext({ tags })
-    Scope-->>App: ctx
-
-    App->>Ctx: ctx.exec({ flow, input, tags })
-    Ctx->>Ctx: merge tags, create childCtx
-    Ctx->>Ext: wrapExec(next, flow, childCtx)
-    Ext->>Flow: parse(input) + factory(childCtx, deps)
-    Flow-->>Ext: output
-    Ext-->>Ctx: output
-    Ctx->>Ctx: childCtx.close() (onClose LIFO)
-    Ctx-->>App: output
-
-    rect rgb(240, 248, 255)
-        Note over App,Ctrl: Reactivity (opt‑in)
-        App->>Scope: controller(atom)
-        Scope-->>Ctrl: ctrl
-        App->>Ctrl: ctrl.get() / ctrl.resolve()
-        Ctrl-->>App: value
-        App->>Ctrl: ctrl.set(v) / ctrl.update(fn)
-        App->>Ctrl: ctrl.on('resolved', listener)
-        Ctrl-->>App: unsubscribe
-        App->>Ctrl: ctrl.invalidate()
-        Ctrl->>Atom: re‑run factory
-        App->>Ctrl: ctrl.release()
-        App->>Scope: release(atom)
-        Scope->>Scope: run cleanups, remove cache
-        App->>Scope: select(atom, selector, { eq })
-        Scope-->>App: { get, subscribe }
-        App->>Scope: on('resolved', atom, listener)
-        Scope-->>App: unsubscribe
-    end
+    %% ── Scope Creation & Extension Init ──
+    App->>Scope: createScope({ extensions, presets, tags, gc })
+    Scope-->>App: scope (sync return)
 
-    rect rgb(255, 250, 240)
-        Note over App,Scope: Introspection
-        App->>App: isAtom(v), isFlow(v), isTag(v), isTagged(v)
-        App->>App: isPreset(v), isControllerDep(v), isTagExecutor(v)
-        App->>App: getAllTags() → Tag[]
+    loop each extension (sequential)
+        Scope->>Ext: await ext.init(scope)
     end
+    Note right of Scope: all init() done → scope.ready resolves
+    Note right of Scope: any init() throws → scope.ready rejects
+    Note right of Scope: resolve() auto‑awaits scope.ready
 
-    App->>Scope: flush()
-    Note right of Scope: wait pending ops
-    App->>Ctx: ctx.close()
-    Ctx->>Ctx: run onClose (LIFO)
-    App->>Scope: dispose()
-    Scope->>Scope: release atoms, run cleanups
-```
-
-## Composition
+    %% ── Observers (register before or after resolve) ──
+    App->>Scope: scope.on('resolving' | 'resolved' | 'failed', atom, listener)
+    Scope-->>App: unsubscribe fn
+    Note right of Scope: scope.on listens to AtomState transitions
 
-```mermaid
-graph LR
-    subgraph Primitives
-        atom["atom({ factory, deps?, tags?, keepAlive? })"]
-        flow["flow({ factory, parse?, deps?, tags? })"]
-        service["service({ factory, deps? })"]
-        tag["tag({ label, default?, parse? })"]
-        preset["preset(target, value)"]
+    %% ── Atom Resolution ──
+    Note right of Scope: singletons — created once, reused across contexts. deps can include tags.required()
+    App->>Scope: resolve(atom)
+    Scope->>Scope: cache hit? → return cached
+    alt preset hit
+        Scope->>Scope: value → store directly, skip factory
+        Scope->>Scope: atom → resolve that atom instead
+        Scope->>Scope: ⚡ emit 'resolved' (no 'resolving')
     end
-
-    subgraph Wrappers
-        typed["typed&lt;T&gt;()"]
-        ctrlDep["controller(atom, { resolve? })"]
-        tagExec["tags.required/optional/all(tag)"]
+    Scope->>Scope: state → resolving
+    Scope->>Scope: ⚡ emit 'resolving' → scope.on listeners
+    Scope->>Ext: wrapResolve(next, { kind: "atom", target, scope })
+    Ext->>Atom: next() → factory(ctx, deps)
+    Note right of Atom: ctx.cleanup(fn) → stored per atom
+    Note right of Atom: cleanups run LIFO on release/invalidate
+    Atom-->>Ext: value
+    Note right of Ext: ext returns value — may transform or replace
+    alt factory succeeds
+        Ext-->>Scope: value (*) cached in entry
+        Scope->>Scope: state → resolved
+        Scope->>Scope: ⚡ emit 'resolved' → scope.on + ctrl.on listeners
+    else factory throws
+        Atom-->>Scope: error
+        Scope->>Scope: state → failed
+        Scope->>Scope: ⚡ emit 'failed' → scope.on listeners (ctrl.on '*' only)
     end
 
-    flow --> typed
-    atom --> ctrlDep
-    tag --> tagExec
-```
-
-## Context Data
+    %% ── Context Creation ──
+    Note right of Scope: HTTP request, job, transaction — groups exec calls with shared tags + guaranteed cleanup
+    App->>Scope: scope.createContext({ tags })
+    Scope-->>App: ctx
 
-```mermaid
-graph TD
-    subgraph "ctx.data"
-        raw["Raw: get/set/has/delete/clear/seek"]
-        typed["Typed: getTag/setTag/hasTag/deleteTag/seekTag/getOrSetTag"]
+    %% ── Execution ──
+    alt ctx.exec({ flow, input, tags })
+        Ctx->>Ctx: preset? → flow: re‑exec with replacement / fn: run as factory
+        Ctx->>Ctx: flow.parse(input) if defined
+        Ctx->>Child: create child (parent = ctx, merged tags)
+        Child->>Ext: wrapExec(next, flow, childCtx)
+        Ext->>Flow: next() → factory(childCtx, deps)
+        Note right of Flow: childCtx.onClose(result: CloseResult) → { ok: true } | { ok: false, error }
+        Flow-->>Ext: output
+        Note right of Ext: ext returns output — may transform or replace
+        Ext-->>Child: output
+    else ctx.exec({ name?, fn, params, tags })
+        Ctx->>Child: create child (parent = ctx)
+        Child->>Ext: wrapExec(next, fn, childCtx)
+        Ext->>Child: next() → fn(childCtx, ...params)
+        Child-->>Ext: result
     end
-    raw --> typed
-```
-
-## Atom Lifecycle (AtomState)
-
-```mermaid
-stateDiagram-v2
-    [*] --> idle
-    idle --> resolving: resolve() / controller()
-    resolving --> resolved: factory completes
-    resolving --> failed: factory throws
-    resolved --> resolving: invalidate()
-    resolved --> idle: release()
-    failed --> resolving: invalidate()
-    failed --> idle: release()
-```
-
-## Tag Resolution
-
-```mermaid
-sequenceDiagram
-    participant App
-    participant Tag
-    participant Source as Atom/Flow/Ctx
-
-    App->>Tag: tag({ label, default? })
-    Tag-->>App: Tag<T>
-
-    App->>Tag: tag(value)
-    Tag-->>App: Tagged<T>
-
-    App->>Source: attach Tagged[] to atom/flow/ctx
-
-    App->>Tag: tag.get(source)
-    Tag->>Source: find first match
-    Source-->>Tag: value or throw
-
-    App->>Tag: tag.find(source)
-    Tag->>Source: find first match
-    Source-->>Tag: value or undefined
-
-    App->>Tag: tag.collect(source)
-    Tag->>Source: gather all matches
-    Source-->>Tag: T[]
-
-    App->>Tag: tag.atoms()
-    Tag-->>App: Atom[] with this tag
-```
-
-## Type Utilities
+    Ctx->>Child: [A] close(result) → run onClose(CloseResult) LIFO
+    Child-->>Ctx: output
+    Ctx-->>App: output
 
-```mermaid
-graph LR
-    subgraph "Lite.Utils"
-        AtomValue["AtomValue&lt;A&gt;"]
-        FlowOutput["FlowOutput&lt;F&gt;"]
-        FlowInput["FlowInput&lt;F&gt;"]
-        TagValue["TagValue&lt;T&gt;"]
-        DepsOf["DepsOf&lt;A|F&gt;"]
-        ControllerValue["ControllerValue&lt;C&gt;"]
-        Simplify["Simplify&lt;T&gt;"]
-        AtomType["AtomType&lt;T, D&gt;"]
-        FlowType["FlowType&lt;O, I, D&gt;"]
+    %% ── Resource (execution‑scoped) ──
+    rect rgb(245, 240, 255)
+        Note over App,Ctrl: Resource (per‑execution middleware)
+        Note right of Scope: reusable factory resolved fresh per execution chain — logger, transaction, trace span
+
+        App->>App: resource({ deps, factory })
+        App-->>App: Resource definition (inert)
+
+        Note right of Child: during dep resolution in ctx.exec():
+        Note right of Child: seek hierarchy for existing instance
+        alt cache hit (seek‑up)
+            Child->>Child: reuse instance from parent ✓
+        else cache miss
+            Child->>Ext: wrapResolve(next, { kind: "resource", target, ctx })
+            Ext->>Child: next() → factory(parentCtx, deps)
+            Note right of Child: parentCtx.onClose(result) → cleanup registered
+            Child-->>Ext: instance stored on parent context
+        end
     end
 
-    subgraph "Type Guards"
-        isAtom
-        isFlow
-        isTag
-        isTagged
-        isPreset
-        isControllerDep
-        isTagExecutor
-    end
+    %% ── Reactivity (opt‑in) ──
+    rect rgb(240, 248, 255)
+        Note over App,Ctrl: Reactivity (opt‑in — atoms are static by default)
+        Note right of Scope: live config, UI state, cache invalidation — when values change after initial resolve
+        App->>Scope: controller(atom)
+        Scope-->>Ctrl: ctrl (*)
 
-    subgraph "Convenience"
-        AnyAtom
-        AnyFlow
-        AnyController
-    end
-```
+        App->>Ctrl: ctrl.on('resolving' | 'resolved' | '*', listener)
+        Ctrl-->>App: unsubscribe
+        Note right of Ctrl: ctrl.on listens to per‑atom entry events
 
-## Introspection
+        App->>Ctrl: ctrl.set(v) / ctrl.update(fn)
+        Ctrl->>Scope: scheduleInvalidation
+        Scope->>Scope: run atom cleanups (LIFO)
+        Scope->>Scope: ⚡ emit 'resolving' → scope.on + ctrl.on
+        Scope->>Atom: apply new value (skip factory)
+        Scope->>Scope: state → resolved
+        Scope->>Scope: ⚡ emit 'resolved' → scope.on + ctrl.on
 
-```mermaid
-sequenceDiagram
-    participant App
-    participant Registry
+        App->>Ctrl: ctrl.invalidate()
+        Ctrl->>Scope: scheduleInvalidation
+        Scope->>Scope: run atom cleanups (LIFO)
+        Scope->>Scope: ⚡ emit 'resolving' → scope.on + ctrl.on
+        Scope->>Atom: re‑run factory
+        Scope->>Scope: state → resolved
+        Scope->>Scope: ⚡ emit 'resolved' → scope.on + ctrl.on
 
-    App->>Registry: getAllTags()
-    Registry-->>App: Tag[] (all live tags)
+        App->>Scope: select(atom, selector, { eq })
+        Scope-->>App: handle { get, subscribe }
+    end
 
-    App->>App: isAtom(v) / isFlow(v) / isTag(v)
-    App->>App: isTagged(v) / isPreset(v)
-    App->>App: isControllerDep(v) / isTagExecutor(v)
-```
+    %% ── Cleanup & Teardown ──
+    rect rgb(255, 245, 238)
+        Note over App,Scope: Teardown
+        App->>Ctx: ctx.close(result?) — same as [A]
+        Ctx->>Ctx: run onClose(CloseResult) cleanups (LIFO, idempotent)
 
-## Additional Exports
+        App->>Scope: release(atom)
+        Scope->>Scope: run atom cleanups (LIFO)
+        Scope->>Scope: remove from cache + controllers
 
-```mermaid
-graph LR
-    subgraph Errors
-        ParseError["ParseError (tag | flow-input)"]
-    end
+        App->>Scope: flush()
+        Note right of Scope: await pending invalidation chain
 
-    subgraph Meta
-        VERSION
+        App->>Scope: dispose()
+        loop each extension
+            Scope->>Ext: ext.dispose(scope)
+        end
+        Scope->>Scope: release all atoms, run all cleanups
     end
 
-    subgraph "Symbols (advanced)"
-        atomSymbol
-        flowSymbol
-        tagSymbol
-        taggedSymbol
-        presetSymbol
-        controllerSymbol
-        controllerDepSymbol
-        tagExecutorSymbol
-        typedSymbol
-    end
 ```
 
-API reference: `packages/lite/dist/index.d.mts`.
+API reference: `dist/index.d.mts` | Patterns: `PATTERNS.md` | CLI: `npx @pumped-fn/lite`
 
 ## License