core-services-sdk 1.3.56 → 1.3.57

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "core-services-sdk",
-  "version": "1.3.56",
+  "version": "1.3.57",
   "main": "src/index.js",
   "type": "module",
   "types": "types/index.d.ts",

package/src/http/helpers/create-request-logger.js

@@ -0,0 +1,38 @@
+import { Context } from '../../util/context.js'
+/**
+ * Creates a request-scoped logger enriched with contextual metadata.
+ *
+ * The logger is derived from the provided Pino logger and augmented with:
+ * - correlationId (from Context)
+ * - client IP (from Context)
+ * - user agent (from Context)
+ * - operation identifier in the form: "<METHOD> <URL>"
+ *
+ * Intended to be used per incoming Fastify request, typically at the beginning
+ * of a request lifecycle, so all subsequent logs automatically include
+ * request-specific context.
+ *
+ * @param {import('fastify').FastifyRequest} request
+ *   The Fastify request object.
+ *
+ * @param {import('pino').Logger} log
+ *   Base Pino logger instance.
+ *
+ * @returns {import('pino').Logger}
+ *   A child Pino logger enriched with request and context metadata.
+ *
+ * @example
+ * const requestLog = createRequestLogger(request, log, Context)
+ * requestLog.info('Handling request')
+ */
+
+export const createRequestLogger = (request, log) => {
+  const { correlationId, ip, userAgent } = Context?.all() || {}
+
+  return log.child({
+    ip,
+    userAgent,
+    correlationId,
+    op: `${request.method} ${request?.url || request?.routeOptions?.url || request.raw.url}`,
+  })
+}

package/src/http/index.js

@@ -2,3 +2,4 @@ export * from './http.js'
 export * from './HttpError.js'
 export * from './http-method.js'
 export * from './responseType.js'
+export * from './helpers/create-request-logger.js'

package/src/util/context.js

@@ -3,79 +3,111 @@ import { AsyncLocalStorage } from 'node:async_hooks'
 const als = new AsyncLocalStorage()
 
 /**
- * Context utility built on top of Node.js AsyncLocalStorage.
- * Provides a per-request (or per-async-chain) storage mechanism that
- * allows passing metadata (like correlation IDs, user info, tenant ID, etc.)
- * without explicitly threading it through every function call.
+ * Represents the data stored in the async context for a single execution flow.
+ *
+ * This object is propagated automatically across async boundaries
+ * using Node.js AsyncLocalStorage.
+ *
+ * It defines the contract between producers (who set values)
+ * and consumers (who read values) of the context.
+ *
+ * @typedef {Object} ContextStore
+ *
+ * @property {string} [correlationId] - Unique identifier for request or operation tracing.
+ * @property {string} [ip] - Client IP address.
+ * @property {string} [userAgent] - Client user agent string.
+ * @property {string} [tenantId] - Active tenant identifier.
+ * @property {string} [userId] - Authenticated user identifier.
  */
 
