@wooksjs/event-core 0.7.1 → 0.7.3

package/dist/index.cjs

@@ -251,9 +251,9 @@ var ContextInjector = class {
 	*/
 	hook(_method, _name, _route) {}
 };
-let ci = new ContextInjector();
+let ci = null;
 /**
-* Returns the current `ContextInjector` instance (default: no-op).
+* Returns the current `ContextInjector` instance, or `null` if none has been installed.
 * Used internally by adapters to wrap lifecycle events.
 */
 function getContextInjector() {
@@ -281,12 +281,19 @@ function getContextInjector() {
 function replaceContextInjector(newCi) {
 	ci = newCi;
 }
+/**
+* Resets the global `ContextInjector` back to `null` (no-op default).
+* Useful for tests or when disabling instrumentation.
+*/
+function resetContextInjector() {
+	ci = null;
+}
 
 //#endregion
 //#region packages/event-core/src/storage.ts
 const STORAGE_KEY = Symbol.for("wooks.core.asyncStorage");
 const VERSION_KEY = Symbol.for("wooks.core.asyncStorage.version");
-const CURRENT_VERSION = "0.7.0";
+const CURRENT_VERSION = "0.7.2";
 const _g = globalThis;
 if (_g[STORAGE_KEY]) {
 	if (_g[VERSION_KEY] !== CURRENT_VERSION) throw new Error(`[wooks] Incompatible versions of @wooksjs/event-core detected: existing v${_g[VERSION_KEY]}, loading v${CURRENT_VERSION}. All packages must use the same @wooksjs/event-core version.`);
@@ -355,7 +362,8 @@ function createEventContext(options, kindOrFn, seedsOrUndefined, maybeFn) {
 	if (typeof kindOrFn === "function") return run(ctx, kindOrFn);
 	return run(ctx, () => {
 		ctx.seed(kindOrFn, seedsOrUndefined);
-		return getContextInjector().with("Event:start", { eventType: kindOrFn.name }, maybeFn);
+		const ci$1 = getContextInjector();
+		return ci$1 ? ci$1.with("Event:start", { eventType: kindOrFn.name }, maybeFn) : maybeFn();
 	});
 }
 
@@ -530,6 +538,7 @@ exports.eventTypeKey = eventTypeKey;
 exports.getContextInjector = getContextInjector;
 exports.key = key;
 exports.replaceContextInjector = replaceContextInjector;
+exports.resetContextInjector = resetContextInjector;
 exports.routeParamsKey = routeParamsKey;
 exports.run = run;
 exports.slot = slot;

package/dist/index.d.ts

@@ -279,10 +279,10 @@ declare class ContextInjector<N> {
     hook(_method: string, _name: 'Handler:not_found' | 'Handler:routed', _route?: string): void;
 }
 /**
- * Returns the current `ContextInjector` instance (default: no-op).
+ * Returns the current `ContextInjector` instance, or `null` if none has been installed.
  * Used internally by adapters to wrap lifecycle events.
  */
-declare function getContextInjector<N = TContextInjectorHooks>(): ContextInjector<N>;
+declare function getContextInjector<N = TContextInjectorHooks>(): ContextInjector<N> | null;
 /**
  * Replaces the global `ContextInjector` with a custom implementation.
  * Use this to integrate OpenTelemetry or other observability tools.
@@ -303,6 +303,11 @@ declare function getContextInjector<N = TContextInjectorHooks>(): ContextInjecto
  * ```
  */
 declare function replaceContextInjector(newCi: ContextInjector<string>): void;
+/**
+ * Resets the global `ContextInjector` back to `null` (no-op default).
+ * Useful for tests or when disabling instrumentation.
+ */
+declare function resetContextInjector(): void;
 /** Built-in hook names used by the framework. */
 type TContextInjectorHooks = 'Event:start';
 
@@ -399,6 +404,9 @@ declare function useLogger(ctx?: EventContext): Logger;
  * @param fn - Callback to execute within the new context
  * @returns The return value of `fn`
  *
+ * The kindless overload is a convenience for tests that need a context scope
+ * without declaring an event kind. Production code should always provide a kind.
+ *
  * @example
  * ```ts
  * createEventContext({ logger }, () => {
@@ -428,5 +436,5 @@ declare function createEventContext<R>(options: EventContextOptions, fn: () => R
  */
 declare function createEventContext<S extends Record<string, any>, R>(options: EventContextOptions, kind: EventKind<S>, seeds: EventKindSeeds<EventKind<S>>, fn: () => R): R;
 
-export { ContextInjector, EventContext, cached, cachedBy, createEventContext, current, defineEventKind, defineWook, eventTypeKey, getContextInjector, key, replaceContextInjector, routeParamsKey, run, slot, tryGetCurrent, useEventId, useLogger, useRouteParams };
+export { ContextInjector, EventContext, cached, cachedBy, createEventContext, current, defineEventKind, defineWook, eventTypeKey, getContextInjector, key, replaceContextInjector, resetContextInjector, routeParamsKey, run, slot, tryGetCurrent, useEventId, useLogger, useRouteParams };
 export type { Accessor, Cached, EventContextOptions, EventKind, EventKindSeeds, Key, Logger, SlotMarker, TContextInjectorHooks };

package/dist/index.mjs

@@ -228,9 +228,9 @@ var ContextInjector = class {
 	*/
 	hook(_method, _name, _route) {}
 };
-let ci = new ContextInjector();
+let ci = null;
 /**
-* Returns the current `ContextInjector` instance (default: no-op).
+* Returns the current `ContextInjector` instance, or `null` if none has been installed.
 * Used internally by adapters to wrap lifecycle events.
 */
 function getContextInjector() {
@@ -258,12 +258,19 @@ function getContextInjector() {
 function replaceContextInjector(newCi) {
 	ci = newCi;
 }
+/**
+* Resets the global `ContextInjector` back to `null` (no-op default).
+* Useful for tests or when disabling instrumentation.
+*/
+function resetContextInjector() {
+	ci = null;
+}
 
 //#endregion
 //#region packages/event-core/src/storage.ts
 const STORAGE_KEY = Symbol.for("wooks.core.asyncStorage");
 const VERSION_KEY = Symbol.for("wooks.core.asyncStorage.version");
-const CURRENT_VERSION = "0.7.0";
+const CURRENT_VERSION = "0.7.2";
 const _g = globalThis;
 if (_g[STORAGE_KEY]) {
 	if (_g[VERSION_KEY] !== CURRENT_VERSION) throw new Error(`[wooks] Incompatible versions of @wooksjs/event-core detected: existing v${_g[VERSION_KEY]}, loading v${CURRENT_VERSION}. All packages must use the same @wooksjs/event-core version.`);
@@ -332,7 +339,8 @@ function createEventContext(options, kindOrFn, seedsOrUndefined, maybeFn) {
 	if (typeof kindOrFn === "function") return run(ctx, kindOrFn);
 	return run(ctx, () => {
 		ctx.seed(kindOrFn, seedsOrUndefined);
-		return getContextInjector().with("Event:start", { eventType: kindOrFn.name }, maybeFn);
+		const ci$1 = getContextInjector();
+		return ci$1 ? ci$1.with("Event:start", { eventType: kindOrFn.name }, maybeFn) : maybeFn();
 	});
 }
 
@@ -495,4 +503,4 @@ function useEventId(ctx) {
 }
 
 //#endregion
-export { ContextInjector, EventContext, cached, cachedBy, createEventContext, current, defineEventKind, defineWook, eventTypeKey, getContextInjector, key, replaceContextInjector, routeParamsKey, run, slot, tryGetCurrent, useEventId, useLogger, useRouteParams };
+export { ContextInjector, EventContext, cached, cachedBy, createEventContext, current, defineEventKind, defineWook, eventTypeKey, getContextInjector, key, replaceContextInjector, resetContextInjector, routeParamsKey, run, slot, tryGetCurrent, useEventId, useLogger, useRouteParams };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wooksjs/event-core",
-  "version": "0.7.1",
+  "version": "0.7.3",
   "description": "@wooksjs/event-core",
   "keywords": [
     "composables",

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

@@ -46,5 +46,6 @@ import {
   ContextInjector,
   getContextInjector,
   replaceContextInjector,
+  resetContextInjector,
 } from '@wooksjs/event-core'
 ```

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

@@ -175,39 +175,52 @@ This prevents subtle bugs from multiple context stores.
 
 ### Pattern: Custom adapter
 
-Build an adapter that creates contexts and runs handlers:
+Build an adapter that creates contexts and runs handlers. Each adapter exports a **context factory** that hardcodes the kind and delegates to `createEventContext`:
 
 ```ts
-import { EventContext, defineEventKind, slot, run } from '@wooksjs/event-core'
+import { createEventContext, defineEventKind, slot } from '@wooksjs/event-core'
+import type { EventContextOptions, EventKindSeeds } from '@wooksjs/event-core'
 
 const myKind = defineEventKind('my-event', {
   data: slot<unknown>(),
 })
 
-function handleEvent(data: unknown, handler: () => unknown, parent?: EventContext) {
-  const ctx = new EventContext({ logger: console, parent })
-  ctx.seed(myKind, { data })
-  return run(ctx, handler)
+// Context factory — same signature as createEventContext, minus the kind
+export function createMyEventContext<R>(
+  options: EventContextOptions,
+  seeds: EventKindSeeds<typeof myKind>,
+  fn: () => R,
+): R {
+  return createEventContext(options, myKind, seeds, fn)
+}
+
+// Usage in the adapter
+function handleEvent(data: unknown, handler: () => unknown) {
+  return createMyEventContext({ logger: console }, { data }, handler)
 }
 ```
 
+All built-in adapters follow this pattern: `createHttpContext`, `createCliContext`, `createWsConnectionContext`, `createWsMessageContext`, `createWfContext`, `resumeWfContext`.
+
 ### Pattern: Child contexts with parent links
 
-Instead of attaching multiple kinds to a single context, create child contexts with parent links. Each child sees its own data plus everything in the parent chain:
+Instead of attaching multiple kinds to a single context, create child contexts by passing `parent` in the options. Each child sees its own data plus everything in the parent chain:
 
 ```ts
 createEventContext({ logger }, httpKind, httpSeeds, () => {
   const parentCtx = current()
 
-  // Create a child context for workflow-specific data
-  const childCtx = new EventContext({ logger, parent: parentCtx })
-  childCtx.seed(workflowKind, { triggerId: 'deploy-42', payload })
-
-  run(childCtx, () => {
-    // Both HTTP and workflow composables work
-    const { method } = useRequest() // found via parent chain
-    const { triggerId } = useWorkflow() // found locally
-  })
+  // Create a child context linked to the HTTP parent
+  createEventContext(
+    { logger, parent: parentCtx },
+    workflowKind,
+    { triggerId: 'deploy-42', payload },
+    () => {
+      // Both HTTP and workflow composables work
+      const { method } = useRequest() // found via parent chain
+      const { triggerId } = useWorkflow() // found locally
+    },
+  )
 })
 ```
 
@@ -234,10 +247,10 @@ const log = ctx.logger
 
 ## ContextInjector (observability)
 
-`ContextInjector` is a hook point for observability tools (OpenTelemetry, etc.). The default implementation is a no-op pass-through.
+`ContextInjector` is a hook point for observability tools (OpenTelemetry, etc.). No injector is installed by default — `getContextInjector()` returns `null`, so all adapters run with zero overhead until one is installed.
 
 ```ts
-import { ContextInjector, replaceContextInjector } from '@wooksjs/event-core'
+import { ContextInjector, replaceContextInjector, resetContextInjector } from '@wooksjs/event-core'
 
 class OtelInjector extends ContextInjector<string> {
   with<T>(name: string, attributes: Record<string, any>, cb: () => T): T {
@@ -246,9 +259,14 @@ class OtelInjector extends ContextInjector<string> {
 }
 
 replaceContextInjector(new OtelInjector())
+
+// To disable instrumentation later:
+resetContextInjector()
 ```
 
-The injector's `with()` method wraps `createEventContext` callbacks and handler invocations.
+The injector's `with()` method wraps `createEventContext` callbacks. All adapters (HTTP, CLI, WS, WF) route through `createEventContext`, so installing an injector automatically instruments every event type.
+
+Adapter callbacks **return their result** (sync value or Promise), so `with()` can track async handler completion for span lifecycle. A `TracingInjector` can detect thenable returns and attach `.then()/.catch()` to end spans when the handler settles — no separate `onEnd()` hook needed.
 
 ## Best Practices
 

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

@@ -62,9 +62,10 @@ Every event (HTTP request, CLI invocation, workflow step) gets its own `EventCon
 | `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)                                                                          |
+| `ContextInjector`                             | class      | Observability hook point (OpenTelemetry etc.). Defaults to `null` — zero overhead until installed.               |
+| `getContextInjector()`                        | function   | Get current injector (returns `null` when none installed)                                                        |
+| `replaceContextInjector(ci)`                  | function   | Install a custom injector (e.g. with OTel spans)                                                                 |
+| `resetContextInjector()`                      | function   | Reset injector back to `null` (disables instrumentation)                                                         |
 
 ## Types