logixia 2.0.4 → 2.0.7

package/dist/{request-trace-wTJdKp6-.js → request-trace-ByujsUZk.js}

@@ -275,10 +275,6 @@ function createTraceMiddleware(config) {
 	};
 }
 // src/utils/request-trace.ts
-/**
-* Per-request trace ID resolution shared by the HTTP logger middleware and the
-* context helpers. Internal: not re-exported from the package entry points.
-*/
 /** Fastify's default `genReqId` output (`req-` + base36 counter), unique only per process. */
 const FASTIFY_COUNTER_ID = /^req-[\da-z]+$/;
 const FALLBACK_KEY = "_logixiaFallbackId";
@@ -399,4 +395,4 @@ Object.defineProperty(exports, "traceStorage", {
 	}
 });
 
-//# sourceMappingURL=request-trace-wTJdKp6-.js.map
+//# sourceMappingURL=request-trace-ByujsUZk.js.map

package/dist/{request-trace-wTJdKp6-.js.map → request-trace-ByujsUZk.js.map}

@@ -1 +1 @@
-{"version":3,"file":"request-trace-wTJdKp6-.js","names":["AsyncLocalStorage","randomUUID"],"sources":["../src/utils/trace.utils.ts","../src/utils/request-trace.ts"],"sourcesContent":["/**\n * Trace ID utilities for Logitron\n */\n\nimport { AsyncLocalStorage } from 'node:async_hooks';\nimport { randomUUID } from 'node:crypto';\n\nimport type { TraceIdConfig, TraceIdExtractorConfig } from '../types';\n\n/** Default key used to store the trace ID in AsyncLocalStorage. */\nexport const TRACE_CONTEXT_KEY = 'traceId' as const;\n\n// ── TraceContext class ────────────────────────────────────────────────────────\n\n/**\n * Singleton that owns the AsyncLocalStorage and the active contextKey.\n *\n * Why a class instead of bare module-level variables?\n *  - The contextKey is user-configurable; encapsulating it here means there is\n *    exactly one place that reads and writes it.\n *  - All helpers (getCurrentTraceId, runWithTraceId, etc.) delegate to this\n *    instance, so the key is always in sync without hidden global state.\n *  - Easier to test: you can reset the singleton between test cases.\n *\n * Usage (advanced):\n *   import { TraceContext } from 'logixia';\n *   TraceContext.instance.contextKey          // → 'traceId' (or custom)\n *   TraceContext.instance.getCurrentTraceId() // same as standalone fn\n */\nexport class TraceContext {\n  private static _instance: TraceContext | null = null;\n\n  readonly storage = new AsyncLocalStorage<Record<string, unknown>>();\n  private _contextKey: string = TRACE_CONTEXT_KEY;\n\n  private constructor() {}\n\n  /** The process-wide singleton. */\n  static get instance(): TraceContext {\n    if (!TraceContext._instance) {\n      TraceContext._instance = new TraceContext();\n    }\n    return TraceContext._instance;\n  }\n\n  /** @internal Reset the singleton (useful in tests). */\n  static _reset(): void {\n    TraceContext._instance = null;\n  }\n\n  // ── Key management ──────────────────────────────────────────────────────────\n\n  /** The AsyncLocalStorage key that holds the trace ID value. */\n  get contextKey(): string {\n    return this._contextKey;\n  }\n\n  /** @internal Called by TraceMiddleware when it boots to register the user's key. */\n  setContextKey(key: string): void {\n    this._contextKey = key;\n  }\n\n  // ── Core operations ─────────────────────────────────────────────────────────\n\n  /** UUID v4 generator (default). */\n  generate(): string {\n    return randomUUID();\n  }\n\n  /** Read the trace ID from the current async context. */\n  getCurrentTraceId(): string | undefined {\n    return this.storage.getStore()?.[this._contextKey] as string | undefined;\n  }\n\n  /**\n   * Mutate the CURRENT async context in-place.\n   *\n   * ⚠️  DEPRECATED — unsafe for concurrent requests.\n   *\n   * Uses `AsyncLocalStorage.enterWith()`, which mutates the current async\n   * execution context and every Promise chain spawned from it. In a server\n   * processing overlapping requests this can cause a trace ID set for one\n   * request to bleed into *other* in-flight requests that share the same\n   * async parent (e.g. a module-level setup function or a cached handler).\n   *\n   * Use {@link run} instead — it scopes the context to a callback so there\n   * is no risk of cross-request leakage.\n   *\n   * @deprecated Use `TraceContext.instance.run(traceId, fn)` — do not call\n   *             `setTraceId` from request-handling code.\n   */\n  setTraceId(traceId: string, data?: Record<string, unknown>): void {\n    const current = this.storage.getStore() ?? {};\n    this.storage.enterWith({ ...current, [this._contextKey]: traceId, ...data });\n  }\n\n  /** Run `fn` inside a new async context that carries `traceId`. */\n  run<T>(traceId: string, fn: () => T, data?: Record<string, unknown>): T {\n    return this.storage.run({ [this._contextKey]: traceId, ...data }, fn);\n  }\n}\n\n// ── Module-level aliases (backwards-compatible public API) ────────────────────\n\n/**\n * The shared AsyncLocalStorage instance.\n * @deprecated Prefer `TraceContext.instance.storage` for new code.\n */\nexport const traceStorage = TraceContext.instance.storage;\n\n/** Returns the key currently used to store the trace ID in AsyncLocalStorage. */\nexport function getTraceContextKey(): string {\n  return TraceContext.instance.contextKey;\n}\n\n/** @internal Called by TraceMiddleware / traceMiddleware() when they boot. */\nexport function _setActiveContextKey(key: string): void {\n  TraceContext.instance.setContextKey(key);\n}\n\n/** Generate a UUID v4 trace ID. */\nexport function generateTraceId(): string {\n  return TraceContext.instance.generate();\n}\n\n/**\n * Get the current trace ID from async context.\n * Returns `undefined` when called outside a traced request.\n */\nexport function getCurrentTraceId(): string | undefined {\n  return TraceContext.instance.getCurrentTraceId();\n}\n\n/**\n * Set trace ID in the CURRENT async context without starting a new one.\n *\n * ⚠️  DEPRECATED — unsafe for concurrent requests.\n *\n * Uses `AsyncLocalStorage.enterWith()`, which mutates the current async\n * execution context and every Promise chain spawned from it. Under load this\n * can cause a trace ID from one request to bleed into others sharing the same\n * async parent.\n *\n * Use {@link runWithTraceId} instead. Migration patterns:\n *\n * **Express / Fastify middleware — before:**\n * ```ts\n * app.use((req, _res, next) => {\n *   setTraceId(req.headers['x-trace-id'] ?? generateTraceId());\n *   next();\n * });\n * ```\n * **after:**\n * ```ts\n * app.use((req, _res, next) => {\n *   runWithTraceId(req.headers['x-trace-id'] ?? generateTraceId(), () => next());\n * });\n * ```\n *\n * **Kafka / queue consumer — before:**\n * ```ts\n * async function handle(msg) {\n *   setTraceId(msg.headers['x-trace-id']);\n *   await processMessage(msg);\n * }\n * ```\n * **after:**\n * ```ts\n * async function handle(msg) {\n *   await runWithTraceId(msg.headers['x-trace-id'], () => processMessage(msg));\n * }\n * ```\n *\n * **Background job — before:**\n * ```ts\n * setTraceId(generateTraceId(), { jobId: job.id });\n * await job.run();\n * ```\n * **after:**\n * ```ts\n * await runWithTraceId(generateTraceId(), () => job.run(), { jobId: job.id });\n * ```\n *\n * @deprecated Use `runWithTraceId(traceId, fn)` — do not call `setTraceId`\n *             from request-handling code.\n */\nexport function setTraceId(traceId: string, data?: Record<string, unknown>): void {\n  TraceContext.instance.setTraceId(traceId, data);\n}\n\n/** Run `fn` inside a new async context carrying `traceId`. */\nexport function runWithTraceId<T>(traceId: string, fn: () => T, data?: Record<string, unknown>): T {\n  return TraceContext.instance.run(traceId, fn, data);\n}\n\n// ── Request extraction ────────────────────────────────────────────────────────\n\ntype HeaderValue = string | string[] | undefined;\n\n/** Shape that extractTraceId accepts (Express-compatible) */\ninterface RequestLike {\n  headers?: Record<string, HeaderValue>;\n  query?: Record<string, HeaderValue>;\n  body?: Record<string, string | undefined>;\n  params?: Record<string, string | undefined>;\n}\n\n/** Maximum accepted length for an incoming trace / correlation / request ID. */\nexport const MAX_INCOMING_ID_LENGTH = 128;\n\nconst SAFE_INCOMING_ID = /^[A-Za-z0-9._:-]{1,128}$/;\n\n/**\n * Validate an externally supplied identifier (trace ID, correlation ID, origin\n * service name, message-queue ID). Accepts only 1-128 characters from\n * `[A-Za-z0-9._:-]`; surrounding whitespace is trimmed first. Arrays use their\n * first element. Returns the cleaned value, or `undefined` when it is unusable\n * so callers can generate a fresh ID instead of passing client text through.\n */\nexport function sanitizeIncomingId(value: unknown): string | undefined {\n  const first = Array.isArray(value) ? value[0] : value;\n  if (typeof first !== 'string' || first.length > MAX_INCOMING_ID_LENGTH * 2) return undefined;\n  const trimmed = first.trim();\n  return SAFE_INCOMING_ID.test(trimmed) ? trimmed : undefined;\n}\n\n/** W3C trace-context: `version-traceId(32hex)-spanId(16hex)-flags(2hex)`. */\nconst W3C_TRACEPARENT_RE = /^[\\da-f]{2}-([\\da-f]{32})-[\\da-f]{16}-[\\da-f]{2}$/i;\n\n/**\n * Extract the 32-hex trace-id segment from a W3C `traceparent` header value.\n * Returns the parsed trace ID, or the original value unchanged when it is not a\n * well-formed traceparent (so non-W3C propagation still works).\n */\nfunction parseTraceparent(value: string): string {\n  const m = W3C_TRACEPARENT_RE.exec(value);\n  return m ? m[1]! : value;\n}\n\n/** Extract trace ID from request using configuration (header → query → body → params). */\nexport function extractTraceId(\n  request: unknown,\n  config: TraceIdExtractorConfig\n): string | undefined {\n  const req = request as RequestLike;\n\n  if (config.header) {\n    const headers = Array.isArray(config.header) ? config.header : [config.header];\n    for (const header of headers) {\n      const lower = header.toLowerCase();\n      const value = sanitizeIncomingId(req.headers?.[lower]);\n      if (value) return lower === 'traceparent' ? parseTraceparent(value) : value;\n    }\n  }\n\n  if (config.query) {\n    const queries = Array.isArray(config.query) ? config.query : [config.query];\n    for (const query of queries) {\n      const value = sanitizeIncomingId(req.query?.[query]);\n      if (value) return value;\n    }\n  }\n\n  if (config.body) {\n    const bodyFields = Array.isArray(config.body) ? config.body : [config.body];\n    for (const field of bodyFields) {\n      const value = sanitizeIncomingId(req.body?.[field]);\n      if (value) return value;\n    }\n  }\n\n  if (config.params) {\n    const paramFields = Array.isArray(config.params) ? config.params : [config.params];\n    for (const param of paramFields) {\n      const value = sanitizeIncomingId(req.params?.[param]);\n      if (value) return value;\n    }\n  }\n\n  return undefined;\n}\n\n/**\n * Default headers checked for incoming trace ID propagation, in priority order:\n *   traceparent (W3C/OTel) → x-trace-id → x-request-id → x-correlation-id → trace-id\n */\nexport const DEFAULT_TRACE_HEADERS = [\n  'traceparent',\n  'x-trace-id',\n  'x-request-id',\n  'x-correlation-id',\n  'trace-id',\n];\n\n/**\n * Create trace ID middleware for Express/NestJS\n */\nexport function createTraceMiddleware(config: TraceIdConfig) {\n  const defaultExtractor = {\n    header: DEFAULT_TRACE_HEADERS,\n    query: ['traceId', 'trace_id'],\n  };\n  const resolvedConfig: TraceIdConfig = {\n    ...config,\n    extractor: config?.extractor ? { ...defaultExtractor, ...config.extractor } : defaultExtractor,\n  };\n\n  _setActiveContextKey(resolvedConfig.contextKey ?? TRACE_CONTEXT_KEY);\n\n  return (req: unknown, res: unknown, next: () => void) => {\n    let traceId: string | undefined;\n\n    if (resolvedConfig.extractor) {\n      traceId = extractTraceId(req, resolvedConfig.extractor);\n    }\n\n    if (!traceId) {\n      traceId = resolvedConfig.generator ? resolvedConfig.generator() : generateTraceId();\n    }\n\n    (req as Record<string, unknown>).traceId = traceId;\n    // Echo the trace ID back on the response, tolerating different response APIs:\n    // Express/Node use res.setHeader(), Fastify replies use reply.header(). Guard\n    // both and never let a missing/!function method (or already-sent headers)\n    // crash the request — the trace ID is still propagated via async context.\n    const resObj = res as {\n      setHeader?: (k: string, v: string) => void;\n      header?: (k: string, v: string) => void;\n      headersSent?: boolean;\n    };\n    if (!resObj.headersSent) {\n      try {\n        if (typeof resObj.setHeader === 'function') {\n          resObj.setHeader('X-Trace-Id', traceId);\n        } else if (typeof resObj.header === 'function') {\n          resObj.header('X-Trace-Id', traceId);\n        }\n      } catch {\n        /* response not in a header-settable state — context propagation still works */\n      }\n    }\n\n    runWithTraceId(traceId, () => next());\n  };\n}\n","/**\n * Per-request trace ID resolution shared by the HTTP logger middleware and the\n * context helpers. Internal: not re-exported from the package entry points.\n */\n\nimport {\n  DEFAULT_TRACE_HEADERS,\n  extractTraceId,\n  generateTraceId,\n  sanitizeIncomingId,\n} from './trace.utils';\n\nexport type TraceHeaderOption = string | readonly string[];\n\n/** Minimal structural request shape; Express and Fastify requests satisfy it. */\nexport interface ContextRequestLike {\n  headers?: Record<string, string | string[] | undefined>;\n  id?: unknown;\n}\n\n/** Fastify's default `genReqId` output (`req-` + base36 counter), unique only per process. */\nconst FASTIFY_COUNTER_ID = /^req-[\\da-z]+$/;\n\nconst FALLBACK_KEY = '_logixiaFallbackId';\n\n/** Header names to read a trace ID from, defaulting to the library-wide list. */\nexport function resolveTraceHeaders(option: TraceHeaderOption | undefined): readonly string[] {\n  if (option === undefined) return DEFAULT_TRACE_HEADERS;\n  return typeof option === 'string' ? [option] : option;\n}\n\n/**\n * Resolve the trace ID for a request: a sanitised incoming header (honouring\n * `traceparent`), then a non-counter `request.id`, then a generated ID. Header\n * and `request.id` are recomputed per call so each caller's own header list is\n * honoured; only the generated fallback is stored on the request so every helper\n * agrees when no ID was sent.\n */\nexport function resolveRequestTraceId(req: ContextRequestLike, headers: readonly string[]): string {\n  const fromHeader = extractTraceId(req, { header: [...headers] });\n  if (fromHeader !== undefined) return fromHeader;\n\n  const fromId = sanitizeIncomingId(req.id);\n  if (fromId !== undefined && !FASTIFY_COUNTER_ID.test(fromId)) return fromId;\n\n  const holder = req as Record<string, unknown>;\n  const cached = holder[FALLBACK_KEY];\n  if (typeof cached === 'string') return cached;\n  const generated = generateTraceId();\n  try {\n    holder[FALLBACK_KEY] = generated;\n  } catch {\n    // frozen request object: each caller generates its own\n  }\n  return generated;\n}\n"],"mappings":"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"}
+{"version":3,"file":"request-trace-ByujsUZk.js","names":["AsyncLocalStorage","randomUUID"],"sources":["../src/utils/trace.utils.ts","../src/utils/request-trace.ts"],"sourcesContent":["/**\n * Trace ID utilities for Logitron\n */\n\nimport { AsyncLocalStorage } from 'node:async_hooks';\nimport { randomUUID } from 'node:crypto';\n\nimport type { TraceIdConfig, TraceIdExtractorConfig } from '../types';\n\n/** Default key used to store the trace ID in AsyncLocalStorage. */\nexport const TRACE_CONTEXT_KEY = 'traceId' as const;\n\n// ── TraceContext class ────────────────────────────────────────────────────────\n\n/**\n * Singleton that owns the AsyncLocalStorage and the active contextKey.\n *\n * Why a class instead of bare module-level variables?\n *  - The contextKey is user-configurable; encapsulating it here means there is\n *    exactly one place that reads and writes it.\n *  - All helpers (getCurrentTraceId, runWithTraceId, etc.) delegate to this\n *    instance, so the key is always in sync without hidden global state.\n *  - Easier to test: you can reset the singleton between test cases.\n *\n * Usage (advanced):\n *   import { TraceContext } from 'logixia';\n *   TraceContext.instance.contextKey          // → 'traceId' (or custom)\n *   TraceContext.instance.getCurrentTraceId() // same as standalone fn\n */\nexport class TraceContext {\n  private static _instance: TraceContext | null = null;\n\n  readonly storage = new AsyncLocalStorage<Record<string, unknown>>();\n  private _contextKey: string = TRACE_CONTEXT_KEY;\n\n  private constructor() {}\n\n  /** The process-wide singleton. */\n  static get instance(): TraceContext {\n    if (!TraceContext._instance) {\n      TraceContext._instance = new TraceContext();\n    }\n    return TraceContext._instance;\n  }\n\n  /** @internal Reset the singleton (useful in tests). */\n  static _reset(): void {\n    TraceContext._instance = null;\n  }\n\n  // ── Key management ──────────────────────────────────────────────────────────\n\n  /** The AsyncLocalStorage key that holds the trace ID value. */\n  get contextKey(): string {\n    return this._contextKey;\n  }\n\n  /** @internal Called by TraceMiddleware when it boots to register the user's key. */\n  setContextKey(key: string): void {\n    this._contextKey = key;\n  }\n\n  // ── Core operations ─────────────────────────────────────────────────────────\n\n  /** UUID v4 generator (default). */\n  generate(): string {\n    return randomUUID();\n  }\n\n  /** Read the trace ID from the current async context. */\n  getCurrentTraceId(): string | undefined {\n    return this.storage.getStore()?.[this._contextKey] as string | undefined;\n  }\n\n  /**\n   * Mutate the CURRENT async context in-place.\n   *\n   * ⚠️  DEPRECATED — unsafe for concurrent requests.\n   *\n   * Uses `AsyncLocalStorage.enterWith()`, which mutates the current async\n   * execution context and every Promise chain spawned from it. In a server\n   * processing overlapping requests this can cause a trace ID set for one\n   * request to bleed into *other* in-flight requests that share the same\n   * async parent (e.g. a module-level setup function or a cached handler).\n   *\n   * Use {@link run} instead — it scopes the context to a callback so there\n   * is no risk of cross-request leakage.\n   *\n   * @deprecated Use `TraceContext.instance.run(traceId, fn)` — do not call\n   *             `setTraceId` from request-handling code.\n   */\n  setTraceId(traceId: string, data?: Record<string, unknown>): void {\n    const current = this.storage.getStore() ?? {};\n    this.storage.enterWith({ ...current, [this._contextKey]: traceId, ...data });\n  }\n\n  /** Run `fn` inside a new async context that carries `traceId`. */\n  run<T>(traceId: string, fn: () => T, data?: Record<string, unknown>): T {\n    return this.storage.run({ [this._contextKey]: traceId, ...data }, fn);\n  }\n}\n\n// ── Module-level aliases (backwards-compatible public API) ────────────────────\n\n/**\n * The shared AsyncLocalStorage instance.\n * @deprecated Prefer `TraceContext.instance.storage` for new code.\n */\nexport const traceStorage = TraceContext.instance.storage;\n\n/** Returns the key currently used to store the trace ID in AsyncLocalStorage. */\nexport function getTraceContextKey(): string {\n  return TraceContext.instance.contextKey;\n}\n\n/** @internal Called by TraceMiddleware / traceMiddleware() when they boot. */\nexport function _setActiveContextKey(key: string): void {\n  TraceContext.instance.setContextKey(key);\n}\n\n/** Generate a UUID v4 trace ID. */\nexport function generateTraceId(): string {\n  return TraceContext.instance.generate();\n}\n\n/**\n * Get the current trace ID from async context.\n * Returns `undefined` when called outside a traced request.\n */\nexport function getCurrentTraceId(): string | undefined {\n  return TraceContext.instance.getCurrentTraceId();\n}\n\n/**\n * Set trace ID in the CURRENT async context without starting a new one.\n *\n * ⚠️  DEPRECATED — unsafe for concurrent requests.\n *\n * Uses `AsyncLocalStorage.enterWith()`, which mutates the current async\n * execution context and every Promise chain spawned from it. Under load this\n * can cause a trace ID from one request to bleed into others sharing the same\n * async parent.\n *\n * Use {@link runWithTraceId} instead. Migration patterns:\n *\n * **Express / Fastify middleware — before:**\n * ```ts\n * app.use((req, _res, next) => {\n *   setTraceId(req.headers['x-trace-id'] ?? generateTraceId());\n *   next();\n * });\n * ```\n * **after:**\n * ```ts\n * app.use((req, _res, next) => {\n *   runWithTraceId(req.headers['x-trace-id'] ?? generateTraceId(), () => next());\n * });\n * ```\n *\n * **Kafka / queue consumer — before:**\n * ```ts\n * async function handle(msg) {\n *   setTraceId(msg.headers['x-trace-id']);\n *   await processMessage(msg);\n * }\n * ```\n * **after:**\n * ```ts\n * async function handle(msg) {\n *   await runWithTraceId(msg.headers['x-trace-id'], () => processMessage(msg));\n * }\n * ```\n *\n * **Background job — before:**\n * ```ts\n * setTraceId(generateTraceId(), { jobId: job.id });\n * await job.run();\n * ```\n * **after:**\n * ```ts\n * await runWithTraceId(generateTraceId(), () => job.run(), { jobId: job.id });\n * ```\n *\n * @deprecated Use `runWithTraceId(traceId, fn)` — do not call `setTraceId`\n *             from request-handling code.\n */\nexport function setTraceId(traceId: string, data?: Record<string, unknown>): void {\n  TraceContext.instance.setTraceId(traceId, data);\n}\n\n/** Run `fn` inside a new async context carrying `traceId`. */\nexport function runWithTraceId<T>(traceId: string, fn: () => T, data?: Record<string, unknown>): T {\n  return TraceContext.instance.run(traceId, fn, data);\n}\n\n// ── Request extraction ────────────────────────────────────────────────────────\n\ntype HeaderValue = string | string[] | undefined;\n\n/** Shape that extractTraceId accepts (Express-compatible) */\ninterface RequestLike {\n  headers?: Record<string, HeaderValue>;\n  query?: Record<string, HeaderValue>;\n  body?: Record<string, string | undefined>;\n  params?: Record<string, string | undefined>;\n}\n\n/** Maximum accepted length for an incoming trace / correlation / request ID. */\nexport const MAX_INCOMING_ID_LENGTH = 128;\n\nconst SAFE_INCOMING_ID = /^[A-Za-z0-9._:-]{1,128}$/;\n\n/**\n * Validate an externally supplied identifier (trace ID, correlation ID, origin\n * service name, message-queue ID). Accepts only 1-128 characters from\n * `[A-Za-z0-9._:-]`; surrounding whitespace is trimmed first. Arrays use their\n * first element. Returns the cleaned value, or `undefined` when it is unusable\n * so callers can generate a fresh ID instead of passing client text through.\n */\nexport function sanitizeIncomingId(value: unknown): string | undefined {\n  const first = Array.isArray(value) ? value[0] : value;\n  if (typeof first !== 'string' || first.length > MAX_INCOMING_ID_LENGTH * 2) return undefined;\n  const trimmed = first.trim();\n  return SAFE_INCOMING_ID.test(trimmed) ? trimmed : undefined;\n}\n\n/** W3C trace-context: `version-traceId(32hex)-spanId(16hex)-flags(2hex)`. */\nconst W3C_TRACEPARENT_RE = /^[\\da-f]{2}-([\\da-f]{32})-[\\da-f]{16}-[\\da-f]{2}$/i;\n\n/**\n * Extract the 32-hex trace-id segment from a W3C `traceparent` header value.\n * Returns the parsed trace ID, or the original value unchanged when it is not a\n * well-formed traceparent (so non-W3C propagation still works).\n */\nfunction parseTraceparent(value: string): string {\n  const m = W3C_TRACEPARENT_RE.exec(value);\n  return m ? m[1]! : value;\n}\n\n/** Extract trace ID from request using configuration (header → query → body → params). */\nexport function extractTraceId(\n  request: unknown,\n  config: TraceIdExtractorConfig\n): string | undefined {\n  const req = request as RequestLike;\n\n  if (config.header) {\n    const headers = Array.isArray(config.header) ? config.header : [config.header];\n    for (const header of headers) {\n      const lower = header.toLowerCase();\n      const value = sanitizeIncomingId(req.headers?.[lower]);\n      if (value) return lower === 'traceparent' ? parseTraceparent(value) : value;\n    }\n  }\n\n  if (config.query) {\n    const queries = Array.isArray(config.query) ? config.query : [config.query];\n    for (const query of queries) {\n      const value = sanitizeIncomingId(req.query?.[query]);\n      if (value) return value;\n    }\n  }\n\n  if (config.body) {\n    const bodyFields = Array.isArray(config.body) ? config.body : [config.body];\n    for (const field of bodyFields) {\n      const value = sanitizeIncomingId(req.body?.[field]);\n      if (value) return value;\n    }\n  }\n\n  if (config.params) {\n    const paramFields = Array.isArray(config.params) ? config.params : [config.params];\n    for (const param of paramFields) {\n      const value = sanitizeIncomingId(req.params?.[param]);\n      if (value) return value;\n    }\n  }\n\n  return undefined;\n}\n\n/**\n * Default headers checked for incoming trace ID propagation, in priority order:\n *   traceparent (W3C/OTel) → x-trace-id → x-request-id → x-correlation-id → trace-id\n */\nexport const DEFAULT_TRACE_HEADERS = [\n  'traceparent',\n  'x-trace-id',\n  'x-request-id',\n  'x-correlation-id',\n  'trace-id',\n];\n\n/**\n * Create trace ID middleware for Express/NestJS\n */\nexport function createTraceMiddleware(config: TraceIdConfig) {\n  const defaultExtractor = {\n    header: DEFAULT_TRACE_HEADERS,\n    query: ['traceId', 'trace_id'],\n  };\n  const resolvedConfig: TraceIdConfig = {\n    ...config,\n    extractor: config?.extractor ? { ...defaultExtractor, ...config.extractor } : defaultExtractor,\n  };\n\n  _setActiveContextKey(resolvedConfig.contextKey ?? TRACE_CONTEXT_KEY);\n\n  return (req: unknown, res: unknown, next: () => void) => {\n    let traceId: string | undefined;\n\n    if (resolvedConfig.extractor) {\n      traceId = extractTraceId(req, resolvedConfig.extractor);\n    }\n\n    if (!traceId) {\n      traceId = resolvedConfig.generator ? resolvedConfig.generator() : generateTraceId();\n    }\n\n    (req as Record<string, unknown>).traceId = traceId;\n    // Echo the trace ID back on the response, tolerating different response APIs:\n    // Express/Node use res.setHeader(), Fastify replies use reply.header(). Guard\n    // both and never let a missing/!function method (or already-sent headers)\n    // crash the request — the trace ID is still propagated via async context.\n    const resObj = res as {\n      setHeader?: (k: string, v: string) => void;\n      header?: (k: string, v: string) => void;\n      headersSent?: boolean;\n    };\n    if (!resObj.headersSent) {\n      try {\n        if (typeof resObj.setHeader === 'function') {\n          resObj.setHeader('X-Trace-Id', traceId);\n        } else if (typeof resObj.header === 'function') {\n          resObj.header('X-Trace-Id', traceId);\n        }\n      } catch {\n        /* response not in a header-settable state — context propagation still works */\n      }\n    }\n\n    runWithTraceId(traceId, () => next());\n  };\n}\n","/**\n * Per-request trace ID resolution shared by the HTTP logger middleware and the\n * context helpers. Internal: not re-exported from the package entry points.\n */\n\nimport type { HttpRequestShape } from '../types/http-shapes';\nimport {\n  DEFAULT_TRACE_HEADERS,\n  extractTraceId,\n  generateTraceId,\n  sanitizeIncomingId,\n} from './trace.utils';\n\nexport type TraceHeaderOption = string | readonly string[];\n\n/** Minimal structural request shape; Express and Fastify requests satisfy it. */\nexport type ContextRequestLike = HttpRequestShape;\n\n/** Fastify's default `genReqId` output (`req-` + base36 counter), unique only per process. */\nconst FASTIFY_COUNTER_ID = /^req-[\\da-z]+$/;\n\nconst FALLBACK_KEY = '_logixiaFallbackId';\n\n/** Header names to read a trace ID from, defaulting to the library-wide list. */\nexport function resolveTraceHeaders(option: TraceHeaderOption | undefined): readonly string[] {\n  if (option === undefined) return DEFAULT_TRACE_HEADERS;\n  return typeof option === 'string' ? [option] : option;\n}\n\n/**\n * Resolve the trace ID for a request: a sanitised incoming header (honouring\n * `traceparent`), then a non-counter `request.id`, then a generated ID. Header\n * and `request.id` are recomputed per call so each caller's own header list is\n * honoured; only the generated fallback is stored on the request so every helper\n * agrees when no ID was sent.\n */\nexport function resolveRequestTraceId(req: ContextRequestLike, headers: readonly string[]): string {\n  const fromHeader = extractTraceId(req, { header: [...headers] });\n  if (fromHeader !== undefined) return fromHeader;\n\n  const fromId = sanitizeIncomingId(req.id);\n  if (fromId !== undefined && !FASTIFY_COUNTER_ID.test(fromId)) return fromId;\n\n  const holder = req as Record<string, unknown>;\n  const cached = holder[FALLBACK_KEY];\n  if (typeof cached === 'string') return cached;\n  const generated = generateTraceId();\n  try {\n    holder[FALLBACK_KEY] = generated;\n  } catch {\n    // frozen request object: each caller generates its own\n  }\n  return generated;\n}\n"],"mappings":"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"}

