@wooksjs/event-core 0.6.5 → 0.7.0

package/dist/index.d.ts

@@ -1,153 +1,432 @@
-import { TConsoleBase, ProstoLogger, TProstoLoggerOptions } from '@prostojs/logger';
-import { AsyncLocalStorage } from 'node:async_hooks';
+/**
+ * Logger interface used throughout Wooks. Passed via `EventContextOptions`
+ * and accessed with `useLogger()`. Compatible with `@prostojs/logger` and
+ * most standard loggers.
+ */
+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;
+    /** Creates a child logger with a topic prefix (optional). */
+    topic?: (name?: string) => Logger;
+}
+/**
+ * A typed, writable context slot. Created with `key<T>(name)`.
+ * Use `ctx.set(k, value)` to store and `ctx.get(k)` to retrieve.
+ */
+interface Key<T> {
+    readonly _id: number;
+    readonly _name: string;
+    /** @internal Type brand — not used at runtime. */
+    readonly _T?: T;
+}
+/**
+ * A lazily-computed, read-only context slot. Created with `cached<T>(fn)`.
+ * The factory runs once per context on first `ctx.get()` call; the result is cached.
+ */
+interface Cached<T> {
+    readonly _id: number;
+    readonly _name: string;
+    readonly _fn: (ctx: EventContext) => T;
+    /** @internal Type brand — not used at runtime. */
+    readonly _T?: T;
+}
+/** Union type for any context slot — either a writable `Key` or a computed `Cached`. */
+type Accessor<T> = Key<T> | Cached<T>;
+/**
+ * Type-level marker used in `defineEventKind` schemas. Each `slot<T>()`
+ * becomes a typed `Key<T>` on the resulting `EventKind`. No runtime behavior.
+ */
+interface SlotMarker<T> {
+    /** @internal Type brand — not used at runtime. */
+    readonly _T?: T;
+}
+/**
+ * Declares the shape of an event type — its name and typed seed slots.
+ * Created with `defineEventKind(name, schema)`.
+ *
+ * Use `kind.keys.<prop>` to access typed context keys for each slot.
+ */
+interface EventKind<S extends Record<string, SlotMarker<any>>> {
+    /** Unique event kind name (e.g. `'http'`, `'cli'`). */
+    readonly name: string;
+    /** Typed context keys for each slot in the schema. */
+    readonly keys: {
+        [K in keyof S]: S[K] extends SlotMarker<infer V> ? Key<V> : never;
+    };
+    /** @internal Pre-computed entries for fast `seed()`. */
+    readonly _entries: Array<[string, Key<unknown>]>;
+}
+/**
+ * Extracts the seed values type for an `EventKind`. This is the object
+ * shape passed to `ctx.seed(kind, seeds)` or `createEventContext(opts, kind, seeds, fn)`.
+ */
+type EventKindSeeds<K> = K extends EventKind<infer S> ? {
+    [P in keyof S]: S[P] extends SlotMarker<infer V> ? V : never;
+} : never;
 
+/** Options for creating an {@link EventContext}. */
+interface EventContextOptions {
+    /** Logger instance available to all composables via `useLogger()`. */
+    logger: Logger;
+    /** Optional parent context. Enables transparent read-through and scoped writes. */
+    parent?: EventContext;
+}
 /**
- * Composable that provides a unique event ID for the current event context.
+ * Per-event container for typed slots, propagated via `AsyncLocalStorage`.
+ * Composables read and write data through `get`/`set` using typed `Key` or `Cached` accessors.
+ *
+ * Supports a parent chain: when a slot is not found locally, `get()` traverses
+ * parent contexts. `set()` writes to the nearest context that already holds the slot,
+ * or locally if the slot is new.
+ *
+ * Typically created by adapters (HTTP, CLI, etc.) — application code
+ * interacts with it indirectly through composables.
  *
  * @example
  * ```ts
- * const { getId } = useEventId()
- * console.log(getId()) // '550e8400-e29b-41d4-a716-446655440000'
+ * const ctx = new EventContext({ logger })
+ * ctx.set(userIdKey, '123')
+ * ctx.get(userIdKey) // '123'
  * ```
  */
