logixia 1.13.3 → 2.0.4

package/README.md

@@ -673,7 +673,7 @@ const logger = createLogger({
     analytics: {
       datadog: {
         apiKey: process.env.DD_API_KEY!,
-        site: 'datadoghq.com', // or 'datadoghq.eu', 'us3.datadoghq.com'
+        site: 'datadoghq.com', // or 'datadoghq.eu', 'us3.datadoghq.com', 'us5.datadoghq.com', 'ap1.datadoghq.com', 'ddog-gov.com'
         service: 'api',
         env: 'production',
         enableLogs: true,
@@ -758,6 +758,31 @@ const logger = createLogger({
 await logger.info('Order placed', { orderId: 'ord_789' });
 ```
 
+### Slack and Discord webhook transports
+
+Send alerts to a chat channel. Both default to `level: 'error'`, batch entries that arrive within `minIntervalMs` (default 1000) into one message, and cap a message at 10 entries (the rest are dropped and counted in the message).
+
+```typescript
+import { createLogger } from 'logixia';
+import { DiscordTransport, SlackTransport } from 'logixia';
+
+const logger = createLogger({
+  appName: 'api',
+  transports: {
+    custom: [
+      new SlackTransport({ webhookUrl: process.env.SLACK_WEBHOOK_URL!, level: 'error' }),
+      new DiscordTransport({ webhookUrl: process.env.DISCORD_WEBHOOK_URL!, level: 'warn' }),
+    ],
+  },
+});
+```
+
+- The webhook URL is a secret. It must be `https:` on `hooks.slack.com` (Slack) or `discord.com` / `discordapp.com` (Discord) unless you pass `allowCustomUrl: true`. It is never logged and never appears in error messages (only the host does).
+- Logged text is escaped: Slack `&`, `<`, `>` (so `<!channel>` and `<@U123>` in log data cannot ping anyone); Discord markdown, plus `allowed_mentions: { parse: [] }` on every request.
+- Platform limits are enforced by truncation (Slack header 150 and data 2,500 chars; Discord title 256, description 4,096, 25 fields, 6,000 per message).
+- HTTP 429 waits for `Retry-After` (Discord: `retry_after`), then retries up to `maxRetries` (default 1). Other failures keep the batch queued with backoff; `flush()` rejects with a host-only error. The queue is bounded by `maxBufferSize` (default 1000, oldest dropped).
+- Also available: `username`, `iconEmoji` (Slack), `avatarUrl` (Discord), `filter`, `formatter`, `flush()` and `close()` (flushes pending entries).
+
 ### Custom transport
 
 Implement `ITransport` to send logs anywhere — Slack, PagerDuty, S3, an internal queue:
@@ -957,23 +982,33 @@ const incomingTraceId = extractTraceId(req, {
 ### Express / Fastify middleware
 
 ```typescript
-import { traceMiddleware } from 'logixia';
+import { createExpressContextMiddleware, createFastifyContextHook } from 'logixia';
 
-// Zero-config — reads from traceparent / x-trace-id / x-request-id / x-correlation-id
-// and generates a UUID v4 if none is present. Sets X-Trace-Id on the response.
-app.use(traceMiddleware());
+// Express: trace ID = first present header of traceIdHeader (default
+// DEFAULT_TRACE_HEADERS: traceparent, x-trace-id, x-request-id, x-correlation-id,
+// trace-id; traceparent is parsed to its 32-hex trace id), else request.id, else a
+// generated UUID. The ID is available via getCurrentTraceId() and is the logger's
+// top-level traceId for everything inside the request. No response header is set
+// unless you ask for one with responseHeader.
+app.use(createExpressContextMiddleware({ responseHeader: 'X-Trace-Id' }));
 
-// With custom config:
-app.use(
-  traceMiddleware({
-    enabled: true,
-    generator: () => `req_${crypto.randomUUID()}`,
-    extractor: {
-      header: ['x-trace-id', 'traceparent'],
-      query: ['traceId'],
-    },
-  })
-);
+// Fastify: same resolution; fastify's default counter ids ('req-1', ...) are never
+// used as trace IDs. Also shared with createFastifyPlugin() from 'logixia/middleware'.
+// traceIdHeader accepts a single name or a list; responseHeader works as above.
+fastify.addHook('onRequest', createFastifyContextHook());
+
+// Prefer full control? Wrap the request yourself:
+app.use((req, res, next) => {
+  const traceId =
+    extractTraceId(req, { header: DEFAULT_TRACE_HEADERS, query: ['traceId'] }) ?? generateTraceId();
+  res.setHeader('X-Trace-Id', traceId);
+  runWithTraceId(traceId, () => next());
+});
+
+// Request/response logging (separate from tracing) lives in 'logixia/middleware':
+//   app.use(createExpressMiddleware(logger));
+//   await fastify.register(createFastifyPlugin(logger));
+// NestJS: import { TraceMiddleware } from 'logixia/nest';
 
 // Service layer — no parameters needed, trace ID propagates automatically
 class OrderService {
@@ -992,6 +1027,25 @@ class OrderService {
 
 The default headers checked for an incoming trace ID (in priority order) are: `traceparent`, `x-trace-id`, `x-request-id`, `x-correlation-id`, `trace-id`.
 
+### Hono
+
+On Node, Hono needs nothing beyond `runWithTraceId()` — wrap `await next()` and every log line in the request carries the trace ID:
+
+```typescript
+app.use(async (c, next) => {
+  const traceId =
+    extractTraceId({ headers: c.req.header() }, { header: DEFAULT_TRACE_HEADERS }) ??
+    generateTraceId();
+  await runWithTraceId(traceId, next);
+});
+```
+
+See [`examples/hono-example.ts`](./examples/hono-example.ts) (`npm run dev:hono`) for the full version.
+
+### Next.js (App Router)
+
+In a route handler on the Node.js runtime (`export const runtime = 'nodejs'`) the regular `logixia` entry works: wrap the handler body in `runWithTraceId(traceId, ...)`. See [`examples/nextjs/`](./examples/nextjs/) for a copy-paste route handler.
+
 ### NestJS trace middleware
 
 The `TraceMiddleware` class integrates directly with NestJS's middleware system. `LogixiaLoggerModule.forRoot()` applies it automatically across all routes — no manual wiring needed:
@@ -1001,7 +1055,7 @@ The `TraceMiddleware` class integrates directly with NestJS's middleware system.
 // For manual use in a custom module:
 
 import { MiddlewareConsumer, Module, NestModule } from '@nestjs/common';
-import { TraceMiddleware } from 'logixia';
+import { TraceMiddleware } from 'logixia/nest';
 
 @Module({})
 export class AppModule implements NestModule {
@@ -1016,7 +1070,7 @@ export class AppModule implements NestModule {
 Propagates trace IDs through Kafka message handlers. Reads `traceId` / `trace_id` / `x-trace-id` from the message body or headers and runs the handler inside that trace context:
 
 ```typescript
-import { KafkaTraceInterceptor } from 'logixia';
+import { KafkaTraceInterceptor } from 'logixia/nest';
 import { UseInterceptors, Controller } from '@nestjs/common';
 import { MessagePattern } from '@nestjs/microservices';
 
@@ -1038,7 +1092,7 @@ export class OrdersConsumer {
 Propagates trace IDs through WebSocket event handlers. Reads `traceId` from the message body, event payload, or handshake query:
 
 ```typescript
-import { WebSocketTraceInterceptor } from 'logixia';
+import { WebSocketTraceInterceptor } from 'logixia/nest';
 import { UseInterceptors, WebSocketGateway, SubscribeMessage } from '@nestjs/websockets';
 
 @UseInterceptors(new WebSocketTraceInterceptor())
@@ -1060,6 +1114,11 @@ export class EventsGateway {
 
 ## NestJS integration
 
+> **Upgrading from 1.x:** since 2.0.0, everything NestJS-specific lives in `logixia/nest` only.
+> Change `import { LogixiaLoggerModule, LogixiaLoggerService, LogixiaExceptionFilter, InjectLogger, LogMethod } from 'logixia'`
+> to `... from 'logixia/nest'`. The root `logixia` entry no longer loads `@nestjs/common`, so plain Node, Express and Fastify apps
+> work without NestJS installed.
+
 Drop-in module with zero boilerplate. Registers `TraceMiddleware` for all routes, provides `LogixiaLoggerService`, `KafkaTraceInterceptor`, and `WebSocketTraceInterceptor` via the global DI container.
 
 > **Full working example** — see [`examples/nestjs-app/`](./examples/nestjs-app/) for a complete NestJS app with Docker Compose (Postgres, MongoDB, Kafka, Kafdrop) that exercises every feature: `LogixiaLoggerModule`, `TraceMiddleware`, `LogixiaExceptionFilter`, `HttpLoggingInterceptor`, `WebSocketTraceInterceptor`, `KafkaTraceInterceptor`, `@LogMethod`, `child()` loggers, `timeAsync`, real Kafka producer + consumer.
@@ -1074,7 +1133,7 @@ Drop-in module with zero boilerplate. Registers `TraceMiddleware` for all routes
 ```typescript
 // app.module.ts
 import { Module } from '@nestjs/common';
-import { LogixiaLoggerModule } from 'logixia';
+import { LogixiaLoggerModule } from 'logixia/nest';
 
 @Module({
   imports: [
@@ -1120,7 +1179,7 @@ LogixiaLoggerModule.forRootAsync({
 ```typescript
 // orders.service.ts
 import { Injectable } from '@nestjs/common';
-import { LogixiaLoggerService } from 'logixia';
+import { LogixiaLoggerService } from 'logixia/nest';
 
 @Injectable()
 export class OrdersService {
@@ -1138,7 +1197,7 @@ export class OrdersService {
 ```typescript
 // orders.module.ts
 import { Module } from '@nestjs/common';
-import { LogixiaLoggerModule } from 'logixia';
+import { LogixiaLoggerModule } from 'logixia/nest';
 import { OrdersService } from './orders.service';
 
 @Module({
@@ -1151,7 +1210,7 @@ export class OrdersModule {}
 ```typescript
 // orders.service.ts — inject the feature-scoped token
 import { Inject, Injectable } from '@nestjs/common';
-import { LOGIXIA_LOGGER_PREFIX, LogixiaLoggerService } from 'logixia';
+import { LOGIXIA_LOGGER_PREFIX, LogixiaLoggerService } from 'logixia/nest';
 
 @Injectable()
 export class OrdersService {
@@ -1186,12 +1245,12 @@ await logger.mysql('Slow query detected', { query, ms: 1240 });
 await logger.payment('Charge captured', { txnId, amount: 99.99 });
 ```
 
-**TraceId** — with `traceId: true`, every log line carries a correlation ID automatically. Use `LogixiaContext.run()` to scope a trace to a block (the `TraceMiddleware` does this per-request automatically):
+**TraceId** — with `traceId: true`, every log line carries a correlation ID automatically. Use `runWithTraceId()` to scope a trace to a block (the `TraceMiddleware` does this per-request automatically):
 
 ```typescript
-import { LogixiaContext } from 'logixia';
+import { runWithTraceId } from 'logixia';
 
-await LogixiaContext.run({ traceId: req.headers['x-request-id'] }, async () => {
+await runWithTraceId(String(req.headers['x-request-id']), async () => {
   await logger.info('Request received'); // traceId: "abc-123" in every line
   await logger.kafka('Event published'); // same traceId
 });
@@ -1206,7 +1265,7 @@ Automatically logs method entry, exit, duration, and errors — no manual `try/c
 
 ```typescript
 import { Injectable } from '@nestjs/common';
-import { LogixiaLoggerService, LogMethod } from 'logixia';
+import { LogixiaLoggerService, LogMethod } from 'logixia/nest';
 
 @Injectable()
 export class PaymentService {
@@ -1243,7 +1302,7 @@ A global NestJS exception filter that automatically logs unhandled exceptions
 ```typescript
 // main.ts
 import { NestFactory } from '@nestjs/core';
-import { LogixiaExceptionFilter } from 'logixia';
+import { LogixiaExceptionFilter } from 'logixia/nest';
 import { AppModule } from './app.module';
 
 async function bootstrap() {
@@ -1258,7 +1317,7 @@ With `LogixiaLoggerModule` set up, inject the service directly so it logs to you
 
 ```typescript
 import { APP_FILTER } from '@nestjs/core';
-import { LogixiaExceptionFilter, LogixiaLoggerService } from 'logixia';
+import { LogixiaExceptionFilter, LogixiaLoggerService } from 'logixia/nest';
 
 // In AppModule providers:
 {
@@ -1357,6 +1416,8 @@ const app = Fastify();
 app.addHook('onRequest', correlationFastifyHook());
 ```
 
+> **Full working example** — see [`examples/fastify-example.ts`](./examples/fastify-example.ts) (`npm run dev:fastify`) for request logging, trace IDs and redaction on Fastify.
+
 ### Outbound fetch / axios
 
 Every outbound HTTP call made inside a correlated context automatically carries the `X-Correlation-ID` header.
@@ -1480,6 +1541,10 @@ const logger = new BrowserLogger({
 });
 ```
 
+Delivery failures (network errors and non-OK HTTP statuses) are counted in `failedFlushes` / `lastError` and passed to the optional `onError` callback. A throttled (at most one per minute) console report containing only the error name, HTTP status and endpoint host is printed everywhere except real browser pages, where it is silent by default; set `silent: true` or `silent: false` to override. Entries written to the transport from inside `onError` or while a report is printed are dropped (counted in `dropped`) to avoid feedback loops.
+
+**Cloudflare Workers** — see [`examples/cloudflare-worker/`](./examples/cloudflare-worker/) for a Worker that logs JSON, tags each request with `child({ requestId })` and flushes a `BrowserRemoteTransport` with `ctx.waitUntil()`. Pass `flushIntervalMs: 0` to the transport: Workers don't allow timers at global scope.
+
 The following utilities from the main package are also re-exported from `logixia/browser` (safe for non-Node runtimes):
 
 ```typescript
@@ -1686,24 +1751,27 @@ interface TransportLogEntry {
 Query your in-memory log history without shipping to Elasticsearch, Datadog, or any external service. Useful in development and lightweight production setups:
 
 ```typescript
-import { SearchManager } from 'logixia';
+import { SearchManager } from 'logixia/search';
 
-const search = new SearchManager({ maxEntries: 10_000 });
+const search = new SearchManager({ maxIndexSize: 10_000 });
 
 // Index a batch of entries (from a file, database query, or any source)
-await search.index(logEntries);
-
-// Search by text query, level, and time range
-const results = await search.search({
-  query: 'payment failed',
-  level: 'error',
-  from: new Date('2025-01-01'),
-  to: new Date(),
-  limit: 50,
-});
-// → sorted by relevance, full metadata included
+await search.indexLogs(logEntries); // or: await search.indexLog(entry)
+
+// Search by text, with filters and options
+const results = await search.search(
+  'payment failed',
+  { levels: ['error'], timeRange: { start: new Date('2025-01-01'), end: new Date() } },
+  { limit: 50 }
+);
+// → sorted by relevance, each result is { log, score, ... }
+
+const nl = await search.naturalLanguageSearch('payment errors'); // plain-English query
+const trace = await search.correlateByTraceId('req-001'); // every log of one request
 ```
 
+The same code runs as [`examples/search-readme.ts`](examples/search-readme.ts).
+
 ---
 
 ## OpenTelemetry
@@ -1757,6 +1825,8 @@ const logger = createLogger({
 // trace↔log correlation. Buffers drain on close() — no loss on shutdown.
 ```
 
+Import it from `logixia` or `logixia/transports`. Ready-made configs (URL and auth headers) for Grafana Loki / Grafana Cloud, Axiom, Better Stack and a local OpenTelemetry Collector are in [docs/otlp-recipes.md](docs/otlp-recipes.md).
+
 ---
 
 ## Wide events / canonical log lines
@@ -2256,11 +2326,14 @@ import {
   registerForShutdown, // (logger) => void
   deregisterFromShutdown, // (logger) => void
   resetShutdownHandlers, // () => void — useful in tests
-  // NestJS extras
+} from 'logixia';
+
+// NestJS extras (requires @nestjs/common):
+import {
   InjectLogger, // @InjectLogger() parameter decorator
   LogMethod, // @LogMethod() method decorator
   LogixiaExceptionFilter, // global exception filter
-} from 'logixia';
+} from 'logixia/nest';
 
 // Cloud transports (subpath imports):
 import { CloudWatchTransport } from 'logixia/cloudwatch';

package/dist/async-context-B05ArHgM.mjs

@@ -0,0 +1,134 @@
+import { n as resolveTraceHeaders, o as TraceContext, t as resolveRequestTraceId } from "./request-trace-C_fvIDv4.mjs";
+import { AsyncLocalStorage } from "node:async_hooks";
+// src/context/async-context.ts
+/**
+* LogixiaContext — Zero-boilerplate AsyncLocalStorage context propagation.
+*
+* Lets every `logger.info()` call inside a context automatically pick up stored
+* fields (requestId, userId, tenantId, …) without passing them through every function.
+*
+* Works across `Promise.all`, `setTimeout`, and event emitters — anything that
+* inherits the async execution context.
+*
+* @example
+* ```ts
+* import { LogixiaContext } from 'logixia';
+*
+* // Wrap a request handler:
+* app.use((req, res, next) => {
+*   LogixiaContext.run({ requestId: req.id, userId: req.user?.id }, next);
+* });
+*
+* // Anywhere deeper in the call tree:
+* async function processOrder(orderId: string) {
+*   const ctx = LogixiaContext.get();  // { requestId, userId, orderId }
+*   logger.info('Processing order', { orderId, ...ctx });
+* }
+* ```
+*/
+const _storage = new AsyncLocalStorage();
+const LogixiaContext = {
+	/**
+	* Run `callback` inside an async context that carries `store` fields.
+	* All loggers queried within `callback` (and its async descendants) will
+	* automatically see these fields.
+	*
+	* @example
+	* ```ts
+	* LogixiaContext.run({ requestId: 'abc', userId: '42' }, async () => {
+	*   await processOrder();   // sees requestId + userId in every log
+	* });
+	* ```
+	*/
+	run(store, callback) {
+		const parent = _storage.getStore() ?? {};
+		const scoped = () => _storage.run({
+			...parent,
+			...store
+		}, callback);
+		const traceId = store.traceId;
+		if (typeof traceId !== "string" || traceId === "") return scoped();
+		const trace = TraceContext.instance;
+		return trace.storage.run({
+			...trace.storage.getStore(),
+			[trace.contextKey]: traceId
+		}, scoped);
+	},
+	/**
+	* Return the context fields active in the current async scope.
+	* Returns `undefined` when called outside any `LogixiaContext.run()`.
+	*/
+	get() {
+		return _storage.getStore();
+	},
+	/**
+	* Merge `fields` into the **existing** context for the current scope.
+	* If called outside a `run()` context this is a no-op (logs a dev warning).
+	*/
+	set(fields) {
+		const store = _storage.getStore();
+		if (!store) return;
+		for (const key of Object.keys(fields)) {
+			if (key === "__proto__" || key === "constructor" || key === "prototype") continue;
+			store[key] = fields[key];
+		}
+	},
+	/**
+	* Retrieve the underlying `AsyncLocalStorage` instance.
+	* Useful for advanced use-cases like custom middleware.
+	*/
+	getStorage() {
+		return _storage;
+	}
+};
+function buildScope(request, options, headers) {
+	return {
+		...options.enrich ? options.enrich(request) : {},
+		traceId: resolveRequestTraceId(request, headers)
+	};
+}
+/**
+* Create an Express/Connect-compatible middleware that wraps each request in
+* a `LogixiaContext.run()` scope populated with common request fields.
+*
+* Trace ID: the first present header of `traceIdHeader` (default
+* `DEFAULT_TRACE_HEADERS`, `traceparent` parsed), else `request.id`, else a
+* generated UUID. It is available via `getCurrentTraceId()` and is the logger's
+* top-level `traceId` inside the request. No response header is set unless
+* `responseHeader` is given.
+*
+* @example
+* ```ts
+* import { createExpressContextMiddleware } from 'logixia';
+* app.use(createExpressContextMiddleware({ responseHeader: 'x-trace-id' }));
+* ```
+*/
+function createExpressContextMiddleware(options = {}) {
+	const headers = resolveTraceHeaders(options.traceIdHeader);
+	return function logixiaContextMiddleware(req, res, next) {
+		var _res$setHeader;
+		const scope = buildScope(req, options, headers);
+		if (options.responseHeader) (_res$setHeader = res.setHeader) === null || _res$setHeader === void 0 || _res$setHeader.call(res, options.responseHeader, scope.traceId);
+		LogixiaContext.run(scope, next);
+	};
+}
+/**
+* Create a Fastify lifecycle hook that wraps each request in a context scope.
+*
+* Register with `fastify.addHook('onRequest', createFastifyContextHook())`.
+* Resolves the trace ID exactly like {@link createExpressContextMiddleware} and
+* shares it with `createFastifyPlugin()` from `logixia/middleware`. Fastify's
+* default counter `request.id` (`req-1`, ...) is never used as a trace ID.
+*/
+function createFastifyContextHook(options = {}) {
+	const headers = resolveTraceHeaders(options.traceIdHeader);
+	return function logixiaFastifyHook(request, reply, done) {
+		var _reply$header;
+		const scope = buildScope(request, options, headers);
+		if (options.responseHeader) (_reply$header = reply.header) === null || _reply$header === void 0 || _reply$header.call(reply, options.responseHeader, scope.traceId);
+		LogixiaContext.run(scope, done);
+	};
+}
+export { createExpressContextMiddleware as n, createFastifyContextHook as r, LogixiaContext as t };
+
+//# sourceMappingURL=async-context-B05ArHgM.mjs.map

package/dist/async-context-B05ArHgM.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"async-context-B05ArHgM.mjs","names":[],"sources":["../src/context/async-context.ts"],"sourcesContent":["/**\n * LogixiaContext — Zero-boilerplate AsyncLocalStorage context propagation.\n *\n * Lets every `logger.info()` call inside a context automatically pick up stored\n * fields (requestId, userId, tenantId, …) without passing them through every function.\n *\n * Works across `Promise.all`, `setTimeout`, and event emitters — anything that\n * inherits the async execution context.\n *\n * @example\n * ```ts\n * import { LogixiaContext } from 'logixia';\n *\n * // Wrap a request handler:\n * app.use((req, res, next) => {\n *   LogixiaContext.run({ requestId: req.id, userId: req.user?.id }, next);\n * });\n *\n * // Anywhere deeper in the call tree:\n * async function processOrder(orderId: string) {\n *   const ctx = LogixiaContext.get();  // { requestId, userId, orderId }\n *   logger.info('Processing order', { orderId, ...ctx });\n * }\n * ```\n */\n\nimport { AsyncLocalStorage } from 'node:async_hooks';\n\nimport {\n  type ContextRequestLike,\n  resolveRequestTraceId,\n  resolveTraceHeaders,\n  type TraceHeaderOption,\n} from '../utils/request-trace';\nimport { TraceContext } from '../utils/trace.utils';\n\nexport interface LogContext {\n  traceId?: string;\n  spanId?: string;\n  userId?: string;\n  tenantId?: string;\n  sessionId?: string;\n  [key: string]: unknown;\n}\n\n// Module-level singleton so all loggers share the same ALS store.\nconst _storage = new AsyncLocalStorage<LogContext>();\n\nexport const LogixiaContext = {\n  /**\n   * Run `callback` inside an async context that carries `store` fields.\n   * All loggers queried within `callback` (and its async descendants) will\n   * automatically see these fields.\n   *\n   * @example\n   * ```ts\n   * LogixiaContext.run({ requestId: 'abc', userId: '42' }, async () => {\n   *   await processOrder();   // sees requestId + userId in every log\n   * });\n   * ```\n   */\n  run<T>(store: LogContext, callback: () => T): T {\n    const parent = _storage.getStore() ?? {};\n    const scoped = (): T => _storage.run({ ...parent, ...store }, callback);\n    const traceId = store.traceId;\n    if (typeof traceId !== 'string' || traceId === '') return scoped();\n    // An explicit traceId also becomes the TraceContext ID, so getCurrentTraceId(),\n    // the logger, outbound propagation and the OTel bridge all see the same value.\n    const trace = TraceContext.instance;\n    return trace.storage.run({ ...trace.storage.getStore(), [trace.contextKey]: traceId }, scoped);\n  },\n\n  /**\n   * Return the context fields active in the current async scope.\n   * Returns `undefined` when called outside any `LogixiaContext.run()`.\n   */\n  get(): LogContext | undefined {\n    return _storage.getStore();\n  },\n\n  /**\n   * Merge `fields` into the **existing** context for the current scope.\n   * If called outside a `run()` context this is a no-op (logs a dev warning).\n   */\n  set(fields: Partial<LogContext>): void {\n    const store = _storage.getStore();\n    if (!store) {\n      // Silently ignore — avoids crashing in code that may call setContext\n      // before a request context is established (e.g. background jobs).\n      return;\n    }\n    for (const key of Object.keys(fields)) {\n      if (key === '__proto__' || key === 'constructor' || key === 'prototype') continue;\n      store[key] = fields[key];\n    }\n  },\n\n  /**\n   * Retrieve the underlying `AsyncLocalStorage` instance.\n   * Useful for advanced use-cases like custom middleware.\n   */\n  getStorage(): AsyncLocalStorage<LogContext> {\n    return _storage;\n  },\n};\n\nexport type { ContextRequestLike };\n\ninterface ContextHelperOptions<Req extends ContextRequestLike> {\n  /**\n   * Extract additional fields from the request. A `traceId` returned here is ignored:\n   * the resolved request trace ID always wins.\n   */\n  enrich?: (request: Req & Record<string, unknown>) => Partial<LogContext>;\n  /**\n   * Header name, or list of names tried in order, to read the trace ID from.\n   * Default: `DEFAULT_TRACE_HEADERS` (traceparent is parsed to its 32-hex trace id).\n   */\n  traceIdHeader?: TraceHeaderOption;\n  /**\n   * Echo the resolved trace ID on the response under this header name.\n   * Default: `false` (no response header is set).\n   */\n  responseHeader?: string | false;\n}\n\nfunction buildScope<Req extends ContextRequestLike>(\n  request: Req,\n  options: ContextHelperOptions<Req>,\n  headers: readonly string[]\n): LogContext {\n  const extra = options.enrich ? options.enrich(request as Req & Record<string, unknown>) : {};\n  return { ...extra, traceId: resolveRequestTraceId(request, headers) };\n}\n\n/**\n * Create an Express/Connect-compatible middleware that wraps each request in\n * a `LogixiaContext.run()` scope populated with common request fields.\n *\n * Trace ID: the first present header of `traceIdHeader` (default\n * `DEFAULT_TRACE_HEADERS`, `traceparent` parsed), else `request.id`, else a\n * generated UUID. It is available via `getCurrentTraceId()` and is the logger's\n * top-level `traceId` inside the request. No response header is set unless\n * `responseHeader` is given.\n *\n * @example\n * ```ts\n * import { createExpressContextMiddleware } from 'logixia';\n * app.use(createExpressContextMiddleware({ responseHeader: 'x-trace-id' }));\n * ```\n */\nexport function createExpressContextMiddleware<Req extends ContextRequestLike = ContextRequestLike>(\n  options: ContextHelperOptions<Req> = {}\n) {\n  const headers = resolveTraceHeaders(options.traceIdHeader);\n\n  return function logixiaContextMiddleware(\n    req: Req,\n    res: { setHeader?: (name: string, value: string) => unknown },\n    next: () => void\n  ): void {\n    const scope = buildScope(req, options, headers);\n    if (options.responseHeader) res.setHeader?.(options.responseHeader, scope.traceId as string);\n    LogixiaContext.run(scope, next);\n  };\n}\n\n/**\n * Create a Fastify lifecycle hook that wraps each request in a context scope.\n *\n * Register with `fastify.addHook('onRequest', createFastifyContextHook())`.\n * Resolves the trace ID exactly like {@link createExpressContextMiddleware} and\n * shares it with `createFastifyPlugin()` from `logixia/middleware`. Fastify's\n * default counter `request.id` (`req-1`, ...) is never used as a trace ID.\n */\nexport function createFastifyContextHook<Req extends ContextRequestLike = ContextRequestLike>(\n  options: ContextHelperOptions<Req> = {}\n) {\n  const headers = resolveTraceHeaders(options.traceIdHeader);\n\n  return function logixiaFastifyHook(\n    request: Req,\n    reply: { header?: (name: string, value: string) => unknown },\n    done: () => void\n  ): void {\n    const scope = buildScope(request, options, headers);\n    if (options.responseHeader) reply.header?.(options.responseHeader, scope.traceId as string);\n    LogixiaContext.run(scope, done);\n  };\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;AA8CA,MAAM,WAAW,IAAI,kBAA8B;AAEnD,MAAa,iBAAiB;;;;;;;;;;;;;CAa5B,IAAO,OAAmB,UAAsB;EAC9C,MAAM,SAAS,SAAS,SAAS,KAAK,CAAC;EACvC,MAAM,eAAkB,SAAS,IAAI;GAAE,GAAG;GAAQ,GAAG;EAAM,GAAG,QAAQ;EACtE,MAAM,UAAU,MAAM;EACtB,IAAI,OAAO,YAAY,YAAY,YAAY,IAAI,OAAO,OAAO;EAGjE,MAAM,QAAQ,aAAa;EAC3B,OAAO,MAAM,QAAQ,IAAI;GAAE,GAAG,MAAM,QAAQ,SAAS;IAAI,MAAM,aAAa;EAAQ,GAAG,MAAM;CAC/F;;;;;CAMA,MAA8B;EAC5B,OAAO,SAAS,SAAS;CAC3B;;;;;CAMA,IAAI,QAAmC;EACrC,MAAM,QAAQ,SAAS,SAAS;EAChC,IAAI,CAAC,OAGH;EAEF,KAAK,MAAM,OAAO,OAAO,KAAK,MAAM,GAAG;GACrC,IAAI,QAAQ,eAAe,QAAQ,iBAAiB,QAAQ,aAAa;GACzE,MAAM,OAAO,OAAO;EACtB;CACF;;;;;CAMA,aAA4C;EAC1C,OAAO;CACT;AACF;AAsBA,SAAS,WACP,SACA,SACA,SACY;CAEZ,OAAO;EAAE,GADK,QAAQ,SAAS,QAAQ,OAAO,OAAwC,IAAI,CAAC;EACxE,SAAS,sBAAsB,SAAS,OAAO;CAAE;AACtE;;;;;;;;;;;;;;;;;AAkBA,SAAgB,+BACd,UAAqC,CAAC,GACtC;CACA,MAAM,UAAU,oBAAoB,QAAQ,aAAa;CAEzD,OAAO,SAAS,yBACd,KACA,KACA,MACM;;EACN,MAAM,QAAQ,WAAW,KAAK,SAAS,OAAO;EAC9C,IAAI,QAAQ,gBAAgB,CAAA,iBAAA,IAAI,eAAA,QAAA,mBAAA,KAAA,KAAA,eAAA,KAAA,KAAY,QAAQ,gBAAgB,MAAM,OAAiB;EAC3F,eAAe,IAAI,OAAO,IAAI;CAChC;AACF;;;;;;;;;AAUA,SAAgB,yBACd,UAAqC,CAAC,GACtC;CACA,MAAM,UAAU,oBAAoB,QAAQ,aAAa;CAEzD,OAAO,SAAS,mBACd,SACA,OACA,MACM;;EACN,MAAM,QAAQ,WAAW,SAAS,SAAS,OAAO;EAClD,IAAI,QAAQ,gBAAgB,CAAA,gBAAA,MAAM,YAAA,QAAA,kBAAA,KAAA,KAAA,cAAA,KAAA,OAAS,QAAQ,gBAAgB,MAAM,OAAiB;EAC1F,eAAe,IAAI,OAAO,IAAI;CAChC;AACF"}

package/dist/async-context-DTQgi8f7.js

@@ -0,0 +1,150 @@
+const require_request_trace = require("./request-trace-wTJdKp6-.js");
+// src/context/async-context.ts
+/**
+* LogixiaContext — Zero-boilerplate AsyncLocalStorage context propagation.
+*
+* Lets every `logger.info()` call inside a context automatically pick up stored
+* fields (requestId, userId, tenantId, …) without passing them through every function.
+*
+* Works across `Promise.all`, `setTimeout`, and event emitters — anything that
+* inherits the async execution context.
+*
+* @example
+* ```ts
+* import { LogixiaContext } from 'logixia';
+*
+* // Wrap a request handler:
+* app.use((req, res, next) => {
+*   LogixiaContext.run({ requestId: req.id, userId: req.user?.id }, next);
+* });
+*
+* // Anywhere deeper in the call tree:
+* async function processOrder(orderId: string) {
+*   const ctx = LogixiaContext.get();  // { requestId, userId, orderId }
+*   logger.info('Processing order', { orderId, ...ctx });
+* }
+* ```
+*/
+const _storage = new (require("node:async_hooks")).AsyncLocalStorage();
+const LogixiaContext = {
+	/**
+	* Run `callback` inside an async context that carries `store` fields.
+	* All loggers queried within `callback` (and its async descendants) will
+	* automatically see these fields.
+	*
+	* @example
+	* ```ts
+	* LogixiaContext.run({ requestId: 'abc', userId: '42' }, async () => {
+	*   await processOrder();   // sees requestId + userId in every log
+	* });
+	* ```
+	*/
+	run(store, callback) {
+		const parent = _storage.getStore() ?? {};
+		const scoped = () => _storage.run({
+			...parent,
+			...store
+		}, callback);
+		const traceId = store.traceId;
+		if (typeof traceId !== "string" || traceId === "") return scoped();
+		const trace = require_request_trace.TraceContext.instance;
+		return trace.storage.run({
+			...trace.storage.getStore(),
+			[trace.contextKey]: traceId
+		}, scoped);
+	},
+	/**
+	* Return the context fields active in the current async scope.
+	* Returns `undefined` when called outside any `LogixiaContext.run()`.
+	*/
+	get() {
+		return _storage.getStore();
+	},
+	/**
+	* Merge `fields` into the **existing** context for the current scope.
+	* If called outside a `run()` context this is a no-op (logs a dev warning).
+	*/
+	set(fields) {
+		const store = _storage.getStore();
+		if (!store) return;
+		for (const key of Object.keys(fields)) {
+			if (key === "__proto__" || key === "constructor" || key === "prototype") continue;
+			store[key] = fields[key];
+		}
+	},
+	/**
+	* Retrieve the underlying `AsyncLocalStorage` instance.
+	* Useful for advanced use-cases like custom middleware.
+	*/
+	getStorage() {
+		return _storage;
+	}
+};
+function buildScope(request, options, headers) {
+	return {
+		...options.enrich ? options.enrich(request) : {},
+		traceId: require_request_trace.resolveRequestTraceId(request, headers)
+	};
+}
+/**
+* Create an Express/Connect-compatible middleware that wraps each request in
+* a `LogixiaContext.run()` scope populated with common request fields.
+*
+* Trace ID: the first present header of `traceIdHeader` (default
+* `DEFAULT_TRACE_HEADERS`, `traceparent` parsed), else `request.id`, else a
+* generated UUID. It is available via `getCurrentTraceId()` and is the logger's
+* top-level `traceId` inside the request. No response header is set unless
+* `responseHeader` is given.
+*
+* @example
+* ```ts
+* import { createExpressContextMiddleware } from 'logixia';
+* app.use(createExpressContextMiddleware({ responseHeader: 'x-trace-id' }));
+* ```
+*/
+function createExpressContextMiddleware(options = {}) {
+	const headers = require_request_trace.resolveTraceHeaders(options.traceIdHeader);
+	return function logixiaContextMiddleware(req, res, next) {
+		var _res$setHeader;
+		const scope = buildScope(req, options, headers);
+		if (options.responseHeader) (_res$setHeader = res.setHeader) === null || _res$setHeader === void 0 || _res$setHeader.call(res, options.responseHeader, scope.traceId);
+		LogixiaContext.run(scope, next);
+	};
+}
+/**
+* Create a Fastify lifecycle hook that wraps each request in a context scope.
+*
+* Register with `fastify.addHook('onRequest', createFastifyContextHook())`.
+* Resolves the trace ID exactly like {@link createExpressContextMiddleware} and
+* shares it with `createFastifyPlugin()` from `logixia/middleware`. Fastify's
+* default counter `request.id` (`req-1`, ...) is never used as a trace ID.
+*/
+function createFastifyContextHook(options = {}) {
+	const headers = require_request_trace.resolveTraceHeaders(options.traceIdHeader);
+	return function logixiaFastifyHook(request, reply, done) {
+		var _reply$header;
+		const scope = buildScope(request, options, headers);
+		if (options.responseHeader) (_reply$header = reply.header) === null || _reply$header === void 0 || _reply$header.call(reply, options.responseHeader, scope.traceId);
+		LogixiaContext.run(scope, done);
+	};
+}
+Object.defineProperty(exports, "LogixiaContext", {
+	enumerable: true,
+	get: function() {
+		return LogixiaContext;
+	}
+});
+Object.defineProperty(exports, "createExpressContextMiddleware", {
+	enumerable: true,
+	get: function() {
+		return createExpressContextMiddleware;
+	}
+});
+Object.defineProperty(exports, "createFastifyContextHook", {
+	enumerable: true,
+	get: function() {
+		return createFastifyContextHook;
+	}
+});
+
+//# sourceMappingURL=async-context-DTQgi8f7.js.map

package/dist/async-context-DTQgi8f7.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"async-context-DTQgi8f7.js","names":["AsyncLocalStorage","TraceContext","resolveRequestTraceId","resolveTraceHeaders"],"sources":["../src/context/async-context.ts"],"sourcesContent":["/**\n * LogixiaContext — Zero-boilerplate AsyncLocalStorage context propagation.\n *\n * Lets every `logger.info()` call inside a context automatically pick up stored\n * fields (requestId, userId, tenantId, …) without passing them through every function.\n *\n * Works across `Promise.all`, `setTimeout`, and event emitters — anything that\n * inherits the async execution context.\n *\n * @example\n * ```ts\n * import { LogixiaContext } from 'logixia';\n *\n * // Wrap a request handler:\n * app.use((req, res, next) => {\n *   LogixiaContext.run({ requestId: req.id, userId: req.user?.id }, next);\n * });\n *\n * // Anywhere deeper in the call tree:\n * async function processOrder(orderId: string) {\n *   const ctx = LogixiaContext.get();  // { requestId, userId, orderId }\n *   logger.info('Processing order', { orderId, ...ctx });\n * }\n * ```\n */\n\nimport { AsyncLocalStorage } from 'node:async_hooks';\n\nimport {\n  type ContextRequestLike,\n  resolveRequestTraceId,\n  resolveTraceHeaders,\n  type TraceHeaderOption,\n} from '../utils/request-trace';\nimport { TraceContext } from '../utils/trace.utils';\n\nexport interface LogContext {\n  traceId?: string;\n  spanId?: string;\n  userId?: string;\n  tenantId?: string;\n  sessionId?: string;\n  [key: string]: unknown;\n}\n\n// Module-level singleton so all loggers share the same ALS store.\nconst _storage = new AsyncLocalStorage<LogContext>();\n\nexport const LogixiaContext = {\n  /**\n   * Run `callback` inside an async context that carries `store` fields.\n   * All loggers queried within `callback` (and its async descendants) will\n   * automatically see these fields.\n   *\n   * @example\n   * ```ts\n   * LogixiaContext.run({ requestId: 'abc', userId: '42' }, async () => {\n   *   await processOrder();   // sees requestId + userId in every log\n   * });\n   * ```\n   */\n  run<T>(store: LogContext, callback: () => T): T {\n    const parent = _storage.getStore() ?? {};\n    const scoped = (): T => _storage.run({ ...parent, ...store }, callback);\n    const traceId = store.traceId;\n    if (typeof traceId !== 'string' || traceId === '') return scoped();\n    // An explicit traceId also becomes the TraceContext ID, so getCurrentTraceId(),\n    // the logger, outbound propagation and the OTel bridge all see the same value.\n    const trace = TraceContext.instance;\n    return trace.storage.run({ ...trace.storage.getStore(), [trace.contextKey]: traceId }, scoped);\n  },\n\n  /**\n   * Return the context fields active in the current async scope.\n   * Returns `undefined` when called outside any `LogixiaContext.run()`.\n   */\n  get(): LogContext | undefined {\n    return _storage.getStore();\n  },\n\n  /**\n   * Merge `fields` into the **existing** context for the current scope.\n   * If called outside a `run()` context this is a no-op (logs a dev warning).\n   */\n  set(fields: Partial<LogContext>): void {\n    const store = _storage.getStore();\n    if (!store) {\n      // Silently ignore — avoids crashing in code that may call setContext\n      // before a request context is established (e.g. background jobs).\n      return;\n    }\n    for (const key of Object.keys(fields)) {\n      if (key === '__proto__' || key === 'constructor' || key === 'prototype') continue;\n      store[key] = fields[key];\n    }\n  },\n\n  /**\n   * Retrieve the underlying `AsyncLocalStorage` instance.\n   * Useful for advanced use-cases like custom middleware.\n   */\n  getStorage(): AsyncLocalStorage<LogContext> {\n    return _storage;\n  },\n};\n\nexport type { ContextRequestLike };\n\ninterface ContextHelperOptions<Req extends ContextRequestLike> {\n  /**\n   * Extract additional fields from the request. A `traceId` returned here is ignored:\n   * the resolved request trace ID always wins.\n   */\n  enrich?: (request: Req & Record<string, unknown>) => Partial<LogContext>;\n  /**\n   * Header name, or list of names tried in order, to read the trace ID from.\n   * Default: `DEFAULT_TRACE_HEADERS` (traceparent is parsed to its 32-hex trace id).\n   */\n  traceIdHeader?: TraceHeaderOption;\n  /**\n   * Echo the resolved trace ID on the response under this header name.\n   * Default: `false` (no response header is set).\n   */\n  responseHeader?: string | false;\n}\n\nfunction buildScope<Req extends ContextRequestLike>(\n  request: Req,\n  options: ContextHelperOptions<Req>,\n  headers: readonly string[]\n): LogContext {\n  const extra = options.enrich ? options.enrich(request as Req & Record<string, unknown>) : {};\n  return { ...extra, traceId: resolveRequestTraceId(request, headers) };\n}\n\n/**\n * Create an Express/Connect-compatible middleware that wraps each request in\n * a `LogixiaContext.run()` scope populated with common request fields.\n *\n * Trace ID: the first present header of `traceIdHeader` (default\n * `DEFAULT_TRACE_HEADERS`, `traceparent` parsed), else `request.id`, else a\n * generated UUID. It is available via `getCurrentTraceId()` and is the logger's\n * top-level `traceId` inside the request. No response header is set unless\n * `responseHeader` is given.\n *\n * @example\n * ```ts\n * import { createExpressContextMiddleware } from 'logixia';\n * app.use(createExpressContextMiddleware({ responseHeader: 'x-trace-id' }));\n * ```\n */\nexport function createExpressContextMiddleware<Req extends ContextRequestLike = ContextRequestLike>(\n  options: ContextHelperOptions<Req> = {}\n) {\n  const headers = resolveTraceHeaders(options.traceIdHeader);\n\n  return function logixiaContextMiddleware(\n    req: Req,\n    res: { setHeader?: (name: string, value: string) => unknown },\n    next: () => void\n  ): void {\n    const scope = buildScope(req, options, headers);\n    if (options.responseHeader) res.setHeader?.(options.responseHeader, scope.traceId as string);\n    LogixiaContext.run(scope, next);\n  };\n}\n\n/**\n * Create a Fastify lifecycle hook that wraps each request in a context scope.\n *\n * Register with `fastify.addHook('onRequest', createFastifyContextHook())`.\n * Resolves the trace ID exactly like {@link createExpressContextMiddleware} and\n * shares it with `createFastifyPlugin()` from `logixia/middleware`. Fastify's\n * default counter `request.id` (`req-1`, ...) is never used as a trace ID.\n */\nexport function createFastifyContextHook<Req extends ContextRequestLike = ContextRequestLike>(\n  options: ContextHelperOptions<Req> = {}\n) {\n  const headers = resolveTraceHeaders(options.traceIdHeader);\n\n  return function logixiaFastifyHook(\n    request: Req,\n    reply: { header?: (name: string, value: string) => unknown },\n    done: () => void\n  ): void {\n    const scope = buildScope(request, options, headers);\n    if (options.responseHeader) reply.header?.(options.responseHeader, scope.traceId as string);\n    LogixiaContext.run(scope, done);\n  };\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;AA8CA,MAAM,WAAW,K,0BAAIA,EAAAA,CAAAA,kBAA8B;AAEnD,MAAa,iBAAiB;;;;;;;;;;;;;CAa5B,IAAO,OAAmB,UAAsB;EAC9C,MAAM,SAAS,SAAS,SAAS,KAAK,CAAC;EACvC,MAAM,eAAkB,SAAS,IAAI;GAAE,GAAG;GAAQ,GAAG;EAAM,GAAG,QAAQ;EACtE,MAAM,UAAU,MAAM;EACtB,IAAI,OAAO,YAAY,YAAY,YAAY,IAAI,OAAO,OAAO;EAGjE,MAAM,QAAQC,sBAAAA,aAAa;EAC3B,OAAO,MAAM,QAAQ,IAAI;GAAE,GAAG,MAAM,QAAQ,SAAS;IAAI,MAAM,aAAa;EAAQ,GAAG,MAAM;CAC/F;;;;;CAMA,MAA8B;EAC5B,OAAO,SAAS,SAAS;CAC3B;;;;;CAMA,IAAI,QAAmC;EACrC,MAAM,QAAQ,SAAS,SAAS;EAChC,IAAI,CAAC,OAGH;EAEF,KAAK,MAAM,OAAO,OAAO,KAAK,MAAM,GAAG;GACrC,IAAI,QAAQ,eAAe,QAAQ,iBAAiB,QAAQ,aAAa;GACzE,MAAM,OAAO,OAAO;EACtB;CACF;;;;;CAMA,aAA4C;EAC1C,OAAO;CACT;AACF;AAsBA,SAAS,WACP,SACA,SACA,SACY;CAEZ,OAAO;EAAE,GADK,QAAQ,SAAS,QAAQ,OAAO,OAAwC,IAAI,CAAC;EACxE,SAASC,sBAAAA,sBAAsB,SAAS,OAAO;CAAE;AACtE;;;;;;;;;;;;;;;;;AAkBA,SAAgB,+BACd,UAAqC,CAAC,GACtC;CACA,MAAM,UAAUC,sBAAAA,oBAAoB,QAAQ,aAAa;CAEzD,OAAO,SAAS,yBACd,KACA,KACA,MACM;;EACN,MAAM,QAAQ,WAAW,KAAK,SAAS,OAAO;EAC9C,IAAI,QAAQ,gBAAgB,CAAA,iBAAA,IAAI,eAAA,QAAA,mBAAA,KAAA,KAAA,eAAA,KAAA,KAAY,QAAQ,gBAAgB,MAAM,OAAiB;EAC3F,eAAe,IAAI,OAAO,IAAI;CAChC;AACF;;;;;;;;;AAUA,SAAgB,yBACd,UAAqC,CAAC,GACtC;CACA,MAAM,UAAUA,sBAAAA,oBAAoB,QAAQ,aAAa;CAEzD,OAAO,SAAS,mBACd,SACA,OACA,MACM;;EACN,MAAM,QAAQ,WAAW,SAAS,SAAS,OAAO;EAClD,IAAI,QAAQ,gBAAgB,CAAA,gBAAA,MAAM,YAAA,QAAA,kBAAA,KAAA,KAAA,cAAA,KAAA,OAAS,QAAQ,gBAAgB,MAAM,OAAiB;EAC1F,eAAe,IAAI,OAAO,IAAI;CAChC;AACF"}