package/dist/{safe-stringify-BMRl3EX3.mjs → safe-stringify--7gbe95n.mjs}

@@ -1,4 +1,27 @@
+import { l as assignOwn } from "./sensitive-names-o__1PUUR.mjs";
 // src/utils/safe-stringify.ts
+/**
+* logixia — robust JSON serialization for log payloads.
+*
+* Modern Winston/Pino already neutralize circular refs to `[Circular]` (via
+* safe-stable-stringify / fast-safe-stringify), so merely "surviving cycles" is
+* not a differentiator. This goes one notch further:
+*
+*  - **BigInt** → serialized (as a string by default; JSON.stringify throws on
+*    BigInt, which silently breaks logging of e.g. DB bigint ids).
+*  - **Deterministic key order** (optional) so identical objects hash/diff equal.
+*  - **True decycle** (optional) — replace repeated references with JSONPath
+*    `$ref` pointers that round-trip back to the original object graph, instead
+*    of the lossy `[Circular]` tag. Useful when you need to reconstruct shared
+*    structure downstream.
+*
+* @example
+* ```ts
+* safeStringify({ id: 10n, self: obj });          // → BigInt + cycle safe
+* safeStringify(graph, { decycle: true });         // → round-trippable $ref pointers
+* const back = retrocycle(JSON.parse(json));       // → reconstruct shared refs
+* ```
+*/
 /** Build a JSONPath like `$["a"][0]["b"]` for a decycle pointer. */
 function jsonPath(parts) {
 	let path = "$";
@@ -28,10 +51,7 @@ function safeStringify(value, options = {}) {
 			const rec = val;
 			const keys = deterministic ? Object.keys(rec).sort() : Object.keys(rec);
 			const obj = {};
-			for (const k of keys) {
-				if (k === "__proto__" || k === "constructor" || k === "prototype") continue;
-				obj[k] = transform(rec[k]);
-			}
+			for (const k of keys) assignOwn(obj, k, transform(rec[k]));
 			out = obj;
 		}
 		seen.delete(val);
@@ -56,10 +76,7 @@ function decycleValue(value, bigint = "string") {
 		if (Array.isArray(val)) return val.map((item, i) => walk(item, [...path, i]));
 		const rec = val;
 		const obj = {};
-		for (const k of Object.keys(rec)) {
-			if (k === "__proto__" || k === "constructor" || k === "prototype") continue;
-			obj[k] = walk(rec[k], [...path, k]);
-		}
+		for (const k of Object.keys(rec)) assignOwn(obj, k, walk(rec[k], [...path, k]));
 		return obj;
 	};
 	return walk(value, []);
@@ -70,6 +87,7 @@ function decycleValue(value, bigint = "string") {
 */
 function retrocycle(root) {
 	const refRe = /^\$(?:\[(?:\d+|"(?:[^"\\]|\\.)*")\])*$/;
+	const UNRESOLVED = Symbol("unresolved");
 	const resolve = (path) => {
 		const segs = [];
 		const partRe = /\[(\d+|"(?:[^"\\]|\\.)*")\]/g;
@@ -79,7 +97,11 @@ function retrocycle(root) {
 			segs.push(raw.startsWith("\"") ? JSON.parse(raw) : Number(raw));
 		}
 		let node = root;
-		for (const s of segs) node = node[s];
+		for (const s of segs) {
+			if (node === null || typeof node !== "object") return UNRESOLVED;
+			if (!Object.prototype.hasOwnProperty.call(node, s)) return UNRESOLVED;
+			node = node[s];
+		}
 		return node;
 	};
 	const walk = (val) => {
@@ -87,8 +109,11 @@ function retrocycle(root) {
 		const rec = val;
 		for (const k of Object.keys(rec)) {
 			const child = rec[k];
-			if (child !== null && typeof child === "object" && typeof child.$ref === "string" && refRe.test(child.$ref)) rec[k] = resolve(child.$ref);
-			else walk(child);
+			if (child !== null && typeof child === "object" && typeof child.$ref === "string" && refRe.test(child.$ref)) {
+				const target = resolve(child.$ref);
+				if (target === UNRESOLVED) walk(child);
+				else assignOwn(rec, k, target);
+			} else walk(child);
 		}
 	};
 	walk(root);
@@ -114,4 +139,4 @@ function stringifyForLog(value) {
 }
 export { stringifyForLog as i, retrocycle as n, safeStringify as r, decycleValue as t };
 
-//# sourceMappingURL=safe-stringify-BMRl3EX3.mjs.map
+//# sourceMappingURL=safe-stringify--7gbe95n.mjs.map

package/dist/safe-stringify--7gbe95n.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"safe-stringify--7gbe95n.mjs","names":[],"sources":["../src/utils/safe-stringify.ts"],"sourcesContent":["/**\n * logixia — robust JSON serialization for log payloads.\n *\n * Modern Winston/Pino already neutralize circular refs to `[Circular]` (via\n * safe-stable-stringify / fast-safe-stringify), so merely \"surviving cycles\" is\n * not a differentiator. This goes one notch further:\n *\n *  - **BigInt** → serialized (as a string by default; JSON.stringify throws on\n *    BigInt, which silently breaks logging of e.g. DB bigint ids).\n *  - **Deterministic key order** (optional) so identical objects hash/diff equal.\n *  - **True decycle** (optional) — replace repeated references with JSONPath\n *    `$ref` pointers that round-trip back to the original object graph, instead\n *    of the lossy `[Circular]` tag. Useful when you need to reconstruct shared\n *    structure downstream.\n *\n * @example\n * ```ts\n * safeStringify({ id: 10n, self: obj });          // → BigInt + cycle safe\n * safeStringify(graph, { decycle: true });         // → round-trippable $ref pointers\n * const back = retrocycle(JSON.parse(json));       // → reconstruct shared refs\n * ```\n */\n\nimport { assignOwn } from './own-property';\n\nexport interface SafeStringifyOptions {\n  /** Indentation passed to JSON.stringify (number of spaces or a string). */\n  indent?: number | string;\n  /** Sort object keys for deterministic output. Default: false. */\n  deterministic?: boolean;\n  /**\n   * Use round-trippable `$ref` JSONPath pointers for repeated references instead\n   * of the lossy \"[Circular]\" tag. Default: false.\n   */\n  decycle?: boolean;\n  /** How to render BigInt: 'string' (default) or 'number' (may lose precision). */\n  bigint?: 'string' | 'number';\n}\n\n/** Build a JSONPath like `$[\"a\"][0][\"b\"]` for a decycle pointer. */\nfunction jsonPath(parts: Array<string | number>): string {\n  let path = '$';\n  for (const p of parts) {\n    path += typeof p === 'number' ? `[${p}]` : `[${JSON.stringify(p)}]`;\n  }\n  return path;\n}\n\n/**\n * Serialize any value to JSON without throwing on circular references or BigInt.\n * Circular refs become `\"[Circular]\"` (or `{ $ref }` pointers when `decycle`).\n */\nexport function safeStringify(value: unknown, options: SafeStringifyOptions = {}): string {\n  const { indent, deterministic = false, decycle = false, bigint = 'string' } = options;\n\n  if (decycle) {\n    return JSON.stringify(decycleValue(value, bigint), undefined, indent);\n  }\n\n  const seen = new WeakSet<object>();\n\n  const transform = (val: unknown): unknown => {\n    if (typeof val === 'bigint') return bigint === 'number' ? Number(val) : val.toString();\n    if (typeof val === 'function') return `[Function: ${val.name || 'anonymous'}]`;\n    if (typeof val === 'symbol') return val.toString();\n    if (val === null || typeof val !== 'object') return val;\n\n    if (seen.has(val)) return '[Circular]';\n    seen.add(val);\n\n    let out: unknown;\n    const toJSON = (val as { toJSON?: unknown }).toJSON;\n    if (Array.isArray(val)) {\n      out = val.map((item) => transform(item));\n    } else if (typeof toJSON === 'function') {\n      // Dates, URLs, Buffers and classes with their own toJSON print the way\n      // JSON.stringify would; a toJSON that returns `this` hits the cycle check.\n      out = transform(toJSON.call(val));\n    } else {\n      const rec = val as Record<string, unknown>;\n      const keys = deterministic ? Object.keys(rec).sort() : Object.keys(rec);\n      const obj: Record<string, unknown> = {};\n      for (const k of keys) {\n        assignOwn(obj, k, transform(rec[k]));\n      }\n      out = obj;\n    }\n    // Allow the same object to appear in sibling branches (not a true cycle):\n    // remove from `seen` after we finish its subtree.\n    seen.delete(val);\n    return out;\n  };\n\n  return JSON.stringify(transform(value), undefined, indent);\n}\n\n/**\n * Replace repeated object references with round-trippable `{ \"$ref\": \"$...\" }`\n * JSONPath pointers (the classic Crockford decycle). Pair with {@link retrocycle}\n * to reconstruct the original shared/circular graph.\n */\nexport function decycleValue(value: unknown, bigint: 'string' | 'number' = 'string'): unknown {\n  const paths = new WeakMap<object, string>();\n\n  const walk = (val: unknown, path: Array<string | number>): unknown => {\n    if (typeof val === 'bigint') return bigint === 'number' ? Number(val) : val.toString();\n    if (val === null || typeof val !== 'object') return val;\n    if (val instanceof Date) return val.toISOString();\n\n    const existing = paths.get(val);\n    if (existing !== undefined) return { $ref: existing };\n    paths.set(val, jsonPath(path));\n\n    if (Array.isArray(val)) {\n      return val.map((item, i) => walk(item, [...path, i]));\n    }\n    const rec = val as Record<string, unknown>;\n    const obj: Record<string, unknown> = {};\n    for (const k of Object.keys(rec)) {\n      assignOwn(obj, k, walk(rec[k], [...path, k]));\n    }\n    return obj;\n  };\n\n  return walk(value, []);\n}\n\n/**\n * Inverse of {@link decycleValue}: resolve `{ \"$ref\": \"$...\" }` pointers back\n * into the live object graph (mutates and returns the parsed input).\n */\nexport function retrocycle<T>(root: T): T {\n  const refRe = /^\\$(?:\\[(?:\\d+|\"(?:[^\"\\\\]|\\\\.)*\")\\])*$/;\n\n  const UNRESOLVED = Symbol('unresolved');\n  const resolve = (path: string): unknown => {\n    // Parse the JSONPath segments back out.\n    const segs: Array<string | number> = [];\n    const partRe = /\\[(\\d+|\"(?:[^\"\\\\]|\\\\.)*\")\\]/g;\n    let m: RegExpExecArray | null;\n    while ((m = partRe.exec(path)) !== null) {\n      const raw = m[1]!;\n      segs.push(raw.startsWith('\"') ? (JSON.parse(raw) as string) : Number(raw));\n    }\n    let node: unknown = root;\n    for (const s of segs) {\n      if (node === null || typeof node !== 'object') return UNRESOLVED;\n      if (!Object.prototype.hasOwnProperty.call(node, s)) return UNRESOLVED;\n      node = (node as Record<string | number, unknown>)[s];\n    }\n    return node;\n  };\n\n  const walk = (val: unknown): void => {\n    if (val === null || typeof val !== 'object') return;\n    const rec = val as Record<string, unknown>;\n    for (const k of Object.keys(rec)) {\n      const child = rec[k];\n      if (\n        child !== null &&\n        typeof child === 'object' &&\n        typeof (child as { $ref?: unknown }).$ref === 'string' &&\n        refRe.test((child as { $ref: string }).$ref)\n      ) {\n        const target = resolve((child as { $ref: string }).$ref);\n        if (target === UNRESOLVED) walk(child);\n        else assignOwn(rec, k, target);\n      } else {\n        walk(child);\n      }\n    }\n  };\n\n  walk(root);\n  return root;\n}\n\n/**\n * `JSON.stringify` for log output. Takes the plain fast path first and only\n * falls back to {@link safeStringify} when that throws (a cycle, a BigInt, a\n * throwing `toJSON`), so a bad payload costs nothing until it shows up.\n * Never throws: if even the safe walk fails, the value is replaced by a marker.\n */\nexport function stringifyForLog(value: unknown): string {\n  try {\n    return JSON.stringify(value);\n  } catch {\n    try {\n      return safeStringify(value);\n    } catch (error) {\n      const reason = error instanceof Error ? error.message : String(error);\n      return JSON.stringify(`[Unserializable: ${reason}]`);\n    }\n  }\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;AAwCA,SAAS,SAAS,OAAuC;CACvD,IAAI,OAAO;CACX,KAAK,MAAM,KAAK,OACd,QAAQ,OAAO,MAAM,WAAW,IAAI,EAAE,KAAK,IAAI,KAAK,UAAU,CAAC,EAAE;CAEnE,OAAO;AACT;;;;;AAMA,SAAgB,cAAc,OAAgB,UAAgC,CAAC,GAAW;CACxF,MAAM,EAAE,QAAQ,gBAAgB,OAAO,UAAU,OAAO,SAAS,aAAa;CAE9E,IAAI,SACF,OAAO,KAAK,UAAU,aAAa,OAAO,MAAM,GAAG,KAAA,GAAW,MAAM;CAGtE,MAAM,uBAAO,IAAI,QAAgB;CAEjC,MAAM,aAAa,QAA0B;EAC3C,IAAI,OAAO,QAAQ,UAAU,OAAO,WAAW,WAAW,OAAO,GAAG,IAAI,IAAI,SAAS;EACrF,IAAI,OAAO,QAAQ,YAAY,OAAO,cAAc,IAAI,QAAQ,YAAY;EAC5E,IAAI,OAAO,QAAQ,UAAU,OAAO,IAAI,SAAS;EACjD,IAAI,QAAQ,QAAQ,OAAO,QAAQ,UAAU,OAAO;EAEpD,IAAI,KAAK,IAAI,GAAG,GAAG,OAAO;EAC1B,KAAK,IAAI,GAAG;EAEZ,IAAI;EACJ,MAAM,SAAU,IAA6B;EAC7C,IAAI,MAAM,QAAQ,GAAG,GACnB,MAAM,IAAI,KAAK,SAAS,UAAU,IAAI,CAAC;OAClC,IAAI,OAAO,WAAW,YAG3B,MAAM,UAAU,OAAO,KAAK,GAAG,CAAC;OAC3B;GACL,MAAM,MAAM;GACZ,MAAM,OAAO,gBAAgB,OAAO,KAAK,GAAG,CAAC,CAAC,KAAK,IAAI,OAAO,KAAK,GAAG;GACtE,MAAM,MAA+B,CAAC;GACtC,KAAK,MAAM,KAAK,MACd,UAAU,KAAK,GAAG,UAAU,IAAI,EAAE,CAAC;GAErC,MAAM;EACR;EAGA,KAAK,OAAO,GAAG;EACf,OAAO;CACT;CAEA,OAAO,KAAK,UAAU,UAAU,KAAK,GAAG,KAAA,GAAW,MAAM;AAC3D;;;;;;AAOA,SAAgB,aAAa,OAAgB,SAA8B,UAAmB;CAC5F,MAAM,wBAAQ,IAAI,QAAwB;CAE1C,MAAM,QAAQ,KAAc,SAA0C;EACpE,IAAI,OAAO,QAAQ,UAAU,OAAO,WAAW,WAAW,OAAO,GAAG,IAAI,IAAI,SAAS;EACrF,IAAI,QAAQ,QAAQ,OAAO,QAAQ,UAAU,OAAO;EACpD,IAAI,eAAe,MAAM,OAAO,IAAI,YAAY;EAEhD,MAAM,WAAW,MAAM,IAAI,GAAG;EAC9B,IAAI,aAAa,KAAA,GAAW,OAAO,EAAE,MAAM,SAAS;EACpD,MAAM,IAAI,KAAK,SAAS,IAAI,CAAC;EAE7B,IAAI,MAAM,QAAQ,GAAG,GACnB,OAAO,IAAI,KAAK,MAAM,MAAM,KAAK,MAAM,CAAC,GAAG,MAAM,CAAC,CAAC,CAAC;EAEtD,MAAM,MAAM;EACZ,MAAM,MAA+B,CAAC;EACtC,KAAK,MAAM,KAAK,OAAO,KAAK,GAAG,GAC7B,UAAU,KAAK,GAAG,KAAK,IAAI,IAAI,CAAC,GAAG,MAAM,CAAC,CAAC,CAAC;EAE9C,OAAO;CACT;CAEA,OAAO,KAAK,OAAO,CAAC,CAAC;AACvB;;;;;AAMA,SAAgB,WAAc,MAAY;CACxC,MAAM,QAAQ;CAEd,MAAM,aAAa,OAAO,YAAY;CACtC,MAAM,WAAW,SAA0B;EAEzC,MAAM,OAA+B,CAAC;EACtC,MAAM,SAAS;EACf,IAAI;EACJ,QAAQ,IAAI,OAAO,KAAK,IAAI,OAAO,MAAM;GACvC,MAAM,MAAM,EAAE;GACd,KAAK,KAAK,IAAI,WAAW,IAAG,IAAK,KAAK,MAAM,GAAG,IAAe,OAAO,GAAG,CAAC;EAC3E;EACA,IAAI,OAAgB;EACpB,KAAK,MAAM,KAAK,MAAM;GACpB,IAAI,SAAS,QAAQ,OAAO,SAAS,UAAU,OAAO;GACtD,IAAI,CAAC,OAAO,UAAU,eAAe,KAAK,MAAM,CAAC,GAAG,OAAO;GAC3D,OAAQ,KAA0C;EACpD;EACA,OAAO;CACT;CAEA,MAAM,QAAQ,QAAuB;EACnC,IAAI,QAAQ,QAAQ,OAAO,QAAQ,UAAU;EAC7C,MAAM,MAAM;EACZ,KAAK,MAAM,KAAK,OAAO,KAAK,GAAG,GAAG;GAChC,MAAM,QAAQ,IAAI;GAClB,IACE,UAAU,QACV,OAAO,UAAU,YACjB,OAAQ,MAA6B,SAAS,YAC9C,MAAM,KAAM,MAA2B,IAAI,GAC3C;IACA,MAAM,SAAS,QAAS,MAA2B,IAAI;IACvD,IAAI,WAAW,YAAY,KAAK,KAAK;SAChC,UAAU,KAAK,GAAG,MAAM;GAC/B,OACE,KAAK,KAAK;EAEd;CACF;CAEA,KAAK,IAAI;CACT,OAAO;AACT;;;;;;;AAQA,SAAgB,gBAAgB,OAAwB;CACtD,IAAI;EACF,OAAO,KAAK,UAAU,KAAK;CAC7B,QAAQ;EACN,IAAI;GACF,OAAO,cAAc,KAAK;EAC5B,SAAS,OAAO;GACd,MAAM,SAAS,iBAAiB,QAAQ,MAAM,UAAU,OAAO,KAAK;GACpE,OAAO,KAAK,UAAU,oBAAoB,OAAO,EAAE;EACrD;CACF;AACF"}

package/dist/{safe-stringify-DLz1Kz3o.js → safe-stringify-CN7icp8S.js}

@@ -1,4 +1,27 @@
+const require_sensitive_names = require("./sensitive-names-CHMowujD.js");
 // src/utils/safe-stringify.ts
+/**
+* logixia — robust JSON serialization for log payloads.
+*
+* Modern Winston/Pino already neutralize circular refs to `[Circular]` (via
+* safe-stable-stringify / fast-safe-stringify), so merely "surviving cycles" is
+* not a differentiator. This goes one notch further:
+*
+*  - **BigInt** → serialized (as a string by default; JSON.stringify throws on
+*    BigInt, which silently breaks logging of e.g. DB bigint ids).
+*  - **Deterministic key order** (optional) so identical objects hash/diff equal.
+*  - **True decycle** (optional) — replace repeated references with JSONPath
+*    `$ref` pointers that round-trip back to the original object graph, instead
+*    of the lossy `[Circular]` tag. Useful when you need to reconstruct shared
+*    structure downstream.
+*
+* @example
+* ```ts
+* safeStringify({ id: 10n, self: obj });          // → BigInt + cycle safe
+* safeStringify(graph, { decycle: true });         // → round-trippable $ref pointers
+* const back = retrocycle(JSON.parse(json));       // → reconstruct shared refs
+* ```
+*/
 /** Build a JSONPath like `$["a"][0]["b"]` for a decycle pointer. */
 function jsonPath(parts) {
 	let path = "$";
@@ -28,10 +51,7 @@ function safeStringify(value, options = {}) {
 			const rec = val;
 			const keys = deterministic ? Object.keys(rec).sort() : Object.keys(rec);
 			const obj = {};
-			for (const k of keys) {
-				if (k === "__proto__" || k === "constructor" || k === "prototype") continue;
-				obj[k] = transform(rec[k]);
-			}
+			for (const k of keys) require_sensitive_names.assignOwn(obj, k, transform(rec[k]));
 			out = obj;
 		}
 		seen.delete(val);
@@ -56,10 +76,7 @@ function decycleValue(value, bigint = "string") {
 		if (Array.isArray(val)) return val.map((item, i) => walk(item, [...path, i]));
 		const rec = val;
 		const obj = {};
-		for (const k of Object.keys(rec)) {
-			if (k === "__proto__" || k === "constructor" || k === "prototype") continue;
-			obj[k] = walk(rec[k], [...path, k]);
-		}
+		for (const k of Object.keys(rec)) require_sensitive_names.assignOwn(obj, k, walk(rec[k], [...path, k]));
 		return obj;
 	};
 	return walk(value, []);
@@ -70,6 +87,7 @@ function decycleValue(value, bigint = "string") {
 */
 function retrocycle(root) {
 	const refRe = /^\$(?:\[(?:\d+|"(?:[^"\\]|\\.)*")\])*$/;
+	const UNRESOLVED = Symbol("unresolved");
 	const resolve = (path) => {
 		const segs = [];
 		const partRe = /\[(\d+|"(?:[^"\\]|\\.)*")\]/g;
@@ -79,7 +97,11 @@ function retrocycle(root) {
 			segs.push(raw.startsWith("\"") ? JSON.parse(raw) : Number(raw));
 		}
 		let node = root;
-		for (const s of segs) node = node[s];
+		for (const s of segs) {
+			if (node === null || typeof node !== "object") return UNRESOLVED;
+			if (!Object.prototype.hasOwnProperty.call(node, s)) return UNRESOLVED;
+			node = node[s];
+		}
 		return node;
 	};
 	const walk = (val) => {
@@ -87,8 +109,11 @@ function retrocycle(root) {
 		const rec = val;
 		for (const k of Object.keys(rec)) {
 			const child = rec[k];
-			if (child !== null && typeof child === "object" && typeof child.$ref === "string" && refRe.test(child.$ref)) rec[k] = resolve(child.$ref);
-			else walk(child);
+			if (child !== null && typeof child === "object" && typeof child.$ref === "string" && refRe.test(child.$ref)) {
+				const target = resolve(child.$ref);
+				if (target === UNRESOLVED) walk(child);
+				else require_sensitive_names.assignOwn(rec, k, target);
+			} else walk(child);
 		}
 	};
 	walk(root);
@@ -137,4 +162,4 @@ Object.defineProperty(exports, "stringifyForLog", {
 	}
 });
 
-//# sourceMappingURL=safe-stringify-DLz1Kz3o.js.map
+//# sourceMappingURL=safe-stringify-CN7icp8S.js.map

package/dist/safe-stringify-CN7icp8S.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"safe-stringify-CN7icp8S.js","names":[],"sources":["../src/utils/safe-stringify.ts"],"sourcesContent":["/**\n * logixia — robust JSON serialization for log payloads.\n *\n * Modern Winston/Pino already neutralize circular refs to `[Circular]` (via\n * safe-stable-stringify / fast-safe-stringify), so merely \"surviving cycles\" is\n * not a differentiator. This goes one notch further:\n *\n *  - **BigInt** → serialized (as a string by default; JSON.stringify throws on\n *    BigInt, which silently breaks logging of e.g. DB bigint ids).\n *  - **Deterministic key order** (optional) so identical objects hash/diff equal.\n *  - **True decycle** (optional) — replace repeated references with JSONPath\n *    `$ref` pointers that round-trip back to the original object graph, instead\n *    of the lossy `[Circular]` tag. Useful when you need to reconstruct shared\n *    structure downstream.\n *\n * @example\n * ```ts\n * safeStringify({ id: 10n, self: obj });          // → BigInt + cycle safe\n * safeStringify(graph, { decycle: true });         // → round-trippable $ref pointers\n * const back = retrocycle(JSON.parse(json));       // → reconstruct shared refs\n * ```\n */\n\nimport { assignOwn } from './own-property';\n\nexport interface SafeStringifyOptions {\n  /** Indentation passed to JSON.stringify (number of spaces or a string). */\n  indent?: number | string;\n  /** Sort object keys for deterministic output. Default: false. */\n  deterministic?: boolean;\n  /**\n   * Use round-trippable `$ref` JSONPath pointers for repeated references instead\n   * of the lossy \"[Circular]\" tag. Default: false.\n   */\n  decycle?: boolean;\n  /** How to render BigInt: 'string' (default) or 'number' (may lose precision). */\n  bigint?: 'string' | 'number';\n}\n\n/** Build a JSONPath like `$[\"a\"][0][\"b\"]` for a decycle pointer. */\nfunction jsonPath(parts: Array<string | number>): string {\n  let path = '$';\n  for (const p of parts) {\n    path += typeof p === 'number' ? `[${p}]` : `[${JSON.stringify(p)}]`;\n  }\n  return path;\n}\n\n/**\n * Serialize any value to JSON without throwing on circular references or BigInt.\n * Circular refs become `\"[Circular]\"` (or `{ $ref }` pointers when `decycle`).\n */\nexport function safeStringify(value: unknown, options: SafeStringifyOptions = {}): string {\n  const { indent, deterministic = false, decycle = false, bigint = 'string' } = options;\n\n  if (decycle) {\n    return JSON.stringify(decycleValue(value, bigint), undefined, indent);\n  }\n\n  const seen = new WeakSet<object>();\n\n  const transform = (val: unknown): unknown => {\n    if (typeof val === 'bigint') return bigint === 'number' ? Number(val) : val.toString();\n    if (typeof val === 'function') return `[Function: ${val.name || 'anonymous'}]`;\n    if (typeof val === 'symbol') return val.toString();\n    if (val === null || typeof val !== 'object') return val;\n\n    if (seen.has(val)) return '[Circular]';\n    seen.add(val);\n\n    let out: unknown;\n    const toJSON = (val as { toJSON?: unknown }).toJSON;\n    if (Array.isArray(val)) {\n      out = val.map((item) => transform(item));\n    } else if (typeof toJSON === 'function') {\n      // Dates, URLs, Buffers and classes with their own toJSON print the way\n      // JSON.stringify would; a toJSON that returns `this` hits the cycle check.\n      out = transform(toJSON.call(val));\n    } else {\n      const rec = val as Record<string, unknown>;\n      const keys = deterministic ? Object.keys(rec).sort() : Object.keys(rec);\n      const obj: Record<string, unknown> = {};\n      for (const k of keys) {\n        assignOwn(obj, k, transform(rec[k]));\n      }\n      out = obj;\n    }\n    // Allow the same object to appear in sibling branches (not a true cycle):\n    // remove from `seen` after we finish its subtree.\n    seen.delete(val);\n    return out;\n  };\n\n  return JSON.stringify(transform(value), undefined, indent);\n}\n\n/**\n * Replace repeated object references with round-trippable `{ \"$ref\": \"$...\" }`\n * JSONPath pointers (the classic Crockford decycle). Pair with {@link retrocycle}\n * to reconstruct the original shared/circular graph.\n */\nexport function decycleValue(value: unknown, bigint: 'string' | 'number' = 'string'): unknown {\n  const paths = new WeakMap<object, string>();\n\n  const walk = (val: unknown, path: Array<string | number>): unknown => {\n    if (typeof val === 'bigint') return bigint === 'number' ? Number(val) : val.toString();\n    if (val === null || typeof val !== 'object') return val;\n    if (val instanceof Date) return val.toISOString();\n\n    const existing = paths.get(val);\n    if (existing !== undefined) return { $ref: existing };\n    paths.set(val, jsonPath(path));\n\n    if (Array.isArray(val)) {\n      return val.map((item, i) => walk(item, [...path, i]));\n    }\n    const rec = val as Record<string, unknown>;\n    const obj: Record<string, unknown> = {};\n    for (const k of Object.keys(rec)) {\n      assignOwn(obj, k, walk(rec[k], [...path, k]));\n    }\n    return obj;\n  };\n\n  return walk(value, []);\n}\n\n/**\n * Inverse of {@link decycleValue}: resolve `{ \"$ref\": \"$...\" }` pointers back\n * into the live object graph (mutates and returns the parsed input).\n */\nexport function retrocycle<T>(root: T): T {\n  const refRe = /^\\$(?:\\[(?:\\d+|\"(?:[^\"\\\\]|\\\\.)*\")\\])*$/;\n\n  const UNRESOLVED = Symbol('unresolved');\n  const resolve = (path: string): unknown => {\n    // Parse the JSONPath segments back out.\n    const segs: Array<string | number> = [];\n    const partRe = /\\[(\\d+|\"(?:[^\"\\\\]|\\\\.)*\")\\]/g;\n    let m: RegExpExecArray | null;\n    while ((m = partRe.exec(path)) !== null) {\n      const raw = m[1]!;\n      segs.push(raw.startsWith('\"') ? (JSON.parse(raw) as string) : Number(raw));\n    }\n    let node: unknown = root;\n    for (const s of segs) {\n      if (node === null || typeof node !== 'object') return UNRESOLVED;\n      if (!Object.prototype.hasOwnProperty.call(node, s)) return UNRESOLVED;\n      node = (node as Record<string | number, unknown>)[s];\n    }\n    return node;\n  };\n\n  const walk = (val: unknown): void => {\n    if (val === null || typeof val !== 'object') return;\n    const rec = val as Record<string, unknown>;\n    for (const k of Object.keys(rec)) {\n      const child = rec[k];\n      if (\n        child !== null &&\n        typeof child === 'object' &&\n        typeof (child as { $ref?: unknown }).$ref === 'string' &&\n        refRe.test((child as { $ref: string }).$ref)\n      ) {\n        const target = resolve((child as { $ref: string }).$ref);\n        if (target === UNRESOLVED) walk(child);\n        else assignOwn(rec, k, target);\n      } else {\n        walk(child);\n      }\n    }\n  };\n\n  walk(root);\n  return root;\n}\n\n/**\n * `JSON.stringify` for log output. Takes the plain fast path first and only\n * falls back to {@link safeStringify} when that throws (a cycle, a BigInt, a\n * throwing `toJSON`), so a bad payload costs nothing until it shows up.\n * Never throws: if even the safe walk fails, the value is replaced by a marker.\n */\nexport function stringifyForLog(value: unknown): string {\n  try {\n    return JSON.stringify(value);\n  } catch {\n    try {\n      return safeStringify(value);\n    } catch (error) {\n      const reason = error instanceof Error ? error.message : String(error);\n      return JSON.stringify(`[Unserializable: ${reason}]`);\n    }\n  }\n}\n"],"mappings":"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"}