-declare function useEventId(): {
-    getId: () => string;
-};
+declare class EventContext {
+    /** Logger instance for this event. */
+    readonly logger: Logger;
+    /** Parent context for read-through and scoped writes. */
+    readonly parent?: EventContext;
+    private slots;
+    constructor(options: EventContextOptions);
+    /**
+     * Reads a value from a typed slot.
+     * - For `Key<T>`: returns the previously `set` value, checking parent chain if not found locally.
+     * - For `Cached<T>`: returns a cached result from this context or any parent. If not found
+     *   anywhere, runs the factory on first access, caches locally, and returns the result.
+     *   Throws on circular dependencies. Errors are cached and re-thrown on subsequent access.
+     */
+    get<T>(accessor: Key<T> | Cached<T>): T;
+    /**
+     * Writes a value to a typed slot. If the slot already exists somewhere in the
+     * parent chain, the value is written there. Otherwise, it is written locally.
+     */
+    set<T>(key: Key<T> | Cached<T>, value: T): void;
+    /**
+     * Returns `true` if the slot has been set or computed in this context or any parent.
+     */
+    has(accessor: Accessor<any>): boolean;
+    /**
+     * Reads a value from a typed slot in this context only, ignoring parents.
+     * Same semantics as `get()` but without parent chain traversal.
+     */
+    getOwn<T>(accessor: Key<T> | Cached<T>): T;
+    /**
+     * Writes a value to a typed slot in this context only, ignoring parents.
+     */
+    setOwn<T>(key: Key<T> | Cached<T>, value: T): void;
+    /**
+     * Returns `true` if the slot has been set or computed in this context only.
+     */
+    hasOwn(accessor: Accessor<any>): boolean;
+    /**
+     * Seeds an event kind's slots into this context. Sets the event type key
+     * and populates all slots declared in the kind's schema.
+     *
+     * @param kind - The event kind (from `defineEventKind`)
+     * @param seeds - Values for each slot in the kind's schema
+     * @param fn - Optional callback to run after seeding (returned value is forwarded)
+     */
+    seed<S extends Record<string, any>>(kind: EventKind<S>, seeds: EventKindSeeds<EventKind<S>>): void;
+    seed<S extends Record<string, any>, R>(kind: EventKind<S>, seeds: EventKindSeeds<EventKind<S>>, fn: () => R): R;
+    /** Walk the parent chain looking for a set slot. Returns `undefined` if not found. */
+    private _findSlot;
+    /** Set value in the first context in the chain that has this slot. Returns true if found. */
+    private _setIfExists;
+}
 
 /**
- * Composable that provides a logger scoped to the current event context.
+ * Creates a typed, writable context slot. Use `ctx.set(k, value)` to store
+ * and `ctx.get(k)` to retrieve. Throws if read before being set.
+ *
+ * @param name - Debug label (shown in error messages, not used for lookup)
  *
- * @param topic - Optional topic name to create a sub-logger for.
  * @example
  * ```ts
- * const logger = useEventLogger('my-handler')
- * logger.log('processing request')
+ * const userIdKey = key<string>('userId')
+ * ctx.set(userIdKey, '123')
+ * ctx.get(userIdKey) // '123'
  * ```
  */
-declare function useEventLogger(topic?: string): TConsoleBase;
-
+declare function key<T>(name: string): Key<T>;
 /**
- * Composable that provides access to route parameters from the current event context.
+ * Creates a lazily-computed, read-only context slot. The factory runs once
+ * per `EventContext` on first `ctx.get(slot)` call; the result is cached
+ * for the context lifetime. Errors are also cached and re-thrown.
+ *
+ * @param fn - Factory receiving the current `EventContext`, returning the value to cache
  *
  * @example
  * ```ts
- * const { get, params } = useRouteParams<{ id: string }>()
- * console.log(get('id')) // '123'
- * console.log(params)    // { id: '123' }
+ * const parsedUrl = cached((ctx) => new URL(ctx.get(rawUrlKey)))
+ * // first call computes, subsequent calls return cached result
+ * ctx.get(parsedUrl)
  * ```
  */
