logixia 1.12.4 → 1.12.6

package/dist/correlation.d.mts

@@ -0,0 +1,238 @@
+//#region src/correlation.d.ts
+/**
+ * logixia — Microservices Correlation ID Propagation
+ *
+ * Provides zero-boilerplate correlation ID generation and propagation for
+ * distributed systems. A single correlation ID travels through every service
+ * in a request fan-out, making it trivial to join logs across services.
+ *
+ * Features:
+ *  - UUID v4 correlation ID generation (via `crypto.randomUUID()`)
+ *  - Express / Fastify / NestJS incoming-request middleware
+ *  - `correlationFetch()` — wraps global `fetch`, auto-injects `X-Correlation-ID`
+ *  - `createCorrelationAxiosInterceptor()` — axios request interceptor
+ *  - `childFromRequest(req, logger)` — child logger with all request identifiers
+ *  - Kafka / SQS / RabbitMQ message context helpers
+ *  - Integration with `LogixiaContext` (AsyncLocalStorage) so every `logger.info()`
+ *    call automatically includes the correlationId without per-call passing.
+ *
+ * @example Express middleware
+ * ```ts
+ * import { correlationMiddleware } from 'logixia/correlation';
+ * import { logger } from 'logixia';
+ *
+ * app.use(correlationMiddleware());
+ *
+ * app.get('/orders', (req, res) => {
+ *   // correlationId is automatically in every log inside this request
+ *   logger.info('Listing orders');
+ *   res.json({ ok: true });
+ * });
+ * ```
+ *
+ * @example Outbound fetch with correlation
+ * ```ts
+ * import { correlationFetch } from 'logixia/correlation';
+ *
+ * // Reads correlationId from current LogixiaContext and injects it as header
+ * const data = await correlationFetch('https://payments.internal/charge', {
+ *   method: 'POST',
+ *   body: JSON.stringify({ amount: 100 }),
+ * });
+ * ```
+ *
+ * @example Manual correlation context
+ * ```ts
+ * import { withCorrelationId } from 'logixia/correlation';
+ *
+ * await withCorrelationId('trace-abc-123', async () => {
+ *   // All logs and outbound fetch calls in here carry 'trace-abc-123'
+ *   await processOrder();
+ * });
+ * ```
+ */
+/** Fields injected into the log context by the correlation middleware. */
+interface CorrelationContext {
+  correlationId: string;
+  traceId?: string;
+  /** Service that originated the request (from `X-Origin-Service` header). */
+  originService?: string;
+  /** Index signature so CorrelationContext is assignable to LogContext. */
+  [key: string]: unknown;
+}
+interface CorrelationMiddlewareOptions {
+  /**
+   * HTTP header to read/write the correlation ID from/to.
+   * @default 'x-correlation-id'
+   */
+  header?: string;
+  /**
+   * HTTP header for the originating service name.
+   * @default 'x-origin-service'
+   */
+  originServiceHeader?: string;
+  /**
+   * Function to generate a new correlation ID when none is present in the request.
+   * @default () => crypto.randomUUID()
+   */
+  generate?: () => string;
+  /**
+   * When `true`, the response will include the correlation ID header so
+   * clients can log it client-side.
+   * @default true
+   */
+  setResponseHeader?: boolean;
+}
+/**
+ * Generate a new correlation ID using `crypto.randomUUID()` (available in
+ * Node.js 14.17+, all modern browsers, and Edge runtimes).
+ *
+ * When the Web Crypto global is unavailable (e.g. Node 18 without
+ * `--experimental-global-webcrypto`), fall back to `node:crypto`'s
+ * `randomUUID`, which returns a proper UUID v4 — matching the shape this
+ * function's JSDoc and README promise. `logixia/correlation` is Node-only
+ * (it builds on `AsyncLocalStorage`), so importing `node:crypto` is safe here.
+ */
+declare function generateCorrelationId(): string;
+/**
+ * Return the correlation ID from the current `LogixiaContext`, or `undefined`
+ * when called outside any context scope.
+ */
+declare function getCurrentCorrelationId(): string | undefined;
+/**
+ * Run `callback` inside a correlation context scope.
+ *
+ * If a correlation ID is not provided, a new UUID is generated.
+ *
+ * @example
+ * ```ts
+ * await withCorrelationId('cid-abc', async () => {
+ *   logger.info('Processing message'); // → { correlationId: 'cid-abc', ... }
+ *   await callDownstream();            // correlationFetch() picks up cid-abc
+ * });
+ * ```
+ */
+declare function withCorrelationId<T>(correlationId: string | undefined, callback: () => T): T;
+/**
+ * Express-compatible middleware that:
+ * 1. Reads `X-Correlation-ID` from the incoming request (or generates a new one)
+ * 2. Wraps the request in a `LogixiaContext` so all loggers in the handler
+ *    automatically include `correlationId`
+ * 3. Writes the correlation ID back to the response header (opt-out via options)
+ *
+ * @example
+ * ```ts
+ * import { correlationMiddleware } from 'logixia/correlation';
+ * app.use(correlationMiddleware());
+ * ```
+ */
+declare function correlationMiddleware(options?: CorrelationMiddlewareOptions): (req: Record<string, unknown>, res: Record<string, unknown>, next: () => void) => void;
+/**
+ * Fastify `onRequest` lifecycle hook — same functionality as `correlationMiddleware`
+ * but adapted to Fastify's hook API.
+ *
+ * @example
+ * ```ts
+ * import { correlationFastifyHook } from 'logixia/correlation';
+ * fastify.addHook('onRequest', correlationFastifyHook());
+ * ```
+ */
+declare function correlationFastifyHook(options?: CorrelationMiddlewareOptions): (request: Record<string, unknown>, reply: Record<string, unknown>, done: () => void) => void;
+/**
+ * A drop-in replacement for `fetch` that automatically injects the current
+ * `correlationId` from `LogixiaContext` as an `X-Correlation-ID` request header.
+ *
+ * Falls back to the global `fetch` when no correlation context is active.
+ *
+ * @example
+ * ```ts
+ * import { correlationFetch } from 'logixia/correlation';
+ *
+ * // Inside a request handler with correlationMiddleware active:
+ * const response = await correlationFetch('https://payments.internal/v1/charge', {
+ *   method: 'POST',
+ *   body: JSON.stringify({ amount: 100 }),
+ * });
+ * ```
+ */
+declare function correlationFetch(input: string | URL | Request, init?: RequestInit, options?: {
+  header?: string;
+}): Promise<Response>;
+/**
+ * Returns an axios request interceptor that automatically injects the current
+ * correlation ID into outgoing axios requests.
+ *
+ * @example
+ * ```ts
+ * import axios from 'axios';
+ * import { createCorrelationAxiosInterceptor } from 'logixia/correlation';
+ *
+ * axios.interceptors.request.use(createCorrelationAxiosInterceptor());
+ * ```
+ */
+declare function createCorrelationAxiosInterceptor(options?: {
+  header?: string;
+}): (config: Record<string, unknown>) => Record<string, unknown>;
+/**
+ * Create a child logger enriched with all correlation-relevant identifiers
+ * extracted from the incoming HTTP request.
+ *
+ * The child logger's every call automatically includes:
+ * `correlationId`, `requestId`, `method`, `url`, `userAgent`, `ip`
+ *
+ * @example
+ * ```ts
+ * import { childFromRequest } from 'logixia/correlation';
+ * import { logger } from 'logixia';
+ *
+ * app.use((req, res, next) => {
+ *   req.logger = childFromRequest(req, logger);
+ *   next();
+ * });
+ *
+ * app.get('/orders', (req, res) => {
+ *   req.logger.info('Listing orders');  // → correlationId, requestId, method, url ...
+ * });
+ * ```
+ */
+declare function childFromRequest<TLogger extends {
+  child(ctx: Record<string, unknown>): TLogger;
+}>(req: Record<string, unknown>, logger: TLogger, options?: {
+  correlationHeader?: string;
+}): TLogger;
+/**
+ * Extract a correlation context from a Kafka / RabbitMQ / SQS message object.
+ *
+ * Looks for `correlationId`, `correlation_id`, or `x-correlation-id` in
+ * `message.headers` (Kafka) or `message.MessageAttributes` (SQS).
+ *
+ * @example Kafka consumer
+ * ```ts
+ * import { extractMessageCorrelationId, withCorrelationId } from 'logixia/correlation';
+ *
+ * consumer.run({
+ *   eachMessage: async ({ message }) => {
+ *     const correlationId = extractMessageCorrelationId(message);
+ *     await withCorrelationId(correlationId, () => processMessage(message));
+ *   },
+ * });
+ * ```
+ */
+declare function extractMessageCorrelationId(message: Record<string, unknown>): string | undefined;
+/**
+ * Build Kafka message headers containing the current correlation context.
+ *
+ * @example
+ * ```ts
+ * import { buildKafkaCorrelationHeaders } from 'logixia/correlation';
+ *
+ * await producer.send({
+ *   topic: 'orders',
+ *   messages: [{ value: JSON.stringify(order), headers: buildKafkaCorrelationHeaders() }],
+ * });
+ * ```
+ */
+declare function buildKafkaCorrelationHeaders(): Record<string, string>;
+//#endregion
+export { CorrelationContext, CorrelationMiddlewareOptions, buildKafkaCorrelationHeaders, childFromRequest, correlationFastifyHook, correlationFetch, correlationMiddleware, createCorrelationAxiosInterceptor, extractMessageCorrelationId, generateCorrelationId, getCurrentCorrelationId, withCorrelationId };
+//# sourceMappingURL=correlation.d.mts.map

