@wooksjs/event-core 0.6.5 → 0.7.0

package/skills/wooksjs-event-core/core.md

@@ -0,0 +1,91 @@
+# Core concepts & setup — @wooksjs/event-core
+
+> Package overview, mental model, installation, and exports map.
+
+## What it is
+
+`@wooksjs/event-core` is the context engine underneath all Wooks adapters. It provides:
+
+- **Typed slots** (`key<T>`) — explicit get/set per event
+- **Lazy cached computations** (`cached`, `cachedBy`) — compute once, cache for event lifetime
+- **Event kind schemas** (`defineEventKind`) — typed seed bundles for domain-specific data
+- **Composable factories** (`defineWook`) — per-event cached functions, resolved via `AsyncLocalStorage`
+- **Async propagation** (`run`, `current`) — context available anywhere in the call stack
+
+## Installation
+
+```bash
+pnpm add @wooksjs/event-core
+```
+
+Typically you don't install this directly — it's a dependency of `@wooksjs/event-http`, `@wooksjs/event-cli`, etc. Install it when building custom adapters or composables that don't depend on a specific event type.
+
+## Mental model
+
+```
+EventContext = Map<number, unknown>  (flat, typed via key/cached accessors)
+    │
+    ├── key<T>(name)         → writable slot, explicit set/get
+    ├── cached<T>(fn)        → read-only slot, lazy, computed on first access
+    ├── cachedBy<K,V>(fn)    → like cached but keyed — one result per unique argument
+    │
+    ├── defineEventKind(name, schema)  → groups slots into a named seed bundle
+    │       └── ctx.seed(kind, seeds)  → populates slots from seeds
+    │
+    ├── defineWook(factory)  → creates a composable: factory runs once per context, cached
+    │       └── useX()       → resolves from AsyncLocalStorage, returns cached result
+    │
+    └── parent chain         → optional parent: EventContext link
+            ├── get/set/has  → traverse local → parent → grandparent → ...
+            └── getOwn/setOwn/hasOwn → local-only (no traversal)
+```
+
+Every event (HTTP request, CLI invocation, workflow step) gets its own `EventContext`. The context is propagated via `AsyncLocalStorage` — composables resolve it implicitly.
+
+## Exports
+
+| Export                                        | Kind       | Purpose                                                                                                          |
+| --------------------------------------------- | ---------- | ---------------------------------------------------------------------------------------------------------------- |
+| `key<T>(name)`                                | primitive  | Writable typed slot                                                                                              |
+| `cached<T>(fn)`                               | primitive  | Lazy computed slot, cached per event                                                                             |
+| `cachedBy<K,V>(fn)`                           | primitive  | Lazy computed slot, cached per key per event                                                                     |
+| `slot<T>()`                                   | primitive  | Type marker for `defineEventKind` schemas                                                                        |
+| `defineEventKind(name, schema)`               | primitive  | Typed seed bundle definition                                                                                     |
+| `defineWook<T>(factory)`                      | primitive  | Composable factory with per-event caching                                                                        |
+| `EventContext`                                | class      | Per-event context container (`get`, `set`, `has`, `seed`, `getOwn`, `setOwn`, `hasOwn`; optional `parent` chain) |
+| `run(ctx, fn)`                                | function   | Execute `fn` within `ctx` via `AsyncLocalStorage`                                                                |
+| `current()`                                   | function   | Get active `EventContext` (throws if none)                                                                       |
+| `tryGetCurrent()`                             | function   | Get active `EventContext` or `undefined`                                                                         |
+| `createEventContext(opts, [kind, seeds,] fn)` | function   | Create context (with optional parent) + optional seed + run                                                      |
+| `useLogger(ctx?)`                             | composable | Shorthand for `(ctx ?? current()).logger`                                                                        |
+| `useRouteParams(ctx?)`                        | composable | Route parameters from router                                                                                     |
+| `useEventId(ctx?)`                            | composable | Lazy UUID per event                                                                                              |
+| `routeParamsKey`                              | key        | Standard key for route params                                                                                    |
+| `eventTypeKey`                                | key        | Standard key for event type name                                                                                 |
+| `ContextInjector`                             | class      | Observability hook point (OpenTelemetry etc.)                                                                    |
+| `getContextInjector()`                        | function   | Get current injector                                                                                             |
+| `replaceContextInjector(ci)`                  | function   | Replace injector (e.g. with OTel spans)                                                                          |
+
+## Types
+
+```ts
+interface Logger {
+  info(msg: string, ...args: unknown[]): void
+  warn(msg: string, ...args: unknown[]): void
+  error(msg: string, ...args: unknown[]): void
+  debug(msg: string, ...args: unknown[]): void
+  topic?: (name?: string) => Logger
+}
+
+interface Key<T> { readonly _id: number; readonly _name: string }
+interface Cached<T> { readonly _id: number; readonly _name: string; readonly _fn: (ctx: EventContext) => T }
+type Accessor<T> = Key<T> | Cached<T>
+interface SlotMarker<T> {}  // phantom type marker
+
+type EventKind<S extends Record<string, SlotMarker<any>>> = {
+  readonly name: string
+  readonly keys: { [K in keyof S]: S[K] extends SlotMarker<infer V> ? Key<V> : never }
+  readonly _entries: Array<[string, Key<unknown>]> // internal, used by ctx.seed()
+}
+type EventKindSeeds<K> = // maps SlotMarker<V> → V for each property
+```

