@nexusts/tracing 0.7.2

package/README.md

@@ -0,0 +1,47 @@
+# @nexusts/tracing
+
+> **NexusTS** — Bun-native fullstack framework
+
+## Description
+
+OpenTelemetry distributed tracing.
+
+Lazy-loads the OTel SDK. W3C + B3 propagation. Hono auto-instrumentation middleware. @Trace() method decorator. Exporter-agnostic.
+
+## Install
+
+This module is part of the NexusTS monorepo. Each module is published as its own npm package under the `@nexusts/` scope.
+
+Most apps start with just the core:
+
+```bash
+bun add @nexusts/core
+```
+
+Then add this module only if you need it:
+
+```bash
+bun add @nexusts/tracing
+```
+
+## Peer dependencies
+
+```bash
+bun add @opentelemetry/api
+```
+
+- **`@opentelemetry/api`** ^1.9.0 — OpenTelemetry API. Required to enable tracing.
+
+Without them the module loads but its public methods throw a clear error pointing to this install command on first call.
+
+## Usage
+
+```typescript
+import { /* public API */ } from "@nexusts/tracing";
+```
+
+See the [user guide](../../docs/user-guide/tracing.md) and the [example app](../../examples/) for a working demo.
+
+## License
+
+MIT — see the root [LICENSE](../../LICENSE).

package/dist/decorators/index.d.ts

@@ -0,0 +1 @@
+export { Trace, getTraceOptions, type TraceOptions } from "./trace.js";

package/dist/decorators/trace.d.ts

@@ -0,0 +1,36 @@
+/**
+ * `@Trace()` — class-method decorator that wraps the call in a span.
+ *
+ * Usage:
+ *   class UserService {
+ *     @Trace()                  // span name = class.method
+ *     async findById(id: string) { ... }
+ *
+ *     @Trace("user.lookup")     // explicit span name
+ *     async lookup(name: string) { ... }
+ *
+ *     @Trace({ name: "user.cache.get", attributes: { cache: "lru" } })
+ *     async getFromCache(key: string) { ... }
+ *   }
+ *
+ * The decorator reads the `TracingService` from the global registry
+ * (set by `TracingModule.forRoot()`). When no service is registered
+ * the decorator is a pass-through.
+ *
+ * Sync methods stay sync; async methods stay async. The decorator
+ * detects `AsyncFunction` and uses `withSpan` / `withSpanSync` accordingly.
+ */
+import type { SpanOptions } from "../types.js";
+export type TraceOptions = string | undefined | (SpanOptions & {
+    name: string;
+});
+/**
+ * Method decorator: wrap a call in a span.
+ *
+ * The decorator works on both async and sync methods. The wrapped
+ * function preserves `this` so decorators on classes still see the
+ * right instance.
+ */
+export declare function Trace(opts?: TraceOptions): (target: object, propertyKey: string | symbol, descriptor: PropertyDescriptor) => PropertyDescriptor;
+/** Read the @Trace options for a given method (used by OpenAPI integration). */
+export declare function getTraceOptions(target: object, method: string): TraceOptions | undefined;

package/dist/hono-instrumentation.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Hono auto-instrumentation for `nexusjs/tracing`.
+ *
+ * Returns a Hono middleware that:
+ * 1. Extracts the incoming trace context (W3C `traceparent`).
+ * 2. Starts a `SERVER` span with HTTP method, route, target, etc.
+ * 3. Records the response status, body size, and any thrown error.
+ *
+ * The middleware is a no-op when the SDK is not configured: the
+ * OTel API returns a no-op span that immediately ends, but the
+ * `traceparent` is still parsed for the response.
+ */
+import type { MiddlewareHandler } from "hono";
+import type { TracingService } from "./service.js";
+export declare function tracingMiddleware(service: TracingService): MiddlewareHandler;
+/**
+ * Inject the active trace context into an outgoing fetch / response.
+ * Use in fetch() calls so downstream services pick up the trace.
+ */
+export declare function injectOutgoingTraceparent(service: TracingService, headers?: Record<string, string>): Record<string, string>;

package/dist/index.d.ts

@@ -0,0 +1,28 @@
+/**
+ * `nexusjs/tracing` — OpenTelemetry-based distributed tracing.
+ *
+ * Public API:
+ * - `TracingService`        — the main service (lives in DI)
+ * - `TracingModule.forRoot()` — wires up the OTel SDK
+ * - `tracingMiddleware()`   — Hono auto-instrumentation
+ * - `@Trace()` decorator    — wrap a method in a span
+ * - `withSpan(name, fn)`    — manual span helper
+ * - W3C + B3 propagation helpers
+ * - `InMemorySpanRecorder`  — for tests / `console` exporter
+ *
+ * The OpenTelemetry **API** package is the only required
+ * dependency (~7kb). The **SDK** packages are optional peer
+ * dependencies — install them when you call `forRoot()`.
+ *
+ *   bun add @opentelemetry/api                          # always
+ *   bun add @opentelemetry/sdk-node                     # for OTLP export
+ *   bun add @opentelemetry/exporter-trace-otlp-http
+ *   bun add @opentelemetry/resources
+ *   bun add @opentelemetry/semantic-conventions
+ */
+export { TracingService, TRACING_SERVICE_TOKEN, InMemorySpanRecorder, setTracingService, getTracingService, } from "./service.js";
+export { TracingModule, TRACING_CONFIG_TOKEN } from "./module.js";
+export { tracingMiddleware, injectOutgoingTraceparent, } from "./hono-instrumentation.js";
+export { parseTraceParent, formatTraceParent, extractB3Context, inject as injectContextHeaders, extract as extractContextHeaders, TRACE_PARENT_HEADER, TRACE_STATE_HEADER, B3_TRACE_ID_HEADER, B3_SPAN_ID_HEADER, B3_SAMPLED_HEADER, type ParsedTraceParent, } from "./propagation.js";
+export { Trace, getTraceOptions, type TraceOptions } from "./decorators/index.js";
+export type { ActiveSpan, FinishedSpan, SpanContext, SpanOptions, SpanStatus, TracingConfig, TracingExporter, } from "./types.js";

package/dist/index.js