package/dist/correlation.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"correlation.d.mts","names":[],"sources":["../src/correlation.ts"],"sourcesContent":[],"mappings":";;AA4DA;AASA;AAoCA;AA2BA;AAkBA;AAoBA;;;;;AA+CA;;;;;AAsDA;;;;;;;AA4CA;AA4CA;;;;;;;AAmDA;AA4CA;;;;;;;;;;;;;;;;;;;;;UA1YiB,kBAAA;;;;;;;;UASA,4BAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAoCD,qBAAA,CAAA;;;;;iBA2BA,uBAAA,CAAA;;;;;;;;;;;;;;iBAkBA,wEAAwE,IAAI;;;;;;;;;;;;;;iBAoB5E,qBAAA,WAA+B,qCAStC,8BACA;;;;;;;;;;;iBAqCO,sBAAA,WAAgC,yCASnC,gCACF;;;;;;;;;;;;;;;;;;iBA4CW,gBAAA,iBACJ,MAAM,gBAChB;;IAEL,QAAQ;;;;;;;;;;;;;iBAwCK,iCAAA;;aAEJ,4BAA4B;;;;;;;;;;;;;;;;;;;;;;;iBA0CxB;aAA8C,0BAA0B;QACjF,iCACG;;IAEP;;;;;;;;;;;;;;;;;;;iBA+Ca,2BAAA,UAAqC;;;;;;;;;;;;;;iBA4CrC,4BAAA,CAAA,GAAgC"}