-declare function useRouteParams<T extends object = Record<string, string | string[]>>(): {
-    params: T;
-    get: <K extends keyof T>(name: K) => T[K];
-};
+declare function cached<T>(fn: (ctx: EventContext) => T): Cached<T>;
 
-/** Data shape passed through logger transports, carrying the event ID. */
-interface TEventLoggerData {
-    eventId: string;
-}
-/** Logger scoped to a single event, automatically tagging messages with the event ID. */
-declare class EventLogger extends ProstoLogger<TEventLoggerData> {
-    constructor(eventId: string, opts?: TEventOptions['eventLogger']);
-}
-
-/** Base event shape shared by all event types. */
-interface TGenericEvent {
-    type: string;
-    logger?: EventLogger;
-    id?: string;
-}
-/** Empty record type used as a default generic parameter. */
-type TEmpty = Record<string, never>;
+/**
+ * Creates a parameterized cached computation. Maintains a `Map<K, V>` per
+ * event context — one cached result per unique key argument.
+ *
+ * @param fn - Factory receiving the lookup key and `EventContext`, returning the value to cache
+ * @returns A function `(key: K, ctx?: EventContext) => V` that computes on first call per key
+ *
+ * @example
+ * ```ts
+ * const parseCookie = cachedBy((name: string, ctx) => {
+ *   const raw = ctx.get(cookieHeaderKey)
+ *   return parseSingleCookie(raw, name)
+ * })
+ *
+ * parseCookie('session') // computed and cached for 'session'
+ * parseCookie('theme')   // computed and cached for 'theme'
+ * parseCookie('session') // returns cached result
+ * ```
+ */
+declare function cachedBy<K, V>(fn: (key: K, ctx: EventContext) => V): (key: K, ctx?: EventContext) => V;
 
-/** Configuration options for event context creation. */
-interface TEventOptions {
-    eventLogger?: {
-        topic?: string;
-    } & TProstoLoggerOptions<TEventLoggerData>;
-}
-/** Shape of the context store that holds event data, options, and route params. */
-interface TGenericContextStore<CustomEventType = TEmpty> {
-    event: CustomEventType & TGenericEvent;
-    options: TEventOptions;
-    parentCtx?: TGenericContextStore;
-    routeParams?: Record<string, string | string[]>;
-    _ended?: boolean;
-}
 /**
- * AsyncLocalStorage instance
+ * Type-level marker used inside `defineEventKind` schemas. Each `slot<T>()`
+ * becomes a typed `Key<T>` on the resulting `EventKind`. Has no runtime behavior.
  *
- * Use on your own risk only if you know what you're doing
+ * @example
+ * ```ts
+ * const httpKind = defineEventKind('http', {
+ *   req: slot<IncomingMessage>(),
+ *   response: slot<HttpResponse>(),
+ * })
+ * ```
  */
-declare const asyncStorage: AsyncLocalStorage<TGenericContextStore>;
+declare function slot<T>(): SlotMarker<T>;
 /**
- * Creates a new async event context and returns a runner function to execute callbacks within it.
+ * Declares a named event kind with typed seed slots. The returned object
+ * contains `keys` — typed accessors for reading seed values from context —
+ * and is passed to `ctx.seed(kind, seeds)` or `createEventContext()`.
+ *
+ * @param name - Unique event kind name (e.g. `'http'`, `'cli'`, `'workflow'`)
+ * @param schema - Object mapping slot names to `slot<T>()` markers
+ * @returns An `EventKind` with typed `keys` for context access
+ *
+ * @example
+ * ```ts
+ * const httpKind = defineEventKind('http', {
+ *   req: slot<IncomingMessage>(),
+ *   response: slot<HttpResponse>(),
+ * })
  *
- * @param data - Initial context store data including the event object and options.
- * @returns A function that runs a callback within the created async context.
+ * // Access typed seed values:
+ * const req = ctx.get(httpKind.keys.req) // IncomingMessage
+ * ```
  */