-export const Context = {
+/**
+ * Async execution context manager built on top of Node.js AsyncLocalStorage.
+ *
+ * This class provides a thin, static API for storing and accessing
+ * request-scoped (or async-chain-scoped) metadata such as correlation IDs,
+ * user information, tenant identifiers, and similar data.
+ *
+ * The context is bound to the current async execution chain using
+ * AsyncLocalStorage and is automatically propagated across `await` boundaries.
+ *
+ * This class is intentionally static and acts as a singleton wrapper
+ * around AsyncLocalStorage.
+ */
+export class Context {
   /**
-   * Run a callback within a given context store.
-   * Everything `await`ed or invoked inside this callback will have access
-   * to the provided store via {@link Context.get}, {@link Context.set}, or {@link Context.all}.
+   * Run a callback within a given async context store.
+   *
+   * All asynchronous operations spawned inside the callback
+   * will have access to the provided store via {@link Context.get},
+   * {@link Context.set}, or {@link Context.all}.
    *
    * @template T
-   * @param {Record<string, any>} store
+   * @param {ContextStore} store - Initial context store for this execution.
    * @param {() => T} callback - Function to execute inside the context.
    * @returns {T} The return value of the callback (sync or async).
    *
    * @example
    * Context.run(
-   *   { correlationId: 'abc123' },
+   *   { correlationId: 'abc123', userId: 'usr_1' },
    *   async () => {
    *     console.log(Context.get('correlationId')) // "abc123"
    *   }
    * )
    */
-  run(store, callback) {
+  static run(store, callback) {
     return als.run(store, callback)
-  },
+  }
 
   /**
    * Retrieve a single value from the current async context store.
    *
-   * @template T
-   * @param {string} key - The key of the value to retrieve.
-   * @returns {T|undefined} The stored value, or `undefined` if no store exists or key not found.
+   * If called outside of an active {@link Context.run},
+   * this method returns `undefined`.
+   *
+   * @template {keyof ContextStore} K
+   * @param {K} key - Context property name.
+   * @returns {ContextStore[K] | undefined} The stored value, if present.
    *
    * @example
-   * const userId = Context.get('userId')
+   * const tenantId = Context.get('tenantId')
    */
-  get(key) {
+  static get(key) {
     const store = als.getStore()
     return store?.[key]
-  },
+  }
 
   /**
-   * Set a single key-value pair in the current async context store.
-   * If there is no active store (i.e. outside of a {@link Context.run}),
-   * this function does nothing.
+   * Set a single key-value pair on the current async context store.
+   *
+   * If called outside of an active {@link Context.run},
+   * this method is a no-op.
    *
-   * @param {string} key - The key under which to store the value.
-   * @param {any} value - The value to store.
+   * @template {keyof ContextStore} K
+   * @param {K} key - Context property name.
+   * @param {ContextStore[K]} value - Value to store.
    *
    * @example
    * Context.set('tenantId', 'tnt_1234')
    */
-  set(key, value) {
+  static set(key, value) {
     const store = als.getStore()
     if (store) {
       store[key] = value
     }
-  },
+  }
 
   /**
-   * Get the entire store object for the current async context.
+   * Get the full context store for the current async execution.
+   *
+   * If no context is active, an empty object is returned.
    *
-   * @returns {Record<string, any>} The current store object,
-   * or an empty object if no store exists.
+   * @returns {ContextStore}
    *
    * @example
-   * const all = Context.all()
-   * console.log(all) // { correlationId: 'abc123', userId: 'usr_789' }
+   * const ctx = Context.all()
+   * console.log(ctx.correlationId)
    */
-  all() {
+  static all() {
     return als.getStore() || {}
-  },
+  }
 }

package/tests/http/helpers/create-request-logger.test.js

@@ -0,0 +1,113 @@
+// @ts-nocheck
+import { describe, it, expect, vi, beforeEach } from 'vitest'
+
+import { createRequestLogger } from '../../../src/http/helpers/create-request-logger.js'
+import { Context } from '../../../src/util/context.js'
+//@ts-ignore
+describe('createRequestLogger', () => {
+  let baseLogger
+
+  beforeEach(() => {
+    baseLogger = {
+      child: vi.fn(),
+    }
+  })
+
+  it('creates a child logger with context and request data', () => {
+    const request = {
+      method: 'GET',
+      url: '/test',
+      raw: { url: '/raw-test' },
+    }
+
+    const childLogger = {}
+    baseLogger.child.mockReturnValue(childLogger)
+
+    Context.run(
+      {
+        correlationId: 'corr-123',
+        ip: '127.0.0.1',
+        userAgent: 'vitest-agent',
+      },
+      () => {
+        const result = createRequestLogger(request, baseLogger)
+
+        expect(baseLogger.child).toHaveBeenCalledOnce()
+        expect(baseLogger.child).toHaveBeenCalledWith({
+          ip: '127.0.0.1',
+          userAgent: 'vitest-agent',
+          correlationId: 'corr-123',
+          op: 'GET /test',
+        })
+
+        expect(result).toBe(childLogger)
+      },
+    )
+  })
+
+  it('falls back to routeOptions.url when request.url is missing', () => {
+    const request = {
+      method: 'POST',
+      routeOptions: { url: '/route-url' },
+      raw: { url: '/raw-url' },
+    }
+
+    Context.run(
+      {
+        correlationId: 'corr-456',
+        ip: '10.0.0.1',
+        userAgent: 'agent-x',
+      },
+      () => {
+        createRequestLogger(request, baseLogger)
+
+        expect(baseLogger.child).toHaveBeenCalledWith(
+          expect.objectContaining({
+            op: 'POST /route-url',
+          }),
+        )
+      },
+    )
+  })
+
+  it('falls back to request.raw.url when neither url nor routeOptions.url exist', () => {
+    const request = {
+      method: 'PUT',
+      raw: { url: '/raw-only' },
+    }
+
+    Context.run(
+      {
+        correlationId: 'corr-789',
+        ip: '192.168.1.1',
+        userAgent: 'agent-y',
+      },
+      () => {
+        createRequestLogger(request, baseLogger)
+
+        expect(baseLogger.child).toHaveBeenCalledWith(
+          expect.objectContaining({
+            op: 'PUT /raw-only',
+          }),
+        )
+      },
+    )
+  })
+
+  it('handles missing context gracefully when no Context is active', () => {
+    const request = {
+      method: 'DELETE',
+      url: '/delete',
+      raw: { url: '/delete' },
+    }
+
+    createRequestLogger(request, baseLogger)
+
+    expect(baseLogger.child).toHaveBeenCalledWith({
+      ip: undefined,
+      userAgent: undefined,
+      correlationId: undefined,
+      op: 'DELETE /delete',
+    })
+  })
+})

package/types/http/helpers/create-request-logger.d.ts

@@ -0,0 +1,4 @@
+export function createRequestLogger(
+  request: import('fastify').FastifyRequest,
+  log: import('pino').Logger,
+): import('pino').Logger

package/types/http/index.d.ts

@@ -2,3 +2,4 @@ export * from './http.js'
 export * from './HttpError.js'
 export * from './http-method.js'
 export * from './responseType.js'
+export * from './helpers/create-request-logger.js'

package/types/util/context.d.ts

@@ -1,55 +1,124 @@
-export namespace Context {
+/**
+ * Represents the data stored in the async context for a single execution flow.
+ *
+ * This object is propagated automatically across async boundaries
+ * using Node.js AsyncLocalStorage.
+ *
+ * It defines the contract between producers (who set values)
+ * and consumers (who read values) of the context.
+ *
+ * @typedef {Object} ContextStore
+ *
+ * @property {string} [correlationId] - Unique identifier for request or operation tracing.
+ * @property {string} [ip] - Client IP address.
+ * @property {string} [userAgent] - Client user agent string.
+ * @property {string} [tenantId] - Active tenant identifier.
+ * @property {string} [userId] - Authenticated user identifier.
+ */
+/**
+ * Async execution context manager built on top of Node.js AsyncLocalStorage.
+ *
+ * This class provides a thin, static API for storing and accessing
+ * request-scoped (or async-chain-scoped) metadata such as correlation IDs,
+ * user information, tenant identifiers, and similar data.
+ *
+ * The context is bound to the current async execution chain using
+ * AsyncLocalStorage and is automatically propagated across `await` boundaries.
+ *
+ * This class is intentionally static and acts as a singleton wrapper
+ * around AsyncLocalStorage.
+ */
+export class Context {
   /**
-   * Run a callback within a given context store.
-   * Everything `await`ed or invoked inside this callback will have access
-   * to the provided store via {@link Context.get}, {@link Context.set}, or {@link Context.all}.
+   * Run a callback within a given async context store.
+   *
+   * All asynchronous operations spawned inside the callback
+   * will have access to the provided store via {@link Context.get},
+   * {@link Context.set}, or {@link Context.all}.
    *
    * @template T
-   * @param {Record<string, any>} store
+   * @param {ContextStore} store - Initial context store for this execution.
    * @param {() => T} callback - Function to execute inside the context.
    * @returns {T} The return value of the callback (sync or async).
    *
    * @example
    * Context.run(
-   *   { correlationId: 'abc123' },
+   *   { correlationId: 'abc123', userId: 'usr_1' },
    *   async () => {
    *     console.log(Context.get('correlationId')) // "abc123"
    *   }
    * )
    */
-  function run<T>(store: Record<string, any>, callback: () => T): T
+  static run<T>(store: ContextStore, callback: () => T): T
   /**
    * Retrieve a single value from the current async context store.
    *
-   * @template T
-   * @param {string} key - The key of the value to retrieve.
-   * @returns {T|undefined} The stored value, or `undefined` if no store exists or key not found.
+   * If called outside of an active {@link Context.run},
+   * this method returns `undefined`.
+   *
+   * @template {keyof ContextStore} K
+   * @param {K} key - Context property name.
+   * @returns {ContextStore[K] | undefined} The stored value, if present.
    *
    * @example
-   * const userId = Context.get('userId')
+   * const tenantId = Context.get('tenantId')
    */
-  function get<T>(key: string): T | undefined
+  static get<K extends keyof ContextStore>(key: K): ContextStore[K] | undefined
   /**
-   * Set a single key-value pair in the current async context store.
-   * If there is no active store (i.e. outside of a {@link Context.run}),
-   * this function does nothing.
+   * Set a single key-value pair on the current async context store.
+   *
+   * If called outside of an active {@link Context.run},
+   * this method is a no-op.
    *
-   * @param {string} key - The key under which to store the value.
-   * @param {any} value - The value to store.
+   * @template {keyof ContextStore} K
+   * @param {K} key - Context property name.
+   * @param {ContextStore[K]} value - Value to store.
    *
    * @example
    * Context.set('tenantId', 'tnt_1234')
    */
-  function set(key: string, value: any): void
+  static set<K extends keyof ContextStore>(key: K, value: ContextStore[K]): void
   /**
-   * Get the entire store object for the current async context.
+   * Get the full context store for the current async execution.
    *
-   * @returns {Record<string, any>} The current store object,
-   * or an empty object if no store exists.
+   * If no context is active, an empty object is returned.
+   *
+   * @returns {ContextStore}
    *
    * @example
-   * const all = Context.all()
-   * console.log(all) // { correlationId: 'abc123', userId: 'usr_789' }
+   * const ctx = Context.all()
+   * console.log(ctx.correlationId)
+   */
+  static all(): ContextStore
+}
+/**
+ * Represents the data stored in the async context for a single execution flow.
+ *
+ * This object is propagated automatically across async boundaries
+ * using Node.js AsyncLocalStorage.
+ *
+ * It defines the contract between producers (who set values)
+ * and consumers (who read values) of the context.
+ */
+export type ContextStore = {
+  /**
+   * - Unique identifier for request or operation tracing.
+   */
+  correlationId?: string
+  /**
+   * - Client IP address.
+   */
+  ip?: string
+  /**
+   * - Client user agent string.
+   */
+  userAgent?: string
+  /**
+   * - Active tenant identifier.
+   */
+  tenantId?: string
+  /**
+   * - Authenticated user identifier.
    */
-  function all(): Record<string, any>
+  userId?: string
 }