package/dist/correlation.d.ts

@@ -0,0 +1,238 @@
+//#region src/correlation.d.ts
+/**
+ * logixia — Microservices Correlation ID Propagation
+ *
+ * Provides zero-boilerplate correlation ID generation and propagation for
+ * distributed systems. A single correlation ID travels through every service
+ * in a request fan-out, making it trivial to join logs across services.
+ *
+ * Features:
+ *  - UUID v4 correlation ID generation (via `crypto.randomUUID()`)
+ *  - Express / Fastify / NestJS incoming-request middleware
+ *  - `correlationFetch()` — wraps global `fetch`, auto-injects `X-Correlation-ID`
+ *  - `createCorrelationAxiosInterceptor()` — axios request interceptor
+ *  - `childFromRequest(req, logger)` — child logger with all request identifiers
+ *  - Kafka / SQS / RabbitMQ message context helpers
+ *  - Integration with `LogixiaContext` (AsyncLocalStorage) so every `logger.info()`
+ *    call automatically includes the correlationId without per-call passing.
+ *
+ * @example Express middleware
+ * ```ts
+ * import { correlationMiddleware } from 'logixia/correlation';
+ * import { logger } from 'logixia';
+ *
+ * app.use(correlationMiddleware());
+ *
+ * app.get('/orders', (req, res) => {
+ *   // correlationId is automatically in every log inside this request
+ *   logger.info('Listing orders');
+ *   res.json({ ok: true });
+ * });
+ * ```
+ *
+ * @example Outbound fetch with correlation
+ * ```ts
+ * import { correlationFetch } from 'logixia/correlation';
+ *
+ * // Reads correlationId from current LogixiaContext and injects it as header
+ * const data = await correlationFetch('https://payments.internal/charge', {
+ *   method: 'POST',
+ *   body: JSON.stringify({ amount: 100 }),
+ * });
+ * ```
+ *
+ * @example Manual correlation context
+ * ```ts
+ * import { withCorrelationId } from 'logixia/correlation';
+ *
+ * await withCorrelationId('trace-abc-123', async () => {
+ *   // All logs and outbound fetch calls in here carry 'trace-abc-123'
+ *   await processOrder();
+ * });
+ * ```
+ */
+/** Fields injected into the log context by the correlation middleware. */
+interface CorrelationContext {
+  correlationId: string;
+  traceId?: string;
+  /** Service that originated the request (from `X-Origin-Service` header). */
+  originService?: string;
+  /** Index signature so CorrelationContext is assignable to LogContext. */
+  [key: string]: unknown;
+}
+interface CorrelationMiddlewareOptions {
+  /**
+   * HTTP header to read/write the correlation ID from/to.
+   * @default 'x-correlation-id'
+   */
+  header?: string;
+  /**
+   * HTTP header for the originating service name.
+   * @default 'x-origin-service'
+   */
+  originServiceHeader?: string;
+  /**
+   * Function to generate a new correlation ID when none is present in the request.
+   * @default () => crypto.randomUUID()
+   */
+  generate?: () => string;
+  /**
+   * When `true`, the response will include the correlation ID header so
+   * clients can log it client-side.
+   * @default true
+   */
+  setResponseHeader?: boolean;
+}
+/**
+ * Generate a new correlation ID using `crypto.randomUUID()` (available in
+ * Node.js 14.17+, all modern browsers, and Edge runtimes).
+ *
+ * When the Web Crypto global is unavailable (e.g. Node 18 without
+ * `--experimental-global-webcrypto`), fall back to `node:crypto`'s
+ * `randomUUID`, which returns a proper UUID v4 — matching the shape this
+ * function's JSDoc and README promise. `logixia/correlation` is Node-only
+ * (it builds on `AsyncLocalStorage`), so importing `node:crypto` is safe here.
+ */
+declare function generateCorrelationId(): string;
+/**
+ * Return the correlation ID from the current `LogixiaContext`, or `undefined`
+ * when called outside any context scope.
+ */
+declare function getCurrentCorrelationId(): string | undefined;
+/**
+ * Run `callback` inside a correlation context scope.
+ *
+ * If a correlation ID is not provided, a new UUID is generated.
+ *
+ * @example
+ * ```ts
+ * await withCorrelationId('cid-abc', async () => {
+ *   logger.info('Processing message'); // → { correlationId: 'cid-abc', ... }
+ *   await callDownstream();            // correlationFetch() picks up cid-abc
+ * });
+ * ```
+ */
+declare function withCorrelationId<T>(correlationId: string | undefined, callback: () => T): T;
+/**
+ * Express-compatible middleware that:
+ * 1. Reads `X-Correlation-ID` from the incoming request (or generates a new one)
+ * 2. Wraps the request in a `LogixiaContext` so all loggers in the handler
+ *    automatically include `correlationId`
+ * 3. Writes the correlation ID back to the response header (opt-out via options)
+ *
+ * @example
+ * ```ts
+ * import { correlationMiddleware } from 'logixia/correlation';
+ * app.use(correlationMiddleware());
+ * ```
+ */
+declare function correlationMiddleware(options?: CorrelationMiddlewareOptions): (req: Record<string, unknown>, res: Record<string, unknown>, next: () => void) => void;
+/**
+ * Fastify `onRequest` lifecycle hook — same functionality as `correlationMiddleware`
+ * but adapted to Fastify's hook API.
+ *
+ * @example
+ * ```ts
+ * import { correlationFastifyHook } from 'logixia/correlation';
+ * fastify.addHook('onRequest', correlationFastifyHook());
+ * ```
+ */
+declare function correlationFastifyHook(options?: CorrelationMiddlewareOptions): (request: Record<string, unknown>, reply: Record<string, unknown>, done: () => void) => void;
+/**
+ * A drop-in replacement for `fetch` that automatically injects the current
+ * `correlationId` from `LogixiaContext` as an `X-Correlation-ID` request header.
+ *
+ * Falls back to the global `fetch` when no correlation context is active.
+ *
+ * @example
+ * ```ts
+ * import { correlationFetch } from 'logixia/correlation';
+ *
+ * // Inside a request handler with correlationMiddleware active:
+ * const response = await correlationFetch('https://payments.internal/v1/charge', {
+ *   method: 'POST',
+ *   body: JSON.stringify({ amount: 100 }),
+ * });
+ * ```
+ */
+declare function correlationFetch(input: string | URL | Request, init?: RequestInit, options?: {
+  header?: string;
+}): Promise<Response>;
+/**
+ * Returns an axios request interceptor that automatically injects the current
+ * correlation ID into outgoing axios requests.
+ *
+ * @example
+ * ```ts
+ * import axios from 'axios';
+ * import { createCorrelationAxiosInterceptor } from 'logixia/correlation';
+ *
+ * axios.interceptors.request.use(createCorrelationAxiosInterceptor());
+ * ```
+ */
+declare function createCorrelationAxiosInterceptor(options?: {
+  header?: string;
+}): (config: Record<string, unknown>) => Record<string, unknown>;
+/**
+ * Create a child logger enriched with all correlation-relevant identifiers
+ * extracted from the incoming HTTP request.
+ *
+ * The child logger's every call automatically includes:
+ * `correlationId`, `requestId`, `method`, `url`, `userAgent`, `ip`
+ *
+ * @example
+ * ```ts
+ * import { childFromRequest } from 'logixia/correlation';
+ * import { logger } from 'logixia';
+ *
+ * app.use((req, res, next) => {
+ *   req.logger = childFromRequest(req, logger);
+ *   next();
+ * });
+ *
+ * app.get('/orders', (req, res) => {
+ *   req.logger.info('Listing orders');  // → correlationId, requestId, method, url ...
+ * });
+ * ```
+ */
+declare function childFromRequest<TLogger extends {
+  child(ctx: Record<string, unknown>): TLogger;
+}>(req: Record<string, unknown>, logger: TLogger, options?: {
+  correlationHeader?: string;
+}): TLogger;
+/**
+ * Extract a correlation context from a Kafka / RabbitMQ / SQS message object.
+ *
+ * Looks for `correlationId`, `correlation_id`, or `x-correlation-id` in
+ * `message.headers` (Kafka) or `message.MessageAttributes` (SQS).
+ *
+ * @example Kafka consumer
+ * ```ts
+ * import { extractMessageCorrelationId, withCorrelationId } from 'logixia/correlation';
+ *
+ * consumer.run({
+ *   eachMessage: async ({ message }) => {
+ *     const correlationId = extractMessageCorrelationId(message);
+ *     await withCorrelationId(correlationId, () => processMessage(message));
+ *   },
+ * });
+ * ```
+ */
+declare function extractMessageCorrelationId(message: Record<string, unknown>): string | undefined;
+/**
+ * Build Kafka message headers containing the current correlation context.
+ *
+ * @example
+ * ```ts
+ * import { buildKafkaCorrelationHeaders } from 'logixia/correlation';
+ *
+ * await producer.send({
+ *   topic: 'orders',
+ *   messages: [{ value: JSON.stringify(order), headers: buildKafkaCorrelationHeaders() }],
+ * });
+ * ```
+ */
+declare function buildKafkaCorrelationHeaders(): Record<string, string>;
+//#endregion
+export { CorrelationContext, CorrelationMiddlewareOptions, buildKafkaCorrelationHeaders, childFromRequest, correlationFastifyHook, correlationFetch, correlationMiddleware, createCorrelationAxiosInterceptor, extractMessageCorrelationId, generateCorrelationId, getCurrentCorrelationId, withCorrelationId };
+//# sourceMappingURL=correlation.d.ts.map