-declare function createAsyncEventContext<S = TEmpty, EventTypeToCreate = TEmpty>(data: S & TGenericContextStore<EventTypeToCreate>): <T>(cb: (...a: any[]) => T) => T;
+declare function defineEventKind<S extends Record<string, SlotMarker<any>>>(name: string, schema: S): EventKind<S>;
+
 /**
- * Retrieves the current async event context and returns helpers for reading/writing the store.
+ * Creates a composable with per-event caching. The factory runs once per
+ * `EventContext`; subsequent calls within the same event return the cached result.
+ *
+ * This is the recommended way to build composables in Wooks. All built-in
+ * composables (`useRequest`, `useResponse`, `useCookies`, etc.) are created with `defineWook`.
  *
- * @param expectedTypes - Optional event type(s) to validate the context against.
- * @throws If no event context exists or if the event type does not match.
+ * @param factory - Receives the `EventContext` and returns the composable's public API
+ * @returns A composable function `(ctx?: EventContext) => T`
+ *
+ * @example
+ * ```ts
+ * export const useCurrentUser = defineWook((ctx) => {
+ *   const { basicCredentials } = useAuthorization(ctx)
+ *   const username = basicCredentials()?.username
+ *   return {
+ *     username,
+ *     profile: async () => username ? await db.findUser(username) : null,
+ *   }
+ * })
+ *
+ * // In a handler — factory runs once, cached for the request:
+ * const { username, profile } = useCurrentUser()
+ * ```
  */
-declare function useAsyncEventContext<S = TEmpty, EventType = TEmpty>(expectedTypes?: string | string[]): TCtxHelpers<S & TGenericContextStore<EventType>>;
-/** Helper methods returned by `useAsyncEventContext` for interacting with the context store. */
-interface TCtxHelpers<T> {
-    getCtx: () => T;
-    store: <K extends keyof Required<T>>(key: K) => {
-        value: T[K];
-        hook: <K2 extends keyof Required<T>[K]>(key2: K2) => {
-            value: Required<T>[K][K2];
-            isDefined: boolean;
-        };
-        init: <K2 extends keyof Required<T>[K]>(key2: K2, getter: () => Required<Required<T>[K]>[K2]) => Required<Required<T>[K]>[K2];
-        set: <K2 extends keyof Required<T>[K]>(key2: K2, v: Required<T[K]>[K2]) => Required<T[K]>[K2];
-        get: <K2 extends keyof Required<T>[K]>(key2: K2) => Required<T>[K][K2] | undefined;
-        has: <K2 extends keyof Required<T>[K]>(key2: K2) => boolean;
-        del: <K2 extends keyof Required<T>[K]>(key2: K2) => void;
-        entries: () => Array<[string, unknown]>;
-        clear: () => void;
-    };
-    getStore: <K extends keyof T>(key: K) => T[K];
-    setStore: <K extends keyof T>(key: K, v: T[K]) => void;
-    setParentCtx: (parentCtx: unknown) => void;
-    hasParentCtx: () => boolean;
-    getParentCtx: <T2 = T>() => TCtxHelpers<T2>;
-}
+declare function defineWook<T>(factory: (ctx: EventContext) => T): (ctx?: EventContext) => T;
 
 /**
- * ContextInjector
+ * No-op base class for observability integration. Subclass and override
+ * `with()` / `hook()` to add tracing, metrics, or logging around event
+ * lifecycle points.
  *
- * Provides a way to inject context
- * Usefull when working with opentelemetry spans
+ * The default implementation simply calls the callback with no overhead.
+ * Replace via `replaceContextInjector()` to enable instrumentation.
  */
 declare class ContextInjector<N> {
-    with<T>(name: N, attributes: Record<string, string | number | boolean>, cb: TContextInjectorCallback<T>): T;
-    with<T>(name: N, cb: TContextInjectorCallback<T>): T;
+    /**
+     * Wraps a callback with optional named attributes for observability.
+     * Default implementation just calls `cb()` — override for tracing.
+     */
+    with<T>(name: N, attributes: Record<string, string | number | boolean>, cb: () => T): T;
+    with<T>(name: N, cb: () => T): T;
+    /**
+     * Hook called by adapters at specific lifecycle points (e.g., after route lookup).
+     * Default implementation is a no-op — override for observability.
+     */
     hook(_method: string, _name: 'Handler:not_found' | 'Handler:routed', _route?: string): void;
 }
