@pumped-fn/lite 1.9.2 → 1.11.0

package/CHANGELOG.md

@@ -1,5 +1,51 @@
 # @pumped-fn/lite
 
+## 1.11.0
+
+### Minor Changes
+
+- 60604a2: Add automatic garbage collection for atoms
+
+  - Atoms are automatically released when they have no subscribers after a configurable grace period (default 3000ms)
+  - Cascading GC: dependencies are protected while dependents are mounted
+  - New `keepAlive: true` option on atoms to prevent auto-release
+  - New `gc: { enabled, graceMs }` option on `createScope()` to configure or disable GC
+  - React Strict Mode compatible via grace period (handles double-mount/unmount)
+  - Disable with `createScope({ gc: { enabled: false } })` to preserve pre-1.11 behavior
+
+- 06d527f: Add utility types for better DX and boundary types for extensions
+
+  - Add `Lite.Utils` namespace with type extraction utilities:
+    - `AtomValue<A>`, `FlowOutput<F>`, `FlowInput<F>`, `TagValue<T>`, `ControllerValue<C>`
+    - `DepsOf<T>`, `Simplify<T>`, `AtomType<T, D>`, `FlowType<O, I, D>`
+  - Add boundary types for passthrough extension code:
+    - `AnyAtom`, `AnyFlow`, `AnyController`
+  - Add `ExecTarget` and `ExecTargetFn` type aliases for cleaner extension signatures
+
+### Patch Changes
+
+- a017021: docs: add Flow Deps & Execution pattern and improve documentation
+
+  - Add "Flow Deps & Execution" section to PATTERNS.md covering:
+    - Deps resolution (atoms from Scope vs tags from context hierarchy)
+    - Service invocation via ctx.exec (observable by extensions)
+    - Cleanup pattern with ctx.onClose (pessimistic cleanup)
+  - Remove redundant patterns (Command, Interceptor) covered by composite patterns
+  - Remove verbose Error Boundary diagram, replaced with bullet point
+  - Add Documentation section to README linking PATTERNS.md and API reference
+
+## 1.10.0
+
+### Minor Changes
+
+- d227191: Add tag and atom registries for automatic tracking
+
+  - Add `tag.atoms()` method to query all atoms that use a specific tag
+  - Add `getAllTags()` function to query all created tags
+  - Tagged values now include a `tag` reference to their parent Tag
+  - Uses WeakRef for memory-efficient tracking (tags and atoms can be GC'd)
+  - Automatic registration when `tag()` and `atom()` are called
+
 ## 1.9.2
 
 ### Patch Changes

package/PATTERNS.md

@@ -44,7 +44,7 @@ sequenceDiagram
     Scope-->>Context: deps (cached in scope)
     Context->>Flow1: factory(childCtx, deps)
     Note over Flow1: childCtx.parent = ctx
-    Flow1->>Flow1: tags.required(userId) from merged tags
+    Flow1->>Flow1: tags.required(userIdTag) from merged tags
     Flow1-->>Context: validated
 
     App->>Context: ctx.exec({ flow: processFlow, input: validated })
@@ -70,46 +70,103 @@ sequenceDiagram
 - 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
 
-**Error Boundary (natural extension):**
+**Primitives:** `createScope()`, `scope.createContext()`, `ctx.exec()`, `ctx.data.setTag/seekTag()`, `ctx.onClose()`, `ctx.close()`
+
+---
+
+### Flow Deps & Execution
+
+**Combines:** Command + Composite + Resource Management
+
+| 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) |
+
+**Deps Resolution:**
+
+```mermaid
+flowchart TB
+    subgraph Flow["flow({ deps, factory })"]
+        Deps["deps: { db: dbAtom, userId: tags.required(userIdTag) }"]
+    end
+
+    subgraph Resolution
+        Deps --> AtomPath["Atom deps"]
+        Deps --> TagPath["Tag deps (TagExecutor)"]
+
+        AtomPath --> Scope["Scope.resolve()"]
+        Scope --> |"cached in scope"| ResolvedAtom["db instance"]
+
+        TagPath --> CtxHierarchy["ctx.data.seekTag()"]
+        CtxHierarchy --> |"traverses parent chain"| ResolvedTag["userId value"]
+    end
+
+    subgraph Factory["factory(ctx, { db, userId })"]
+        ResolvedAtom --> DepsObj["deps object"]
+        ResolvedTag --> DepsObj
+    end
+```
+
+**Service Invocation:**
 
 ```mermaid
 sequenceDiagram
-    participant App
-    participant Scope
-    participant Context as ExecutionContext
     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
+```
 