package/skills/wooksjs-event-core/primitives.md

@@ -0,0 +1,213 @@
+# Primitives — @wooksjs/event-core
+
+> `key`, `cached`, `cachedBy`, `slot`, `defineEventKind` — the building blocks for typed per-event state.
+
+## Concepts
+
+All state lives in `EventContext` — a flat `Map<number, unknown>`. Primitives give you typed accessors into that map:
+
+- **`key<T>`** — a writable slot. You `set` and `get` values explicitly.
+- **`cached<T>`** — a read-only slot. Computed lazily on first `get`, cached for the event lifetime.
+- **`cachedBy<K,V>`** — like `cached`, but parameterized. One cached result per unique key.
+- **`slot<T>`** / **`defineEventKind`** — group multiple keys into a typed seed bundle that can be seeded into a context in one call.
+
+All primitives are defined at module level (not per request). They produce lightweight descriptors with auto-incremented numeric IDs.
+
+## API Reference
+
+### `key<T>(name: string): Key<T>`
+
+Creates a writable typed slot. The `name` is for debugging only — lookup is by numeric ID.
+
+```ts
+import { key, EventContext } from '@wooksjs/event-core'
+
+const userId = key<string>('userId')
+
+const ctx = new EventContext({ logger })
+ctx.set(userId, 'u-123')
+ctx.get(userId) // 'u-123' (typed as string)
+```
+
+Throws `Key "name" is not set` if `get` is called before `set`.
+
+Supports `undefined`, `null`, `0`, `''`, `false` — all falsy values are stored correctly.
+
+### `cached<T>(fn: (ctx: EventContext) => T): Cached<T>`
+
+Creates a lazy computed slot. The function runs on first `ctx.get()` and the result is cached.
+
+```ts
+import { cached, key } from '@wooksjs/event-core'
+
+const url = key<string>('url')
+const parsedQuery = cached((ctx) => {
+  return Object.fromEntries(new URL(ctx.get(url)).searchParams)
+})
+
+// First access: computes and caches
+ctx.get(parsedQuery)
+// Second access: returns cached result, fn never runs again
+ctx.get(parsedQuery)
+```
+
+**Async:** The Promise itself is cached — concurrent access deduplicates:
+
+```ts
+const rawBody = cached(async (ctx) => {
+  const chunks: Buffer[] = []
+  for await (const chunk of ctx.get(reqStream)) chunks.push(chunk)
+  return Buffer.concat(chunks)
+})
+
+// Two concurrent calls → one stream read, one Promise
+const [a, b] = await Promise.all([ctx.get(rawBody), ctx.get(rawBody)])
+a === b // true
+```
+
+**Errors** are cached too — a failed computation throws the same error on subsequent access without re-executing.
+
+**Circular dependencies** are detected and throw immediately: `Circular dependency detected for "name"`.
+
+### `cachedBy<K, V>(fn: (key: K, ctx: EventContext) => V): (key: K, ctx?: EventContext) => V`
+
+Like `cached`, but parameterized. Maintains a `Map<K, V>` per context — each unique key computes once.
+
+```ts
+import { cachedBy } from '@wooksjs/event-core'
+
+const getCookie = cachedBy((name: string, ctx) => {
+  const header = ctx.get(rawHeaders)['cookie'] ?? ''
+  const match = header.match(new RegExp(`(?:^|;\\s*)${name}=([^;]*)`))
+  return match?.[1]
+})
+
+getCookie('session') // extracts + caches
+getCookie('session') // cache hit
+getCookie('theme') // extracts + caches (different key)
+```
+
+The returned function accepts an optional `ctx` parameter to skip `AsyncLocalStorage` lookup:
+
+```ts
+const ctx = current()
+getCookie('session', ctx) // explicit context, no ALS overhead
+```
+
+### `slot<T>(): SlotMarker<T>`
+
+A phantom type marker used in `defineEventKind` schemas. Has no runtime behavior — it only carries the type `T`.
+
+```ts
+import { slot } from '@wooksjs/event-core'
+
+const schema = {
+  method: slot<string>(),
+  path: slot<string>(),
+  req: slot<IncomingMessage>(),
+}
+```
+
+### `defineEventKind<S>(name: string, schema: S): EventKind<S>`
+
+Groups slots into a named kind. Creates a `Key<T>` for each slot in the schema, namespaced under the kind name.
+
+```ts
+import { defineEventKind, slot } from '@wooksjs/event-core'
+
+const httpKind = defineEventKind('http', {
+  method: slot<string>(),
+  path: slot<string>(),
+  rawHeaders: slot<Record<string, string>>(),
+})
+
+// httpKind.name === 'http'
+// httpKind.keys.method is Key<string> with _name 'http.method'
+// httpKind.keys.path is Key<string> with _name 'http.path'
+```
+
+Seed into a context with `ctx.seed()`:
+
+```ts
+ctx.seed(httpKind, {
+  method: 'POST',
+  path: '/api/users',
+  rawHeaders: { 'content-type': 'application/json' },
+})
+
+ctx.get(httpKind.keys.method) // 'POST'
+```
+
+Multiple kinds can be layered via **parent-linked contexts** instead of seeding everything into one context:
+
+```ts
+const parentCtx = new EventContext({ logger })
+parentCtx.seed(httpKind, { method: 'POST', path: '/webhook', rawHeaders: {} })
+
+const childCtx = new EventContext({ logger, parent: parentCtx })
+childCtx.seed(workflowKind, { triggerId: 'deploy-42', payload: { env: 'prod' } })
+
+// Child sees both its own and parent data via the parent chain
+childCtx.get(httpKind.keys.method) // 'POST' (from parent)
+childCtx.get(workflowKind.keys.triggerId) // 'deploy-42' (local)
+```
+
+## Common Patterns
+
+### Pattern: Derived computation chain
+
+Cached values can depend on keys and on other cached values. The dependency graph is resolved lazily.
+
+```ts
+const base = key<number>('base')
+const doubled = cached((ctx) => ctx.get(base) * 2)
+const quadrupled = cached((ctx) => ctx.get(doubled) * 2)
+
+ctx.set(base, 5)
+ctx.get(quadrupled) // 20 — computes doubled (10) then quadrupled (20)
+```
+
+### Pattern: Library extension via cached slots
+
+Libraries export `cached` slots for other libraries to depend on:
+
+```ts
+// http-context library
+export const rawBody = cached(async (ctx) => readStream(ctx.get(httpKind.keys.req)))
+
+// body-parser library (depends on http-context)
+import { rawBody } from 'http-context'
+
+const parsedBody = cached(async (ctx) => {
+  const buf = await ctx.get(rawBody)
+  return JSON.parse(buf.toString())
+})
+```
+
+### Pattern: Sparse access with cachedBy
+
+When the data source is large but your app reads few entries:
+
+```ts
+// Parses only requested cookies, not all 40
+const getCookie = cachedBy((name: string, ctx) => {
+  const header = ctx.get(rawHeaders)['cookie'] ?? ''
+  const match = header.match(new RegExp(`(?:^|;\\s*)${name}=([^;]*)`))
+  return match?.[1]
+})
+```
+
+## Best Practices
+
+- Define keys/cached/cachedBy at **module level**, not inside handlers — they're descriptors, not values
+- Use `cached` for anything computed from request data — it guarantees single computation
+- Use `cachedBy` when computation varies by a parameter (cookie name, header name, etc.)
+- Async `cached` values cache the Promise — safe for concurrent access
+- Errors from `cached` are also cached — a failing computation won't retry
+
+## Gotchas
+
+- `key` throws on `get` if never `set` — use `ctx.has(k)` to check first
+- `cached` functions receive `ctx` as parameter — don't call `current()` inside them, use the provided `ctx`
+- Circular `cached` dependencies throw immediately — the cycle is detected at runtime
+- `cachedBy` uses a `Map` — keys are compared by identity (`===`), not deep equality