-type TContextInjectorCallback<T> = () => T;
-/** Returns the current global `ContextInjector` instance. */
+/**
+ * Returns the current `ContextInjector` instance (default: no-op).
+ * Used internally by adapters to wrap lifecycle events.
+ */
 declare function getContextInjector<N = TContextInjectorHooks>(): ContextInjector<N>;
-/** Replaces the global `ContextInjector` instance (e.g., to integrate with OpenTelemetry). */
+/**
+ * Replaces the global `ContextInjector` with a custom implementation.
+ * Use this to integrate OpenTelemetry or other observability tools.
+ *
+ * @param newCi - Custom `ContextInjector` subclass instance
+ *
+ * @example
+ * ```ts
+ * class OtelInjector extends ContextInjector<string> {
+ *   with<T>(name: string, attrs: Record<string, any>, cb: () => T): T {
+ *     return tracer.startActiveSpan(name, (span) => {
+ *       span.setAttributes(attrs)
+ *       try { return cb() } finally { span.end() }
+ *     })
+ *   }
+ * }
+ * replaceContextInjector(new OtelInjector())
+ * ```
+ */
 declare function replaceContextInjector(newCi: ContextInjector<string>): void;
+/** Built-in hook names used by the framework. */
 type TContextInjectorHooks = 'Event:start';
 