-    App->>Scope: createContext({ tags: [requestId] })
-    Scope-->>App: ctx
-    App->>Context: ctx.onClose(() => releaseResources())
-
-    alt Success path
-        App->>Context: ctx.exec({ flow, input })
-        Context->>Scope: resolve flow deps
-        Scope-->>Context: deps (cached)
-        Context->>Flow: factory(childCtx, deps)
-        Flow-->>Context: result
-        Note over Context: childCtx auto-closes
-        Context-->>App: result
-        App->>Context: ctx.close()
-        Context->>Context: run onClose cleanups
-    else Error path
-        App->>Context: ctx.exec({ flow, input })
-        Context->>Scope: resolve flow deps
-        Scope-->>Context: deps (cached)
-        Context->>Flow: factory(childCtx, deps)
-        Flow-->>Flow: throws Error
-        Note over Context: childCtx auto-closes
-        Context-->>App: throws Error
-        App->>App: catch(error)
-        App->>Context: ctx.close()
-        Context->>Context: run onClose cleanups
-        App-->>App: return error response
+**Cleanup Pattern:**
+
+```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
 ```
 
-**Primitives:** `createScope()`, `scope.createContext()`, `ctx.exec()`, `ctx.data.setTag/seekTag()`, `ctx.onClose()`, `ctx.close()`
+**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
+
+**Primitives:** `flow({ deps })`, `tags.required()`, `tags.optional()`, `tags.all()`, `ctx.exec()`, `ctx.onClose()`
 
 ---
 
@@ -272,45 +329,6 @@ stateDiagram-v2
 
 ---
 
-### Command
-
-**GoF:** Command Pattern
-
-```mermaid
-graph LR
-    Client -->|exec| Context[ExecutionContext]
-    Context -->|invoke| Flow
-    Flow -->|input| Factory
-    Factory -->|output| Context
-    Context -->|result| Client
-```
-
-**Primitives:** `flow()`, `ctx.exec()`, `ctx.input`, `parse`
-
-**Characteristics:** Encapsulated request/response, input validation via `parse`, nestable execution, auto-closing child contexts.
-
----
-
-### Interceptor
-
-**GoF:** Interceptor / Chain of Responsibility
-
-```mermaid
-graph LR
-    Request --> Ext1[Extension 1]
-    Ext1 -->|next| Ext2[Extension 2]
-    Ext2 -->|next| Target[Atom/Flow]
-    Target --> Ext2
-    Ext2 --> Ext1
-    Ext1 --> Response
-```
-
-**Primitives:** `Extension`, `wrapResolve()`, `wrapExec()`, `init()`, `dispose()`
-
-**Characteristics:** Wraps both atom resolution and flow execution, registration order determines nesting, access to scope and context.
-
----
-
 ### Context Object
 
 **GoF:** Context Object / Ambient Context

package/README.md

@@ -4,6 +4,13 @@ A lightweight effect system for TypeScript with managed lifecycles and minimal r
 
 **Zero dependencies** · **<17KB bundle** · **Full TypeScript support**
 
+## Documentation
+
+| Resource | Purpose |
+|----------|---------|
+| [PATTERNS.md](./PATTERNS.md) | Architecture patterns, flow design, deps resolution, cleanup strategies |
+| [dist/index.d.mts](./dist/index.d.mts) | API reference with TSDoc |
+
 ## How It Works
 
 ```mermaid
@@ -74,20 +81,26 @@ sequenceDiagram
     Context->>Context: run onClose cleanups (LIFO)
 ```
 