@@ -0,0 +1,546 @@
+// @bun
+var __legacyDecorateClassTS = function(decorators, target, key, desc) {
+  var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+  if (typeof Reflect === "object" && typeof Reflect.decorate === "function")
+    r = Reflect.decorate(decorators, target, key, desc);
+  else
+    for (var i = decorators.length - 1;i >= 0; i--)
+      if (d = decorators[i])
+        r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+  return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __legacyDecorateParamTS = (index, decorator) => (target, key) => decorator(target, key, index);
+var __legacyMetadataTS = (k, v) => {
+  if (typeof Reflect === "object" && typeof Reflect.metadata === "function")
+    return Reflect.metadata(k, v);
+};
+var __require = import.meta.require;
+
+// packages/tracing/src/service.ts
+import {
+  context as otelContext,
+  propagation,
+  SpanStatusCode,
+  SpanKind,
+  trace
+} from "@opentelemetry/api";
+
+class InMemorySpanRecorder {
+  finished = [];
+  nextEventCounter = 0;
+  record(span) {
+    this.finished.push(span);
+    this.nextEventCounter++;
+  }
+  getAll() {
+    return this.finished;
+  }
+  findByName(name) {
+    return this.finished.filter((s) => s.name === name);
+  }
+  clear() {
+    this.finished = [];
+    this.nextEventCounter = 0;
+  }
+  get size() {
+    return this.finished.length;
+  }
+}
+
+class OtelActiveSpan {
+  name;
+  traceId;
+  spanId;
+  isRecording;
+  otelSpan;
+  constructor(name, traceId, spanId, isRecording, otelSpan) {
+    this.name = name;
+    this.traceId = traceId;
+    this.spanId = spanId;
+    this.isRecording = isRecording;
+    this.otelSpan = otelSpan;
+  }
+  setAttribute(key, value) {
+    this.otelSpan.setAttribute(key, value);
+  }
+  setAttributes(attributes) {
+    this.otelSpan.setAttributes(attributes);
+  }
+  addEvent(name, attributes) {
+    this.otelSpan.addEvent(name, attributes);
+  }
+  recordException(err) {
+    if (err instanceof Error) {
+      this.otelSpan.recordException(err);
+    } else {
+      this.otelSpan.recordException(new Error(String(err)));
+    }
+  }
+  setStatus(status, description) {
+    const code = status === "ok" ? SpanStatusCode.OK : status === "error" ? SpanStatusCode.ERROR : SpanStatusCode.UNSET;
+    this.otelSpan.setStatus({ code, message: description });
+  }
+  end() {
+    this.otelSpan.end();
+  }
+}
+var TRACING_SERVICE_TOKEN = Symbol.for("nexus:TracingService");
+var _current;
+function setTracingService(service) {
+  _current = service;
+}
+function getTracingService() {
+  return _current;
+}
+
+class TracingService {
+  tracer;
+  recorder = new InMemorySpanRecorder;
+  sdkStop;
+  initialized = false;
+  constructor() {
+    this.tracer = trace.getTracer("nexusjs", "0.4.0");
+  }
+  get isInitialized() {
+    return this.initialized;
+  }
+  getSpans() {
+    return this.recorder.getAll();
+  }
+  findSpans(name) {
+    return this.recorder.findByName(name);
+  }
+  clearSpans() {
+    this.recorder.clear();
+  }
+  startSpan(name, options = {}) {
+    const kind = toOtelKind(options.kind ?? "internal");
+    const otelSpan = this.tracer.startSpan(name, {
+      kind,
+      attributes: options.attributes,
+      startTime: options.startTime
+    });
+    const ctx = otelSpan.spanContext();
+    return new OtelActiveSpan(name, ctx.traceId, ctx.spanId, otelSpan.isRecording(), otelSpan);
+  }
+  async withSpan(name, fn, options = {}) {
+    const span = this.startSpan(name, options);
+    const ctx = trace.setSpan(otelContext.active(), span["otelSpan"]);
+    try {
+      const result = await otelContext.with(ctx, () => fn(span));
+      if (span.isRecording)
+        span.setStatus("ok");
+      return result;
+    } catch (err) {
+      if (span.isRecording) {
+        span.recordException(err);
+        span.setStatus("error", err instanceof Error ? err.message : String(err));
+      }
+      throw err;
+    } finally {
+      span.end();
+    }
+  }
+  withSpanSync(name, fn, options = {}) {
+    const span = this.startSpan(name, options);
+    try {
+      const result = fn(span);
+      if (span.isRecording)
+        span.setStatus("ok");
+      return result;
+    } catch (err) {
+      if (span.isRecording) {
+        span.recordException(err);
+        span.setStatus("error", err instanceof Error ? err.message : String(err));
+      }
+      throw err;
+    } finally {
+      span.end();
+    }
+  }
+  getCurrentTraceId() {
+    const ctx = trace.getSpan(otelContext.active())?.spanContext();
+    return ctx?.traceId;
+  }
+  getCurrentSpanId() {
+    const ctx = trace.getSpan(otelContext.active())?.spanContext();
+    return ctx?.spanId;
+  }
+  getCurrentContext() {
+    return otelContext.active();
+  }
+  extractContext(headers) {
+    const flat = flattenHeaders(headers);
+    return propagation.extract(otelContext.active(), flat);
+  }
+  injectContext(headers = {}) {
+    const out = { ...headers };
+    propagation.inject(otelContext.active(), out);
+    return out;
+  }
+  async startSdk(config) {
+    if (this.initialized)
+      return;
+    const serviceName = config.serviceName ?? process.env.OTEL_SERVICE_NAME ?? "nexusjs";
+    const endpoint = config.endpoint ?? process.env.OTEL_EXPORTER_OTLP_ENDPOINT ?? "http://localhost:4318";
+    const sampleRatio = config.sampleRatio ?? 1;
+    let NodeSDK, OTLPTraceExporter, Resource, SemanticResourceAttributes;
+    try {
+      ({ NodeSDK } = await import("@opentelemetry/sdk-node"));
+      ({ OTLPTraceExporter } = await import("@opentelemetry/exporter-trace-otlp-http"));
+      ({ Resource } = await import("@opentelemetry/resources"));
+      const semconv = await import("@opentelemetry/semantic-conventions");
+      SemanticResourceAttributes = semconv.SemanticResourceAttributes ?? semconv;
+    } catch (err) {
+      throw new Error("TracingModule.forRoot() requires the OTel SDK packages. Install with: bun add @opentelemetry/sdk-node @opentelemetry/exporter-trace-otlp-http @opentelemetry/resources @opentelemetry/semantic-conventions");
+    }
+    const resourceAttrs = {
+      [SemanticResourceAttributes.SERVICE_NAME ?? "service.name"]: serviceName,
+      [SemanticResourceAttributes.SERVICE_VERSION ?? "service.version"]: config.serviceVersion ?? "0.0.0",
+      [SemanticResourceAttributes.DEPLOYMENT_ENVIRONMENT ?? "deployment.environment"]: config.environment ?? "development" ?? "development",
+      ...config.resourceAttributes
+    };
+    const resource = new Resource(resourceAttrs);
+    let traceExporter;
+    if (config.exporter === "console" || config.exporter === "memory" || !config.exporter) {
+      traceExporter = undefined;
+    } else {
+      traceExporter = new OTLPTraceExporter({ url: `${endpoint.replace(/\/$/, "")}/v1/traces` });
+    }
+    const sdk = new NodeSDK({
+      resource,
+      traceExporter,
+      sampler: {
+        shouldSample: () => ({
+          decision: Math.random() < sampleRatio ? 1 : 0
+        }),
+        toString: () => `RatioSampler(${sampleRatio})`
+      }
+    });
+    sdk.start();
+    this.sdkStop = async () => {
+      try {
+        await sdk.shutdown();
+      } catch {}
+    };
+    this.initialized = true;
+  }
+  async stopSdk() {
+    if (this.sdkStop) {
+      await this.sdkStop();
+      this.sdkStop = undefined;
+    }
+    this.initialized = false;
+  }
+}
+function toOtelKind(kind) {
+  switch (kind) {
+    case "server":
+      return SpanKind.SERVER;
+    case "client":
+      return SpanKind.CLIENT;
+    case "producer":
+      return SpanKind.PRODUCER;
+    case "consumer":
+      return SpanKind.CONSUMER;
+    default:
+      return SpanKind.INTERNAL;
+  }
+}
+function flattenHeaders(headers) {
+  const out = {};
+  for (const [k, v] of Object.entries(headers)) {
+    if (v === undefined)
+      continue;
+    out[k.toLowerCase()] = Array.isArray(v) ? v.join(",") : v;
+  }
+  return out;
+}
+// packages/tracing/src/module.ts
+import { Inject, Injectable, Module } from "@nexusts/core";
+
+// packages/tracing/src/hono-instrumentation.ts
+import { SpanKind as SpanKind2, SpanStatusCode as SpanStatusCode2, trace as trace2 } from "@opentelemetry/api";
+function tracingMiddleware(service) {
+  return async (c, next) => {
+    const incoming = c.req.raw.headers;
+    const flat = {};
+    incoming.forEach((v, k) => flat[k] = v);
+    const extractedCtx = service.extractContext(flat);
+    const method = c.req.method;
+    const path = c.req.path;
+    const route = c.req.routePath ?? path;
+    const userAgent = c.req.header("user-agent") ?? "";
+    const url = new URL(c.req.url);
+    const clientIp = c.req.header("x-forwarded-for") ?? c.req.header("x-real-ip") ?? "";
+    const span = service.tracer.startSpan(`HTTP ${method} ${route}`, {
+      kind: SpanKind2.SERVER,
+      attributes: {
+        "http.method": method,
+        "http.target": path,
+        "http.route": route,
+        "http.scheme": url.protocol.replace(":", ""),
+        "http.host": url.host,
+        "http.user_agent": userAgent,
+        "http.client_ip": clientIp,
+        "url.path": path
+      }
+    }, extractedCtx);
+    const ctxWithSpan = trace2.setSpan(extractedCtx, span);
+    const result = await service.tracer.startActiveSpan(`HTTP ${method} ${route} handler`, { kind: SpanKind2.SERVER }, ctxWithSpan, async () => {
+      try {
+        await next();
+        const status = c.res.status;
+        span.setAttribute("http.status_code", status);
+        if (status >= 500) {
+          span.setStatus({ code: SpanStatusCode2.ERROR });
+        } else {
+          span.setStatus({ code: SpanStatusCode2.OK });
+        }
+      } catch (err) {
+        span.recordException(err);
+        span.setStatus({ code: SpanStatusCode2.ERROR, message: err.message });
+        span.setAttribute("http.status_code", 500);
+        throw err;
+      } finally {
+        span.end();
+      }
+    });
+    return result;
+  };
+}
+function injectOutgoingTraceparent(service, headers = {}) {
+  return service.injectContext(headers);
+}
+
+// packages/tracing/src/module.ts
+var TRACING_CONFIG_TOKEN = Symbol.for("nexus:TracingConfig");
+
+class TracingConfigHolder {
+  config;
+  constructor(config) {
+    this.config = config;
+  }
+}
+TracingConfigHolder = __legacyDecorateClassTS([
+  Injectable(),
+  __legacyDecorateParamTS(0, Inject(TRACING_CONFIG_TOKEN)),
+  __legacyMetadataTS("design:paramtypes", [
+    typeof Required === "undefined" ? Object : Required
+  ])
+], TracingConfigHolder);
+
+class TracingServiceWithLifecycle extends TracingService {
+  async onApplicationBootstrap() {}
+  async onApplicationShutdown() {
+    await this.stopSdk();
+  }
+}
+TracingServiceWithLifecycle = __legacyDecorateClassTS([
+  Injectable()
+], TracingServiceWithLifecycle);
+
+class TracingModule {
+  static forRoot(config = {}) {
+    const fullConfig = {
+      serviceName: config.serviceName ?? process.env.OTEL_SERVICE_NAME ?? "nexusjs",
+      serviceVersion: config.serviceVersion ?? "0.0.0",
+      environment: config.environment ?? "development" ?? "development",
+      exporter: config.exporter ?? "otlp-http",
+      endpoint: config.endpoint ?? process.env.OTEL_EXPORTER_OTLP_ENDPOINT ?? "http://localhost:4318",
+      sampleRatio: config.sampleRatio ?? 1,
+      enableHttpInstrumentation: config.enableHttpInstrumentation ?? true,
+      enableDbInstrumentation: config.enableDbInstrumentation ?? true,
+      resourceAttributes: config.resourceAttributes ?? {},
+      throwOnError: config.throwOnError ?? false
+    };
+
+    class ConfiguredTracingModule {
+      svc;
+      constructor(svc) {
+        this.svc = svc;
+        svc.startSdk(fullConfig);
+        setTracingService(svc);
+      }
+    }
+    ConfiguredTracingModule = __legacyDecorateClassTS([
+      Module({
+        providers: [
+          TracingServiceWithLifecycle,
+          { provide: TRACING_CONFIG_TOKEN, useValue: fullConfig },
+          { provide: TRACING_SERVICE_TOKEN, useExisting: TracingServiceWithLifecycle }
+        ],
+        exports: [TracingServiceWithLifecycle, TRACING_CONFIG_TOKEN, TRACING_SERVICE_TOKEN]
+      }),
+      __legacyDecorateParamTS(0, Inject(TracingServiceWithLifecycle)),
+      __legacyMetadataTS("design:paramtypes", [
+        typeof TracingServiceWithLifecycle === "undefined" ? Object : TracingServiceWithLifecycle
+      ])
+    ], ConfiguredTracingModule);
+    Object.defineProperty(ConfiguredTracingModule, "name", { value: "ConfiguredTracingModule" });
+    const mod = ConfiguredTracingModule;
+    mod.middleware = () => {
+      const svc = new TracingService;
+      setTracingService(svc);
+      return tracingMiddleware(svc);
+    };
+    return mod;
+  }
+}
+TracingModule = __legacyDecorateClassTS([
+  Module({
+    providers: [
+      TracingServiceWithLifecycle,
+      { provide: TRACING_SERVICE_TOKEN, useExisting: TracingServiceWithLifecycle }
+    ],
+    exports: [TracingServiceWithLifecycle, TRACING_SERVICE_TOKEN]
+  })
+], TracingModule);
+// packages/tracing/src/propagation.ts
+import { propagation as propagation2, context } from "@opentelemetry/api";
+var TRACE_PARENT_HEADER = "traceparent";
+var TRACE_STATE_HEADER = "tracestate";
+var B3_TRACE_ID_HEADER = "x-b3-traceid";
+var B3_SPAN_ID_HEADER = "x-b3-spanid";
+var B3_SAMPLED_HEADER = "x-b3-sampled";
+function parseTraceParent(value) {
+  if (!value)
+    return;
+  const parts = value.trim().split("-");
+  if (parts.length !== 4)
+    return;
+  const [version, traceId, parentSpanId, flags] = parts;
+  if (!/^[0-9a-f]{2}$/i.test(version))
+    return;
+  if (!/^[0-9a-f]{32}$/i.test(traceId))
+    return;
+  if (traceId === "0".repeat(32))
+    return;
+  if (!/^[0-9a-f]{16}$/i.test(parentSpanId))
+    return;
+  if (parentSpanId === "0".repeat(16))
+    return;
+  if (!/^[0-9a-f]{2}$/i.test(flags))
+    return;
+  return {
+    version,
+    traceId: traceId.toLowerCase(),
+    parentSpanId: parentSpanId.toLowerCase(),
+    flags: flags.toLowerCase(),
+    sampled: (parseInt(flags, 16) & 1) === 1
+  };
+}
+function formatTraceParent(traceId, spanId, sampled = true) {
+  const flags = sampled ? "01" : "00";
+  return `00-${traceId.toLowerCase()}-${spanId.toLowerCase()}-${flags}`;
+}
+function extractB3Context(headers) {
+  const b3 = headers["b3"] ?? headers["x-b3-traceid"];
+  if (!b3)
+    return;
+  if (b3.includes("-")) {
+    const [traceId, spanId, sampled] = b3.split("-");
+    if (traceId && spanId) {
+      return { traceId, spanId, sampled: sampled === "1" };
+    }
+  } else {
+    const spanId = headers["x-b3-spanid"];
+    const sampled = headers["x-b3-sampled"] === "1";
+    if (spanId)
+      return { traceId: b3, spanId, sampled };
+  }
+  return;
+}
+function inject(headers) {
+  const out = { ...headers };
+  propagation2.inject(context.active(), out);
+  return out;
+}
+function extract(headers) {
+  return propagation2.extract(context.active(), headers);
+}
+// packages/tracing/src/decorators/trace.ts
+var TRACE_KEY = Symbol.for("nexus:trace:options");
+function Trace(opts) {
+  return function(target, propertyKey, descriptor) {
+    const original = descriptor.value;
+    if (typeof original !== "function") {
+      throw new Error(`@Trace() can only be applied to methods, got ${typeof original}`);
+    }
+    const options = normalizeOptions(opts ?? {}, target, propertyKey);
+    target[TRACE_KEY] = target[TRACE_KEY] ?? {};
+    target[TRACE_KEY][String(propertyKey)] = options;
+    const isAsync = original.constructor?.name === "AsyncFunction";
+    if (isAsync) {
+      descriptor.value = async function wrapped(...args) {
+        const service = getTracingService();
+        if (!service)
+          return original.apply(this, args);
+        return service.withSpan(options.name, async (span) => {
+          if (options.attributes)
+            span.setAttributes(options.attributes);
+          return original.apply(this, args);
+        }, { kind: options.kind ?? "internal", attributes: options.attributes });
+      };
+    } else {
+      descriptor.value = function wrapped(...args) {
+        const service = getTracingService();
+        if (!service)
+          return original.apply(this, args);
+        return service.withSpanSync(options.name, (span) => {
+          if (options.attributes)
+            span.setAttributes(options.attributes);
+          return original.apply(this, args);
+        }, { kind: options.kind ?? "internal", attributes: options.attributes });
+      };
+    }
+    return descriptor;
+  };
+}
+function getTraceOptions(target, method) {
+  return target[TRACE_KEY]?.[method];
+}
+function normalizeOptions(opts, target, propertyKey) {
+  if (typeof opts === "string") {
+    return { name: opts, kind: "internal" };
+  }
+  if (opts && typeof opts === "object" && "name" in opts && opts.name) {
+    const o = opts;
+    return {
+      name: o.name,
+      kind: o.kind ?? "internal",
+      attributes: o.attributes
+    };
+  }
+  const cls = target?.constructor?.name ?? "Anonymous";
+  return {
+    name: `${cls}.${String(propertyKey)}`,
+    kind: "internal"
+  };
+}
+export {
+  tracingMiddleware,
+  setTracingService,
+  parseTraceParent,
+  injectOutgoingTraceparent,
+  inject as injectContextHeaders,
+  getTracingService,
+  getTraceOptions,
+  formatTraceParent,
+  extract as extractContextHeaders,
+  extractB3Context,
+  TracingService,
+  TracingModule,
+  Trace,
+  TRACING_SERVICE_TOKEN,
+  TRACING_CONFIG_TOKEN,
+  TRACE_STATE_HEADER,
+  TRACE_PARENT_HEADER,
+  InMemorySpanRecorder,
+  B3_TRACE_ID_HEADER,
+  B3_SPAN_ID_HEADER,
+  B3_SAMPLED_HEADER
+};
+
+//# debugId=283916FBDA13049264756E2164756E21
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1,14 @@
+{
+  "version": 3,
+  "sources": ["../src/service.ts", "../src/module.ts", "../src/hono-instrumentation.ts", "../src/propagation.ts", "../src/decorators/trace.ts"],
+  "sourcesContent": [
+    "/**\n * `TracingService` — the framework's distributed-tracing primitive.\n *\n * Design:\n * 1. The OpenTelemetry API (`@opentelemetry/api`) is the only\n *    required dependency; it's ~7kb and provides the no-op default\n *    tracer when the SDK is not configured.\n * 2. The OTel SDK is **lazy-loaded**: only when the user calls\n *    `TracingModule.forRoot(...)` is `@opentelemetry/sdk-node` and\n *    the configured exporter imported. This keeps the bundle small\n *    for users who don't trace.\n * 3. Without `forRoot()`, the service returns no-op spans. They have\n *    valid `traceId` / `spanId` (the OTel no-op span id format) so\n *    log lines and error reports don't need to special-case \"not\n *    configured\".\n *\n * Public API:\n * - `startSpan(name, options?)` — create a new active span\n * - `withSpan(name, fn, options?)` — run `fn` inside a span, return its result\n * - `getCurrentTraceId()` / `getCurrentSpanId()` — read the active context\n * - `extractContext(headers)` / `injectContext(headers)` — W3C trace context\n * - `getSpans()` — read the in-memory span recorder (always available,\n *   used for tests and for the `console` exporter)\n * - `reset()` — clear the in-memory recorder\n *\n * The service is registered in the DI container as a singleton. The\n * framework does **not** call `trace.getTracer` until something\n * actually starts a span.\n */\n\nimport {\n\tcontext as otelContext,\n\tpropagation,\n\tSpanStatusCode,\n\tSpanKind,\n\ttrace,\n\ttype Context,\n\ttype Span as OtelSpan,\n\ttype Tracer,\n} from \"@opentelemetry/api\";\nimport type {\n\tActiveSpan,\n\tFinishedSpan,\n\tSpanContext,\n\tSpanOptions,\n\tSpanStatus,\n} from \"./types.js\";\n\n/* ------------------------------------------------------------------ *\n * In-memory recorder\n * ------------------------------------------------------------------ */\n\nexport class InMemorySpanRecorder {\n\tprivate finished: FinishedSpan[] = [];\n\tprivate nextEventCounter = 0;\n\n\t/** Append a finished span. */\n\trecord(span: FinishedSpan): void {\n\t\tthis.finished.push(span);\n\t\tthis.nextEventCounter++;\n\t}\n\n\t/** Return all finished spans (most recent last). */\n\tgetAll(): FinishedSpan[] {\n\t\treturn this.finished;\n\t}\n\n\t/** Return only the spans whose `name` matches. */\n\tfindByName(name: string): FinishedSpan[] {\n\t\treturn this.finished.filter((s) => s.name === name);\n\t}\n\n\t/** Clear the recorder. */\n\tclear(): void {\n\t\tthis.finished = [];\n\t\tthis.nextEventCounter = 0;\n\t}\n\n\t/** Number of recorded spans. */\n\tget size(): number {\n\t\treturn this.finished.length;\n\t}\n}\n\n/* ------------------------------------------------------------------ *\n * ActiveSpan wrapper around OTel span\n * ------------------------------------------------------------------ */\n\nclass OtelActiveSpan implements ActiveSpan {\n\tconstructor(\n\t\tpublic readonly name: string,\n\t\tpublic readonly traceId: string,\n\t\tpublic readonly spanId: string,\n\t\tpublic readonly isRecording: boolean,\n\t\tprivate readonly otelSpan: OtelSpan,\n\t) {}\n\n\tsetAttribute(key: string, value: string | number | boolean): void {\n\t\tthis.otelSpan.setAttribute(key, value);\n\t}\n\n\tsetAttributes(attributes: Record<string, string | number | boolean>): void {\n\t\tthis.otelSpan.setAttributes(attributes);\n\t}\n\n\taddEvent(name: string, attributes?: Record<string, unknown>): void {\n\t\tthis.otelSpan.addEvent(name, attributes as never);\n\t}\n\n\trecordException(err: unknown): void {\n\t\tif (err instanceof Error) {\n\t\t\tthis.otelSpan.recordException(err);\n\t\t} else {\n\t\t\tthis.otelSpan.recordException(new Error(String(err)));\n\t\t}\n\t}\n\n\tsetStatus(status: \"ok\" | \"error\" | \"unset\", description?: string): void {\n\t\tconst code =\n\t\t\tstatus === \"ok\"\n\t\t\t\t? SpanStatusCode.OK\n\t\t\t\t: status === \"error\"\n\t\t\t\t\t? SpanStatusCode.ERROR\n\t\t\t\t\t: SpanStatusCode.UNSET;\n\t\tthis.otelSpan.setStatus({ code, message: description });\n\t}\n\n\tend(): void {\n\t\tthis.otelSpan.end();\n\t}\n}\n\n/* ------------------------------------------------------------------ *\n * TracingService\n * ------------------------------------------------------------------ */\n\nexport const TRACING_SERVICE_TOKEN = Symbol.for(\"nexus:TracingService\");\n\n/**\n * Global registry of the active `TracingService` instance.\n * The framework's `TracingModule.forRoot()` calls `setTracingService()`.\n * Decorators that need a `TracingService` (e.g. `@Trace()`) call\n * `getTracingService()` to look it up without DI plumbing.\n */\nlet _current: TracingService | undefined;\n\nexport function setTracingService(service: TracingService): void {\n\t_current = service;\n}\n\nexport function getTracingService(): TracingService | undefined {\n\treturn _current;\n}\n\nexport class TracingService {\n\treadonly tracer: Tracer;\n\tprivate readonly recorder = new InMemorySpanRecorder();\n\tprivate sdkStop?: () => Promise<void>;\n\tprivate initialized = false;\n\n\tconstructor() {\n\t\t// Default OTel tracer: \"nexusjs\". Even with no SDK, this returns\n\t\t// a no-op tracer that produces no-op spans — never throws.\n\t\tthis.tracer = trace.getTracer(\"nexusjs\", \"0.4.0\");\n\t}\n\n\t/** True if the SDK has been started (i.e. `forRoot()` was called). */\n\tget isInitialized(): boolean {\n\t\treturn this.initialized;\n\t}\n\n\t/** Read all finished spans recorded so far. */\n\tgetSpans(): FinishedSpan[] {\n\t\treturn this.recorder.getAll();\n\t}\n\n\t/** Find spans by name. */\n\tfindSpans(name: string): FinishedSpan[] {\n\t\treturn this.recorder.findByName(name);\n\t}\n\n\t/** Clear the in-memory recorder (and the SDK's batch, if any). */\n\tclearSpans(): void {\n\t\tthis.recorder.clear();\n\t}\n\n\t/* ---------------- span lifecycle ---------------- */\n\n\tstartSpan(name: string, options: SpanOptions = {}): ActiveSpan {\n\t\tconst kind = toOtelKind(options.kind ?? \"internal\");\n\t\tconst otelSpan = this.tracer.startSpan(name, {\n\t\t\tkind,\n\t\t\tattributes: options.attributes as never,\n\t\t\tstartTime: options.startTime,\n\t\t});\n\n\t\tconst ctx = otelSpan.spanContext();\n\t\treturn new OtelActiveSpan(\n\t\t\tname,\n\t\t\tctx.traceId,\n\t\t\tctx.spanId,\n\t\t\totelSpan.isRecording(),\n\t\t\totelSpan,\n\t\t);\n\t}\n\n\t/** Run `fn` inside a new span. Returns the result of `fn`. */\n\tasync withSpan<T>(\n\t\tname: string,\n\t\tfn: (span: ActiveSpan) => Promise<T> | T,\n\t\toptions: SpanOptions = {},\n\t): Promise<T> {\n\t\tconst span = this.startSpan(name, options);\n\t\tconst ctx = trace.setSpan(otelContext.active(), (span as OtelActiveSpan)[\"otelSpan\"] as OtelSpan);\n\t\ttry {\n\t\t\tconst result = await otelContext.with(ctx, () => fn(span));\n\t\t\tif (span.isRecording) span.setStatus(\"ok\");\n\t\t\treturn result;\n\t\t} catch (err) {\n\t\t\tif (span.isRecording) {\n\t\t\t\tspan.recordException(err);\n\t\t\t\tspan.setStatus(\"error\", err instanceof Error ? err.message : String(err));\n\t\t\t}\n\t\t\tthrow err;\n\t\t} finally {\n\t\t\tspan.end();\n\t\t}\n\t}\n\n\t/** Synchronous version of `withSpan`. */\n\twithSpanSync<T>(name: string, fn: (span: ActiveSpan) => T, options: SpanOptions = {}): T {\n\t\tconst span = this.startSpan(name, options);\n\t\ttry {\n\t\t\tconst result = fn(span);\n\t\t\tif (span.isRecording) span.setStatus(\"ok\");\n\t\t\treturn result;\n\t\t} catch (err) {\n\t\t\tif (span.isRecording) {\n\t\t\t\tspan.recordException(err);\n\t\t\t\tspan.setStatus(\"error\", err instanceof Error ? err.message : String(err));\n\t\t\t}\n\t\t\tthrow err;\n\t\t} finally {\n\t\t\tspan.end();\n\t\t}\n\t}\n\n\t/* ---------------- context propagation ---------------- */\n\n\t/** Get the trace id of the active span, or `undefined`. */\n\tgetCurrentTraceId(): string | undefined {\n\t\tconst ctx = trace.getSpan(otelContext.active())?.spanContext();\n\t\treturn ctx?.traceId;\n\t}\n\n\t/** Get the span id of the active span, or `undefined`. */\n\tgetCurrentSpanId(): string | undefined {\n\t\tconst ctx = trace.getSpan(otelContext.active())?.spanContext();\n\t\treturn ctx?.spanId;\n\t}\n\n\t/** Get the current OTel `Context`. */\n\tgetCurrentContext(): Context {\n\t\treturn otelContext.active();\n\t}\n\n\t/**\n\t * Extract a span context from incoming HTTP headers.\n\t * Reads `traceparent` (W3C) and `x-b3-*` (B3 single) when present.\n\t * Returns `undefined` if no recognizable header is found.\n\t */\n\textractContext(headers: Record<string, string | string[] | undefined>): Context {\n\t\tconst flat = flattenHeaders(headers);\n\t\treturn propagation.extract(otelContext.active(), flat);\n\t}\n\n\t/**\n\t * Inject the active span context into outgoing HTTP headers.\n\t * Writes `traceparent` (W3C) by default.\n\t */\n\tinjectContext(headers: Record<string, string> = {}): Record<string, string> {\n\t\tconst out: Record<string, string> = { ...headers };\n\t\tpropagation.inject(otelContext.active(), out);\n\t\treturn out;\n\t}\n\n\t/* ---------------- SDK bootstrap (called by module) ---------------- */\n\n\t/**\n\t * Initialize the OpenTelemetry SDK with the given configuration.\n\t * This is called by `TracingModule.forRoot()`. It's idempotent.\n\t */\n\tasync startSdk(config: import(\"./types.js\").TracingConfig): Promise<void> {\n\t\tif (this.initialized) return;\n\n\t\tconst serviceName = config.serviceName ?? process.env.OTEL_SERVICE_NAME ?? \"nexusjs\";\n\t\tconst endpoint = config.endpoint ?? process.env.OTEL_EXPORTER_OTLP_ENDPOINT ?? \"http://localhost:4318\";\n\t\tconst sampleRatio = config.sampleRatio ?? 1.0;\n\n\t\t// Lazy import the SDK so apps that don't use tracing don't pay the cost.\n\t\t// The SDK packages are optional peer dependencies; we resolve them\n\t\t// dynamically so users who don't trace don't need them.\n\t\tlet NodeSDK: any, OTLPTraceExporter: any, Resource: any, SemanticResourceAttributes: any;\n\t\ttry {\n\t\t\t// @ts-ignore - optional peer dep\n\t\t\t({ NodeSDK } = await import(\"@opentelemetry/sdk-node\"));\n\t\t\t// @ts-ignore - optional peer dep\n\t\t\t({ OTLPTraceExporter } = await import(\"@opentelemetry/exporter-trace-otlp-http\"));\n\t\t\t// @ts-ignore - optional peer dep\n\t\t\t({ Resource } = await import(\"@opentelemetry/resources\"));\n\t\t\tconst semconv = await import(\"@opentelemetry/semantic-conventions\");\n\t\t\tSemanticResourceAttributes = (semconv as any).SemanticResourceAttributes ?? semconv;\n\t\t} catch (err) {\n\t\t\tthrow new Error(\n\t\t\t\t\"TracingModule.forRoot() requires the OTel SDK packages. \" +\n\t\t\t\t\t\"Install with: bun add @opentelemetry/sdk-node @opentelemetry/exporter-trace-otlp-http @opentelemetry/resources @opentelemetry/semantic-conventions\",\n\t\t\t);\n\t\t}\n\n\t\t// Build the resource\n\t\tconst resourceAttrs: Record<string, string> = {\n\t\t\t[SemanticResourceAttributes.SERVICE_NAME ?? \"service.name\"]: serviceName,\n\t\t\t[SemanticResourceAttributes.SERVICE_VERSION ?? \"service.version\"]:\n\t\t\t\tconfig.serviceVersion ?? \"0.0.0\",\n\t\t\t[SemanticResourceAttributes.DEPLOYMENT_ENVIRONMENT ?? \"deployment.environment\"]:\n\t\t\t\tconfig.environment ?? process.env.NODE_ENV ?? \"development\",\n\t\t\t...config.resourceAttributes,\n\t\t};\n\t\tconst resource = new Resource(resourceAttrs);\n\n\t\t// Pick the exporter\n\t\tlet traceExporter: any;\n\t\tif (config.exporter === \"console\" || config.exporter === \"memory\" || !config.exporter) {\n\t\t\t// Console exporter: print to stdout. (Bun has no in-process\n\t\t\t// console exporter, so we use a simple OTel-compatible one\n\t\t\t// via the in-memory recorder.)\n\t\t\ttraceExporter = undefined; // We use the recorder for the in-memory case\n\t\t} else {\n\t\t\ttraceExporter = new OTLPTraceExporter({ url: `${endpoint.replace(/\\/$/, \"\")}/v1/traces` });\n\t\t}\n\n\t\t// Build the SDK\n\t\tconst sdk = new NodeSDK({\n\t\t\tresource,\n\t\t\ttraceExporter,\n\t\t\tsampler: {\n\t\t\t\t// Custom simple ratio sampler to avoid pulling the full sampler package.\n\t\t\t\tshouldSample: () => ({\n\t\t\t\t\tdecision: Math.random() < sampleRatio ? 1 : 0,\n\t\t\t\t}),\n\t\t\t\ttoString: () => `RatioSampler(${sampleRatio})`,\n\t\t\t},\n\t\t});\n\t\tsdk.start();\n\n\t\tthis.sdkStop = async () => {\n\t\t\ttry {\n\t\t\t\tawait sdk.shutdown();\n\t\t\t} catch {\n\t\t\t\t/* ignore shutdown errors */\n\t\t\t}\n\t\t};\n\n\t\tthis.initialized = true;\n\t}\n\n\t/** Stop the SDK. Called on process exit / app shutdown. */\n\tasync stopSdk(): Promise<void> {\n\t\tif (this.sdkStop) {\n\t\t\tawait this.sdkStop();\n\t\t\tthis.sdkStop = undefined;\n\t\t}\n\t\tthis.initialized = false;\n\t}\n}\n\n/* ------------------------------------------------------------------ *\n * Helpers\n * ------------------------------------------------------------------ */\n\nfunction toOtelKind(kind: NonNullable<SpanOptions[\"kind\"]>): SpanKind {\n\tswitch (kind) {\n\t\tcase \"server\":\n\t\t\treturn SpanKind.SERVER;\n\t\tcase \"client\":\n\t\t\treturn SpanKind.CLIENT;\n\t\tcase \"producer\":\n\t\t\treturn SpanKind.PRODUCER;\n\t\tcase \"consumer\":\n\t\t\treturn SpanKind.CONSUMER;\n\t\tdefault:\n\t\t\treturn SpanKind.INTERNAL;\n\t}\n}\n\nfunction flattenHeaders(\n\theaders: Record<string, string | string[] | undefined>,\n): Record<string, string> {\n\tconst out: Record<string, string> = {};\n\tfor (const [k, v] of Object.entries(headers)) {\n\t\tif (v === undefined) continue;\n\t\tout[k.toLowerCase()] = Array.isArray(v) ? v.join(\",\") : v;\n\t}\n\treturn out;\n}\n\n/** Re-export for downstream type users. */\nexport type { SpanContext, SpanStatus };\n",
+    "/**\n * `TracingModule` — wires up `TracingService` into the DI container\n * and (optionally) installs the Hono auto-instrumentation middleware.\n *\n * Usage:\n *   @Module({\n *     imports: [TracingModule.forRoot({\n *       serviceName: \"my-app\",\n *       exporter: \"otlp-http\",\n *       endpoint: \"http://otel-collector:4318\",\n *       sampleRatio: 0.1,\n *     })],\n *   })\n *   class AppModule {}\n *\n * When `forRoot()` is called:\n * 1. The OTel SDK is started (lazy `import()` of the SDK packages).\n * 2. The Hono `tracingMiddleware` is installed in the framework's\n *    HTTP server (when `enableHttpInstrumentation !== false`).\n * 3. The `TracingService` becomes the active global service that\n *    `@Trace()` decorators read from.\n *\n * When `forRoot()` is **not** called, `nexusjs/tracing` is a no-op:\n *   - `TracingService` instances use OTel's default no-op tracer.\n *   - `@Trace()` returns the original method unchanged.\n *   - No SDK packages are loaded.\n */\n\nimport { Inject, Injectable, Module } from \"@nexusts/core\";\nimport type { MiddlewareHandler } from \"hono\";\nimport { TracingService, TRACING_SERVICE_TOKEN, setTracingService } from \"./service.js\";\nimport { tracingMiddleware } from \"./hono-instrumentation.js\";\nimport type { TracingConfig } from \"./types.js\";\n\nexport const TRACING_CONFIG_TOKEN = Symbol.for(\"nexus:TracingConfig\");\n\n@Injectable()\nexport class TracingConfigHolder {\n\tconstructor(@Inject(TRACING_CONFIG_TOKEN) public readonly config: Required<TracingConfig>) {}\n}\n\n@Injectable()\nexport class TracingServiceWithLifecycle extends TracingService {\n\tasync onApplicationBootstrap(): Promise<void> {\n\t\t// Will be set in the module factory; no-op here.\n\t}\n\n\tasync onApplicationShutdown(): Promise<void> {\n\t\tawait this.stopSdk();\n\t}\n}\n\n@Module({\n\tproviders: [\n\t\tTracingServiceWithLifecycle,\n\t\t{ provide: TRACING_SERVICE_TOKEN, useExisting: TracingServiceWithLifecycle },\n\t],\n\texports: [TracingServiceWithLifecycle, TRACING_SERVICE_TOKEN],\n})\nexport class TracingModule {\n\tstatic forRoot(config: TracingConfig = {}) {\n\t\tconst fullConfig: Required<TracingConfig> = {\n\t\t\tserviceName: config.serviceName ?? process.env.OTEL_SERVICE_NAME ?? \"nexusjs\",\n\t\t\tserviceVersion: config.serviceVersion ?? \"0.0.0\",\n\t\t\tenvironment: config.environment ?? process.env.NODE_ENV ?? \"development\",\n\t\t\texporter: config.exporter ?? \"otlp-http\",\n\t\t\tendpoint: config.endpoint ?? process.env.OTEL_EXPORTER_OTLP_ENDPOINT ?? \"http://localhost:4318\",\n\t\t\tsampleRatio: config.sampleRatio ?? 1.0,\n\t\t\tenableHttpInstrumentation: config.enableHttpInstrumentation ?? true,\n\t\t\tenableDbInstrumentation: config.enableDbInstrumentation ?? true,\n\t\t\tresourceAttributes: config.resourceAttributes ?? {},\n\t\t\tthrowOnError: config.throwOnError ?? false,\n\t\t};\n\n\t\t@Module({\n\t\t\tproviders: [\n\t\t\t\tTracingServiceWithLifecycle,\n\t\t\t\t{ provide: TRACING_CONFIG_TOKEN, useValue: fullConfig },\n\t\t\t\t{ provide: TRACING_SERVICE_TOKEN, useExisting: TracingServiceWithLifecycle },\n\t\t\t],\n\t\t\texports: [TracingServiceWithLifecycle, TRACING_CONFIG_TOKEN, TRACING_SERVICE_TOKEN],\n\t\t})\n\t\tclass ConfiguredTracingModule {\n\t\t\tconstructor(@Inject(TracingServiceWithLifecycle) private svc: TracingServiceWithLifecycle) {\n\t\t\t\t// Side-effect: start the SDK & register the global.\n\t\t\t\tvoid svc.startSdk(fullConfig);\n\t\t\t\tsetTracingService(svc);\n\t\t\t}\n\t\t}\n\t\tObject.defineProperty(ConfiguredTracingModule, \"name\", { value: \"ConfiguredTracingModule\" });\n\n\t\t// Return both the module class and a helper for installing the\n\t\t// Hono middleware (for users who want to use `nexusjs/tracing` with\n\t\t// a custom Hono app, not the framework's HTTP server).\n\t\tconst mod = ConfiguredTracingModule as unknown as Function & {\n\t\t\tmiddleware: () => MiddlewareHandler;\n\t\t};\n\t\tmod.middleware = () => {\n\t\t\tconst svc = new TracingService();\n\t\t\tsetTracingService(svc);\n\t\t\treturn tracingMiddleware(svc);\n\t\t};\n\n\t\treturn mod;\n\t}\n}\n",
+    "/**\n * Hono auto-instrumentation for `nexusjs/tracing`.\n *\n * Returns a Hono middleware that:\n * 1. Extracts the incoming trace context (W3C `traceparent`).\n * 2. Starts a `SERVER` span with HTTP method, route, target, etc.\n * 3. Records the response status, body size, and any thrown error.\n *\n * The middleware is a no-op when the SDK is not configured: the\n * OTel API returns a no-op span that immediately ends, but the\n * `traceparent` is still parsed for the response.\n */\n\nimport { SpanKind, SpanStatusCode, trace, type Context } from \"@opentelemetry/api\";\nimport type { MiddlewareHandler } from \"hono\";\nimport type { TracingService } from \"./service.js\";\n\nexport function tracingMiddleware(service: TracingService): MiddlewareHandler {\n\treturn async (c, next) => {\n\t\tconst incoming = c.req.raw.headers;\n\t\tconst flat: Record<string, string> = {};\n\t\tincoming.forEach((v, k) => (flat[k] = v));\n\t\tconst extractedCtx: Context = service.extractContext(flat);\n\n\t\tconst method = c.req.method;\n\t\tconst path = c.req.path;\n\t\tconst route = c.req.routePath ?? path;\n\t\tconst userAgent = c.req.header(\"user-agent\") ?? \"\";\n\t\tconst url = new URL(c.req.url);\n\t\tconst clientIp = c.req.header(\"x-forwarded-for\") ?? c.req.header(\"x-real-ip\") ?? \"\";\n\n\t\tconst span = service.tracer.startSpan(\n\t\t\t`HTTP ${method} ${route}`,\n\t\t\t{\n\t\t\t\tkind: SpanKind.SERVER,\n\t\t\t\tattributes: {\n\t\t\t\t\t\"http.method\": method,\n\t\t\t\t\t\"http.target\": path,\n\t\t\t\t\t\"http.route\": route,\n\t\t\t\t\t\"http.scheme\": url.protocol.replace(\":\", \"\"),\n\t\t\t\t\t\"http.host\": url.host,\n\t\t\t\t\t\"http.user_agent\": userAgent,\n\t\t\t\t\t\"http.client_ip\": clientIp,\n\t\t\t\t\t\"url.path\": path,\n\t\t\t\t},\n\t\t\t},\n\t\t\textractedCtx,\n\t\t);\n\n\t\tconst ctxWithSpan = trace.setSpan(extractedCtx, span);\n\t\tconst result = await service.tracer.startActiveSpan(\n\t\t\t`HTTP ${method} ${route} handler`,\n\t\t\t{ kind: SpanKind.SERVER },\n\t\t\tctxWithSpan,\n\t\t\tasync () => {\n\t\t\t\ttry {\n\t\t\t\t\tawait next();\n\t\t\t\t\tconst status = c.res.status;\n\t\t\t\t\tspan.setAttribute(\"http.status_code\", status);\n\t\t\t\t\tif (status >= 500) {\n\t\t\t\t\t\tspan.setStatus({ code: SpanStatusCode.ERROR });\n\t\t\t\t\t} else {\n\t\t\t\t\t\tspan.setStatus({ code: SpanStatusCode.OK });\n\t\t\t\t\t}\n\t\t\t\t} catch (err) {\n\t\t\t\t\tspan.recordException(err as Error);\n\t\t\t\t\tspan.setStatus({ code: SpanStatusCode.ERROR, message: (err as Error).message });\n\t\t\t\t\tspan.setAttribute(\"http.status_code\", 500);\n\t\t\t\t\tthrow err;\n\t\t\t\t} finally {\n\t\t\t\t\tspan.end();\n\t\t\t\t}\n\t\t\t},\n\t\t);\n\t\treturn result as never;\n\t};\n}\n\n/**\n * Inject the active trace context into an outgoing fetch / response.\n * Use in fetch() calls so downstream services pick up the trace.\n */\nexport function injectOutgoingTraceparent(\n\tservice: TracingService,\n\theaders: Record<string, string> = {},\n): Record<string, string> {\n\treturn service.injectContext(headers);\n}\n",
+    "/**\n * W3C Trace Context propagation.\n *\n * The OTel API ships a default W3C propagator, so most use cases\n * don't need anything here. This file provides:\n * 1. Constants for header names.\n * 2. Helpers to format / parse a `traceparent` value.\n * 3. A simple B3 single-header propagator for legacy systems.\n *\n * Format reference: https://www.w3.org/TR/trace-context/#traceparent-header\n */\n\nimport { propagation, context, type Context } from \"@opentelemetry/api\";\n\n/* ------------------------------------------------------------------ *\n * Header constants\n * ------------------------------------------------------------------ */\n\nexport const TRACE_PARENT_HEADER = \"traceparent\";\nexport const TRACE_STATE_HEADER = \"tracestate\";\nexport const B3_TRACE_ID_HEADER = \"x-b3-traceid\";\nexport const B3_SPAN_ID_HEADER = \"x-b3-spanid\";\nexport const B3_SAMPLED_HEADER = \"x-b3-sampled\";\n\n/* ------------------------------------------------------------------ *\n * traceparent parser\n * ------------------------------------------------------------------ */\n\nexport interface ParsedTraceParent {\n\t/** \"00\" (version 0) for now. */\n\tversion: string;\n\t/** Full trace id (32 hex chars). */\n\ttraceId: string;\n\t/** Parent span id (16 hex chars). */\n\tparentSpanId: string;\n\t/** Trace flags byte, hex. */\n\tflags: string;\n\t/** True if the trace is sampled (flags bit 0 set). */\n\tsampled: boolean;\n}\n\n/**\n * Parse a `traceparent` header value.\n * Returns `undefined` if the value is malformed.\n */\nexport function parseTraceParent(value: string | undefined | null): ParsedTraceParent | undefined {\n\tif (!value) return undefined;\n\tconst parts = value.trim().split(\"-\");\n\tif (parts.length !== 4) return undefined;\n\tconst [version, traceId, parentSpanId, flags] = parts;\n\tif (!/^[0-9a-f]{2}$/i.test(version)) return undefined;\n\tif (!/^[0-9a-f]{32}$/i.test(traceId)) return undefined;\n\tif (traceId === \"0\".repeat(32)) return undefined;\n\tif (!/^[0-9a-f]{16}$/i.test(parentSpanId)) return undefined;\n\tif (parentSpanId === \"0\".repeat(16)) return undefined;\n\tif (!/^[0-9a-f]{2}$/i.test(flags)) return undefined;\n\treturn {\n\t\tversion,\n\t\ttraceId: traceId.toLowerCase(),\n\t\tparentSpanId: parentSpanId.toLowerCase(),\n\t\tflags: flags.toLowerCase(),\n\t\tsampled: (parseInt(flags, 16) & 0x01) === 0x01,\n\t};\n}\n\n/**\n * Format a `traceparent` value from a known context.\n *   `00-<traceId>-<spanId>-<flags>`\n */\nexport function formatTraceParent(traceId: string, spanId: string, sampled = true): string {\n\tconst flags = sampled ? \"01\" : \"00\";\n\treturn `00-${traceId.toLowerCase()}-${spanId.toLowerCase()}-${flags}`;\n}\n\n/* ------------------------------------------------------------------ *\n * B3 single-header helpers (legacy Zipkin)\n * ------------------------------------------------------------------ */\n\n/**\n * Extract context from a B3 single-header (`b3: <traceId>-<spanId>-1`).\n * Falls through to W3C if no B3 header is present.\n */\nexport function extractB3Context(\n\theaders: Record<string, string>,\n): { traceId: string; spanId: string; sampled: boolean } | undefined {\n\tconst b3 = headers[\"b3\"] ?? headers[\"x-b3-traceid\"];\n\tif (!b3) return undefined;\n\tif (b3.includes(\"-\")) {\n\t\t// b3 single header: \"traceId-spanId-sampled-parentSpanId\"\n\t\tconst [traceId, spanId, sampled] = b3.split(\"-\");\n\t\tif (traceId && spanId) {\n\t\t\treturn { traceId, spanId, sampled: sampled === \"1\" };\n\t\t}\n\t} else {\n\t\t// x-b3-traceid + x-b3-spanid pair\n\t\tconst spanId = headers[\"x-b3-spanid\"];\n\t\tconst sampled = headers[\"x-b3-sampled\"] === \"1\";\n\t\tif (spanId) return { traceId: b3, spanId, sampled };\n\t}\n\treturn undefined;\n}\n\n/* ------------------------------------------------------------------ *\n * Re-export OTel's propagation API\n * ------------------------------------------------------------------ */\n\n/** Inject the active context into the given carrier. */\nexport function inject(headers: Record<string, string>): Record<string, string> {\n\tconst out: Record<string, string> = { ...headers };\n\tpropagation.inject(context.active(), out);\n\treturn out;\n}\n\n/** Extract a context from a header carrier. */\nexport function extract(headers: Record<string, string>): Context {\n\treturn propagation.extract(context.active(), headers);\n}\n",
+    "/**\n * `@Trace()` — class-method decorator that wraps the call in a span.\n *\n * Usage:\n *   class UserService {\n *     @Trace()                  // span name = class.method\n *     async findById(id: string) { ... }\n *\n *     @Trace(\"user.lookup\")     // explicit span name\n *     async lookup(name: string) { ... }\n *\n *     @Trace({ name: \"user.cache.get\", attributes: { cache: \"lru\" } })\n *     async getFromCache(key: string) { ... }\n *   }\n *\n * The decorator reads the `TracingService` from the global registry\n * (set by `TracingModule.forRoot()`). When no service is registered\n * the decorator is a pass-through.\n *\n * Sync methods stay sync; async methods stay async. The decorator\n * detects `AsyncFunction` and uses `withSpan` / `withSpanSync` accordingly.\n */\n\nimport type { ActiveSpan, SpanOptions } from \"../types.js\";\nimport { getTracingService } from \"../service.js\";\n\nexport type TraceOptions =\n\t| string\n\t| undefined\n\t| (SpanOptions & { name: string });\n\nconst TRACE_KEY = Symbol.for(\"nexus:trace:options\");\n\n/**\n * Method decorator: wrap a call in a span.\n *\n * The decorator works on both async and sync methods. The wrapped\n * function preserves `this` so decorators on classes still see the\n * right instance.\n */\nexport function Trace(opts?: TraceOptions) {\n\treturn function (target: object, propertyKey: string | symbol, descriptor: PropertyDescriptor) {\n\t\tconst original = descriptor.value as (...args: unknown[]) => unknown;\n\t\tif (typeof original !== \"function\") {\n\t\t\tthrow new Error(`@Trace() can only be applied to methods, got ${typeof original}`);\n\t\t}\n\n\t\tconst options = normalizeOptions(opts ?? {}, target, propertyKey);\n\t\t(target as any)[TRACE_KEY] = (target as any)[TRACE_KEY] ?? {};\n\t\t(target as any)[TRACE_KEY][String(propertyKey)] = options;\n\n\t\tconst isAsync = (original as any).constructor?.name === \"AsyncFunction\";\n\n\t\tif (isAsync) {\n\t\t\tdescriptor.value = async function wrapped(this: unknown, ...args: unknown[]) {\n\t\t\t\tconst service = getTracingService();\n\t\t\t\tif (!service) return original.apply(this, args);\n\t\t\t\treturn service.withSpan(\n\t\t\t\t\toptions.name,\n\t\t\t\t\tasync (span: ActiveSpan) => {\n\t\t\t\t\t\tif (options.attributes) span.setAttributes(options.attributes!);\n\t\t\t\t\t\treturn original.apply(this, args);\n\t\t\t\t\t},\n\t\t\t\t\t{ kind: options.kind ?? \"internal\", attributes: options.attributes },\n\t\t\t\t);\n\t\t\t};\n\t\t} else {\n\t\t\tdescriptor.value = function wrapped(this: unknown, ...args: unknown[]) {\n\t\t\t\tconst service = getTracingService();\n\t\t\t\tif (!service) return original.apply(this, args);\n\t\t\t\treturn service.withSpanSync(\n\t\t\t\t\toptions.name,\n\t\t\t\t\t(span: ActiveSpan) => {\n\t\t\t\t\t\tif (options.attributes) span.setAttributes(options.attributes!);\n\t\t\t\t\t\treturn original.apply(this, args);\n\t\t\t\t\t},\n\t\t\t\t\t{ kind: options.kind ?? \"internal\", attributes: options.attributes },\n\t\t\t\t);\n\t\t\t};\n\t\t}\n\t\treturn descriptor;\n\t};\n}\n\n/** Read the @Trace options for a given method (used by OpenAPI integration). */\nexport function getTraceOptions(target: object, method: string): TraceOptions | undefined {\n\treturn (target as any)[TRACE_KEY]?.[method];\n}\n\nfunction normalizeOptions(\n\topts: TraceOptions | object,\n\ttarget: object,\n\tpropertyKey: string | symbol,\n): { name: string; kind: NonNullable<SpanOptions[\"kind\"]>; attributes?: SpanOptions[\"attributes\"] } {\n\tif (typeof opts === \"string\") {\n\t\treturn { name: opts, kind: \"internal\" };\n\t}\n\tif (opts && typeof opts === \"object\" && \"name\" in opts && (opts as any).name) {\n\t\tconst o = opts as { name: string; kind?: SpanOptions[\"kind\"]; attributes?: SpanOptions[\"attributes\"] };\n\t\treturn {\n\t\t\tname: o.name,\n\t\t\tkind: o.kind ?? \"internal\",\n\t\t\tattributes: o.attributes,\n\t\t};\n\t}\n\t// Default: use \"ClassName.methodName\"\n\tconst cls = (target as any)?.constructor?.name ?? \"Anonymous\";\n\treturn {\n\t\tname: `${cls}.${String(propertyKey)}`,\n\t\tkind: \"internal\",\n\t};\n}\n"
+  ],
+  "mappings": "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",
+  "debugId": "283916FBDA13049264756E2164756E21",
+  "names": []
+}

package/dist/module.d.ts

@@ -0,0 +1,44 @@
+/**
+ * `TracingModule` — wires up `TracingService` into the DI container
+ * and (optionally) installs the Hono auto-instrumentation middleware.
+ *
+ * Usage:
+ *   @Module({
+ *     imports: [TracingModule.forRoot({
+ *       serviceName: "my-app",
+ *       exporter: "otlp-http",
+ *       endpoint: "http://otel-collector:4318",
+ *       sampleRatio: 0.1,
+ *     })],
+ *   })
+ *   class AppModule {}
+ *
+ * When `forRoot()` is called:
+ * 1. The OTel SDK is started (lazy `import()` of the SDK packages).
+ * 2. The Hono `tracingMiddleware` is installed in the framework's
+ *    HTTP server (when `enableHttpInstrumentation !== false`).
+ * 3. The `TracingService` becomes the active global service that
+ *    `@Trace()` decorators read from.
+ *
+ * When `forRoot()` is **not** called, `nexusjs/tracing` is a no-op:
+ *   - `TracingService` instances use OTel's default no-op tracer.
+ *   - `@Trace()` returns the original method unchanged.
+ *   - No SDK packages are loaded.
+ */
+import type { MiddlewareHandler } from "hono";
+import { TracingService } from "./service.js";
+import type { TracingConfig } from "./types.js";
+export declare const TRACING_CONFIG_TOKEN: unique symbol;
+export declare class TracingConfigHolder {
+    readonly config: Required<TracingConfig>;
+    constructor(config: Required<TracingConfig>);
+}
+export declare class TracingServiceWithLifecycle extends TracingService {
+    onApplicationBootstrap(): Promise<void>;
+    onApplicationShutdown(): Promise<void>;
+}
+export declare class TracingModule {
+    static forRoot(config?: TracingConfig): Function & {
+        middleware: () => MiddlewareHandler;
+    };
+}

package/dist/propagation.d.ts

@@ -0,0 +1,52 @@
+/**
+ * W3C Trace Context propagation.
+ *
+ * The OTel API ships a default W3C propagator, so most use cases
+ * don't need anything here. This file provides:
+ * 1. Constants for header names.
+ * 2. Helpers to format / parse a `traceparent` value.
+ * 3. A simple B3 single-header propagator for legacy systems.
+ *
+ * Format reference: https://www.w3.org/TR/trace-context/#traceparent-header
+ */
+import { type Context } from "@opentelemetry/api";
+export declare const TRACE_PARENT_HEADER = "traceparent";
+export declare const TRACE_STATE_HEADER = "tracestate";
+export declare const B3_TRACE_ID_HEADER = "x-b3-traceid";
+export declare const B3_SPAN_ID_HEADER = "x-b3-spanid";
+export declare const B3_SAMPLED_HEADER = "x-b3-sampled";
+export interface ParsedTraceParent {
+    /** "00" (version 0) for now. */
+    version: string;
+    /** Full trace id (32 hex chars). */
+    traceId: string;
+    /** Parent span id (16 hex chars). */
+    parentSpanId: string;
+    /** Trace flags byte, hex. */
+    flags: string;
+    /** True if the trace is sampled (flags bit 0 set). */
+    sampled: boolean;
+}
+/**
+ * Parse a `traceparent` header value.
+ * Returns `undefined` if the value is malformed.
+ */
+export declare function parseTraceParent(value: string | undefined | null): ParsedTraceParent | undefined;
+/**
+ * Format a `traceparent` value from a known context.
+ *   `00-<traceId>-<spanId>-<flags>`
+ */
+export declare function formatTraceParent(traceId: string, spanId: string, sampled?: boolean): string;
+/**
+ * Extract context from a B3 single-header (`b3: <traceId>-<spanId>-1`).
+ * Falls through to W3C if no B3 header is present.
+ */
+export declare function extractB3Context(headers: Record<string, string>): {
+    traceId: string;
+    spanId: string;
+    sampled: boolean;
+} | undefined;
+/** Inject the active context into the given carrier. */
+export declare function inject(headers: Record<string, string>): Record<string, string>;
+/** Extract a context from a header carrier. */
+export declare function extract(headers: Record<string, string>): Context;

package/dist/service.d.ts

@@ -0,0 +1,94 @@
+/**
+ * `TracingService` — the framework's distributed-tracing primitive.
+ *
+ * Design:
+ * 1. The OpenTelemetry API (`@opentelemetry/api`) is the only
+ *    required dependency; it's ~7kb and provides the no-op default
+ *    tracer when the SDK is not configured.
+ * 2. The OTel SDK is **lazy-loaded**: only when the user calls
+ *    `TracingModule.forRoot(...)` is `@opentelemetry/sdk-node` and
+ *    the configured exporter imported. This keeps the bundle small
+ *    for users who don't trace.
+ * 3. Without `forRoot()`, the service returns no-op spans. They have
+ *    valid `traceId` / `spanId` (the OTel no-op span id format) so
+ *    log lines and error reports don't need to special-case "not
+ *    configured".
+ *
+ * Public API:
+ * - `startSpan(name, options?)` — create a new active span
+ * - `withSpan(name, fn, options?)` — run `fn` inside a span, return its result
+ * - `getCurrentTraceId()` / `getCurrentSpanId()` — read the active context
+ * - `extractContext(headers)` / `injectContext(headers)` — W3C trace context
+ * - `getSpans()` — read the in-memory span recorder (always available,
+ *   used for tests and for the `console` exporter)
+ * - `reset()` — clear the in-memory recorder
+ *
+ * The service is registered in the DI container as a singleton. The
+ * framework does **not** call `trace.getTracer` until something
+ * actually starts a span.
+ */
+import { type Context, type Tracer } from "@opentelemetry/api";
+import type { ActiveSpan, FinishedSpan, SpanContext, SpanOptions, SpanStatus } from "./types.js";
+export declare class InMemorySpanRecorder {
+    private finished;
+    private nextEventCounter;
+    /** Append a finished span. */
+    record(span: FinishedSpan): void;
+    /** Return all finished spans (most recent last). */
+    getAll(): FinishedSpan[];
+    /** Return only the spans whose `name` matches. */
+    findByName(name: string): FinishedSpan[];
+    /** Clear the recorder. */
+    clear(): void;
+    /** Number of recorded spans. */
+    get size(): number;
+}
+export declare const TRACING_SERVICE_TOKEN: unique symbol;
+export declare function setTracingService(service: TracingService): void;
+export declare function getTracingService(): TracingService | undefined;
+export declare class TracingService {
+    readonly tracer: Tracer;
+    private readonly recorder;
+    private sdkStop?;
+    private initialized;
+    constructor();
+    /** True if the SDK has been started (i.e. `forRoot()` was called). */
+    get isInitialized(): boolean;
+    /** Read all finished spans recorded so far. */
+    getSpans(): FinishedSpan[];
+    /** Find spans by name. */
+    findSpans(name: string): FinishedSpan[];
+    /** Clear the in-memory recorder (and the SDK's batch, if any). */
+    clearSpans(): void;
+    startSpan(name: string, options?: SpanOptions): ActiveSpan;
+    /** Run `fn` inside a new span. Returns the result of `fn`. */
+    withSpan<T>(name: string, fn: (span: ActiveSpan) => Promise<T> | T, options?: SpanOptions): Promise<T>;
+    /** Synchronous version of `withSpan`. */
+    withSpanSync<T>(name: string, fn: (span: ActiveSpan) => T, options?: SpanOptions): T;
+    /** Get the trace id of the active span, or `undefined`. */
+    getCurrentTraceId(): string | undefined;
+    /** Get the span id of the active span, or `undefined`. */
+    getCurrentSpanId(): string | undefined;
+    /** Get the current OTel `Context`. */
+    getCurrentContext(): Context;
+    /**
+     * Extract a span context from incoming HTTP headers.
+     * Reads `traceparent` (W3C) and `x-b3-*` (B3 single) when present.
+     * Returns `undefined` if no recognizable header is found.
+     */
+    extractContext(headers: Record<string, string | string[] | undefined>): Context;
+    /**
+     * Inject the active span context into outgoing HTTP headers.
+     * Writes `traceparent` (W3C) by default.
+     */
+    injectContext(headers?: Record<string, string>): Record<string, string>;
+    /**
+     * Initialize the OpenTelemetry SDK with the given configuration.
+     * This is called by `TracingModule.forRoot()`. It's idempotent.
+     */
+    startSdk(config: import("./types.js").TracingConfig): Promise<void>;
+    /** Stop the SDK. Called on process exit / app shutdown. */
+    stopSdk(): Promise<void>;
+}
+/** Re-export for downstream type users. */
+export type { SpanContext, SpanStatus };

package/dist/types.d.ts

@@ -0,0 +1,89 @@
+/**
+ * Public types for `nexusjs/tracing`.
+ *
+ * `nexusjs/tracing` is a thin, ergonomic wrapper around the
+ * OpenTelemetry API (and, when configured, the SDK). It is
+ * intentionally minimal — no global side effects on import.
+ *
+ * If you don't import `TracingModule.forRoot()`, this module
+ * is a complete no-op: no OpenTelemetry packages are loaded
+ * and `TracingService` falls back to in-memory no-op spans.
+ */
+import type { SpanContext as OtelSpanContext } from "@opentelemetry/api";
+export type TracingExporter = "otlp-http" | "otlp-grpc" | "console" | "memory";
+export interface TracingConfig {
+    /** Service name reported in spans. Defaults to `process.env.OTEL_SERVICE_NAME ?? "nexusjs"`. */
+    serviceName?: string;
+    /** Service version (sent as `service.version` resource attribute). */
+    serviceVersion?: string;
+    /** Deployment environment (e.g. "production", "staging"). */
+    environment?: string;
+    /** Exporter to use. Default: `"otlp-http"`. */
+    exporter?: TracingExporter;
+    /** OTLP endpoint. Default: `process.env.OTEL_EXPORTER_OTLP_ENDPOINT ?? "http://localhost:4318"`. */
+    endpoint?: string;
+    /** Sampling ratio in [0, 1]. 0.0 = drop everything, 1.0 = keep everything. Default: `1.0`. */
+    sampleRatio?: number;
+    /** Whether to install the Hono HTTP server middleware. Default: `true`. */
+    enableHttpInstrumentation?: boolean;
+    /** Whether to capture DB spans via `nexusjs/drizzle` (if installed). Default: `true`. */
+    enableDbInstrumentation?: boolean;
+    /** Extra static resource attributes (service.namespace, deployment.id, ...). */
+    resourceAttributes?: Record<string, string>;
+    /** When true, exit process on uncaught span error. Default: `false`. */
+    throwOnError?: boolean;
+}
+/** Public-facing span context (mirrors OTel's, but vendor-neutral). */
+export interface SpanContext extends OtelSpanContext {
+}
+/** Status of a span — mirrors OTel's `SpanStatusCode`. */
+export type SpanStatus = "unset" | "ok" | "error";
+/** A finished span, returned from `withSpan()` / `endSpan()`. */
+export interface FinishedSpan {
+    readonly name: string;
+    readonly traceId: string;
+    readonly spanId: string;
+    readonly parentSpanId?: string;
+    readonly startTime: number;
+    readonly endTime: number;
+    readonly durationMs: number;
+    readonly status: SpanStatus;
+    readonly attributes: Record<string, string | number | boolean>;
+    readonly events: Array<{
+        name: string;
+        time: number;
+        attributes?: Record<string, unknown>;
+    }>;
+}
+/** Per-span options. */
+export interface SpanOptions {
+    /** Span kind. Default: `"internal"`. */
+    kind?: "server" | "client" | "producer" | "consumer" | "internal";
+    /** Initial attributes. */
+    attributes?: Record<string, string | number | boolean>;
+    /** Span start time override (epoch ms). */
+    startTime?: number;
+}
+/** Active span handle returned from `startSpan()`. */
+export interface ActiveSpan {
+    /** Span name. */
+    readonly name: string;
+    /** Current trace id (32 hex chars). */
+    readonly traceId: string;
+    /** Current span id (16 hex chars). */
+    readonly spanId: string;
+    /** True if the underlying OTel span is a no-op (no SDK configured). */
+    readonly isRecording: boolean;
+    /** Set an attribute. */
+    setAttribute(key: string, value: string | number | boolean): void;
+    /** Set multiple attributes at once. */
+    setAttributes(attributes: Record<string, string | number | boolean>): void;
+    /** Record an event with optional attributes. */
+    addEvent(name: string, attributes?: Record<string, unknown>): void;
+    /** Record an exception. */
+    recordException(err: unknown): void;
+    /** Set the span status to "ok" with an optional description. */
+    setStatus(status: "ok" | "error" | "unset", description?: string): void;
+    /** End the span. After calling, no other methods are valid. */
+    end(): void;
+}

package/package.json

@@ -0,0 +1,26 @@
+{
+  "name": "@nexusts/tracing",
+  "version": "0.7.2",
+  "description": "OpenTelemetry distributed tracing",
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": ["dist", "README.md"],
+  "scripts": {
+    "build": "bun run ../../build.ts"
+  },
+  "keywords": ["nexusts", "framework", "bun"],
+  "license": "MIT",
+  "peerDependencies": { "@opentelemetry/api": "^1.9.0" },
+  "peerDependenciesMeta": { "@opentelemetry/api": { "optional": true } },
+  "dependencies": {
+    "@nexusts/core": "file:../core"
+  }
+}