autotel 4.3.0 → 5.0.0

package/dist/testing.js.map

@@ -1 +1 @@
-{"version":3,"file":"testing.js","names":["otelTrace"],"sources":["../src/testing.ts"],"sourcesContent":["/**\n * Testing Utilities\n *\n * Helpers for testing instrumented code and verifying telemetry.\n * Perfect for integration tests and QA in production validation.\n *\n * @example Verify traces are created\n * ```typescript\n * import { assertTraceCreated, collectTraces } from '@your-org/otel-decorators/testing'\n *\n * describe('UserService', () => {\n *   it('should create trace for user creation', async () => {\n *     const collector = collectTraces()\n *\n *     const service = new UserService()\n *     await service.createUser({ email: 'test@example.com' })\n *\n *     assertTraceCreated(collector, 'user.createUser')\n *   })\n * })\n * ```\n */\n\nimport {\n  SpanStatusCode,\n  type SpanStatus,\n  type Attributes,\n  type AttributeValue,\n  context,\n  trace as otelTrace,\n  type Span,\n  type SpanContext,\n  type TimeInput,\n  type Exception,\n  type SpanOptions,\n  type Context as OtelContext,\n  type Tracer,\n} from '@opentelemetry/api';\nimport { type Logger } from './logger';\nimport { configure } from './config';\n\n// Re-export events testing utilities\nexport {\n  createEventCollector,\n  assertEventTracked,\n  assertOutcomeTracked,\n  type EventCollector,\n  type EventData,\n  type EventsFunnelStep,\n  type EventsOutcome,\n  type EventsValue,\n} from './event-testing';\n\n/**\n * Note: OpenTelemetry exporters and processors have moved to dedicated modules\n * for better semantic clarity.\n *\n * For exporters (ConsoleSpanExporter, InMemorySpanExporter):\n * @see {@link autotel/exporters}\n *\n * For processors (SimpleSpanProcessor, BatchSpanProcessor):\n * @see {@link autotel/processors}\n *\n * This module focuses on high-level testing utilities with assertion helpers\n * and trace collectors.\n *\n * @example High-level testing (recommended)\n * ```typescript\n * import { createTraceCollector, assertTraceCreated } from 'autotel/testing'\n *\n * const collector = createTraceCollector()\n * await myService.doSomething()\n * assertTraceCreated(collector, 'myService.doSomething')\n * ```\n *\n * @example Low-level testing (when you need raw OTel spans)\n * ```typescript\n * import { InMemorySpanExporter } from 'autotel/exporters'\n * import { SimpleSpanProcessor } from 'autotel/processors'\n *\n * const exporter = new InMemorySpanExporter()\n * init({ service: 'test', spanProcessor: new SimpleSpanProcessor(exporter) })\n * ```\n */\n\n/**\n * Simplified span representation for testing\n */\nexport interface TestSpan {\n  name: string;\n  status: SpanStatus;\n  attributes: Attributes;\n  startTime: number;\n  endTime: number;\n  duration: number;\n}\n\n/**\n * In-memory trace collector for testing\n */\nexport interface TraceCollector {\n  /** Get all collected spans */\n  getSpans(): TestSpan[];\n  /** Get spans matching a name */\n  getSpansByName(name: string): TestSpan[];\n  /** Get spans matching attributes */\n  getSpansByAttributes(attributes: Record<string, unknown>): TestSpan[];\n  /** Clear all collected spans */\n  clear(): void;\n  /** Record a span (internal use) */\n  recordSpan(span: TestSpan): void;\n}\n\n/**\n * Create an in-memory trace collector for testing\n *\n * IMPORTANT: This automatically configures the global tracer to record spans.\n * Call this in your test's beforeEach() to ensure proper setup.\n *\n * @example\n * ```typescript\n * import { createTraceCollector } from 'autotel/testing'\n *\n * describe('MyService', () => {\n *   let collector: TraceCollector\n *\n *   beforeEach(() => {\n *     collector = createTraceCollector()\n *   })\n *\n *   it('should trace operations', async () => {\n *     await myService.doSomething()\n *\n *     const spans = collector.getSpansByName('myService.doSomething')\n *     expect(spans).toHaveLength(1)\n *   })\n * })\n * ```\n */\nexport function createTraceCollector(): TraceCollector {\n  const spans: TestSpan[] = [];\n\n  // Create mock span that captures data and implements full Span interface\n  const createMockSpan = (name: string, startTime: number): Span => {\n    const spanData: Partial<TestSpan> = {\n      name,\n      startTime,\n      attributes: {},\n      status: { code: SpanStatusCode.OK },\n    };\n\n    const spanContextData: SpanContext = {\n      traceId: '1234567890abcdef1234567890abcdef', // 128-bit trace ID (32 hex chars)\n      spanId: '1234567890abcdef', // 64-bit span ID (16 hex chars)\n      traceFlags: 1,\n      isRemote: false,\n    };\n\n    const mockSpan: Span = {\n      spanContext: () => spanContextData,\n\n      setStatus(status: SpanStatus) {\n        spanData.status = status;\n        return this;\n      },\n\n      setAttributes(attributes: Attributes) {\n        spanData.attributes = { ...spanData.attributes, ...attributes };\n        return this;\n      },\n\n      setAttribute(key: string, value: AttributeValue) {\n        spanData.attributes = spanData.attributes || {};\n        spanData.attributes[key] = value;\n        return this;\n      },\n\n      addEvent(\n        name: string,\n        attributesOrStartTime?: Attributes | TimeInput,\n        startTime?: TimeInput,\n      ) {\n        void name;\n        void attributesOrStartTime;\n        void startTime;\n        return this;\n      },\n\n      addLink(link: { context: SpanContext; attributes?: Attributes }) {\n        void link;\n        return this;\n      },\n\n      addLinks(\n        links: Array<{ context: SpanContext; attributes?: Attributes }>,\n      ) {\n        void links;\n        return this;\n      },\n\n      updateName(newName: string) {\n        spanData.name = newName;\n        return this;\n      },\n\n      isRecording() {\n        return true;\n      },\n\n      recordException(exception: Exception, time?: TimeInput) {\n        void exception;\n        void time;\n      },\n\n      end(endTimeArg?: TimeInput) {\n        void endTimeArg;\n        const endTime = performance.now();\n        spans.push({\n          name: spanData.name!,\n          status: spanData.status!,\n          attributes: spanData.attributes || {},\n          startTime: spanData.startTime!,\n          endTime,\n          duration: endTime - spanData.startTime!,\n        });\n      },\n    };\n\n    return mockSpan;\n  };\n\n  // Create mock tracer\n  const mockTracer: Tracer = {\n    startSpan(name: string, options?: SpanOptions, ctx?: OtelContext): Span {\n      void options;\n      void ctx;\n      const startTime = performance.now();\n      return createMockSpan(name, startTime);\n    },\n\n    startActiveSpan<F extends (span: Span) => unknown>(\n      name: string,\n      optionsOrFn: SpanOptions | F,\n      contextOrFn?: OtelContext | F,\n      fn?: F,\n    ): ReturnType<F> {\n      const callback = (() => {\n        if (typeof optionsOrFn === 'function') {\n          return optionsOrFn;\n        }\n        if (typeof contextOrFn === 'function') {\n          return contextOrFn;\n        }\n        if (fn) {\n          return fn;\n        }\n        throw new Error('startActiveSpan requires a callback');\n      })();\n\n      const startTime = performance.now();\n      const mockSpan = createMockSpan(name, startTime);\n\n      // Set span as active in context (makes otelTrace.getActiveSpan() work)\n      const ctx = otelTrace.setSpan(context.active(), mockSpan);\n      return context.with(ctx, () => callback(mockSpan)) as ReturnType<F>;\n    },\n  };\n\n  // Auto-configure global tracer\n  configure({ tracer: mockTracer });\n\n  return {\n    getSpans(): TestSpan[] {\n      return [...spans];\n    },\n\n    getSpansByName(name: string): TestSpan[] {\n      return spans.filter((span) => span.name === name);\n    },\n\n    getSpansByAttributes(attributes: Record<string, unknown>): TestSpan[] {\n      return spans.filter((span) => {\n        return Object.entries(attributes).every(\n          ([key, value]) => span.attributes[key] === value,\n        );\n      });\n    },\n\n    clear(): void {\n      spans.length = 0;\n    },\n\n    recordSpan(span: TestSpan): void {\n      spans.push(span);\n    },\n  };\n}\n\n/**\n * Assert that a trace was created for an operation\n *\n * @param collector - Trace collector\n * @param operationName - Expected operation name\n * @param options - Optional assertion options\n * @throws Error if trace was not found or doesn't match expectations\n *\n * @example\n * ```typescript\n * assertTraceCreated(collector, 'user.createUser')\n * assertTraceCreated(collector, 'user.createUser', {\n *   minCount: 1,\n *   maxCount: 1,\n *   status: SpanStatusCode.OK,\n *   attributes: { 'user.email': 'test@example.com' }\n * })\n * ```\n */\nexport function assertTraceCreated(\n  collector: TraceCollector,\n  operationName: string,\n  options?: {\n    minCount?: number;\n    maxCount?: number;\n    status?: SpanStatusCode;\n    attributes?: Record<string, unknown>;\n  },\n): void {\n  const spans = collector.getSpansByName(operationName);\n\n  if (options?.minCount !== undefined && spans.length < options.minCount) {\n    throw new Error(\n      `Expected at least ${options.minCount} traces for ${operationName}, got ${spans.length}`,\n    );\n  }\n\n  if (options?.maxCount !== undefined && spans.length > options.maxCount) {\n    throw new Error(\n      `Expected at most ${options.maxCount} traces for ${operationName}, got ${spans.length}`,\n    );\n  }\n\n  if (spans.length === 0) {\n    throw new Error(`No traces found for operation: ${operationName}`);\n  }\n\n  if (options?.status !== undefined) {\n    const matchingSpans = spans.filter(\n      (span) => span.status.code === options.status,\n    );\n    if (matchingSpans.length === 0) {\n      throw new Error(\n        `No traces with status ${options.status} found for ${operationName}`,\n      );\n    }\n  }\n\n  if (options?.attributes) {\n    const matchingSpans = spans.filter((span) => {\n      return Object.entries(options.attributes!).every(\n        ([key, value]) => span.attributes[key] === value,\n      );\n    });\n    if (matchingSpans.length === 0) {\n      throw new Error(\n        `No traces with attributes ${JSON.stringify(options.attributes)} found for ${operationName}`,\n      );\n    }\n  }\n}\n\n/**\n * Assert that no errors were logged\n *\n * Use this in smoke tests to verify critical paths don't have errors.\n *\n * @param collector - Trace collector\n * @throws Error if any error traces are found\n *\n * @example\n * ```typescript\n * // Run critical user flows\n * await runSmokeTests()\n *\n * // Verify no errors occurred\n * assertNoErrors(collector)\n * ```\n */\nexport function assertNoErrors(collector: TraceCollector): void {\n  const errorSpans = collector\n    .getSpans()\n    .filter((span) => span.status.code === SpanStatusCode.ERROR);\n\n  if (errorSpans.length > 0) {\n    const errorSummary = errorSpans\n      .map((span) => `${span.name}: ${span.status.message}`)\n      .join('\\n');\n    throw new Error(`Found ${errorSpans.length} error spans:\\n${errorSummary}`);\n  }\n}\n\n/**\n * Assert that a trace was created and succeeded\n *\n * @param collector - Trace collector\n * @param operationName - Expected operation name\n *\n * @example\n * ```typescript\n * assertTraceSucceeded(collector, 'user.createUser')\n * ```\n */\nexport function assertTraceSucceeded(\n  collector: TraceCollector,\n  operationName: string,\n): void {\n  assertTraceCreated(collector, operationName, { status: SpanStatusCode.OK });\n}\n\n/**\n * Assert that a trace was created and failed\n *\n * @param collector - Trace collector\n * @param operationName - Expected operation name\n * @param errorMessage - Optional expected error message\n *\n * @example\n * ```typescript\n * assertTraceFailed(collector, 'user.createUser', 'Invalid email')\n * ```\n */\nexport function assertTraceFailed(\n  collector: TraceCollector,\n  operationName: string,\n  errorMessage?: string,\n): void {\n  const spans = collector.getSpansByName(operationName);\n\n  if (spans.length === 0) {\n    throw new Error(`No traces found for operation: ${operationName}`);\n  }\n\n  const errorSpans = spans.filter(\n    (span) => span.status.code === SpanStatusCode.ERROR,\n  );\n\n  if (errorSpans.length === 0) {\n    throw new Error(`No error traces found for operation: ${operationName}`);\n  }\n\n  if (errorMessage) {\n    const matchingSpans = errorSpans.filter(\n      (span) => span.status.message === errorMessage,\n    );\n    if (matchingSpans.length === 0) {\n      throw new Error(\n        `No error traces with message \"${errorMessage}\" found for ${operationName}`,\n      );\n    }\n  }\n}\n\n/**\n * In-memory log collector for testing\n */\nexport interface LogCollector {\n  /** Get all collected logs */\n  getLogs(): LogEntry[];\n  /** Get logs by level */\n  getLogsByLevel(level: 'info' | 'warn' | 'error' | 'debug'): LogEntry[];\n  /** Get logs containing a message */\n  getLogsByMessage(message: string): LogEntry[];\n  /** Clear all collected logs */\n  clear(): void;\n}\n\n/**\n * Log entry\n */\nexport interface LogEntry {\n  level: 'info' | 'warn' | 'error' | 'debug';\n  message: string;\n  extra?: Record<string, unknown>;\n  error?: Error;\n}\n\n/**\n * Create an in-memory log collector for testing\n *\n * @example\n * ```typescript\n * const logger = createMockLogger()\n *\n * // Use logger in your code\n * service.log = logger\n * await service.doSomething()\n *\n * // Assert logs were created\n * const logs = logger.getLogs()\n * expect(logs).toHaveLength(2)\n * expect(logs[0].message).toBe('Operation started')\n * ```\n */\nexport function createMockLogger(): Logger & LogCollector {\n  const logs: LogEntry[] = [];\n\n  // Pino-compatible signature: supports both:\n  // - logger.info('message') - string only\n  // - logger.info({ extra }, 'message') - object first with optional message\n  const createLogMethod = (level: 'info' | 'warn' | 'debug') => {\n    return (objOrMsg: Record<string, unknown> | string, msg?: string): void => {\n      if (typeof objOrMsg === 'string') {\n        // String-only call: logger.info('message')\n        logs.push({\n          level,\n          message: objOrMsg,\n          extra: undefined,\n        });\n      } else {\n        // Pino style: logger.info({ extra }, 'message')\n        logs.push({\n          level,\n          message: msg || '',\n          extra: objOrMsg,\n        });\n      }\n    };\n  };\n\n  return {\n    info: createLogMethod('info'),\n    warn: createLogMethod('warn'),\n    debug: createLogMethod('debug'),\n\n    error(objOrMsg: Record<string, unknown> | string, msg?: string): void {\n      if (typeof objOrMsg === 'string') {\n        // String-only call: logger.error('message')\n        logs.push({\n          level: 'error',\n          message: objOrMsg,\n          extra: undefined,\n          error: undefined,\n        });\n        return;\n      }\n\n      // Pino style: logger.error({ err, ...extra }, 'message')\n      // Extract err from extra if present (Pino convention)\n      const { err, ...rest } = objOrMsg as Record<string, unknown> & {\n        err?: unknown;\n      };\n      logs.push({\n        level: 'error',\n        message: msg || '',\n        error: err instanceof Error ? err : undefined,\n        extra:\n          err !== undefined && !(err instanceof Error)\n            ? { err, ...rest }\n            : rest,\n      });\n    },\n\n    getLogs(): LogEntry[] {\n      return [...logs];\n    },\n\n    getLogsByLevel(level: 'info' | 'warn' | 'error' | 'debug'): LogEntry[] {\n      return logs.filter((log) => log.level === level);\n    },\n\n    getLogsByMessage(message: string): LogEntry[] {\n      return logs.filter((log) => log.message.includes(message));\n    },\n\n    clear(): void {\n      logs.length = 0;\n    },\n  };\n}\n\n/**\n * Assert that no error logs were created\n *\n * @param logger - Log collector\n * @throws Error if any error logs are found\n *\n * @example\n * ```typescript\n * assertNoErrorsLogged(logger)\n * ```\n */\nexport function assertNoErrorsLogged(logger: LogCollector): void {\n  const errorLogs = logger.getLogsByLevel('error');\n\n  if (errorLogs.length > 0) {\n    const errorSummary = errorLogs\n      .map(\n        (log) => `${log.message}${log.error ? ': ' + log.error.message : ''}`,\n      )\n      .join('\\n');\n    throw new Error(`Found ${errorLogs.length} error logs:\\n${errorSummary}`);\n  }\n}\n\n/**\n * Wait for a specific trace to be created\n *\n * Useful for async operations where you need to wait for telemetry.\n *\n * @param collector - Trace collector\n * @param operationName - Expected operation name\n * @param timeoutMs - Timeout in milliseconds (default 5000)\n * @returns Promise that resolves when trace is found\n * @throws Error if timeout is reached\n *\n * @example\n * ```typescript\n * // Start async operation\n * const promise = service.doAsyncWork()\n *\n * // Wait for trace\n * await waitForTrace(collector, 'service.doAsyncWork', 1000)\n *\n * // Now you can assert on the trace\n * assertTraceSucceeded(collector, 'service.doAsyncWork')\n * ```\n */\nexport async function waitForTrace(\n  collector: TraceCollector,\n  operationName: string,\n  timeoutMs: number = 5000,\n): Promise<void> {\n  const startTime = Date.now();\n\n  while (Date.now() - startTime < timeoutMs) {\n    const spans = collector.getSpansByName(operationName);\n    if (spans.length > 0) {\n      return;\n    }\n    await new Promise((resolve) => setTimeout(resolve, 10));\n  }\n\n  throw new Error(\n    `Timeout waiting for trace ${operationName} after ${timeoutMs}ms`,\n  );\n}\n\n/**\n * Get trace duration in milliseconds\n *\n * @param collector - Trace collector\n * @param operationName - Operation name\n * @returns Duration in milliseconds, or undefined if trace not found\n *\n * @example\n * ```typescript\n * const duration = getTraceDuration(collector, 'user.createUser')\n * expect(duration).toBeLessThan(1000) // Should be < 1s\n * ```\n */\nexport function getTraceDuration(\n  collector: TraceCollector,\n  operationName: string,\n): number | undefined {\n  const spans = collector.getSpansByName(operationName);\n  if (spans.length === 0) {\n    return undefined;\n  }\n\n  return spans[0]?.duration;\n}\n\n/**\n * Assert that an operation completed within a time threshold\n *\n * Perfect for performance testing and SLO validation.\n *\n * @param collector - Trace collector\n * @param operationName - Operation name\n * @param maxDurationMs - Maximum allowed duration in milliseconds\n * @throws Error if operation took too long\n *\n * @example\n * ```typescript\n * // Verify operation meets SLO\n * await service.createUser({ email: 'test@example.com' })\n * assertTraceDuration(collector, 'user.createUser', 500) // Must be < 500ms\n * ```\n */\nexport function assertTraceDuration(\n  collector: TraceCollector,\n  operationName: string,\n  maxDurationMs: number,\n): void {\n  const duration = getTraceDuration(collector, operationName);\n\n  if (duration === undefined) {\n    throw new Error(`No trace found for operation: ${operationName}`);\n  }\n\n  if (duration > maxDurationMs) {\n    throw new Error(\n      `Operation ${operationName} took ${duration.toFixed(2)}ms, exceeding ${maxDurationMs}ms threshold`,\n    );\n  }\n}\n"],"mappings":"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"}
+{"version":3,"file":"testing.js","names":["otelTrace"],"sources":["../src/testing.ts"],"sourcesContent":["/**\n * Testing Utilities\n *\n * Helpers for testing instrumented code and verifying telemetry.\n * Perfect for integration tests and QA in production validation.\n *\n * @example Verify traces are created\n * ```typescript\n * import { assertTraceCreated, collectTraces } from '@your-org/otel-decorators/testing'\n *\n * describe('UserService', () => {\n *   it('should create trace for user creation', async () => {\n *     const collector = collectTraces()\n *\n *     const service = new UserService()\n *     await service.createUser({ email: 'test@example.com' })\n *\n *     assertTraceCreated(collector, 'user.createUser')\n *   })\n * })\n * ```\n */\n\nimport {\n  SpanStatusCode,\n  type SpanStatus,\n  type Attributes,\n  type AttributeValue,\n  context,\n  trace as otelTrace,\n  type Span,\n  type SpanContext,\n  type TimeInput,\n  type Exception,\n  type Link,\n  type SpanOptions,\n  type Context as OtelContext,\n  type Tracer,\n  type SpanKind,\n} from '@opentelemetry/api';\nimport * as nodeAsyncHooks from 'node:async_hooks';\nimport { type Logger } from './logger';\nimport { configure } from './config';\n\n// Re-export events testing utilities\nexport {\n  createEventCollector,\n  assertEventTracked,\n  assertOutcomeTracked,\n  type EventCollector,\n  type EventData,\n  type EventsFunnelStep,\n  type EventsOutcome,\n  type EventsValue,\n} from './event-testing';\nexport {\n  TestSpanCollector,\n  serializeSpan,\n  type SerializedSpan,\n} from './test-span-collector';\n\n/**\n * Note: OpenTelemetry exporters and processors have moved to dedicated modules\n * for better semantic clarity.\n *\n * For exporters (ConsoleSpanExporter, InMemorySpanExporter):\n * @see {@link autotel/exporters}\n *\n * For processors (SimpleSpanProcessor, BatchSpanProcessor):\n * @see {@link autotel/processors}\n *\n * This module focuses on high-level testing utilities with assertion helpers\n * and trace collectors.\n *\n * @example High-level testing (recommended)\n * ```typescript\n * import { createTraceCollector, assertTraceCreated } from 'autotel/testing'\n *\n * const collector = createTraceCollector()\n * await myService.doSomething()\n * assertTraceCreated(collector, 'myService.doSomething')\n * ```\n *\n * @example Low-level testing (when you need raw OTel spans)\n * ```typescript\n * import { InMemorySpanExporter } from 'autotel/exporters'\n * import { SimpleSpanProcessor } from 'autotel/processors'\n *\n * const exporter = new InMemorySpanExporter()\n * init({ service: 'test', spanProcessor: new SimpleSpanProcessor(exporter) })\n * ```\n */\n\n/**\n * Simplified span representation for testing\n */\nexport interface TestSpan {\n  traceId: string;\n  spanId: string;\n  parentSpanId?: string;\n  kind?: SpanKind;\n  name: string;\n  status: SpanStatus;\n  attributes: Attributes;\n  events: Array<{ name: string; attributes?: Attributes }>;\n  links: Link[];\n  startTime: number;\n  endTime: number;\n  duration: number;\n}\n\nexport interface SpanMatch {\n  name?: string;\n  traceId?: string;\n  spanId?: string;\n  parentSpanId?: string;\n  kind?: SpanKind;\n  attributes?: Record<string, unknown>;\n}\n\n/**\n * In-memory trace collector for testing\n */\nexport interface TraceCollector {\n  /** Get all collected spans */\n  getSpans(): TestSpan[];\n  /** Get spans matching a name */\n  getSpansByName(name: string): TestSpan[];\n  /** Get spans matching attributes */\n  getSpansByAttributes(attributes: Record<string, unknown>): TestSpan[];\n  /** Get spans belonging to a trace */\n  getSpansByTraceId(traceId: string): TestSpan[];\n  /** Get spans without a recorded parent */\n  getRootSpans(): TestSpan[];\n  /** Get all descendants of a span, ordered by completion */\n  getDescendants(rootSpanId: string): TestSpan[];\n  /** Find exactly one span or throw an actionable assertion error */\n  expectSpan(criteria: string | SpanMatch): TestSpan;\n  /** Clear all collected spans */\n  clear(): void;\n  /** Record a span (internal use) */\n  recordSpan(span: TestSpan): void;\n}\n\n/**\n * Create an in-memory trace collector for testing\n *\n * IMPORTANT: This automatically configures the global tracer to record spans.\n * Call this in your test's beforeEach() to ensure proper setup.\n *\n * @example\n * ```typescript\n * import { createTraceCollector } from 'autotel/testing'\n *\n * describe('MyService', () => {\n *   let collector: TraceCollector\n *\n *   beforeEach(() => {\n *     collector = createTraceCollector()\n *   })\n *\n *   it('should trace operations', async () => {\n *     await myService.doSomething()\n *\n *     const spans = collector.getSpansByName('myService.doSomething')\n *     expect(spans).toHaveLength(1)\n *   })\n * })\n * ```\n */\nexport function createTraceCollector(): TraceCollector {\n  const spans: TestSpan[] = [];\n  const activeMockSpanStorage = new nodeAsyncHooks.AsyncLocalStorage<Span>();\n  let nextTraceId = 1;\n  let nextSpanId = 1;\n\n  const hexId = (value: number, length: number) =>\n    value.toString(16).padStart(length, '0');\n\n  // Create mock span that captures data and implements full Span interface\n  const createMockSpan = (\n    name: string,\n    startTime: number,\n    parentSpanContext?: SpanContext,\n    options?: SpanOptions,\n  ): Span => {\n    const spanContextData: SpanContext = {\n      traceId: parentSpanContext?.traceId ?? hexId(nextTraceId++, 32),\n      spanId: hexId(nextSpanId++, 16),\n      traceFlags: 1,\n      isRemote: false,\n    };\n    const spanData: Partial<TestSpan> = {\n      traceId: spanContextData.traceId,\n      spanId: spanContextData.spanId,\n      parentSpanId: parentSpanContext?.spanId,\n      kind: options?.kind,\n      name,\n      startTime,\n      attributes: {},\n      events: [],\n      links: [],\n      status: { code: SpanStatusCode.OK },\n    };\n\n    const mockSpan: Span = {\n      spanContext: () => spanContextData,\n\n      setStatus(status: SpanStatus) {\n        spanData.status = status;\n        return this;\n      },\n\n      setAttributes(attributes: Attributes) {\n        spanData.attributes = { ...spanData.attributes, ...attributes };\n        return this;\n      },\n\n      setAttribute(key: string, value: AttributeValue) {\n        spanData.attributes = spanData.attributes || {};\n        spanData.attributes[key] = value;\n        return this;\n      },\n\n      addEvent(\n        name: string,\n        attributesOrStartTime?: Attributes | TimeInput,\n        startTime?: TimeInput,\n      ) {\n        const attributes =\n          attributesOrStartTime &&\n          !Array.isArray(attributesOrStartTime) &&\n          typeof attributesOrStartTime === 'object'\n            ? (attributesOrStartTime as Attributes)\n            : undefined;\n        spanData.events!.push({ name, attributes });\n        void startTime;\n        return this;\n      },\n\n      addLink(link: { context: SpanContext; attributes?: Attributes }) {\n        spanData.links!.push(link);\n        return this;\n      },\n\n      addLinks(\n        links: Array<{ context: SpanContext; attributes?: Attributes }>,\n      ) {\n        spanData.links!.push(...links);\n        return this;\n      },\n\n      updateName(newName: string) {\n        spanData.name = newName;\n        return this;\n      },\n\n      isRecording() {\n        return true;\n      },\n\n      recordException(exception: Exception, time?: TimeInput) {\n        void exception;\n        void time;\n      },\n\n      end(endTimeArg?: TimeInput) {\n        void endTimeArg;\n        const endTime = performance.now();\n        spans.push({\n          traceId: spanData.traceId!,\n          spanId: spanData.spanId!,\n          parentSpanId: spanData.parentSpanId,\n          kind: spanData.kind,\n          name: spanData.name!,\n          status: spanData.status!,\n          attributes: spanData.attributes || {},\n          events: spanData.events || [],\n          links: spanData.links || [],\n          startTime: spanData.startTime!,\n          endTime,\n          duration: endTime - spanData.startTime!,\n        });\n      },\n    };\n\n    return mockSpan;\n  };\n\n  // Create mock tracer\n  const mockTracer: Tracer = {\n    startSpan(name: string, options?: SpanOptions, ctx?: OtelContext): Span {\n      const startTime = performance.now();\n      const parent =\n        (ctx ? otelTrace.getSpan(ctx)?.spanContext() : undefined) ??\n        activeMockSpanStorage.getStore()?.spanContext();\n      return createMockSpan(name, startTime, parent, options);\n    },\n\n    startActiveSpan<F extends (span: Span) => unknown>(\n      name: string,\n      optionsOrFn: SpanOptions | F,\n      contextOrFn?: OtelContext | F,\n      fn?: F,\n    ): ReturnType<F> {\n      const callback = (() => {\n        if (typeof optionsOrFn === 'function') {\n          return optionsOrFn;\n        }\n        if (typeof contextOrFn === 'function') {\n          return contextOrFn;\n        }\n        if (fn) {\n          return fn;\n        }\n        throw new Error('startActiveSpan requires a callback');\n      })();\n\n      const startTime = performance.now();\n      const suppliedContext =\n        typeof optionsOrFn === 'function'\n          ? context.active()\n          : typeof contextOrFn === 'function' || contextOrFn === undefined\n            ? context.active()\n            : contextOrFn;\n      const parent =\n        otelTrace.getSpan(suppliedContext)?.spanContext() ??\n        activeMockSpanStorage.getStore()?.spanContext();\n      const spanOptions =\n        typeof optionsOrFn === 'function' ? undefined : optionsOrFn;\n      const mockSpan = createMockSpan(name, startTime, parent, spanOptions);\n\n      // Set span as active in context (makes otelTrace.getActiveSpan() work)\n      const ctx = otelTrace.setSpan(suppliedContext, mockSpan);\n      return activeMockSpanStorage.run(mockSpan, () => {\n        return context.with(ctx, () => callback(mockSpan)) as ReturnType<F>;\n      });\n    },\n  };\n\n  // Auto-configure global tracer\n  configure({ tracer: mockTracer });\n\n  return {\n    getSpans(): TestSpan[] {\n      return [...spans];\n    },\n\n    getSpansByName(name: string): TestSpan[] {\n      return spans.filter((span) => span.name === name);\n    },\n\n    getSpansByAttributes(attributes: Record<string, unknown>): TestSpan[] {\n      return spans.filter((span) => {\n        return Object.entries(attributes).every(\n          ([key, value]) => span.attributes[key] === value,\n        );\n      });\n    },\n\n    getSpansByTraceId(traceId: string): TestSpan[] {\n      return spans.filter((span) => span.traceId === traceId);\n    },\n\n    getRootSpans(): TestSpan[] {\n      return spans.filter((span) => span.parentSpanId === undefined);\n    },\n\n    getDescendants(rootSpanId: string): TestSpan[] {\n      const included = new Set([rootSpanId]);\n      let changed = true;\n      while (changed) {\n        changed = false;\n        for (const span of spans) {\n          if (\n            span.parentSpanId &&\n            included.has(span.parentSpanId) &&\n            !included.has(span.spanId)\n          ) {\n            included.add(span.spanId);\n            changed = true;\n          }\n        }\n      }\n      included.delete(rootSpanId);\n      return spans.filter((span) => included.has(span.spanId));\n    },\n\n    expectSpan(criteria: string | SpanMatch): TestSpan {\n      const matches =\n        typeof criteria === 'string'\n          ? spans.filter((span) => span.name === criteria)\n          : spans.filter((span) => {\n              if (criteria.name !== undefined && span.name !== criteria.name) {\n                return false;\n              }\n              if (\n                criteria.traceId !== undefined &&\n                span.traceId !== criteria.traceId\n              ) {\n                return false;\n              }\n              if (\n                criteria.spanId !== undefined &&\n                span.spanId !== criteria.spanId\n              ) {\n                return false;\n              }\n              if (\n                criteria.parentSpanId !== undefined &&\n                span.parentSpanId !== criteria.parentSpanId\n              ) {\n                return false;\n              }\n              if (criteria.kind !== undefined && span.kind !== criteria.kind) {\n                return false;\n              }\n              return Object.entries(criteria.attributes ?? {}).every(\n                ([key, value]) => span.attributes[key] === value,\n              );\n            });\n      if (matches.length !== 1) {\n        throw new Error(\n          `Expected exactly one span matching ${JSON.stringify(criteria)}, found ${matches.length}`,\n        );\n      }\n      return matches[0]!;\n    },\n\n    clear(): void {\n      spans.length = 0;\n    },\n\n    recordSpan(span: TestSpan): void {\n      spans.push(span);\n    },\n  };\n}\n\n/**\n * Assert that a trace was created for an operation\n *\n * @param collector - Trace collector\n * @param operationName - Expected operation name\n * @param options - Optional assertion options\n * @throws Error if trace was not found or doesn't match expectations\n *\n * @example\n * ```typescript\n * assertTraceCreated(collector, 'user.createUser')\n * assertTraceCreated(collector, 'user.createUser', {\n *   minCount: 1,\n *   maxCount: 1,\n *   status: SpanStatusCode.OK,\n *   attributes: { 'user.email': 'test@example.com' }\n * })\n * ```\n */\nexport function assertTraceCreated(\n  collector: TraceCollector,\n  operationName: string,\n  options?: {\n    minCount?: number;\n    maxCount?: number;\n    status?: SpanStatusCode;\n    attributes?: Record<string, unknown>;\n  },\n): void {\n  const spans = collector.getSpansByName(operationName);\n\n  if (options?.minCount !== undefined && spans.length < options.minCount) {\n    throw new Error(\n      `Expected at least ${options.minCount} traces for ${operationName}, got ${spans.length}`,\n    );\n  }\n\n  if (options?.maxCount !== undefined && spans.length > options.maxCount) {\n    throw new Error(\n      `Expected at most ${options.maxCount} traces for ${operationName}, got ${spans.length}`,\n    );\n  }\n\n  if (spans.length === 0) {\n    throw new Error(`No traces found for operation: ${operationName}`);\n  }\n\n  if (options?.status !== undefined) {\n    const matchingSpans = spans.filter(\n      (span) => span.status.code === options.status,\n    );\n    if (matchingSpans.length === 0) {\n      throw new Error(\n        `No traces with status ${options.status} found for ${operationName}`,\n      );\n    }\n  }\n\n  if (options?.attributes) {\n    const matchingSpans = spans.filter((span) => {\n      return Object.entries(options.attributes!).every(\n        ([key, value]) => span.attributes[key] === value,\n      );\n    });\n    if (matchingSpans.length === 0) {\n      throw new Error(\n        `No traces with attributes ${JSON.stringify(options.attributes)} found for ${operationName}`,\n      );\n    }\n  }\n}\n\n/**\n * Assert that no errors were logged\n *\n * Use this in smoke tests to verify critical paths don't have errors.\n *\n * @param collector - Trace collector\n * @throws Error if any error traces are found\n *\n * @example\n * ```typescript\n * // Run critical user flows\n * await runSmokeTests()\n *\n * // Verify no errors occurred\n * assertNoErrors(collector)\n * ```\n */\nexport function assertNoErrors(collector: TraceCollector): void {\n  const errorSpans = collector\n    .getSpans()\n    .filter((span) => span.status.code === SpanStatusCode.ERROR);\n\n  if (errorSpans.length > 0) {\n    const errorSummary = errorSpans\n      .map((span) => `${span.name}: ${span.status.message}`)\n      .join('\\n');\n    throw new Error(`Found ${errorSpans.length} error spans:\\n${errorSummary}`);\n  }\n}\n\n/**\n * Assert that a trace was created and succeeded\n *\n * @param collector - Trace collector\n * @param operationName - Expected operation name\n *\n * @example\n * ```typescript\n * assertTraceSucceeded(collector, 'user.createUser')\n * ```\n */\nexport function assertTraceSucceeded(\n  collector: TraceCollector,\n  operationName: string,\n): void {\n  assertTraceCreated(collector, operationName, { status: SpanStatusCode.OK });\n}\n\n/**\n * Assert that a trace was created and failed\n *\n * @param collector - Trace collector\n * @param operationName - Expected operation name\n * @param errorMessage - Optional expected error message\n *\n * @example\n * ```typescript\n * assertTraceFailed(collector, 'user.createUser', 'Invalid email')\n * ```\n */\nexport function assertTraceFailed(\n  collector: TraceCollector,\n  operationName: string,\n  errorMessage?: string,\n): void {\n  const spans = collector.getSpansByName(operationName);\n\n  if (spans.length === 0) {\n    throw new Error(`No traces found for operation: ${operationName}`);\n  }\n\n  const errorSpans = spans.filter(\n    (span) => span.status.code === SpanStatusCode.ERROR,\n  );\n\n  if (errorSpans.length === 0) {\n    throw new Error(`No error traces found for operation: ${operationName}`);\n  }\n\n  if (errorMessage) {\n    const matchingSpans = errorSpans.filter(\n      (span) => span.status.message === errorMessage,\n    );\n    if (matchingSpans.length === 0) {\n      throw new Error(\n        `No error traces with message \"${errorMessage}\" found for ${operationName}`,\n      );\n    }\n  }\n}\n\n/**\n * In-memory log collector for testing\n */\nexport interface LogCollector {\n  /** Get all collected logs */\n  getLogs(): LogEntry[];\n  /** Get logs by level */\n  getLogsByLevel(level: 'info' | 'warn' | 'error' | 'debug'): LogEntry[];\n  /** Get logs containing a message */\n  getLogsByMessage(message: string): LogEntry[];\n  /** Clear all collected logs */\n  clear(): void;\n}\n\n/**\n * Log entry\n */\nexport interface LogEntry {\n  level: 'info' | 'warn' | 'error' | 'debug';\n  message: string;\n  extra?: Record<string, unknown>;\n  error?: Error;\n}\n\n/**\n * Create an in-memory log collector for testing\n *\n * @example\n * ```typescript\n * const logger = createMockLogger()\n *\n * // Use logger in your code\n * service.log = logger\n * await service.doSomething()\n *\n * // Assert logs were created\n * const logs = logger.getLogs()\n * expect(logs).toHaveLength(2)\n * expect(logs[0].message).toBe('Operation started')\n * ```\n */\nexport function createMockLogger(): Logger & LogCollector {\n  const logs: LogEntry[] = [];\n\n  // Pino-compatible signature: supports both:\n  // - logger.info('message') - string only\n  // - logger.info({ extra }, 'message') - object first with optional message\n  const createLogMethod = (level: 'info' | 'warn' | 'debug') => {\n    return (objOrMsg: Record<string, unknown> | string, msg?: string): void => {\n      if (typeof objOrMsg === 'string') {\n        // String-only call: logger.info('message')\n        logs.push({\n          level,\n          message: objOrMsg,\n          extra: undefined,\n        });\n      } else {\n        // Pino style: logger.info({ extra }, 'message')\n        logs.push({\n          level,\n          message: msg || '',\n          extra: objOrMsg,\n        });\n      }\n    };\n  };\n\n  return {\n    info: createLogMethod('info'),\n    warn: createLogMethod('warn'),\n    debug: createLogMethod('debug'),\n\n    error(objOrMsg: Record<string, unknown> | string, msg?: string): void {\n      if (typeof objOrMsg === 'string') {\n        // String-only call: logger.error('message')\n        logs.push({\n          level: 'error',\n          message: objOrMsg,\n          extra: undefined,\n          error: undefined,\n        });\n        return;\n      }\n\n      // Pino style: logger.error({ err, ...extra }, 'message')\n      // Extract err from extra if present (Pino convention)\n      const { err, ...rest } = objOrMsg as Record<string, unknown> & {\n        err?: unknown;\n      };\n      logs.push({\n        level: 'error',\n        message: msg || '',\n        error: err instanceof Error ? err : undefined,\n        extra:\n          err !== undefined && !(err instanceof Error)\n            ? { err, ...rest }\n            : rest,\n      });\n    },\n\n    getLogs(): LogEntry[] {\n      return [...logs];\n    },\n\n    getLogsByLevel(level: 'info' | 'warn' | 'error' | 'debug'): LogEntry[] {\n      return logs.filter((log) => log.level === level);\n    },\n\n    getLogsByMessage(message: string): LogEntry[] {\n      return logs.filter((log) => log.message.includes(message));\n    },\n\n    clear(): void {\n      logs.length = 0;\n    },\n  };\n}\n\n/**\n * Assert that no error logs were created\n *\n * @param logger - Log collector\n * @throws Error if any error logs are found\n *\n * @example\n * ```typescript\n * assertNoErrorsLogged(logger)\n * ```\n */\nexport function assertNoErrorsLogged(logger: LogCollector): void {\n  const errorLogs = logger.getLogsByLevel('error');\n\n  if (errorLogs.length > 0) {\n    const errorSummary = errorLogs\n      .map(\n        (log) => `${log.message}${log.error ? ': ' + log.error.message : ''}`,\n      )\n      .join('\\n');\n    throw new Error(`Found ${errorLogs.length} error logs:\\n${errorSummary}`);\n  }\n}\n\n/**\n * Wait for a specific trace to be created\n *\n * Useful for async operations where you need to wait for telemetry.\n *\n * @param collector - Trace collector\n * @param operationName - Expected operation name\n * @param timeoutMs - Timeout in milliseconds (default 5000)\n * @returns Promise that resolves when trace is found\n * @throws Error if timeout is reached\n *\n * @example\n * ```typescript\n * // Start async operation\n * const promise = service.doAsyncWork()\n *\n * // Wait for trace\n * await waitForTrace(collector, 'service.doAsyncWork', 1000)\n *\n * // Now you can assert on the trace\n * assertTraceSucceeded(collector, 'service.doAsyncWork')\n * ```\n */\nexport async function waitForTrace(\n  collector: TraceCollector,\n  operationName: string,\n  timeoutMs: number = 5000,\n): Promise<void> {\n  const startTime = Date.now();\n\n  while (Date.now() - startTime < timeoutMs) {\n    const spans = collector.getSpansByName(operationName);\n    if (spans.length > 0) {\n      return;\n    }\n    await new Promise((resolve) => setTimeout(resolve, 10));\n  }\n\n  throw new Error(\n    `Timeout waiting for trace ${operationName} after ${timeoutMs}ms`,\n  );\n}\n\n/**\n * Get trace duration in milliseconds\n *\n * @param collector - Trace collector\n * @param operationName - Operation name\n * @returns Duration in milliseconds, or undefined if trace not found\n *\n * @example\n * ```typescript\n * const duration = getTraceDuration(collector, 'user.createUser')\n * expect(duration).toBeLessThan(1000) // Should be < 1s\n * ```\n */\nexport function getTraceDuration(\n  collector: TraceCollector,\n  operationName: string,\n): number | undefined {\n  const spans = collector.getSpansByName(operationName);\n  if (spans.length === 0) {\n    return undefined;\n  }\n\n  return spans[0]?.duration;\n}\n\n/**\n * Assert that an operation completed within a time threshold\n *\n * Perfect for performance testing and SLO validation.\n *\n * @param collector - Trace collector\n * @param operationName - Operation name\n * @param maxDurationMs - Maximum allowed duration in milliseconds\n * @throws Error if operation took too long\n *\n * @example\n * ```typescript\n * // Verify operation meets SLO\n * await service.createUser({ email: 'test@example.com' })\n * assertTraceDuration(collector, 'user.createUser', 500) // Must be < 500ms\n * ```\n */\nexport function assertTraceDuration(\n  collector: TraceCollector,\n  operationName: string,\n  maxDurationMs: number,\n): void {\n  const duration = getTraceDuration(collector, operationName);\n\n  if (duration === undefined) {\n    throw new Error(`No trace found for operation: ${operationName}`);\n  }\n\n  if (duration > maxDurationMs) {\n    throw new Error(\n      `Operation ${operationName} took ${duration.toFixed(2)}ms, exceeding ${maxDurationMs}ms threshold`,\n    );\n  }\n}\n"],"mappings":"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"}