-## Tag Inheritance
+## Tag Inheritance (ADR-023)
+
+Tags are auto-populated into `ctx.data` and resolved via `seekTag()`:
 
 ```mermaid
 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'"]
+    subgraph Root["Root Context (ctx.data)"]
+        S["scope.tags → auto-populated"]
+        C["context.tags → auto-populated"]
+        subgraph Child["Child Context (exec)"]
+            E["exec.tags → auto-populated"]
+            F["flow.tags → auto-populated"]
+            D["ctx.data.setTag() → runtime"]
+            subgraph Deps["tags.required(tag)"]
+                R["seekTag() traverses: Child → Root"]
             end
         end
     end
 
-    Note["Inner inherits from outer. Override by passing same tag at inner level."]
+    Note["Nearest value wins. Propagates to all descendants."]
 ```
 
 ## Controller Reactivity
@@ -155,11 +168,29 @@ Short-lived operation with input/output.
 
 Contextual value passed through execution without explicit wiring.
 
-- `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
+- Hierarchical lookup via `seekTag()` (ADR-023)
+- Auto-populates into `ctx.data`: scope → context → exec → flow
+- Registry tracks atom↔tag relationships (ADR-026)
+
+```mermaid
+flowchart TD
+    subgraph "Tag Registry (ADR-026)"
+        direction LR
+        A["atom({ tags: [...] })"] -->|auto-register| R["WeakMap⟨Tag, WeakRef⟨Atom⟩[]⟩"]
+        R -->|"tag.atoms()"| Q["query atoms by tag"]
+        R -->|"getAllTags()"| T["query all tags"]
+    end
+
+    subgraph "Tag Inheritance (ADR-023)"
+        S[scope.tags] --> D[ctx.data]
+        C[context.tags] --> D
+        E[exec.tags] --> D
+        F[flow.tags] --> D
+        D -->|"seekTag()"| V["nearest value wins"]
+    end
+```
+
+Memory: `WeakRef` allows GC of unused atoms/tags. Cleanup on query.
 
 ### Controller
 
@@ -194,9 +225,43 @@ AOP-style middleware for cross-cutting concerns.
 - `dispose(scope)` — cleanup when scope disposed
 - Pass via `createScope({ extensions: [...] })`
 
-## Full API
+## Patterns
+
+### Eager Resolution via Tag Registry
+
+Use tags to mark atoms for eager resolution without hardcoding atom references:
+
+```mermaid
+flowchart LR
+    subgraph "Define"
+        T[eagerTag] --> A1[atomA]
+        T --> A2[atomB]
+        T --> A3[atomC]
+    end
+
+    subgraph "Extension init()"
+        E["eagerTag.atoms()"] --> R["resolve all marked atoms"]
+    end
+
+    A1 & A2 & A3 -.->|"auto-tracked"| E
+```
+
+### Extension Discovery via getAllTags()
+
+Extensions can discover and process all tags at runtime:
+
+```mermaid
+flowchart LR
+    subgraph "Runtime"
+        G["getAllTags()"] --> F{"filter by criteria"}
+        F --> P["process matching tags"]
+        P --> A["tag.atoms() for each"]
+    end
+```
+
+Use cases: metrics collection, debugging, documentation generation.
 
-See [`dist/index.d.mts`](./dist/index.d.mts) for complete type definitions.
+## Types
 
 All types available under the `Lite` namespace:
 
@@ -229,9 +294,9 @@ ctx.data.getOrSetTag(countTag)  // 0 (uses default, now stored)
 ctx.data.getTag(countTag)       // 0 (now stored)
 ```
 
-### Hierarchical Data Lookup with seek()
+### Hierarchical Data Lookup with seekTag() (ADR-023)
 
-Each execution context has isolated data, but `seekTag()` traverses the parent chain:
+Tag dependencies (`tags.required()`, `tags.optional()`, `tags.all()`) use `seekTag()` internally to traverse the ExecutionContext parent chain. Tags from all sources are auto-populated into `ctx.data`:
 
 ```typescript
 const requestIdTag = tag<string>({ label: 'requestId' })
@@ -244,9 +309,9 @@ const middleware = flow({
 })
 
 const handler = flow({
-  factory: (ctx) => {
-    // seekTag() finds value from parent context
-    const reqId = ctx.data.seekTag(requestIdTag)  // 'req-123'
+  deps: { reqId: tags.required(requestIdTag) },
+  factory: (ctx, { reqId }) => {
+    // reqId === 'req-123' (found via seekTag from parent)
   }
 })
 ```
