@moostjs/otel 0.5.33 → 0.6.0

package/README.md

@@ -1 +1,41 @@
-# @moostjs/otel
+# @moostjs/otel
+
+OpenTelemetry integration for [Moost](https://moost.org). Provides automatic tracing for event handlers, custom span creation, metrics collection, and trace propagation. Works by replacing Moost's context injector with a span-aware implementation.
+
+## Installation
+
+```bash
+npm install @moostjs/otel @opentelemetry/api @opentelemetry/sdk-trace-base
+```
+
+## Quick Start
+
+```ts
+import { enableOtelForMoost } from '@moostjs/otel'
+
+// Call before creating your Moost app
+enableOtelForMoost()
+```
+
+## Composables
+
+- `useOtelContext()` — Access tracing utilities (span, propagation headers, custom attributes).
+- `useTrace()` — Get the OpenTelemetry `trace` API.
+- `useSpan()` — Get the current event's root span.
+- `useOtelPropagation()` — Get W3C trace-context headers for outgoing requests.
+
+## Decorators
+
+- `@OtelIgnoreSpan()` — Suppress span export for a controller or handler.
+- `@OtelIgnoreMeter()` — Suppress metrics for a controller or handler.
+
+## Span Processors
+
+- `MoostBatchSpanProcessor` — Batch processor that respects `@OtelIgnoreSpan()`.
+- `MoostSimpleSpanProcessor` — Simple processor that respects `@OtelIgnoreSpan()`.
+
+## [Official Documentation](https://moost.org/moost/otel)
+
+## License
+
+MIT

package/dist/index.cjs

@@ -6,11 +6,11 @@ var __getOwnPropNames = Object.getOwnPropertyNames;
 var __getProtoOf = Object.getPrototypeOf;
 var __hasOwnProp = Object.prototype.hasOwnProperty;
 var __copyProps = (to, from, except, desc) => {
-	if (from && typeof from === "object" || typeof from === "function") for (var keys = __getOwnPropNames(from), i = 0, n = keys.length, key; i < n; i++) {
-		key = keys[i];
-		if (!__hasOwnProp.call(to, key) && key !== except) __defProp(to, key, {
-			get: ((k) => from[k]).bind(null, key),
-			enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable
+	if (from && typeof from === "object" || typeof from === "function") for (var keys = __getOwnPropNames(from), i = 0, n = keys.length, key$1; i < n; i++) {
+		key$1 = keys[i];
+		if (!__hasOwnProp.call(to, key$1) && key$1 !== except) __defProp(to, key$1, {
+			get: ((k) => from[k]).bind(null, key$1),
+			enumerable: !(desc = __getOwnPropDesc(from, key$1)) || desc.enumerable
 		});
 	}
 	return to;
@@ -23,18 +23,34 @@ var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__ge
 //#endregion
 const __opentelemetry_api = __toESM(require("@opentelemetry/api"));
 const moost = __toESM(require("moost"));
+const __moostjs_event_http = __toESM(require("@moostjs/event-http"));
 const __opentelemetry_sdk_trace_base = __toESM(require("@opentelemetry/sdk-trace-base"));
 
 //#region packages/otel/src/context.ts
+/** Event context key storing the root OpenTelemetry span. */ const otelSpanKey = (0, moost.key)("otel.span");
+/** Event context key storing the resolved route path for span naming. */ const otelRouteKey = (0, moost.key)("otel.route");
+/** Event context key storing the event start time (epoch ms) for duration metrics. */ const otelStartTimeKey = (0, moost.key)("otel.startTime");
+/** Event context key storing custom span attributes set via `useOtelContext().customSpanAttr()`. */ const customSpanAttrsKey = (0, moost.key)("customSpanAttrs");
+/** Event context key storing custom metric attributes set via `useOtelContext().customMetricAttr()`. */ const customMetricAttrsKey = (0, moost.key)("customMetricAttrs");
 const spanStack = [];
-function useOtelContext() {
-	const eventContext = (0, moost.useAsyncEventContext)();
-	const store = eventContext.store("otel");
-	const csa = eventContext.store("customSpanAttrs");
-	const cma = eventContext.store("customMetricAttrs");
-	const customSpanAttr = (name, value) => csa.set(name, value);
-	const customMetricAttr = (name, value) => cma.set(name, value);
-	const getSpan = () => store.get("span");
+/**
+* Provides OpenTelemetry tracing utilities scoped to the current event.
+* Must be called within an active event handler context.
+*
+* @returns Tracing utilities including span access, propagation headers, and custom attributes.
+*/ function useOtelContext(ctx) {
+	const _ctx = ctx || (0, moost.current)();
+	const customSpanAttr = (name, value) => {
+		const attrs = _ctx.has(customSpanAttrsKey) ? _ctx.get(customSpanAttrsKey) : {};
+		attrs[name] = value;
+		_ctx.set(customSpanAttrsKey, attrs);
+	};
+	const customMetricAttr = (name, value) => {
+		const attrs = _ctx.has(customMetricAttrsKey) ? _ctx.get(customMetricAttrsKey) : {};
+		attrs[name] = value;
+		_ctx.set(customMetricAttrsKey, attrs);
+	};
+	const getSpan = () => _ctx.has(otelSpanKey) ? _ctx.get(otelSpanKey) : void 0;
 	const getSpanContext = () => {
 		const span = getSpan();
 		if (span) return span.spanContext();
@@ -75,19 +91,23 @@ function useOtelContext() {
 		getSpan,
 		getSpanContext,
 		getPropagationHeaders,
-		registerSpan: (span) => store.set("span", span),
+		registerSpan: (span) => _ctx.set(otelSpanKey, span),
 		pushSpan,
 		customSpanAttr,
 		customMetricAttr
 	};
 }
-function useTrace() {
+/** Returns the OpenTelemetry `trace` API for creating tracers and spans. */ function useTrace() {
 	return __opentelemetry_api.trace;
 }
-function useSpan() {
+/** Returns the root span for the current event, or `undefined` if no span is active. */ function useSpan() {
 	return useOtelContext().getSpan();
 }
-function useOtelPropagation() {
+/**
+* Returns W3C trace-context propagation data for the current event.
+* Use the returned `headers` (traceparent, tracestate) in outgoing HTTP requests
+* to propagate the trace to downstream services.
+*/ function useOtelPropagation() {
 	const { getPropagationHeaders, getSpanContext } = useOtelContext();
 	return {
 		...getSpanContext(),
@@ -156,24 +176,24 @@ function getMoostMetrics() {
 
 //#endregion
 //#region packages/otel/src/span-injector.ts
-function _define_property(obj, key, value) {
-	if (key in obj) Object.defineProperty(obj, key, {
+function _define_property(obj, key$1, value) {
+	if (key$1 in obj) Object.defineProperty(obj, key$1, {
 		value,
 		enumerable: true,
 		configurable: true,
 		writable: true
 	});
-	else obj[key] = value;
+	else obj[key$1] = value;
 	return obj;
 }
 const tracer = __opentelemetry_api.trace.getTracer("moost-tracer");
-var SpanInjector = class extends moost.ContextInjector {
+/** Context injector that wraps Moost lifecycle hooks with OpenTelemetry spans and records metrics. */ var SpanInjector = class extends moost.ContextInjector {
 	with(name, attributes, cb) {
 		const fn = typeof attributes === "function" ? attributes : cb;
 		const attrs = typeof attributes === "object" ? attributes : void 0;
 		if (name === "Event:start" && attrs?.eventType) return this.startEvent(attrs.eventType, fn);
-		else if (name !== "Event:start") if (this.getIgnoreSpan()) return fn();
-		else {
+		else if (name !== "Event:start") {
+			if (this.getIgnoreSpan()) return fn();
 			const span = tracer.startSpan(name, {
 				kind: __opentelemetry_api.SpanKind.INTERNAL,
 				attributes: attrs
@@ -217,7 +237,8 @@ var SpanInjector = class extends moost.ContextInjector {
 		return cb();
 	}
 	getEventType() {
-		return (0, moost.useAsyncEventContext)().getCtx().event.type;
+		const ctx = (0, moost.current)();
+		return ctx.has(moost.eventTypeKey) ? ctx.get(moost.eventTypeKey) : void 0;
 	}
 	getIgnoreSpan() {
 		const { getMethodMeta, getControllerMeta } = (0, moost.useControllerContext)();
@@ -249,7 +270,8 @@ var SpanInjector = class extends moost.ContextInjector {
 	hook(method, name, route) {
 		if (method === "WF_STEP") return;
 		if (method === "__SYSTEM__") return;
-		const { getSpan } = useOtelContext();
+		const ctx = (0, moost.current)();
+		const { getSpan } = useOtelContext(ctx);
 		if (name === "Handler:not_found") {
 			const chm = this.getControllerHandlerMeta();
 			const span = getSpan();
@@ -262,7 +284,7 @@ var SpanInjector = class extends moost.ContextInjector {
 			}
 			this.startEventMetrics(chm.attrs, route);
 		} else if (name === "Controller:registered") {
-			const _route = (0, moost.useAsyncEventContext)().store("otel").get("route");
+			const _route = ctx.has(otelRouteKey) ? ctx.get(otelRouteKey) : void 0;
 			const chm = this.getControllerHandlerMeta();
 			if (!chm.ignoreMeter) this.startEventMetrics(chm.attrs, _route);
 			const span = getSpan();
@@ -272,7 +294,7 @@ var SpanInjector = class extends moost.ContextInjector {
 				else span.updateName(`${chm.attrs["moost.event_type"]} ${_route || "<unresolved>"}`);
 			}
 		}
-		if (name !== "Controller:registered") (0, moost.useAsyncEventContext)().store("otel").set("route", route);
+		if (name !== "Controller:registered") ctx.set(otelRouteKey, route);
 	}
 	withSpan(span, cb, opts) {
 		return withSpan(span, cb, (_span, exception, result) => {
@@ -282,20 +304,22 @@ var SpanInjector = class extends moost.ContextInjector {
 				if (!chm.ignoreMeter) this.endEventMetrics(chm.attrs, result instanceof Error ? result : exception);
 			}
 			if (opts.endSpan) {
-				const customAttrs = (0, moost.useAsyncEventContext)().store("customSpanAttrs").value;
+				const ctx = (0, moost.current)();
+				const customAttrs = ctx.has(customSpanAttrsKey) ? ctx.get(customSpanAttrsKey) : void 0;
 				if (customAttrs) _span.setAttributes(customAttrs);
 				_span.end();
 			}
 		});
 	}
 	startEventMetrics(a, route) {
-		(0, moost.useAsyncEventContext)().store("otel").set("startTime", Date.now());
+		(0, moost.current)().set(otelStartTimeKey, Date.now());
 	}
 	endEventMetrics(a, error) {
-		const otelStore = (0, moost.useAsyncEventContext)().store("otel");
-		const route = otelStore.get("route");
-		const duration = Date.now() - (otelStore.get("startTime") || Date.now() - 1);
-		const customAttrs = (0, moost.useAsyncEventContext)().store("customMetricAttrs").value || {};
+		const ctx = (0, moost.current)();
+		const route = ctx.has(otelRouteKey) ? ctx.get(otelRouteKey) : void 0;
+		const startTime = ctx.has(otelStartTimeKey) ? ctx.get(otelStartTimeKey) : void 0;
+		const duration = Date.now() - (startTime || Date.now() - 1);
+		const customAttrs = ctx.has(customMetricAttrsKey) ? ctx.get(customMetricAttrsKey) : {};
 		const attrs = {
 			...customAttrs,
 			route,
@@ -310,10 +334,19 @@ var SpanInjector = class extends moost.ContextInjector {
 		this.metrics.moostEventDuration.record(duration, attrs);
 	}
 	getRequest() {
-		return (0, moost.useAsyncEventContext)().store("event").get("req");
+		try {
+			return (0, moost.current)().get(__moostjs_event_http.httpKind.keys.req);
+		} catch {
+			return void 0;
+		}
 	}
 	getResponse() {
-		return (0, moost.useAsyncEventContext)().store("event").get("res");
+		try {
+			const response = (0, moost.current)().get(__moostjs_event_http.httpKind.keys.response);
+			return response?.getRawRes(true);
+		} catch {
+			return void 0;
+		}
 	}
 	constructor(...args) {
 		super(...args), _define_property(this, "metrics", getMoostMetrics());
@@ -322,13 +355,17 @@ var SpanInjector = class extends moost.ContextInjector {
 
 //#endregion
 //#region packages/otel/src/init.ts
-function enableOtelForMoost() {
+/**
+* Enables OpenTelemetry integration for Moost by replacing the default
+* context injector with a span-aware `SpanInjector`.
+* Call this before creating or starting your Moost application.
+*/ function enableOtelForMoost() {
 	(0, moost.replaceContextInjector)(new SpanInjector());
 }
 
 //#endregion
 //#region packages/otel/src/otel.mate.ts
-function getOtelMate() {
+/** Returns the shared `Mate` instance extended with OpenTelemetry metadata fields. */ function getOtelMate() {
 	return (0, moost.getMoostMate)();
 }
 
@@ -347,13 +384,16 @@ const mate = getOtelMate();
 
 //#endregion
 //#region packages/otel/src/processors/span-filter.ts
-function shouldSpanBeIgnored(span) {
+/** Returns `true` if the span has the `moost.ignore` attribute set by `@OtelIgnoreSpan()`. */ function shouldSpanBeIgnored(span) {
 	return span.attributes["moost.ignore"] === true;
 }
 
 //#endregion
 //#region packages/otel/src/processors/batch-processor.ts
-var MoostBatchSpanProcessor = class extends __opentelemetry_sdk_trace_base.BatchSpanProcessor {
+/**
+* Batch span processor that filters out spans marked with `@OtelIgnoreSpan()`.
+* Drop-in replacement for `BatchSpanProcessor` from `@opentelemetry/sdk-trace-base`.
+*/ var MoostBatchSpanProcessor = class extends __opentelemetry_sdk_trace_base.BatchSpanProcessor {
 	onEnd(span) {
 		if (shouldSpanBeIgnored(span)) return;
 		super.onEnd(span);
@@ -362,7 +402,10 @@ var MoostBatchSpanProcessor = class extends __opentelemetry_sdk_trace_base.Batch
 
 //#endregion
 //#region packages/otel/src/processors/simple-processor.ts
-var MoostSimpleSpanProcessor = class extends __opentelemetry_sdk_trace_base.SimpleSpanProcessor {
+/**
+* Simple span processor that filters out spans marked with `@OtelIgnoreSpan()`.
+* Drop-in replacement for `SimpleSpanProcessor` from `@opentelemetry/sdk-trace-base`.
+*/ var MoostSimpleSpanProcessor = class extends __opentelemetry_sdk_trace_base.SimpleSpanProcessor {
 	onEnd(span) {
 		if (shouldSpanBeIgnored(span)) return;
 		super.onEnd(span);
@@ -375,8 +418,13 @@ exports.MoostSimpleSpanProcessor = MoostSimpleSpanProcessor;
 exports.OtelIgnoreMeter = OtelIgnoreMeter;
 exports.OtelIgnoreSpan = OtelIgnoreSpan;
 exports.SpanInjector = SpanInjector;
+exports.customMetricAttrsKey = customMetricAttrsKey;
+exports.customSpanAttrsKey = customSpanAttrsKey;
 exports.enableOtelForMoost = enableOtelForMoost;
 exports.getOtelMate = getOtelMate;
+exports.otelRouteKey = otelRouteKey;
+exports.otelSpanKey = otelSpanKey;
+exports.otelStartTimeKey = otelStartTimeKey;
 exports.shouldSpanBeIgnored = shouldSpanBeIgnored;
 exports.useOtelContext = useOtelContext;
 exports.useOtelPropagation = useOtelPropagation;

package/dist/index.d.ts

@@ -1,19 +1,29 @@
 import * as _opentelemetry_api from '@opentelemetry/api';
 import { Span, SpanOptions } from '@opentelemetry/api';
+import * as moost from 'moost';
 import { Mate, TMoostMetadata, TMateParamMeta, ContextInjector, TContextInjectorHook } from 'moost';
+import { EventContext } from '@wooksjs/event-core';
 import { BatchSpanProcessor, ReadableSpan, SimpleSpanProcessor } from '@opentelemetry/sdk-trace-base';
-import { IncomingMessage, ServerResponse } from 'http';
+import * as http from 'http';
+import { ServerResponse } from 'http';
 
-interface TOtelContext {
-    otel?: {
-        span?: Span;
-        route?: string;
-        startTime?: number;
-    };
-    customSpanAttrs?: Record<string, string>;
-    customMetricAttrs?: Record<string, string>;
-}
-declare function useOtelContext(): {
+/** Event context key storing the root OpenTelemetry span. */
+declare const otelSpanKey: moost.Key<Span | undefined>;
+/** Event context key storing the resolved route path for span naming. */
+declare const otelRouteKey: moost.Key<string | undefined>;
+/** Event context key storing the event start time (epoch ms) for duration metrics. */
+declare const otelStartTimeKey: moost.Key<number | undefined>;
+/** Event context key storing custom span attributes set via `useOtelContext().customSpanAttr()`. */
+declare const customSpanAttrsKey: moost.Key<Record<string, string | number>>;
+/** Event context key storing custom metric attributes set via `useOtelContext().customMetricAttr()`. */
+declare const customMetricAttrsKey: moost.Key<Record<string, string | number>>;
+/**
+ * Provides OpenTelemetry tracing utilities scoped to the current event.
+ * Must be called within an active event handler context.
+ *
+ * @returns Tracing utilities including span access, propagation headers, and custom attributes.
+ */
+declare function useOtelContext(ctx?: EventContext): {
     trace: _opentelemetry_api.TraceAPI;
     withChildSpan: <T>(name: string, cb: (...a: any[]) => T, opts?: SpanOptions) => () => T;
     getSpan: () => Span | undefined;
@@ -25,13 +35,20 @@ declare function useOtelContext(): {
         traceparent?: undefined;
         tracestate?: undefined;
     };
-    registerSpan: (span: Span) => unknown;
+    registerSpan: (span: Span) => void;
     pushSpan: (span: Span) => void;
-    customSpanAttr: (name: string, value: string | number) => unknown;
-    customMetricAttr: (name: string, value: string | number) => unknown;
+    customSpanAttr: (name: string, value: string | number) => void;
+    customMetricAttr: (name: string, value: string | number) => void;
 };
+/** Returns the OpenTelemetry `trace` API for creating tracers and spans. */
 declare function useTrace(): _opentelemetry_api.TraceAPI;
+/** Returns the root span for the current event, or `undefined` if no span is active. */
 declare function useSpan(): Span | undefined;
+/**
+ * Returns W3C trace-context propagation data for the current event.
+ * Use the returned `headers` (traceparent, tracestate) in outgoing HTTP requests
+ * to propagate the trace to downstream services.
+ */
 declare function useOtelPropagation(): {
     headers: {
         traceparent: string;
@@ -47,6 +64,11 @@ declare function useOtelPropagation(): {
     traceState?: _opentelemetry_api.TraceState;
 };
 
+/**
+ * Enables OpenTelemetry integration for Moost by replacing the default
+ * context injector with a span-aware `SpanInjector`.
+ * Call this before creating or starting your Moost application.
+ */
 declare function enableOtelForMoost(): void;
 
 /**
@@ -61,27 +83,39 @@ declare const OtelIgnoreSpan: () => MethodDecorator & ClassDecorator & Parameter
  */
 declare const OtelIgnoreMeter: () => MethodDecorator & ClassDecorator & ParameterDecorator & PropertyDecorator;
 
+/** OpenTelemetry metadata fields attached to classes and methods by OTEL decorators. */
 interface TOtelMate {
     otelIgnoreSpan: boolean;
     otelIgnoreMeter: boolean;
 }
+/** Returns the shared `Mate` instance extended with OpenTelemetry metadata fields. */
 declare function getOtelMate(): Mate<TMoostMetadata & TOtelMate & {
-    params: Array<TOtelMate & TMateParamMeta>;
+    params: (TOtelMate & TMateParamMeta)[];
 }, TMoostMetadata & TOtelMate & {
-    params: Array<TOtelMate & TMateParamMeta>;
+    params: (TOtelMate & TMateParamMeta)[];
 }>;
 
+/**
+ * Batch span processor that filters out spans marked with `@OtelIgnoreSpan()`.
+ * Drop-in replacement for `BatchSpanProcessor` from `@opentelemetry/sdk-trace-base`.
+ */
 declare class MoostBatchSpanProcessor extends BatchSpanProcessor {
     onEnd(span: ReadableSpan): void;
 }
 
+/**
+ * Simple span processor that filters out spans marked with `@OtelIgnoreSpan()`.
+ * Drop-in replacement for `SimpleSpanProcessor` from `@opentelemetry/sdk-trace-base`.
+ */
 declare class MoostSimpleSpanProcessor extends SimpleSpanProcessor {
     onEnd(span: ReadableSpan): void;
 }
 
+/** Returns `true` if the span has the `moost.ignore` attribute set by `@OtelIgnoreSpan()`. */
 declare function shouldSpanBeIgnored(span: ReadableSpan): boolean;
 
 type TAttributes = Record<string, string | number | boolean>;
+/** Context injector that wraps Moost lifecycle hooks with OpenTelemetry spans and records metrics. */
 declare class SpanInjector extends ContextInjector<TContextInjectorHook> {
     metrics: {
         moostEventDuration: _opentelemetry_api.Histogram;
@@ -90,7 +124,7 @@ declare class SpanInjector extends ContextInjector<TContextInjectorHook> {
     with<T>(name: TContextInjectorHook, cb: () => T): T;
     protected patchRsponse(): void;
     protected startEvent<T>(eventType: string, cb: () => T): T;
-    getEventType(): string;
+    getEventType(): string | undefined;
     getIgnoreSpan(): boolean | undefined;
     getControllerHandlerMeta(): {
         ignoreMeter: boolean | undefined;
@@ -102,8 +136,8 @@ declare class SpanInjector extends ContextInjector<TContextInjectorHook> {
             'moost.handler_label': string | undefined;
             'moost.handler_id': string | undefined;
             'moost.ignore': boolean | undefined;
-            'moost.route': string | undefined;
-            'moost.event_type': string;
+            'moost.route': string;
+            'moost.event_type': string | undefined;
         };
     };
     hook(method: string, name: 'Handler:not_found' | 'Handler:routed' | 'Controller:registered', route?: string): void;
@@ -113,14 +147,16 @@ declare class SpanInjector extends ContextInjector<TContextInjectorHook> {
     }): T;
     startEventMetrics(a: Record<string, string | number | boolean | undefined>, route?: string): void;
     endEventMetrics(a: Record<string, string | number | boolean | undefined>, error?: Error): void;
-    getRequest(): IncomingMessage | undefined;
-    getResponse(): (ServerResponse<IncomingMessage> & {
+    getRequest(): http.IncomingMessage | undefined;
+    getResponse(): (ServerResponse<http.IncomingMessage> & {
         _statusCode?: number;
         _contentLength?: number;
     }) | undefined;
 }
 
+/** Callback invoked after span execution for enrichment. When provided, you must call `span.end()` yourself. */
 type TPostSpanProcessFn<T> = (span: Span, exception: Error | undefined, result: Awaited<T> | undefined) => void;
+/** Input for creating a new span with `withSpan()`. */
 interface TSpanInput {
     name: string;
     options?: SpanOptions;
@@ -139,5 +175,5 @@ interface TSpanInput {
  */
 declare function withSpan<T>(span: TSpanInput | Span, cb: () => T, postProcess?: TPostSpanProcessFn<T>): T;
 
-export { MoostBatchSpanProcessor, MoostSimpleSpanProcessor, OtelIgnoreMeter, OtelIgnoreSpan, SpanInjector, enableOtelForMoost, getOtelMate, shouldSpanBeIgnored, useOtelContext, useOtelPropagation, useSpan, useTrace, withSpan };
-export type { TOtelContext, TOtelMate, TPostSpanProcessFn, TSpanInput };
+export { MoostBatchSpanProcessor, MoostSimpleSpanProcessor, OtelIgnoreMeter, OtelIgnoreSpan, SpanInjector, customMetricAttrsKey, customSpanAttrsKey, enableOtelForMoost, getOtelMate, otelRouteKey, otelSpanKey, otelStartTimeKey, shouldSpanBeIgnored, useOtelContext, useOtelPropagation, useSpan, useTrace, withSpan };
+export type { TOtelMate, TPostSpanProcessFn, TSpanInput };

package/dist/index.mjs

@@ -1,17 +1,33 @@
 import { SpanKind, SpanStatusCode, context, metrics, trace } from "@opentelemetry/api";
-import { ContextInjector, getConstructor, getMoostMate, replaceContextInjector, useAsyncEventContext, useControllerContext } from "moost";
+import { ContextInjector, current, eventTypeKey, getConstructor, getMoostMate, key, replaceContextInjector, useControllerContext } from "moost";
+import { httpKind } from "@moostjs/event-http";
 import { BatchSpanProcessor, SimpleSpanProcessor } from "@opentelemetry/sdk-trace-base";
 
 //#region packages/otel/src/context.ts
+/** Event context key storing the root OpenTelemetry span. */ const otelSpanKey = key("otel.span");
+/** Event context key storing the resolved route path for span naming. */ const otelRouteKey = key("otel.route");
+/** Event context key storing the event start time (epoch ms) for duration metrics. */ const otelStartTimeKey = key("otel.startTime");
+/** Event context key storing custom span attributes set via `useOtelContext().customSpanAttr()`. */ const customSpanAttrsKey = key("customSpanAttrs");
+/** Event context key storing custom metric attributes set via `useOtelContext().customMetricAttr()`. */ const customMetricAttrsKey = key("customMetricAttrs");
 const spanStack = [];
-function useOtelContext() {
-	const eventContext = useAsyncEventContext();
-	const store = eventContext.store("otel");
-	const csa = eventContext.store("customSpanAttrs");
-	const cma = eventContext.store("customMetricAttrs");
-	const customSpanAttr = (name, value) => csa.set(name, value);
-	const customMetricAttr = (name, value) => cma.set(name, value);
-	const getSpan = () => store.get("span");
+/**
+* Provides OpenTelemetry tracing utilities scoped to the current event.
+* Must be called within an active event handler context.
+*
+* @returns Tracing utilities including span access, propagation headers, and custom attributes.
+*/ function useOtelContext(ctx) {
+	const _ctx = ctx || current();
+	const customSpanAttr = (name, value) => {
+		const attrs = _ctx.has(customSpanAttrsKey) ? _ctx.get(customSpanAttrsKey) : {};
+		attrs[name] = value;
+		_ctx.set(customSpanAttrsKey, attrs);
+	};
+	const customMetricAttr = (name, value) => {
+		const attrs = _ctx.has(customMetricAttrsKey) ? _ctx.get(customMetricAttrsKey) : {};
+		attrs[name] = value;
+		_ctx.set(customMetricAttrsKey, attrs);
+	};
+	const getSpan = () => _ctx.has(otelSpanKey) ? _ctx.get(otelSpanKey) : void 0;
 	const getSpanContext = () => {
 		const span = getSpan();
 		if (span) return span.spanContext();
@@ -52,19 +68,23 @@ function useOtelContext() {
 		getSpan,
 		getSpanContext,
 		getPropagationHeaders,
-		registerSpan: (span) => store.set("span", span),
+		registerSpan: (span) => _ctx.set(otelSpanKey, span),
 		pushSpan,
 		customSpanAttr,
 		customMetricAttr
 	};
 }
-function useTrace() {
+/** Returns the OpenTelemetry `trace` API for creating tracers and spans. */ function useTrace() {
 	return trace;
 }
-function useSpan() {
+/** Returns the root span for the current event, or `undefined` if no span is active. */ function useSpan() {
 	return useOtelContext().getSpan();
 }
-function useOtelPropagation() {
+/**
+* Returns W3C trace-context propagation data for the current event.
+* Use the returned `headers` (traceparent, tracestate) in outgoing HTTP requests
+* to propagate the trace to downstream services.
+*/ function useOtelPropagation() {
 	const { getPropagationHeaders, getSpanContext } = useOtelContext();
 	return {
 		...getSpanContext(),
@@ -133,24 +153,24 @@ function getMoostMetrics() {
 
 //#endregion
 //#region packages/otel/src/span-injector.ts
-function _define_property(obj, key, value) {
-	if (key in obj) Object.defineProperty(obj, key, {
+function _define_property(obj, key$1, value) {
+	if (key$1 in obj) Object.defineProperty(obj, key$1, {
 		value,
 		enumerable: true,
 		configurable: true,
 		writable: true
 	});
-	else obj[key] = value;
+	else obj[key$1] = value;
 	return obj;
 }
 const tracer = trace.getTracer("moost-tracer");
-var SpanInjector = class extends ContextInjector {
+/** Context injector that wraps Moost lifecycle hooks with OpenTelemetry spans and records metrics. */ var SpanInjector = class extends ContextInjector {
 	with(name, attributes, cb) {
 		const fn = typeof attributes === "function" ? attributes : cb;
 		const attrs = typeof attributes === "object" ? attributes : void 0;
 		if (name === "Event:start" && attrs?.eventType) return this.startEvent(attrs.eventType, fn);
-		else if (name !== "Event:start") if (this.getIgnoreSpan()) return fn();
-		else {
+		else if (name !== "Event:start") {
+			if (this.getIgnoreSpan()) return fn();
 			const span = tracer.startSpan(name, {
 				kind: SpanKind.INTERNAL,
 				attributes: attrs
@@ -194,7 +214,8 @@ var SpanInjector = class extends ContextInjector {
 		return cb();
 	}
 	getEventType() {
-		return useAsyncEventContext().getCtx().event.type;
+		const ctx = current();
+		return ctx.has(eventTypeKey) ? ctx.get(eventTypeKey) : void 0;
 	}
 	getIgnoreSpan() {
 		const { getMethodMeta, getControllerMeta } = useControllerContext();
@@ -226,7 +247,8 @@ var SpanInjector = class extends ContextInjector {
 	hook(method, name, route) {
 		if (method === "WF_STEP") return;
 		if (method === "__SYSTEM__") return;
-		const { getSpan } = useOtelContext();
+		const ctx = current();
+		const { getSpan } = useOtelContext(ctx);
 		if (name === "Handler:not_found") {
 			const chm = this.getControllerHandlerMeta();
 			const span = getSpan();
@@ -239,7 +261,7 @@ var SpanInjector = class extends ContextInjector {
 			}
 			this.startEventMetrics(chm.attrs, route);
 		} else if (name === "Controller:registered") {
-			const _route = useAsyncEventContext().store("otel").get("route");
+			const _route = ctx.has(otelRouteKey) ? ctx.get(otelRouteKey) : void 0;
 			const chm = this.getControllerHandlerMeta();
 			if (!chm.ignoreMeter) this.startEventMetrics(chm.attrs, _route);
 			const span = getSpan();
@@ -249,7 +271,7 @@ var SpanInjector = class extends ContextInjector {
 				else span.updateName(`${chm.attrs["moost.event_type"]} ${_route || "<unresolved>"}`);
 			}
 		}
-		if (name !== "Controller:registered") useAsyncEventContext().store("otel").set("route", route);
+		if (name !== "Controller:registered") ctx.set(otelRouteKey, route);
 	}
 	withSpan(span, cb, opts) {
 		return withSpan(span, cb, (_span, exception, result) => {
@@ -259,20 +281,22 @@ var SpanInjector = class extends ContextInjector {
 				if (!chm.ignoreMeter) this.endEventMetrics(chm.attrs, result instanceof Error ? result : exception);
 			}
 			if (opts.endSpan) {
-				const customAttrs = useAsyncEventContext().store("customSpanAttrs").value;
+				const ctx = current();
+				const customAttrs = ctx.has(customSpanAttrsKey) ? ctx.get(customSpanAttrsKey) : void 0;
 				if (customAttrs) _span.setAttributes(customAttrs);
 				_span.end();
 			}
 		});
 	}
 	startEventMetrics(a, route) {
-		useAsyncEventContext().store("otel").set("startTime", Date.now());
+		current().set(otelStartTimeKey, Date.now());
 	}
 	endEventMetrics(a, error) {
-		const otelStore = useAsyncEventContext().store("otel");
-		const route = otelStore.get("route");
-		const duration = Date.now() - (otelStore.get("startTime") || Date.now() - 1);
-		const customAttrs = useAsyncEventContext().store("customMetricAttrs").value || {};
+		const ctx = current();
+		const route = ctx.has(otelRouteKey) ? ctx.get(otelRouteKey) : void 0;
+		const startTime = ctx.has(otelStartTimeKey) ? ctx.get(otelStartTimeKey) : void 0;
+		const duration = Date.now() - (startTime || Date.now() - 1);
+		const customAttrs = ctx.has(customMetricAttrsKey) ? ctx.get(customMetricAttrsKey) : {};
 		const attrs = {
 			...customAttrs,
 			route,
@@ -287,10 +311,19 @@ var SpanInjector = class extends ContextInjector {
 		this.metrics.moostEventDuration.record(duration, attrs);
 	}
 	getRequest() {
-		return useAsyncEventContext().store("event").get("req");
+		try {
+			return current().get(httpKind.keys.req);
+		} catch {
+			return void 0;
+		}
 	}
 	getResponse() {
-		return useAsyncEventContext().store("event").get("res");
+		try {
+			const response = current().get(httpKind.keys.response);
+			return response?.getRawRes(true);
+		} catch {
+			return void 0;
+		}
 	}
 	constructor(...args) {
 		super(...args), _define_property(this, "metrics", getMoostMetrics());
@@ -299,13 +332,17 @@ var SpanInjector = class extends ContextInjector {
 
 //#endregion
 //#region packages/otel/src/init.ts
-function enableOtelForMoost() {
+/**
+* Enables OpenTelemetry integration for Moost by replacing the default
+* context injector with a span-aware `SpanInjector`.
+* Call this before creating or starting your Moost application.
+*/ function enableOtelForMoost() {
 	replaceContextInjector(new SpanInjector());
 }
 
 //#endregion
 //#region packages/otel/src/otel.mate.ts
-function getOtelMate() {
+/** Returns the shared `Mate` instance extended with OpenTelemetry metadata fields. */ function getOtelMate() {
 	return getMoostMate();
 }
 
@@ -324,13 +361,16 @@ const mate = getOtelMate();
 
 //#endregion
 //#region packages/otel/src/processors/span-filter.ts
-function shouldSpanBeIgnored(span) {
+/** Returns `true` if the span has the `moost.ignore` attribute set by `@OtelIgnoreSpan()`. */ function shouldSpanBeIgnored(span) {
 	return span.attributes["moost.ignore"] === true;
 }
 
 //#endregion
 //#region packages/otel/src/processors/batch-processor.ts
-var MoostBatchSpanProcessor = class extends BatchSpanProcessor {
+/**
+* Batch span processor that filters out spans marked with `@OtelIgnoreSpan()`.
+* Drop-in replacement for `BatchSpanProcessor` from `@opentelemetry/sdk-trace-base`.
+*/ var MoostBatchSpanProcessor = class extends BatchSpanProcessor {
 	onEnd(span) {
 		if (shouldSpanBeIgnored(span)) return;
 		super.onEnd(span);
@@ -339,7 +379,10 @@ var MoostBatchSpanProcessor = class extends BatchSpanProcessor {
 
 //#endregion
 //#region packages/otel/src/processors/simple-processor.ts
-var MoostSimpleSpanProcessor = class extends SimpleSpanProcessor {
+/**
+* Simple span processor that filters out spans marked with `@OtelIgnoreSpan()`.
+* Drop-in replacement for `SimpleSpanProcessor` from `@opentelemetry/sdk-trace-base`.
+*/ var MoostSimpleSpanProcessor = class extends SimpleSpanProcessor {
 	onEnd(span) {
 		if (shouldSpanBeIgnored(span)) return;
 		super.onEnd(span);
@@ -347,4 +390,4 @@ var MoostSimpleSpanProcessor = class extends SimpleSpanProcessor {
 };
 
 //#endregion
-export { MoostBatchSpanProcessor, MoostSimpleSpanProcessor, OtelIgnoreMeter, OtelIgnoreSpan, SpanInjector, enableOtelForMoost, getOtelMate, shouldSpanBeIgnored, useOtelContext, useOtelPropagation, useSpan, useTrace, withSpan };
+export { MoostBatchSpanProcessor, MoostSimpleSpanProcessor, OtelIgnoreMeter, OtelIgnoreSpan, SpanInjector, customMetricAttrsKey, customSpanAttrsKey, enableOtelForMoost, getOtelMate, otelRouteKey, otelSpanKey, otelStartTimeKey, shouldSpanBeIgnored, useOtelContext, useOtelPropagation, useSpan, useTrace, withSpan };

package/package.json

@@ -1,11 +1,34 @@
 {
   "name": "@moostjs/otel",
-  "version": "0.5.33",
+  "version": "0.6.0",
   "description": "@moostjs/otel",
+  "keywords": [
+    "composables",
+    "framework",
+    "moost",
+    "moostjs",
+    "prostojs",
+    "wooksjs"
+  ],
+  "homepage": "https://github.com/moostjs/moostjs/tree/main/packages/otel#readme",
+  "bugs": {
+    "url": "https://github.com/moostjs/moostjs/issues"
+  },
+  "license": "MIT",
+  "author": "Artem Maltsev",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/moostjs/moostjs.git",
+    "directory": "packages/otel"
+  },
+  "files": [
+    "dist"
+  ],
+  "type": "module",
+  "sideEffects": false,
   "main": "dist/index.cjs",
   "module": "dist/index.mjs",
   "types": "dist/index.d.ts",
-  "sideEffects": false,
   "exports": {
     "./package.json": "./package.json",
     ".": {
@@ -14,38 +37,18 @@
       "require": "./dist/index.cjs"
     }
   },
-  "files": [
-    "dist"
-  ],
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/moostjs/moostjs.git",
-    "directory": "packages/otel"
-  },
-  "keywords": [
-    "moost",
-    "moostjs",
-    "composables",
-    "framework",
-    "wooksjs",
-    "prostojs"
-  ],
-  "author": "Artem Maltsev",
-  "license": "MIT",
-  "bugs": {
-    "url": "https://github.com/moostjs/moostjs/issues"
-  },
-  "homepage": "https://github.com/moostjs/moostjs/tree/main/packages/otel#readme",
-  "peerDependencies": {
-    "moost": "^0.5.33"
-  },
   "dependencies": {
     "@opentelemetry/api": "^1.9.0",
-    "@opentelemetry/sdk-trace-base": "^2.0.1"
+    "@opentelemetry/sdk-trace-base": "^2.5.1"
   },
   "devDependencies": {
     "vitest": "3.2.4"
   },
+  "peerDependencies": {
+    "@wooksjs/event-core": "^0.7.3",
+    "@moostjs/event-http": "^0.6.0",
+    "moost": "^0.6.0"
+  },
   "scripts": {
     "pub": "pnpm publish --access public",
     "test": "vitest"