package/dist/{trace-context-Cijqoi6e.d.ts → trace-context-IuyoPyNq.d.cts}

@@ -1,6 +1,5 @@
-import { BaggageEntry, Context, Link, Span, SpanStatusCode } from "@opentelemetry/api";
+import { AttributeValue, Attributes, BaggageEntry, Context, Link, Span, SpanStatusCode } from "@opentelemetry/api";
 import { AsyncLocalStorage } from "node:async_hooks";
-
 //#region src/trace-context.d.ts
 /**
  * Base trace context containing trace identifiers
@@ -14,7 +13,7 @@ interface TraceContextBase {
  * Attribute value types following OpenTelemetry specification.
  * Supports primitive values and arrays of homogeneous primitives.
  */
-type AttributeValue$1 = string | number | boolean | string[] | number[] | boolean[];
+type AttributeValue$1 = AttributeValue;
 /**
  * Span methods available on trace context
  */
@@ -22,7 +21,7 @@ interface SpanMethods {
   /** Set a single attribute on the span */
   setAttribute(key: string, value: AttributeValue$1): void;
   /** Set multiple attributes on the span */
-  setAttributes(attrs: Record<string, AttributeValue$1>): void;
+  setAttributes(attrs: Attributes): void;
   /** Set the status of the span */
   setStatus(status: {
     code: SpanStatusCode;
@@ -117,14 +116,14 @@ interface BaggageMethods<TBaggage extends Record<string, unknown> | undefined =
 /**
  * Complete trace context that merges base context, span methods, and baggage methods
  *
- * This is the ctx parameter passed to factory functions in trace().
- * It provides access to trace IDs, span manipulation methods, and baggage operations.
+ * This is the ctx parameter passed to `withTracing()` factories and the value
+ * returned by `getActiveTraceContext()` inside plain `trace()` wrappers.
  *
  * @template TBaggage - Optional type for typed baggage support
  *
  * @example Untyped (default)
  * ```typescript
- * export const handler = trace((ctx) => async () => {
+ * export const handler = withTracing({})((ctx) => async () => {
  *   ctx.getBaggage('key'); // returns string | undefined
  * });
  * ```
@@ -133,7 +132,8 @@ interface BaggageMethods<TBaggage extends Record<string, unknown> | undefined =
  * ```typescript
  * type TenantBaggage = { tenantId: string; region?: string };
  *
- * export const handler = trace<TenantBaggage>((ctx) => async () => {
+ * export const handler = trace(async () => {
+ *   const ctx = getActiveTraceContext<TenantBaggage>()!;
  *   // Use typed schema helper for type-safe access
  *   const schema = defineBaggageSchema<TenantBaggage>('tenant');
  *   const tenant = schema.get(ctx); // Partial<TenantBaggage> | undefined
@@ -209,4 +209,4 @@ declare function defineBaggageSchema<T extends Record<string, unknown>>(namespac
 };
 //#endregion
 export { TraceContext as n, defineBaggageSchema as r, AttributeValue$1 as t };
-//# sourceMappingURL=trace-context-Cijqoi6e.d.ts.map
+//# sourceMappingURL=trace-context-IuyoPyNq.d.cts.map

package/dist/trace-context-IuyoPyNq.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"trace-context-IuyoPyNq.d.cts","names":[],"sources":["../src/trace-context.ts"],"mappings":";;;;;;UAiHiB;EACf;EACA;EACA;;;;;;KAOU,mBAAiB;;;;UAKZ;;EAEf,aAAa,aAAa,OAAO;;EAEjC,cAAc,OAAO;;EAErB,UAAU;IAAU,MAAM;IAAgB;;;EAE1C,QAAQ,MAAM;;EAEd,SAAS,OAAO;;EAEhB,WAAW;;EAEX;;;;;;;;;;EAUA,YAAY;;;;;;;EAOZ,MAAM,eAAe,0BAA0B,yBAC7C,aAAa,iBACb,OAAO,aAAa;;;;;;;UASP,eACf,iBAAiB;;;;;;EAOjB,WAAW;;;;;;;;;;;;;;;;;;;EAoBX,WAAW,aAAa;;;;;;;;;EAUxB,cAAc;;;;;EAMd,iBAAiB,YAAY;;;;;;;EAQ7B,kBAAkB,iBAAiB,2BAC9B,UAAU,UAAU,uBAAuB,QAAQ;;;;;;;EASxD,kBAAkB,iBAAiB,2BAC9B,UAAU,UACT,+BACA,OAAO,QAAQ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;KAgCX,aACV,iBAAiB,mDACf,mBAAmB,cAAc,eAAe;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAoOpC,oBAAoB,UAAU,yBAC5C;;;;;;EAQa,MAAA,KAAA,aAAa,OAAK,QAAQ;;;;;;;;;EAa1B,MAAA,KAAA,aAAa,IAAE,OAAS,QAAQ;;;;;;;;;;;EAepC,OAAA,GAAC,YACM,aAAa,KAAK,QAAQ,IAAE,WAC7B,QAAQ,YAAY,IAAI,QAAQ,KAAG,gBAC9B,IAAI,QAAQ,OAC3B,IAAI,QAAQ"}

package/dist/{trace-context-Cijqoi6e.d.cts → trace-context-IuyoPyNq.d.ts}

@@ -1,6 +1,5 @@
-import { BaggageEntry, Context, Link, Span, SpanStatusCode } from "@opentelemetry/api";
+import { AttributeValue, Attributes, BaggageEntry, Context, Link, Span, SpanStatusCode } from "@opentelemetry/api";
 import { AsyncLocalStorage } from "node:async_hooks";
-
 //#region src/trace-context.d.ts
 /**
  * Base trace context containing trace identifiers
@@ -14,7 +13,7 @@ interface TraceContextBase {
  * Attribute value types following OpenTelemetry specification.
  * Supports primitive values and arrays of homogeneous primitives.
  */
-type AttributeValue$1 = string | number | boolean | string[] | number[] | boolean[];
+type AttributeValue$1 = AttributeValue;
 /**
  * Span methods available on trace context
  */
@@ -22,7 +21,7 @@ interface SpanMethods {
   /** Set a single attribute on the span */
   setAttribute(key: string, value: AttributeValue$1): void;
   /** Set multiple attributes on the span */
-  setAttributes(attrs: Record<string, AttributeValue$1>): void;
+  setAttributes(attrs: Attributes): void;
   /** Set the status of the span */
   setStatus(status: {
     code: SpanStatusCode;
@@ -117,14 +116,14 @@ interface BaggageMethods<TBaggage extends Record<string, unknown> | undefined =
 /**
  * Complete trace context that merges base context, span methods, and baggage methods
  *
- * This is the ctx parameter passed to factory functions in trace().
- * It provides access to trace IDs, span manipulation methods, and baggage operations.
+ * This is the ctx parameter passed to `withTracing()` factories and the value
+ * returned by `getActiveTraceContext()` inside plain `trace()` wrappers.
  *
  * @template TBaggage - Optional type for typed baggage support
  *
  * @example Untyped (default)
  * ```typescript
- * export const handler = trace((ctx) => async () => {
+ * export const handler = withTracing({})((ctx) => async () => {
  *   ctx.getBaggage('key'); // returns string | undefined
  * });
  * ```
@@ -133,7 +132,8 @@ interface BaggageMethods<TBaggage extends Record<string, unknown> | undefined =
  * ```typescript
  * type TenantBaggage = { tenantId: string; region?: string };
  *
- * export const handler = trace<TenantBaggage>((ctx) => async () => {
+ * export const handler = trace(async () => {
+ *   const ctx = getActiveTraceContext<TenantBaggage>()!;
  *   // Use typed schema helper for type-safe access
  *   const schema = defineBaggageSchema<TenantBaggage>('tenant');
  *   const tenant = schema.get(ctx); // Partial<TenantBaggage> | undefined
@@ -209,4 +209,4 @@ declare function defineBaggageSchema<T extends Record<string, unknown>>(namespac
 };
 //#endregion
 export { TraceContext as n, defineBaggageSchema as r, AttributeValue$1 as t };
-//# sourceMappingURL=trace-context-Cijqoi6e.d.cts.map
+//# sourceMappingURL=trace-context-IuyoPyNq.d.ts.map

package/dist/trace-context-IuyoPyNq.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"trace-context-IuyoPyNq.d.ts","names":[],"sources":["../src/trace-context.ts"],"mappings":";;;;;;UAiHiB;EACf;EACA;EACA;;;;;;KAOU,mBAAiB;;;;UAKZ;;EAEf,aAAa,aAAa,OAAO;;EAEjC,cAAc,OAAO;;EAErB,UAAU;IAAU,MAAM;IAAgB;;;EAE1C,QAAQ,MAAM;;EAEd,SAAS,OAAO;;EAEhB,WAAW;;EAEX;;;;;;;;;;EAUA,YAAY;;;;;;;EAOZ,MAAM,eAAe,0BAA0B,yBAC7C,aAAa,iBACb,OAAO,aAAa;;;;;;;UASP,eACf,iBAAiB;;;;;;EAOjB,WAAW;;;;;;;;;;;;;;;;;;;EAoBX,WAAW,aAAa;;;;;;;;;EAUxB,cAAc;;;;;EAMd,iBAAiB,YAAY;;;;;;;EAQ7B,kBAAkB,iBAAiB,2BAC9B,UAAU,UAAU,uBAAuB,QAAQ;;;;;;;EASxD,kBAAkB,iBAAiB,2BAC9B,UAAU,UACT,+BACA,OAAO,QAAQ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;KAgCX,aACV,iBAAiB,mDACf,mBAAmB,cAAc,eAAe;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAoOpC,oBAAoB,UAAU,yBAC5C;;;;;;EAQa,MAAA,KAAA,aAAa,OAAK,QAAQ;;;;;;;;;EAa1B,MAAA,KAAA,aAAa,IAAE,OAAS,QAAQ;;;;;;;;;;;EAepC,OAAA,GAAC,YACM,aAAa,KAAK,QAAQ,IAAE,WAC7B,QAAQ,YAAY,IAAI,QAAQ,KAAG,gBAC9B,IAAI,QAAQ,OAC3B,IAAI,QAAQ"}

package/dist/trace-factory-validation-BjVAinz6.js

@@ -0,0 +1,13 @@
+//#region src/trace-factory-validation.ts
+/**
+* Validate the two stages of Autotel's public factory wrappers without
+* coupling helper modules to the large functional tracing implementation.
+*/
+function assertTraceFactory(helperName, value, stage = "factory") {
+	if (typeof value === "function") return;
+	throw new TypeError(stage === "factory" ? `${helperName}: expected a factory (ctx) => (...args) => result` : `${helperName}: factory must return a function; expected (ctx) => (...args) => result`);
+}
+
+//#endregion
+export { assertTraceFactory as t };
+//# sourceMappingURL=trace-factory-validation-BjVAinz6.js.map

package/dist/trace-factory-validation-BjVAinz6.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"trace-factory-validation-BjVAinz6.js","names":[],"sources":["../src/trace-factory-validation.ts"],"sourcesContent":["/**\n * Validate the two stages of Autotel's public factory wrappers without\n * coupling helper modules to the large functional tracing implementation.\n */\nexport function assertTraceFactory(\n  helperName: string,\n  value: unknown,\n  stage: 'factory' | 'result' = 'factory',\n): asserts value is (...args: never[]) => unknown {\n  if (typeof value === 'function') return;\n\n  throw new TypeError(\n    stage === 'factory'\n      ? `${helperName}: expected a factory (ctx) => (...args) => result`\n      : `${helperName}: factory must return a function; expected (ctx) => (...args) => result`,\n  );\n}\n"],"mappings":";;;;;AAIA,SAAgB,mBACd,YACA,OACA,QAA8B,WACkB;CAChD,IAAI,OAAO,UAAU,YAAY;CAEjC,MAAM,IAAI,UACR,UAAU,YACN,GAAG,WAAW,qDACd,GAAG,WAAW,wEACpB;AACF"}

package/dist/trace-factory-validation-Dc8epn87.cjs

@@ -0,0 +1,19 @@
+
+//#region src/trace-factory-validation.ts
+/**
+* Validate the two stages of Autotel's public factory wrappers without
+* coupling helper modules to the large functional tracing implementation.
+*/
+function assertTraceFactory(helperName, value, stage = "factory") {
+	if (typeof value === "function") return;
+	throw new TypeError(stage === "factory" ? `${helperName}: expected a factory (ctx) => (...args) => result` : `${helperName}: factory must return a function; expected (ctx) => (...args) => result`);
+}
+
+//#endregion
+Object.defineProperty(exports, 'assertTraceFactory', {
+  enumerable: true,
+  get: function () {
+    return assertTraceFactory;
+  }
+});
+//# sourceMappingURL=trace-factory-validation-Dc8epn87.cjs.map

package/dist/trace-factory-validation-Dc8epn87.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"trace-factory-validation-Dc8epn87.cjs","names":[],"sources":["../src/trace-factory-validation.ts"],"sourcesContent":["/**\n * Validate the two stages of Autotel's public factory wrappers without\n * coupling helper modules to the large functional tracing implementation.\n */\nexport function assertTraceFactory(\n  helperName: string,\n  value: unknown,\n  stage: 'factory' | 'result' = 'factory',\n): asserts value is (...args: never[]) => unknown {\n  if (typeof value === 'function') return;\n\n  throw new TypeError(\n    stage === 'factory'\n      ? `${helperName}: expected a factory (ctx) => (...args) => result`\n      : `${helperName}: factory must return a function; expected (ctx) => (...args) => result`,\n  );\n}\n"],"mappings":";;;;;;AAIA,SAAgB,mBACd,YACA,OACA,QAA8B,WACkB;CAChD,IAAI,OAAO,UAAU,YAAY;CAEjC,MAAM,IAAI,UACR,UAAU,YACN,GAAG,WAAW,qDACd,GAAG,WAAW,wEACpB;AACF"}

package/dist/trace-helpers.cjs

@@ -483,9 +483,9 @@ async function createDeterministicTraceId(seed) {
 * @example Basic metadata flattening
 * ```typescript
 * import { flattenMetadata } from 'autotel/trace-helpers'
-* import { trace } from 'autotel'
+* import { trace, withTracing } from 'autotel'
 *
-* export const processOrder = trace(ctx => async (orderId: string) => {
+* export const processOrder = withTracing({})(ctx => async (orderId: string) => {
 *   const order = await getOrder(orderId)
 *
 *   // Flatten complex order metadata
@@ -510,9 +510,9 @@ async function createDeterministicTraceId(seed) {
 * @example Custom prefix for semantic conventions
 * ```typescript
 * import { flattenMetadata } from 'autotel/trace-helpers'
-* import { trace } from 'autotel'
+* import { trace, withTracing } from 'autotel'
 *
-* export const fetchUser = trace(ctx => async (userId: string) => {
+* export const fetchUser = withTracing({})(ctx => async (userId: string) => {
 *   const user = await db.users.findOne({ id: userId })
 *
 *   // Use semantic convention prefix
@@ -538,9 +538,9 @@ async function createDeterministicTraceId(seed) {
 * @example With complex objects (auto-serialized)
 * ```typescript
 * import { flattenMetadata } from 'autotel/trace-helpers'
-* import { trace } from 'autotel'
+* import { trace, withTracing } from 'autotel'
 *
-* export const analyzeRequest = trace(ctx => async (req: Request) => {
+* export const analyzeRequest = withTracing({})(ctx => async (req: Request) => {
 *   const metadata = flattenMetadata({
 *     headers: req.headers,  // Object - will be JSON serialized
 *     query: req.query,       // Object - will be JSON serialized
@@ -584,7 +584,7 @@ async function createDeterministicTraceId(seed) {
 function resolveTraceUrl(template, traceId) {
 	const t = template ?? process.env.OTEL_TRACE_URL_TEMPLATE;
 	if (!t) return void 0;
-	return t.replace(/\{traceId\}/g, traceId);
+	return t.replaceAll("{traceId}", traceId);
 }
 function flattenMetadata(metadata, prefix = "metadata") {
 	const flattened = {};

package/dist/trace-helpers.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"trace-helpers.cjs","names":["trace","requireModule","context","SpanStatusCode"],"sources":["../src/trace-helpers.ts"],"sourcesContent":["/**\n * Trace context helpers - Core primitives for trace correlation\n *\n * These are the building blocks that allow users to bring their own logger\n * (bunyan, log4js, custom, etc.) and add trace correlation.\n *\n * @example Using with bunyan\n * ```typescript\n * import bunyan from 'bunyan';\n * import { enrichWithTraceContext } from 'autotel/trace-helpers';\n *\n * const bunyanLogger = bunyan.createLogger({ name: 'myapp' });\n *\n * const logger = {\n *   info: (msg: string, extra?: object) => {\n *     bunyanLogger.info(enrichWithTraceContext(extra || {}), msg);\n *   }\n * };\n * ```\n *\n * @example Using with log4js\n * ```typescript\n * import log4js from 'log4js';\n * import { getTraceContext } from 'autotel/trace-helpers';\n *\n * const log4jsLogger = log4js.getLogger();\n *\n * function logWithTrace(level: string, msg: string, extra?: object) {\n *   const context = getTraceContext();\n *   log4jsLogger[level](msg, { ...extra, ...context });\n * }\n * ```\n */\n\nimport { trace, context, SpanStatusCode } from '@opentelemetry/api';\nimport type { Span, Tracer, Context } from '@opentelemetry/api';\nimport { requireModule } from './node-require';\n\n/**\n * WeakMap to store span names for active spans\n * This allows us to retrieve the span name even though OpenTelemetry\n * doesn't expose it through the public API\n */\nconst spanNameMap = new WeakMap<Span, string>();\n\n/**\n * Store span name for a given span\n * Called internally when spans are created\n */\nexport function setSpanName(span: Span, name: string): void {\n  spanNameMap.set(span, name);\n}\n\n/**\n * Trace context extracted from active span\n */\nexport interface TraceContext {\n  /** Full 32-character hex trace ID */\n  traceId: string;\n  /** 16-character hex span ID */\n  spanId: string;\n  /** First 16 characters of trace ID (for log grouping/correlation) */\n  correlationId: string;\n  /** Function/operation name (OpenTelemetry semantic convention: code.function) */\n  'code.function'?: string;\n  /** Datadog trace ID in decimal format (lower 64 bits) for log-trace correlation */\n  'dd.trace_id'?: string;\n  /** Datadog span ID in decimal format for log-trace correlation */\n  'dd.span_id'?: string;\n}\n\n/**\n * Convert hex string to decimal string representation\n * Handles 64-bit unsigned integers for Datadog correlation\n *\n * @param hex - Hex string (up to 16 characters for 64-bit)\n * @returns Decimal string representation\n */\nfunction hexToDecimal(hex: string): string {\n  // For 64-bit values, use BigInt to avoid precision loss\n  return BigInt('0x' + hex).toString(10);\n}\n\n/**\n * Get current trace context from active span\n *\n * Returns null if no span is active (e.g., outside of trace operation)\n *\n * Includes both OpenTelemetry standard fields (hex) and Datadog-specific\n * fields (decimal) for maximum compatibility.\n *\n * @returns Trace context with traceId, spanId, correlationId, and Datadog decimal IDs, or null\n *\n * @example\n * ```typescript\n * import { getTraceContext } from 'autotel/trace-helpers';\n *\n * const context = getTraceContext();\n * if (context) {\n *   console.log('Current trace:', context.traceId);\n *   // Current trace: 4bf92f3577b34da6a3ce929d0e0e4736\n *   console.log('Datadog trace ID:', context['dd.trace_id']);\n *   // Datadog trace ID: 12007117331170166582 (decimal for log correlation)\n * }\n * ```\n */\nexport function getTraceContext(): TraceContext | null {\n  const span = trace.getActiveSpan();\n  if (!span) return null;\n\n  const spanContext = span.spanContext();\n  const traceId = spanContext.traceId;\n  const spanId = spanContext.spanId;\n\n  // Get span name from WeakMap (set when span is created)\n  // Map to OpenTelemetry semantic convention: code.function\n  const spanName = spanNameMap.get(span);\n\n  // Datadog uses the lower 64 bits of the 128-bit OpenTelemetry trace ID\n  // Convert from hex to decimal for Datadog's log-trace correlation\n  const traceIdLower64 = traceId.slice(-16); // Last 16 hex chars = lower 64 bits\n  const ddTraceId = hexToDecimal(traceIdLower64);\n  const ddSpanId = hexToDecimal(spanId);\n\n  return {\n    traceId,\n    spanId,\n    correlationId: traceId.slice(0, 16),\n    ...(spanName && { 'code.function': spanName }),\n    // Datadog-specific fields for log-trace correlation\n    'dd.trace_id': ddTraceId,\n    'dd.span_id': ddSpanId,\n  };\n}\n\n/**\n * Enrich object with trace context (traceId, spanId, correlationId, and Datadog fields)\n *\n * If no span is active, returns the object unchanged.\n * This prevents \"undefined\" or \"null\" values in logs.\n *\n * Automatically adds both OpenTelemetry standard fields (hex) and Datadog-specific\n * fields (decimal) for maximum compatibility with observability backends.\n *\n * @param obj - Object to enrich (e.g., log metadata)\n * @returns Object with trace context merged in, or unchanged if no active span\n *\n * @example\n * ```typescript\n * import { enrichWithTraceContext } from 'autotel/trace-helpers';\n *\n * // Inside a trace operation:\n * const enriched = enrichWithTraceContext({ userId: '123' });\n * // {\n * //   userId: '123',\n * //   traceId: '4bf92f3577b34da6a3ce929d0e0e4736',\n * //   spanId: '00f067aa0ba902b7',\n * //   correlationId: '4bf92f3577b34da6',\n * //   'dd.trace_id': '12007117331170166582',  // Datadog decimal format\n * //   'dd.span_id': '67667974448284583'       // Datadog decimal format\n * // }\n *\n * // Outside trace operation:\n * const unchanged = enrichWithTraceContext({ userId: '123' });\n * // { userId: '123' } - no trace fields added\n * ```\n */\nexport function enrichWithTraceContext<T extends Record<string, unknown>>(\n  obj: T,\n): T {\n  const context = getTraceContext();\n  return context ? ({ ...obj, ...context } as T) : obj;\n}\n\n/**\n * Check if currently in a trace context\n *\n * Useful for conditional logic based on trace presence\n *\n * @returns true if active span exists, false otherwise\n *\n * @example\n * ```typescript\n * import { isTracing } from 'autotel/trace-helpers';\n *\n * if (isTracing()) {\n *   // Add expensive debug metadata only when tracing\n *   logger.debug('Detailed context', expensiveDebugData());\n * }\n * ```\n */\nexport function isTracing(): boolean {\n  return trace.getActiveSpan() !== undefined;\n}\n\n/**\n * Get a tracer instance for creating custom spans\n *\n * Use this when you need low-level control over span lifecycle.\n * For most use cases, prefer trace(), span(), or instrument() instead.\n *\n * @param name - Tracer name (usually your service or module name)\n * @param version - Optional version string\n * @returns OpenTelemetry Tracer instance\n *\n * @example Basic usage\n * ```typescript\n * import { getTracer } from 'autotel';\n *\n * const tracer = getTracer('my-service');\n * const span = tracer.startSpan('custom.operation');\n * try {\n *   // Your logic\n *   span.setAttribute('key', 'value');\n * } finally {\n *   span.end();\n * }\n * ```\n *\n * @example With AI SDK\n * ```typescript\n * import { getTracer } from 'autotel';\n * import { generateText } from 'ai';\n *\n * const tracer = getTracer('ai-agent');\n * const result = await generateText({\n *   model: myModel,\n *   prompt: 'Hello',\n *   experimental_telemetry: {\n *     isEnabled: true,\n *     tracer,\n *   },\n * });\n * ```\n */\nexport function getTracer(name: string, version?: string): Tracer {\n  return trace.getTracer(name, version);\n}\n\n/**\n * Get the currently active span\n *\n * Returns undefined if no span is currently active.\n * Useful for adding attributes to the current span.\n *\n * @returns Active span or undefined\n *\n * @example Adding attributes to active span\n * ```typescript\n * import { getActiveSpan } from 'autotel';\n *\n * const span = getActiveSpan();\n * if (span) {\n *   span.setAttribute('user.id', userId);\n *   span.setAttribute('user.action', 'click');\n * }\n * ```\n *\n * @example Checking span status\n * ```typescript\n * import { getActiveSpan, SpanStatusCode } from 'autotel';\n *\n * const span = getActiveSpan();\n * if (span?.isRecording()) {\n *   span.setStatus({ code: SpanStatusCode.OK });\n * }\n * ```\n */\nexport function getActiveSpan(): Span | undefined {\n  return trace.getActiveSpan();\n}\n\n/**\n * Get the currently active OpenTelemetry context\n *\n * The context contains the active span and any baggage.\n * Useful for context propagation and custom instrumentation.\n *\n * @returns Current active context\n *\n * @example Propagating context\n * ```typescript\n * import { getActiveContext } from 'autotel';\n *\n * const currentContext = getActiveContext();\n * // Pass context to another function or service\n * ```\n *\n * @example With context injection\n * ```typescript\n * import { getActiveContext, injectTraceContext } from 'autotel';\n *\n * const headers = {};\n * injectTraceContext(headers);\n * // Headers now contain trace propagation data\n * ```\n */\nexport function getActiveContext(): Context {\n  // Check stored context first (from baggage setters), then fall back to active context\n  // This ensures ctx.setBaggage() changes are visible to OpenTelemetry operations\n  try {\n    const { getActiveContextWithBaggage } = requireModule<{\n      getActiveContextWithBaggage: () => Context;\n    }>('./trace-context');\n    return getActiveContextWithBaggage();\n  } catch {\n    // Fallback if trace-context isn't available\n    return context.active();\n  }\n}\n\n/**\n * Run a function with a specific span set as active\n *\n * This is a convenience wrapper around the two-step process of\n * setting a span in context and running code within that context.\n *\n * @param span - The span to set as active\n * @param fn - Function to execute with the span active\n * @returns The return value of the function\n *\n * @example Running code with a custom span\n * ```typescript\n * import { getTracer, runWithSpan } from 'autotel';\n *\n * const tracer = getTracer('my-service');\n * const span = tracer.startSpan('background.job');\n *\n * try {\n *   const result = await runWithSpan(span, async () => {\n *     // Any spans created here will be children of 'background.job'\n *     await processData();\n *     return { success: true };\n *   });\n *   console.log(result);\n * } finally {\n *   span.end();\n * }\n * ```\n *\n * @example Testing with custom spans\n * ```typescript\n * import { runWithSpan, otelTrace } from 'autotel';\n *\n * const tracer = otelTrace.getTracer('test');\n * const span = tracer.startSpan('test.operation');\n *\n * const result = runWithSpan(span, () => {\n *   // Code under test runs with this span as active\n *   return myFunction();\n * });\n *\n * span.end();\n * ```\n */\nexport function runWithSpan<T>(span: Span, fn: () => T): T {\n  const ctx = trace.setSpan(context.active(), span);\n  return context.with(ctx, fn);\n}\n\n/**\n * Finalize a span with appropriate status and optional error recording\n *\n * This is a convenience function that:\n * - Records exceptions if an error is provided\n * - Sets span status to ERROR if error exists, OK otherwise\n * - Ends the span\n *\n * @param span - The span to finalize\n * @param error - Optional error to record\n *\n * @example Without error (success case)\n * ```typescript\n * import { getTracer, finalizeSpan } from 'autotel';\n *\n * const tracer = getTracer('my-service');\n * const span = tracer.startSpan('operation');\n *\n * try {\n *   await doWork();\n *   finalizeSpan(span);\n * } catch (error) {\n *   finalizeSpan(span, error);\n *   throw error;\n * }\n * ```\n *\n * @example With error\n * ```typescript\n * import { getTracer, finalizeSpan } from 'autotel';\n *\n * const tracer = getTracer('my-service');\n * const span = tracer.startSpan('operation');\n *\n * try {\n *   await riskyOperation();\n *   finalizeSpan(span);\n * } catch (error) {\n *   finalizeSpan(span, error); // Records exception and sets ERROR status\n *   throw error;\n * }\n * ```\n *\n * @example In instrumentation\n * ```typescript\n * import { getTracer, runWithSpan, finalizeSpan } from 'autotel';\n *\n * function instrumentedQuery(query: string) {\n *   const tracer = getTracer('db');\n *   const span = tracer.startSpan('db.query');\n *\n *   return runWithSpan(span, () => {\n *     try {\n *       const result = executeQuery(query);\n *       finalizeSpan(span);\n *       return result;\n *     } catch (error) {\n *       finalizeSpan(span, error);\n *       throw error;\n *     }\n *   });\n * }\n * ```\n */\nexport function finalizeSpan(span: Span, error?: unknown): void {\n  if (error) {\n    if (error instanceof Error) {\n      span.recordException(error);\n    } else {\n      span.recordException(new Error(String(error)));\n    }\n    span.setStatus({ code: SpanStatusCode.ERROR });\n  } else {\n    span.setStatus({ code: SpanStatusCode.OK });\n  }\n  span.end();\n}\n\n/**\n * Creates a deterministic trace ID from a seed string.\n *\n * Generates a consistent 128-bit trace ID (32 hex characters) from an input seed\n * using SHA-256 hashing. Useful for correlating external system IDs (request IDs,\n * order IDs, session IDs) with OpenTelemetry trace IDs.\n *\n * **Use Cases:**\n * - Correlate external request IDs with traces\n * - Link customer support tickets to trace data\n * - Associate business entities (orders, sessions) with observability data\n * - Debug specific user flows by deterministic trace lookup\n *\n * **Important:** Only use this when you need deterministic trace IDs for correlation.\n * For normal tracing, let OpenTelemetry generate random trace IDs automatically.\n *\n * **Runtime Support:**\n * - Node.js 15+ (native crypto.subtle)\n * - All modern browsers\n * - Edge runtimes (Cloudflare Workers, Deno, etc.)\n *\n * @param seed - Input string to generate trace ID from (e.g., request ID, order ID)\n * @returns Promise resolving to a 32-character hex trace ID (128 bits)\n *\n * @example Correlate external request ID with trace\n * ```typescript\n * import { createDeterministicTraceId } from 'autotel/trace-helpers'\n * import { trace, context } from '@opentelemetry/api'\n *\n * // In middleware or request handler\n * const requestId = req.headers['x-request-id']\n * const traceId = await createDeterministicTraceId(requestId)\n *\n * // Use with manual span creation (advanced - not needed with trace/span functions)\n * const tracer = trace.getTracer('my-service')\n * const spanContext = {\n *   traceId,\n *   spanId: '0123456789abcdef', // Still random\n *   traceFlags: 1\n * }\n * ```\n *\n * @example Link customer support tickets to traces\n * ```typescript\n * import { createDeterministicTraceId } from 'autotel/trace-helpers'\n *\n * // Support dashboard integration\n * const ticketId = 'TICKET-12345'\n * const traceId = await createDeterministicTraceId(ticketId)\n *\n * // Generate direct link to traces in observability backend\n * const traceUrl = `https://your-otel-backend.com/traces/${traceId}`\n * console.log(`View related traces: ${traceUrl}`)\n * ```\n *\n * @example Session-based correlation\n * ```typescript\n * import { createDeterministicTraceId } from 'autotel/trace-helpers'\n *\n * // Track all operations for a user session\n * const sessionId = req.session.id\n * const traceId = await createDeterministicTraceId(sessionId)\n *\n * // All operations in this session share the same trace ID\n * // Makes it easy to find all activity for a specific session\n * ```\n *\n * @public\n */\nexport async function createDeterministicTraceId(\n  seed: string,\n): Promise<string> {\n  // Encode seed string to bytes\n  const encoder = new TextEncoder();\n  const data = encoder.encode(seed);\n\n  // Generate SHA-256 hash (256 bits)\n  const hashBuffer = await crypto.subtle.digest('SHA-256', data);\n\n  // Convert to hex string and truncate to 32 characters (128 bits)\n  // OpenTelemetry trace IDs are 128 bits (16 bytes, 32 hex characters)\n  const hashArray = new Uint8Array(hashBuffer);\n  return [...hashArray]\n    .map((byte) => byte.toString(16).padStart(2, '0'))\n    .join('')\n    .slice(0, 32);\n}\n\n/**\n * Flattens nested metadata objects into dot-notation span attributes.\n *\n * Converts complex nested objects into flat key-value pairs suitable for\n * OpenTelemetry span attributes. Non-string values are JSON serialized.\n * Handles serialization failures gracefully with a fallback value.\n *\n * **Use Cases:**\n * - Structured metadata with nested objects\n * - User context with multiple properties\n * - Request/response metadata\n * - Business entity attributes\n *\n * **Note:** Filters out null/undefined values automatically to keep spans clean.\n *\n * @param metadata - Nested metadata object to flatten\n * @param prefix - Prefix for all attribute keys (default: 'metadata')\n * @returns Flattened attributes as { [key: string]: string }\n *\n * @example Basic metadata flattening\n * ```typescript\n * import { flattenMetadata } from 'autotel/trace-helpers'\n * import { trace } from 'autotel'\n *\n * export const processOrder = trace(ctx => async (orderId: string) => {\n *   const order = await getOrder(orderId)\n *\n *   // Flatten complex order metadata\n *   const flattened = flattenMetadata({\n *     user: { id: order.userId, tier: 'premium' },\n *     payment: { method: 'card', processor: 'stripe' },\n *     items: order.items.length\n *   })\n *\n *   ctx.setAttributes(flattened)\n *   // Results in:\n *   // {\n *   //   'metadata.user.id': 'user-123',\n *   //   'metadata.user.tier': 'premium',\n *   //   'metadata.payment.method': 'card',\n *   //   'metadata.payment.processor': 'stripe',\n *   //   'metadata.items': '5'\n *   // }\n * })\n * ```\n *\n * @example Custom prefix for semantic conventions\n * ```typescript\n * import { flattenMetadata } from 'autotel/trace-helpers'\n * import { trace } from 'autotel'\n *\n * export const fetchUser = trace(ctx => async (userId: string) => {\n *   const user = await db.users.findOne({ id: userId })\n *\n *   // Use semantic convention prefix\n *   const userAttrs = flattenMetadata(\n *     {\n *       id: user.id,\n *       email: user.email,\n *       plan: user.subscription.plan\n *     },\n *     'user'  // Custom prefix\n *   )\n *\n *   ctx.setAttributes(userAttrs)\n *   // Results in:\n *   // {\n *   //   'user.id': 'user-123',\n *   //   'user.email': 'user@example.com',\n *   //   'user.plan': 'enterprise'\n *   // }\n * })\n * ```\n *\n * @example With complex objects (auto-serialized)\n * ```typescript\n * import { flattenMetadata } from 'autotel/trace-helpers'\n * import { trace } from 'autotel'\n *\n * export const analyzeRequest = trace(ctx => async (req: Request) => {\n *   const metadata = flattenMetadata({\n *     headers: req.headers,  // Object - will be JSON serialized\n *     query: req.query,       // Object - will be JSON serialized\n *     timestamp: new Date()   // Non-string - will be JSON serialized\n *   })\n *\n *   ctx.setAttributes(metadata)\n *   // Results in:\n *   // {\n *   //   'metadata.headers': '{\"accept\":\"application/json\",...}',\n *   //   'metadata.query': '{\"page\":\"1\",\"limit\":\"10\"}',\n *   //   'metadata.timestamp': '\"2024-01-15T12:00:00.000Z\"'\n *   // }\n * })\n * ```\n *\n * @example Error handling\n * ```typescript\n * import { flattenMetadata } from 'autotel/trace-helpers'\n *\n * // Objects with circular references are handled gracefully\n * const circular: any = { a: 1 }\n * circular.self = circular\n *\n * const flattened = flattenMetadata({ data: circular })\n * // Results in:\n * // { 'metadata.data': '<serialization-failed>' }\n * ```\n *\n * @public\n */\n/**\n * Resolve a trace URL from a template string and trace ID.\n *\n * Templates use `{traceId}` as placeholder. Falls back to `OTEL_TRACE_URL_TEMPLATE` env var.\n *\n * @example\n * resolveTraceUrl('https://grafana.example.com/explore?traceId={traceId}', 'abc123')\n * // => 'https://grafana.example.com/explore?traceId=abc123'\n */\nexport function resolveTraceUrl(\n  template: string | undefined,\n  traceId: string,\n): string | undefined {\n  const t = template ?? process.env.OTEL_TRACE_URL_TEMPLATE;\n  if (!t) return undefined;\n  return t.replace(/\\{traceId\\}/g, traceId);\n}\n\nexport function flattenMetadata(\n  metadata: Record<string, unknown>,\n  prefix = 'metadata',\n): Record<string, string> {\n  const flattened: Record<string, string> = {};\n  const seen = new WeakSet<object>(); // Track visited objects to detect cycles\n\n  function flatten(obj: Record<string, unknown>, currentPrefix: string): void {\n    for (const [key, value] of Object.entries(obj)) {\n      // Skip null/undefined values\n      if (value == null) continue;\n\n      const attributeKey = `${currentPrefix}.${key}`;\n\n      // Handle primitives directly (string, number, boolean)\n      if (typeof value === 'string') {\n        flattened[attributeKey] = value;\n        continue;\n      }\n      if (typeof value === 'number' || typeof value === 'boolean') {\n        flattened[attributeKey] = String(value);\n        continue;\n      }\n\n      // Recursively flatten plain objects (with cycle detection)\n      if (\n        typeof value === 'object' &&\n        value !== null &&\n        value.constructor === Object\n      ) {\n        // Detect circular references\n        if (seen.has(value)) {\n          flattened[attributeKey] = '<circular-reference>';\n          continue;\n        }\n\n        // Mark as visited and recursively flatten\n        seen.add(value);\n        flatten(value as Record<string, unknown>, attributeKey);\n        continue;\n      }\n\n      // Serialize arrays and other non-plain objects to JSON\n      try {\n        flattened[attributeKey] = JSON.stringify(value);\n      } catch {\n        // Handle circular references or non-serializable objects\n        flattened[attributeKey] = '<serialization-failed>';\n      }\n    }\n  }\n\n  flatten(metadata, prefix);\n  return flattened;\n}\n"],"mappings":"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"}
+{"version":3,"file":"trace-helpers.cjs","names":["trace","requireModule","context","SpanStatusCode"],"sources":["../src/trace-helpers.ts"],"sourcesContent":["/**\n * Trace context helpers - Core primitives for trace correlation\n *\n * These are the building blocks that allow users to bring their own logger\n * (bunyan, log4js, custom, etc.) and add trace correlation.\n *\n * @example Using with bunyan\n * ```typescript\n * import bunyan from 'bunyan';\n * import { enrichWithTraceContext } from 'autotel/trace-helpers';\n *\n * const bunyanLogger = bunyan.createLogger({ name: 'myapp' });\n *\n * const logger = {\n *   info: (msg: string, extra?: object) => {\n *     bunyanLogger.info(enrichWithTraceContext(extra || {}), msg);\n *   }\n * };\n * ```\n *\n * @example Using with log4js\n * ```typescript\n * import log4js from 'log4js';\n * import { getTraceContext } from 'autotel/trace-helpers';\n *\n * const log4jsLogger = log4js.getLogger();\n *\n * function logWithTrace(level: string, msg: string, extra?: object) {\n *   const context = getTraceContext();\n *   log4jsLogger[level](msg, { ...extra, ...context });\n * }\n * ```\n */\n\nimport { trace, context, SpanStatusCode } from '@opentelemetry/api';\nimport type { Span, Tracer, Context } from '@opentelemetry/api';\nimport { requireModule } from './node-require';\n\n/**\n * WeakMap to store span names for active spans\n * This allows us to retrieve the span name even though OpenTelemetry\n * doesn't expose it through the public API\n */\nconst spanNameMap = new WeakMap<Span, string>();\n\n/**\n * Store span name for a given span\n * Called internally when spans are created\n */\nexport function setSpanName(span: Span, name: string): void {\n  spanNameMap.set(span, name);\n}\n\n/**\n * Trace context extracted from active span\n */\nexport interface TraceContext {\n  /** Full 32-character hex trace ID */\n  traceId: string;\n  /** 16-character hex span ID */\n  spanId: string;\n  /** First 16 characters of trace ID (for log grouping/correlation) */\n  correlationId: string;\n  /** Function/operation name (OpenTelemetry semantic convention: code.function) */\n  'code.function'?: string;\n  /** Datadog trace ID in decimal format (lower 64 bits) for log-trace correlation */\n  'dd.trace_id'?: string;\n  /** Datadog span ID in decimal format for log-trace correlation */\n  'dd.span_id'?: string;\n}\n\n/**\n * Convert hex string to decimal string representation\n * Handles 64-bit unsigned integers for Datadog correlation\n *\n * @param hex - Hex string (up to 16 characters for 64-bit)\n * @returns Decimal string representation\n */\nfunction hexToDecimal(hex: string): string {\n  // For 64-bit values, use BigInt to avoid precision loss\n  return BigInt('0x' + hex).toString(10);\n}\n\n/**\n * Get current trace context from active span\n *\n * Returns null if no span is active (e.g., outside of trace operation)\n *\n * Includes both OpenTelemetry standard fields (hex) and Datadog-specific\n * fields (decimal) for maximum compatibility.\n *\n * @returns Trace context with traceId, spanId, correlationId, and Datadog decimal IDs, or null\n *\n * @example\n * ```typescript\n * import { getTraceContext } from 'autotel/trace-helpers';\n *\n * const context = getTraceContext();\n * if (context) {\n *   console.log('Current trace:', context.traceId);\n *   // Current trace: 4bf92f3577b34da6a3ce929d0e0e4736\n *   console.log('Datadog trace ID:', context['dd.trace_id']);\n *   // Datadog trace ID: 12007117331170166582 (decimal for log correlation)\n * }\n * ```\n */\nexport function getTraceContext(): TraceContext | null {\n  const span = trace.getActiveSpan();\n  if (!span) return null;\n\n  const spanContext = span.spanContext();\n  const traceId = spanContext.traceId;\n  const spanId = spanContext.spanId;\n\n  // Get span name from WeakMap (set when span is created)\n  // Map to OpenTelemetry semantic convention: code.function\n  const spanName = spanNameMap.get(span);\n\n  // Datadog uses the lower 64 bits of the 128-bit OpenTelemetry trace ID\n  // Convert from hex to decimal for Datadog's log-trace correlation\n  const traceIdLower64 = traceId.slice(-16); // Last 16 hex chars = lower 64 bits\n  const ddTraceId = hexToDecimal(traceIdLower64);\n  const ddSpanId = hexToDecimal(spanId);\n\n  return {\n    traceId,\n    spanId,\n    correlationId: traceId.slice(0, 16),\n    ...(spanName && { 'code.function': spanName }),\n    // Datadog-specific fields for log-trace correlation\n    'dd.trace_id': ddTraceId,\n    'dd.span_id': ddSpanId,\n  };\n}\n\n/**\n * Enrich object with trace context (traceId, spanId, correlationId, and Datadog fields)\n *\n * If no span is active, returns the object unchanged.\n * This prevents \"undefined\" or \"null\" values in logs.\n *\n * Automatically adds both OpenTelemetry standard fields (hex) and Datadog-specific\n * fields (decimal) for maximum compatibility with observability backends.\n *\n * @param obj - Object to enrich (e.g., log metadata)\n * @returns Object with trace context merged in, or unchanged if no active span\n *\n * @example\n * ```typescript\n * import { enrichWithTraceContext } from 'autotel/trace-helpers';\n *\n * // Inside a trace operation:\n * const enriched = enrichWithTraceContext({ userId: '123' });\n * // {\n * //   userId: '123',\n * //   traceId: '4bf92f3577b34da6a3ce929d0e0e4736',\n * //   spanId: '00f067aa0ba902b7',\n * //   correlationId: '4bf92f3577b34da6',\n * //   'dd.trace_id': '12007117331170166582',  // Datadog decimal format\n * //   'dd.span_id': '67667974448284583'       // Datadog decimal format\n * // }\n *\n * // Outside trace operation:\n * const unchanged = enrichWithTraceContext({ userId: '123' });\n * // { userId: '123' } - no trace fields added\n * ```\n */\nexport function enrichWithTraceContext<T extends Record<string, unknown>>(\n  obj: T,\n): T {\n  const context = getTraceContext();\n  return context ? ({ ...obj, ...context } as T) : obj;\n}\n\n/**\n * Check if currently in a trace context\n *\n * Useful for conditional logic based on trace presence\n *\n * @returns true if active span exists, false otherwise\n *\n * @example\n * ```typescript\n * import { isTracing } from 'autotel/trace-helpers';\n *\n * if (isTracing()) {\n *   // Add expensive debug metadata only when tracing\n *   logger.debug('Detailed context', expensiveDebugData());\n * }\n * ```\n */\nexport function isTracing(): boolean {\n  return trace.getActiveSpan() !== undefined;\n}\n\n/**\n * Get a tracer instance for creating custom spans\n *\n * Use this when you need low-level control over span lifecycle.\n * For most use cases, prefer trace(), span(), or instrument() instead.\n *\n * @param name - Tracer name (usually your service or module name)\n * @param version - Optional version string\n * @returns OpenTelemetry Tracer instance\n *\n * @example Basic usage\n * ```typescript\n * import { getTracer } from 'autotel';\n *\n * const tracer = getTracer('my-service');\n * const span = tracer.startSpan('custom.operation');\n * try {\n *   // Your logic\n *   span.setAttribute('key', 'value');\n * } finally {\n *   span.end();\n * }\n * ```\n *\n * @example With AI SDK\n * ```typescript\n * import { getTracer } from 'autotel';\n * import { generateText } from 'ai';\n *\n * const tracer = getTracer('ai-agent');\n * const result = await generateText({\n *   model: myModel,\n *   prompt: 'Hello',\n *   experimental_telemetry: {\n *     isEnabled: true,\n *     tracer,\n *   },\n * });\n * ```\n */\nexport function getTracer(name: string, version?: string): Tracer {\n  return trace.getTracer(name, version);\n}\n\n/**\n * Get the currently active span\n *\n * Returns undefined if no span is currently active.\n * Useful for adding attributes to the current span.\n *\n * @returns Active span or undefined\n *\n * @example Adding attributes to active span\n * ```typescript\n * import { getActiveSpan } from 'autotel';\n *\n * const span = getActiveSpan();\n * if (span) {\n *   span.setAttribute('user.id', userId);\n *   span.setAttribute('user.action', 'click');\n * }\n * ```\n *\n * @example Checking span status\n * ```typescript\n * import { getActiveSpan, SpanStatusCode } from 'autotel';\n *\n * const span = getActiveSpan();\n * if (span?.isRecording()) {\n *   span.setStatus({ code: SpanStatusCode.OK });\n * }\n * ```\n */\nexport function getActiveSpan(): Span | undefined {\n  return trace.getActiveSpan();\n}\n\n/**\n * Get the currently active OpenTelemetry context\n *\n * The context contains the active span and any baggage.\n * Useful for context propagation and custom instrumentation.\n *\n * @returns Current active context\n *\n * @example Propagating context\n * ```typescript\n * import { getActiveContext } from 'autotel';\n *\n * const currentContext = getActiveContext();\n * // Pass context to another function or service\n * ```\n *\n * @example With context injection\n * ```typescript\n * import { getActiveContext, injectTraceContext } from 'autotel';\n *\n * const headers = {};\n * injectTraceContext(headers);\n * // Headers now contain trace propagation data\n * ```\n */\nexport function getActiveContext(): Context {\n  // Check stored context first (from baggage setters), then fall back to active context\n  // This ensures ctx.setBaggage() changes are visible to OpenTelemetry operations\n  try {\n    const { getActiveContextWithBaggage } = requireModule<{\n      getActiveContextWithBaggage: () => Context;\n    }>('./trace-context');\n    return getActiveContextWithBaggage();\n  } catch {\n    // Fallback if trace-context isn't available\n    return context.active();\n  }\n}\n\n/**\n * Run a function with a specific span set as active\n *\n * This is a convenience wrapper around the two-step process of\n * setting a span in context and running code within that context.\n *\n * @param span - The span to set as active\n * @param fn - Function to execute with the span active\n * @returns The return value of the function\n *\n * @example Running code with a custom span\n * ```typescript\n * import { getTracer, runWithSpan } from 'autotel';\n *\n * const tracer = getTracer('my-service');\n * const span = tracer.startSpan('background.job');\n *\n * try {\n *   const result = await runWithSpan(span, async () => {\n *     // Any spans created here will be children of 'background.job'\n *     await processData();\n *     return { success: true };\n *   });\n *   console.log(result);\n * } finally {\n *   span.end();\n * }\n * ```\n *\n * @example Testing with custom spans\n * ```typescript\n * import { runWithSpan, otelTrace } from 'autotel';\n *\n * const tracer = otelTrace.getTracer('test');\n * const span = tracer.startSpan('test.operation');\n *\n * const result = runWithSpan(span, () => {\n *   // Code under test runs with this span as active\n *   return myFunction();\n * });\n *\n * span.end();\n * ```\n */\nexport function runWithSpan<T>(span: Span, fn: () => T): T {\n  const ctx = trace.setSpan(context.active(), span);\n  return context.with(ctx, fn);\n}\n\n/**\n * Finalize a span with appropriate status and optional error recording\n *\n * This is a convenience function that:\n * - Records exceptions if an error is provided\n * - Sets span status to ERROR if error exists, OK otherwise\n * - Ends the span\n *\n * @param span - The span to finalize\n * @param error - Optional error to record\n *\n * @example Without error (success case)\n * ```typescript\n * import { getTracer, finalizeSpan } from 'autotel';\n *\n * const tracer = getTracer('my-service');\n * const span = tracer.startSpan('operation');\n *\n * try {\n *   await doWork();\n *   finalizeSpan(span);\n * } catch (error) {\n *   finalizeSpan(span, error);\n *   throw error;\n * }\n * ```\n *\n * @example With error\n * ```typescript\n * import { getTracer, finalizeSpan } from 'autotel';\n *\n * const tracer = getTracer('my-service');\n * const span = tracer.startSpan('operation');\n *\n * try {\n *   await riskyOperation();\n *   finalizeSpan(span);\n * } catch (error) {\n *   finalizeSpan(span, error); // Records exception and sets ERROR status\n *   throw error;\n * }\n * ```\n *\n * @example In instrumentation\n * ```typescript\n * import { getTracer, runWithSpan, finalizeSpan } from 'autotel';\n *\n * function instrumentedQuery(query: string) {\n *   const tracer = getTracer('db');\n *   const span = tracer.startSpan('db.query');\n *\n *   return runWithSpan(span, () => {\n *     try {\n *       const result = executeQuery(query);\n *       finalizeSpan(span);\n *       return result;\n *     } catch (error) {\n *       finalizeSpan(span, error);\n *       throw error;\n *     }\n *   });\n * }\n * ```\n */\nexport function finalizeSpan(span: Span, error?: unknown): void {\n  if (error) {\n    if (error instanceof Error) {\n      span.recordException(error);\n    } else {\n      span.recordException(new Error(String(error)));\n    }\n    span.setStatus({ code: SpanStatusCode.ERROR });\n  } else {\n    span.setStatus({ code: SpanStatusCode.OK });\n  }\n  span.end();\n}\n\n/**\n * Creates a deterministic trace ID from a seed string.\n *\n * Generates a consistent 128-bit trace ID (32 hex characters) from an input seed\n * using SHA-256 hashing. Useful for correlating external system IDs (request IDs,\n * order IDs, session IDs) with OpenTelemetry trace IDs.\n *\n * **Use Cases:**\n * - Correlate external request IDs with traces\n * - Link customer support tickets to trace data\n * - Associate business entities (orders, sessions) with observability data\n * - Debug specific user flows by deterministic trace lookup\n *\n * **Important:** Only use this when you need deterministic trace IDs for correlation.\n * For normal tracing, let OpenTelemetry generate random trace IDs automatically.\n *\n * **Runtime Support:**\n * - Node.js 15+ (native crypto.subtle)\n * - All modern browsers\n * - Edge runtimes (Cloudflare Workers, Deno, etc.)\n *\n * @param seed - Input string to generate trace ID from (e.g., request ID, order ID)\n * @returns Promise resolving to a 32-character hex trace ID (128 bits)\n *\n * @example Correlate external request ID with trace\n * ```typescript\n * import { createDeterministicTraceId } from 'autotel/trace-helpers'\n * import { trace, context } from '@opentelemetry/api'\n *\n * // In middleware or request handler\n * const requestId = req.headers['x-request-id']\n * const traceId = await createDeterministicTraceId(requestId)\n *\n * // Use with manual span creation (advanced - not needed with trace/span functions)\n * const tracer = trace.getTracer('my-service')\n * const spanContext = {\n *   traceId,\n *   spanId: '0123456789abcdef', // Still random\n *   traceFlags: 1\n * }\n * ```\n *\n * @example Link customer support tickets to traces\n * ```typescript\n * import { createDeterministicTraceId } from 'autotel/trace-helpers'\n *\n * // Support dashboard integration\n * const ticketId = 'TICKET-12345'\n * const traceId = await createDeterministicTraceId(ticketId)\n *\n * // Generate direct link to traces in observability backend\n * const traceUrl = `https://your-otel-backend.com/traces/${traceId}`\n * console.log(`View related traces: ${traceUrl}`)\n * ```\n *\n * @example Session-based correlation\n * ```typescript\n * import { createDeterministicTraceId } from 'autotel/trace-helpers'\n *\n * // Track all operations for a user session\n * const sessionId = req.session.id\n * const traceId = await createDeterministicTraceId(sessionId)\n *\n * // All operations in this session share the same trace ID\n * // Makes it easy to find all activity for a specific session\n * ```\n *\n * @public\n */\nexport async function createDeterministicTraceId(\n  seed: string,\n): Promise<string> {\n  // Encode seed string to bytes\n  const encoder = new TextEncoder();\n  const data = encoder.encode(seed);\n\n  // Generate SHA-256 hash (256 bits)\n  const hashBuffer = await crypto.subtle.digest('SHA-256', data);\n\n  // Convert to hex string and truncate to 32 characters (128 bits)\n  // OpenTelemetry trace IDs are 128 bits (16 bytes, 32 hex characters)\n  const hashArray = new Uint8Array(hashBuffer);\n  return [...hashArray]\n    .map((byte) => byte.toString(16).padStart(2, '0'))\n    .join('')\n    .slice(0, 32);\n}\n\n/**\n * Flattens nested metadata objects into dot-notation span attributes.\n *\n * Converts complex nested objects into flat key-value pairs suitable for\n * OpenTelemetry span attributes. Non-string values are JSON serialized.\n * Handles serialization failures gracefully with a fallback value.\n *\n * **Use Cases:**\n * - Structured metadata with nested objects\n * - User context with multiple properties\n * - Request/response metadata\n * - Business entity attributes\n *\n * **Note:** Filters out null/undefined values automatically to keep spans clean.\n *\n * @param metadata - Nested metadata object to flatten\n * @param prefix - Prefix for all attribute keys (default: 'metadata')\n * @returns Flattened attributes as { [key: string]: string }\n *\n * @example Basic metadata flattening\n * ```typescript\n * import { flattenMetadata } from 'autotel/trace-helpers'\n * import { trace, withTracing } from 'autotel'\n *\n * export const processOrder = withTracing({})(ctx => async (orderId: string) => {\n *   const order = await getOrder(orderId)\n *\n *   // Flatten complex order metadata\n *   const flattened = flattenMetadata({\n *     user: { id: order.userId, tier: 'premium' },\n *     payment: { method: 'card', processor: 'stripe' },\n *     items: order.items.length\n *   })\n *\n *   ctx.setAttributes(flattened)\n *   // Results in:\n *   // {\n *   //   'metadata.user.id': 'user-123',\n *   //   'metadata.user.tier': 'premium',\n *   //   'metadata.payment.method': 'card',\n *   //   'metadata.payment.processor': 'stripe',\n *   //   'metadata.items': '5'\n *   // }\n * })\n * ```\n *\n * @example Custom prefix for semantic conventions\n * ```typescript\n * import { flattenMetadata } from 'autotel/trace-helpers'\n * import { trace, withTracing } from 'autotel'\n *\n * export const fetchUser = withTracing({})(ctx => async (userId: string) => {\n *   const user = await db.users.findOne({ id: userId })\n *\n *   // Use semantic convention prefix\n *   const userAttrs = flattenMetadata(\n *     {\n *       id: user.id,\n *       email: user.email,\n *       plan: user.subscription.plan\n *     },\n *     'user'  // Custom prefix\n *   )\n *\n *   ctx.setAttributes(userAttrs)\n *   // Results in:\n *   // {\n *   //   'user.id': 'user-123',\n *   //   'user.email': 'user@example.com',\n *   //   'user.plan': 'enterprise'\n *   // }\n * })\n * ```\n *\n * @example With complex objects (auto-serialized)\n * ```typescript\n * import { flattenMetadata } from 'autotel/trace-helpers'\n * import { trace, withTracing } from 'autotel'\n *\n * export const analyzeRequest = withTracing({})(ctx => async (req: Request) => {\n *   const metadata = flattenMetadata({\n *     headers: req.headers,  // Object - will be JSON serialized\n *     query: req.query,       // Object - will be JSON serialized\n *     timestamp: new Date()   // Non-string - will be JSON serialized\n *   })\n *\n *   ctx.setAttributes(metadata)\n *   // Results in:\n *   // {\n *   //   'metadata.headers': '{\"accept\":\"application/json\",...}',\n *   //   'metadata.query': '{\"page\":\"1\",\"limit\":\"10\"}',\n *   //   'metadata.timestamp': '\"2024-01-15T12:00:00.000Z\"'\n *   // }\n * })\n * ```\n *\n * @example Error handling\n * ```typescript\n * import { flattenMetadata } from 'autotel/trace-helpers'\n *\n * // Objects with circular references are handled gracefully\n * const circular: any = { a: 1 }\n * circular.self = circular\n *\n * const flattened = flattenMetadata({ data: circular })\n * // Results in:\n * // { 'metadata.data': '<serialization-failed>' }\n * ```\n *\n * @public\n */\n/**\n * Resolve a trace URL from a template string and trace ID.\n *\n * Templates use `{traceId}` as placeholder. Falls back to `OTEL_TRACE_URL_TEMPLATE` env var.\n *\n * @example\n * resolveTraceUrl('https://grafana.example.com/explore?traceId={traceId}', 'abc123')\n * // => 'https://grafana.example.com/explore?traceId=abc123'\n */\nexport function resolveTraceUrl(\n  template: string | undefined,\n  traceId: string,\n): string | undefined {\n  const t = template ?? process.env.OTEL_TRACE_URL_TEMPLATE;\n  if (!t) return undefined;\n  return t.replaceAll('{traceId}', traceId);\n}\n\nexport function flattenMetadata(\n  metadata: Record<string, unknown>,\n  prefix = 'metadata',\n): Record<string, string> {\n  const flattened: Record<string, string> = {};\n  const seen = new WeakSet<object>(); // Track visited objects to detect cycles\n\n  function flatten(obj: Record<string, unknown>, currentPrefix: string): void {\n    for (const [key, value] of Object.entries(obj)) {\n      // Skip null/undefined values\n      if (value == null) continue;\n\n      const attributeKey = `${currentPrefix}.${key}`;\n\n      // Handle primitives directly (string, number, boolean)\n      if (typeof value === 'string') {\n        flattened[attributeKey] = value;\n        continue;\n      }\n      if (typeof value === 'number' || typeof value === 'boolean') {\n        flattened[attributeKey] = String(value);\n        continue;\n      }\n\n      // Recursively flatten plain objects (with cycle detection)\n      if (\n        typeof value === 'object' &&\n        value !== null &&\n        value.constructor === Object\n      ) {\n        // Detect circular references\n        if (seen.has(value)) {\n          flattened[attributeKey] = '<circular-reference>';\n          continue;\n        }\n\n        // Mark as visited and recursively flatten\n        seen.add(value);\n        flatten(value as Record<string, unknown>, attributeKey);\n        continue;\n      }\n\n      // Serialize arrays and other non-plain objects to JSON\n      try {\n        flattened[attributeKey] = JSON.stringify(value);\n      } catch {\n        // Handle circular references or non-serializable objects\n        flattened[attributeKey] = '<serialization-failed>';\n      }\n    }\n  }\n\n  flatten(metadata, prefix);\n  return flattened;\n}\n"],"mappings":"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"}

package/dist/trace-helpers.d.cts

@@ -1,5 +1,4 @@
 import { Context, Span, Tracer } from "@opentelemetry/api";
-
 //#region src/trace-helpers.d.ts
 /**
  * Store span name for a given span
@@ -397,9 +396,9 @@ declare function createDeterministicTraceId(seed: string): Promise<string>;
  * @example Basic metadata flattening
  * ```typescript
  * import { flattenMetadata } from 'autotel/trace-helpers'
- * import { trace } from 'autotel'
+ * import { trace, withTracing } from 'autotel'
  *
- * export const processOrder = trace(ctx => async (orderId: string) => {
+ * export const processOrder = withTracing({})(ctx => async (orderId: string) => {
  *   const order = await getOrder(orderId)
  *
  *   // Flatten complex order metadata
@@ -424,9 +423,9 @@ declare function createDeterministicTraceId(seed: string): Promise<string>;
  * @example Custom prefix for semantic conventions
  * ```typescript
  * import { flattenMetadata } from 'autotel/trace-helpers'
- * import { trace } from 'autotel'
+ * import { trace, withTracing } from 'autotel'
  *
- * export const fetchUser = trace(ctx => async (userId: string) => {
+ * export const fetchUser = withTracing({})(ctx => async (userId: string) => {
  *   const user = await db.users.findOne({ id: userId })
  *
  *   // Use semantic convention prefix
@@ -452,9 +451,9 @@ declare function createDeterministicTraceId(seed: string): Promise<string>;
  * @example With complex objects (auto-serialized)
  * ```typescript
  * import { flattenMetadata } from 'autotel/trace-helpers'
- * import { trace } from 'autotel'
+ * import { trace, withTracing } from 'autotel'
  *
- * export const analyzeRequest = trace(ctx => async (req: Request) => {
+ * export const analyzeRequest = withTracing({})(ctx => async (req: Request) => {
  *   const metadata = flattenMetadata({
  *     headers: req.headers,  // Object - will be JSON serialized
  *     query: req.query,       // Object - will be JSON serialized

package/dist/trace-helpers.d.cts.map

@@ -1 +1 @@
-{"version":3,"file":"trace-helpers.d.cts","names":[],"sources":["../src/trace-helpers.ts"],"mappings":";;;;;;;iBAiDgB,WAAA,CAAY,IAAA,EAAM,IAAI,EAAE,IAAA;;;;UAOvB,YAAA;EAiHb;EA/GF,OAAA;EAqIuB;EAnIvB,MAAA;EAmIuB;EAjIvB,aAAA;EA6Kc;EA3Kd,eAAA;;EAEA,aAAA;EAyKwB;EAvKxB,YAAA;AAAA;;AAuK+D;AAiCjE;;;;AAAqC;AA6BrC;;;;AAA2C;AA0D3C;;;;;;;;;;;iBAzPgB,eAAA,IAAmB,YAAY;;;;AAyPW;AAqE1D;;;;;;;;AAAwD;AAmFxD;;;;AAEU;AAyIV;;;;AAEiB;AAOjB;;;;;;;;;iBAxegB,sBAAA,WAAiC,MAAA,mBAC/C,GAAA,EAAK,CAAA,GACJ,CAAA;;;;;;;;;;;;;;;;;;iBAsBa,SAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBA4CA,SAAA,CAAU,IAAA,UAAc,OAAA,YAAmB,MAAM;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAiCjD,aAAA,IAAiB,IAAI;;;;;;;;;;;;;;;;;;;;;;;;;;iBA6BrB,gBAAA,IAAoB,OAAO;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBA0D3B,WAAA,IAAe,IAAA,EAAM,IAAA,EAAM,EAAA,QAAU,CAAA,GAAI,CAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAqEzC,YAAA,CAAa,IAAA,EAAM,IAAI,EAAE,KAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAmFnB,0BAAA,CACpB,IAAA,WACC,OAAO;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAyIM,eAAA,CACd,QAAA,sBACA,OAAe;AAAA,iBAOD,eAAA,CACd,QAAA,EAAU,MAAA,mBACV,MAAA,YACC,MAAM"}
+{"version":3,"file":"trace-helpers.d.cts","names":[],"sources":["../src/trace-helpers.ts"],"mappings":";;;;;;iBAiDgB,YAAY,MAAM,MAAM;;;;UAOvB;;EAEf;;EAEA;;EAEA;;EAEA;;EAEA;;EAEA;;;;;;;;;;;;;;;;;;;;;;;;;iBAsCc,mBAAmB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBA6DnB,uBAAuB,UAAU,yBAC/C,KAAK,IACJ;;;;;;;;;;;;;;;;;;iBAsBa;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBA4CA,UAAU,cAAc,mBAAmB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAiC3C,iBAAiB;;;;;;;;;;;;;;;;;;;;;;;;;;iBA6BjB,oBAAoB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBA0DpB,YAAY,GAAG,MAAM,MAAM,UAAU,IAAI;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAqEzC,aAAa,MAAM,MAAM;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAmFnB,2BACpB,eACC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAyIa,gBACd,8BACA;iBAOc,gBACd,UAAU,yBACV,kBACC"}

package/dist/trace-helpers.d.ts

@@ -1,5 +1,4 @@
 import { Context, Span, Tracer } from "@opentelemetry/api";
-
 //#region src/trace-helpers.d.ts
 /**
  * Store span name for a given span
@@ -397,9 +396,9 @@ declare function createDeterministicTraceId(seed: string): Promise<string>;
  * @example Basic metadata flattening
  * ```typescript
  * import { flattenMetadata } from 'autotel/trace-helpers'
- * import { trace } from 'autotel'
+ * import { trace, withTracing } from 'autotel'
  *
- * export const processOrder = trace(ctx => async (orderId: string) => {
+ * export const processOrder = withTracing({})(ctx => async (orderId: string) => {
  *   const order = await getOrder(orderId)
  *
  *   // Flatten complex order metadata
@@ -424,9 +423,9 @@ declare function createDeterministicTraceId(seed: string): Promise<string>;
  * @example Custom prefix for semantic conventions
  * ```typescript
  * import { flattenMetadata } from 'autotel/trace-helpers'
- * import { trace } from 'autotel'
+ * import { trace, withTracing } from 'autotel'
  *
- * export const fetchUser = trace(ctx => async (userId: string) => {
+ * export const fetchUser = withTracing({})(ctx => async (userId: string) => {
  *   const user = await db.users.findOne({ id: userId })
  *
  *   // Use semantic convention prefix
@@ -452,9 +451,9 @@ declare function createDeterministicTraceId(seed: string): Promise<string>;
  * @example With complex objects (auto-serialized)
  * ```typescript
  * import { flattenMetadata } from 'autotel/trace-helpers'
- * import { trace } from 'autotel'
+ * import { trace, withTracing } from 'autotel'
  *
- * export const analyzeRequest = trace(ctx => async (req: Request) => {
+ * export const analyzeRequest = withTracing({})(ctx => async (req: Request) => {
  *   const metadata = flattenMetadata({
  *     headers: req.headers,  // Object - will be JSON serialized
  *     query: req.query,       // Object - will be JSON serialized

package/dist/trace-helpers.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"trace-helpers.d.ts","names":[],"sources":["../src/trace-helpers.ts"],"mappings":";;;;;;;iBAiDgB,WAAA,CAAY,IAAA,EAAM,IAAI,EAAE,IAAA;;;;UAOvB,YAAA;EAiHb;EA/GF,OAAA;EAqIuB;EAnIvB,MAAA;EAmIuB;EAjIvB,aAAA;EA6Kc;EA3Kd,eAAA;;EAEA,aAAA;EAyKwB;EAvKxB,YAAA;AAAA;;AAuK+D;AAiCjE;;;;AAAqC;AA6BrC;;;;AAA2C;AA0D3C;;;;;;;;;;;iBAzPgB,eAAA,IAAmB,YAAY;;;;AAyPW;AAqE1D;;;;;;;;AAAwD;AAmFxD;;;;AAEU;AAyIV;;;;AAEiB;AAOjB;;;;;;;;;iBAxegB,sBAAA,WAAiC,MAAA,mBAC/C,GAAA,EAAK,CAAA,GACJ,CAAA;;;;;;;;;;;;;;;;;;iBAsBa,SAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBA4CA,SAAA,CAAU,IAAA,UAAc,OAAA,YAAmB,MAAM;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAiCjD,aAAA,IAAiB,IAAI;;;;;;;;;;;;;;;;;;;;;;;;;;iBA6BrB,gBAAA,IAAoB,OAAO;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBA0D3B,WAAA,IAAe,IAAA,EAAM,IAAA,EAAM,EAAA,QAAU,CAAA,GAAI,CAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAqEzC,YAAA,CAAa,IAAA,EAAM,IAAI,EAAE,KAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAmFnB,0BAAA,CACpB,IAAA,WACC,OAAO;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAyIM,eAAA,CACd,QAAA,sBACA,OAAe;AAAA,iBAOD,eAAA,CACd,QAAA,EAAU,MAAA,mBACV,MAAA,YACC,MAAM"}
+{"version":3,"file":"trace-helpers.d.ts","names":[],"sources":["../src/trace-helpers.ts"],"mappings":";;;;;;iBAiDgB,YAAY,MAAM,MAAM;;;;UAOvB;;EAEf;;EAEA;;EAEA;;EAEA;;EAEA;;EAEA;;;;;;;;;;;;;;;;;;;;;;;;;iBAsCc,mBAAmB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBA6DnB,uBAAuB,UAAU,yBAC/C,KAAK,IACJ;;;;;;;;;;;;;;;;;;iBAsBa;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBA4CA,UAAU,cAAc,mBAAmB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAiC3C,iBAAiB;;;;;;;;;;;;;;;;;;;;;;;;;;iBA6BjB,oBAAoB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBA0DpB,YAAY,GAAG,MAAM,MAAM,UAAU,IAAI;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAqEzC,aAAa,MAAM,MAAM;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAmFnB,2BACpB,eACC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAyIa,gBACd,8BACA;iBAOc,gBACd,UAAU,yBACV,kBACC"}