@@ -256,6 +321,122 @@ const handler = flow({
 | `getTag(tag)` | Local only | Per-exec isolated data |
 | `seekTag(tag)` | Local → parent → root | Cross-cutting concerns |
 | `setTag(tag, v)` | Local only | Always writes to current context |
+| `tags.required(tag)` | Uses `seekTag()` | Dependency injection |
+
+### Resolution Timing
+
+Tag dependencies resolve **once** at factory start. Direct `seekTag()` calls reflect runtime changes:
+
+```typescript
+const handler = flow({
+  deps: { userId: tags.required(userIdTag) },
+  factory: (ctx, { userId }) => {
+    ctx.data.setTag(userIdTag, 'changed')
+
+    console.log(userId)                      // Original (stable)
+    console.log(ctx.data.seekTag(userIdTag)) // 'changed' (dynamic)
+  }
+})
+```
+
+| Access | Resolution | Runtime Changes |
+|--------|------------|-----------------|
+| `deps: { x: tags.required(tag) }` | Once at start | Stable snapshot |
+| `ctx.data.seekTag(tag)` | Each call | Sees changes |
+
+## Automatic Garbage Collection
+
+Atoms are automatically released when they have no subscribers, preventing memory leaks in long-running applications.
+
+### How It Works
+
+```mermaid
+sequenceDiagram
+    participant Component
+    participant Controller
+    participant Scope
+    participant Timer
+
+    Component->>Controller: ctrl.on('resolved', callback)
+    Note over Controller: subscriberCount = 1
+    
+    Component->>Controller: unsubscribe()
+    Note over Controller: subscriberCount = 0
+    Controller->>Timer: schedule GC (3000ms)
+    
+    alt Resubscribe before timeout
+        Component->>Controller: ctrl.on('resolved', callback)
+        Controller->>Timer: cancel GC
+        Note over Controller: Atom stays alive
+    else Timeout fires
+        Timer->>Scope: release(atom)
+        Note over Scope: Cleanups run, cache cleared
+        Scope->>Scope: Check dependencies for cascading GC
+    end
+```
+
+### Configuration
+
+```typescript
+// Default: GC enabled with 3000ms grace period
+const scope = createScope()
+
+// Custom grace period (useful for tests)
+const scope = createScope({
+  gc: { graceMs: 100 }
+})
+
+// Disable GC entirely (preserves pre-1.11 behavior)
+const scope = createScope({
+  gc: { enabled: false }
+})
+```
+
+### Opt-Out with keepAlive
+
+Mark atoms that should never be automatically released:
+
+```typescript
+const configAtom = atom({
+  factory: () => loadConfig(),
+  keepAlive: true  // Never auto-released
+})
+```
+
+### Cascading Dependency Protection
+
+Dependencies are protected while dependents are mounted:
+
+```
+configAtom (keepAlive: true)
+    ↑
+dbAtom ←── userServiceAtom ←── [Component subscribes]
+```
+
+- `dbAtom` won't be GC'd while `userServiceAtom` is mounted
+- When component unmounts, `userServiceAtom` is GC'd after grace period
+- Then `dbAtom` becomes eligible for GC (no dependents)
+- `configAtom` stays alive due to `keepAlive: true`
+
+### React Strict Mode Compatibility
+
+The 3000ms default grace period handles React's double-mount behavior:
+
+```
+Mount (render 1):     subscribe    → count=1
+Unmount (cleanup 1):  unsubscribe  → count=0 → schedule GC
+Mount (render 2):     subscribe    → count=1 → CANCEL GC
+```
+
+The second mount always happens before the GC timer fires.
+
+### API Summary
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `gc.enabled` | `true` | Enable/disable automatic GC |
+| `gc.graceMs` | `3000` | Delay before releasing (ms) |
+| `atom.keepAlive` | `false` | Prevent auto-release for specific atoms |
 
 ## License