+/** Context key for route parameters. Set by adapters after route matching. */
+declare const routeParamsKey: Key<Record<string, string | string[]>>;
+/** Context key for the event type name (e.g. `'http'`, `'cli'`). Set by `ctx.seed()`. */
+declare const eventTypeKey: Key<string>;
+
+/**
+ * Returns the route parameters for the current event. Works with HTTP
+ * routes, CLI commands, workflow steps — any adapter that sets `routeParamsKey`.
+ *
+ * @param ctx - Optional explicit context (defaults to `current()`)
+ * @returns Object with `params` (the full params record) and `get(name)` for typed access
+ *
+ * @example
+ * ```ts
+ * app.get('/users/:id', () => {
+ *   const { params, get } = useRouteParams<{ id: string }>()
+ *   console.log(get('id')) // typed as string
+ * })
+ * ```
+ */
+declare function useRouteParams<T extends Record<string, string | string[]> = Record<string, string | string[]>>(ctx?: EventContext): {
+    params: T;
+    get: <K extends keyof T>(name: K) => T[K];
+};
+/**
+ * Provides a unique, per-event identifier. The ID is a random UUID, generated
+ * lazily on first `getId()` call and cached for the event lifetime.
+ *
+ * @param ctx - Optional explicit context (defaults to `current()`)
+ *
+ * @example
+ * ```ts
+ * const { getId } = useEventId()
+ * logger.info(`Request ${getId()}`)
+ * ```
+ */
+declare function useEventId(ctx?: EventContext): {
+    getId: () => string;
+};
+
 /**
- * Attaches a getter/setter hook to a target object property via `Object.defineProperty`.
+ * Runs a callback with the given `EventContext` as the active context.
+ * All composables and `current()` calls inside `fn` will resolve to `ctx`.
+ *
+ * @param ctx - The event context to make active
+ * @param fn - Callback to execute within the context scope
+ * @returns The return value of `fn`
  *
- * @param target - The object to attach the hook to.
- * @param opts - Getter and optional setter for the hooked property.
- * @param name - Property name to hook (defaults to `'value'`).
+ * @example
+ * ```ts
+ * const ctx = new EventContext({ logger })
+ * run(ctx, () => {
+ *   // current() returns ctx here
+ *   const logger = useLogger()
+ * })
+ * ```
+ */
+declare function run<R>(ctx: EventContext, fn: () => R): R;
+/**
+ * Returns the active `EventContext` for the current async scope.
+ * Throws if called outside an event context (e.g., at module level).
+ *
+ * All composables use this internally. Prefer composables over direct `current()` access.
+ *
+ * @throws Error if no active event context exists
+ */
+declare function current(): EventContext;
+/**
+ * Returns the active `EventContext`, or `undefined` if none is active.
+ * Use this when context availability is uncertain (e.g., in code that may
+ * run both inside and outside an event handler).
+ */
+declare function tryGetCurrent(): EventContext | undefined;
+/**
+ * Returns the logger for the current event context.
+ *
+ * @param ctx - Optional explicit context (defaults to `current()`)
+ *
+ * @example
+ * ```ts
+ * const logger = useLogger()
+ * logger.info('Processing request')
+ * ```
+ */
+declare function useLogger(ctx?: EventContext): Logger;
+/**
+ * Creates a new `EventContext`, makes it the active context via
+ * `AsyncLocalStorage`, and runs `fn` inside it.
+ *
+ * @param options - Context options (must include `logger`)
+ * @param fn - Callback to execute within the new context
+ * @returns The return value of `fn`
+ *
+ * @example
+ * ```ts
+ * createEventContext({ logger }, () => {
+ *   // composables work here
+ * })
+ * ```
+ */
+declare function createEventContext<R>(options: EventContextOptions, fn: () => R): R;
+/**
+ * Creates a new `EventContext` with an event kind, seeds the kind's slots,
+ * and runs `fn` inside the context.
+ *
+ * @param options - Context options (must include `logger`)
+ * @param kind - Event kind (from `defineEventKind`)
+ * @param seeds - Seed values for the event kind's slots
+ * @param fn - Callback to execute within the new context
+ * @returns The return value of `fn`
+ *
+ * @example
+ * ```ts
+ * const httpKind = defineEventKind('http', { req: slot<IncomingMessage>() })
+ *
+ * createEventContext({ logger }, httpKind, { req: incomingMessage }, () => {
+ *   const req = current().get(httpKind.keys.req)
+ * })
+ * ```
  */
-declare function attachHook<V = unknown, T extends object | Function = object, P extends PropertyKey = 'value'>(target: T, opts: {
-    get: () => V | undefined;
-    set?: (value: V) => void;
-}, name?: P): T & THook<V, P>;
-/** A record type representing a hooked property on an object. */
-type THook<T = string, K extends PropertyKey = 'value'> = Record<K, T>;
+declare function createEventContext<S extends Record<string, any>, R>(options: EventContextOptions, kind: EventKind<S>, seeds: EventKindSeeds<EventKind<S>>, fn: () => R): R;
 
-export { ContextInjector, EventLogger, asyncStorage, attachHook, createAsyncEventContext, getContextInjector, replaceContextInjector, useAsyncEventContext, useEventId, useEventLogger, useRouteParams };
-export type { TContextInjectorHooks, TCtxHelpers, TEmpty, TEventLoggerData, TEventOptions, TGenericContextStore, TGenericEvent, THook };
+export { ContextInjector, EventContext, cached, cachedBy, createEventContext, current, defineEventKind, defineWook, eventTypeKey, getContextInjector, key, replaceContextInjector, routeParamsKey, run, slot, tryGetCurrent, useEventId, useLogger, useRouteParams };
+export type { Accessor, Cached, EventContextOptions, EventKind, EventKindSeeds, Key, Logger, SlotMarker, TContextInjectorHooks };