package/dist/correlation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"correlation.d.ts","names":[],"sources":["../src/correlation.ts"],"sourcesContent":[],"mappings":";;AA4DA;AASA;AAoCA;AA2BA;AAkBA;AAoBA;;;;;AA+CA;;;;;AAsDA;;;;;;;AA4CA;AA4CA;;;;;;;AAmDA;AA4CA;;;;;;;;;;;;;;;;;;;;;UA1YiB,kBAAA;;;;;;;;UASA,4BAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAoCD,qBAAA,CAAA;;;;;iBA2BA,uBAAA,CAAA;;;;;;;;;;;;;;iBAkBA,wEAAwE,IAAI;;;;;;;;;;;;;;iBAoB5E,qBAAA,WAA+B,qCAStC,8BACA;;;;;;;;;;;iBAqCO,sBAAA,WAAgC,yCASnC,gCACF;;;;;;;;;;;;;;;;;;iBA4CW,gBAAA,iBACJ,MAAM,gBAChB;;IAEL,QAAQ;;;;;;;;;;;;;iBAwCK,iCAAA;;aAEJ,4BAA4B;;;;;;;;;;;;;;;;;;;;;;;iBA0CxB;aAA8C,0BAA0B;QACjF,iCACG;;IAEP;;;;;;;;;;;;;;;;;;;iBA+Ca,2BAAA,UAAqC;;;;;;;;;;;;;;iBA4CrC,4BAAA,CAAA,GAAgC"}