core-services-sdk 1.3.56 → 1.3.59

package/.claude/settings.local.json

@@ -0,0 +1,22 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(npm test:*)",
+      "Bash(docker rm:*)",
+      "Bash(docker run:*)",
+      "Bash(mongosh:*)",
+      "Bash(for:*)",
+      "Bash(do if mongosh --port 27099 --eval \"db.runCommand({ ping: 1 })\")",
+      "Bash(then echo \"Connected after $i attempts\")",
+      "Bash(break)",
+      "Bash(fi)",
+      "Bash(echo:*)",
+      "Bash(done)",
+      "Bash(docker logs:*)",
+      "Bash(docker system:*)",
+      "Bash(docker volume prune:*)",
+      "Bash(docker image prune:*)",
+      "Bash(docker builder prune:*)"
+    ]
+  }
+}

package/.prettierrc.json

@@ -4,7 +4,6 @@
   "endOfLine": "lf",
   "requirePragma": false,
   "insertPragma": false,
-  "jsxBracketSameLine": false,
   "jsxSingleQuote": true,
   "printWidth": 80,
   "quoteProps": "consistent",

package/package.json

@@ -1,15 +1,17 @@
 {
   "name": "core-services-sdk",
-  "version": "1.3.56",
+  "version": "1.3.59",
   "main": "src/index.js",
   "type": "module",
   "types": "types/index.d.ts",
   "scripts": {
     "lint": "eslint .",
     "lint:fix": "eslint . --fix",
-    "test": "vitest run --coverage",
     "format": "prettier --write .",
+    "test": "vitest run --coverage",
+    "check-format": "prettier --check .",
     "bump": "node ./scripts/bump-version.js",
+    "check": "npm run lint && npm run check-format && npm run test",
     "build:types": "tsc --project tsconfig.json && prettier --write ."
   },
   "repository": {

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/mongodb/index.js

@@ -3,3 +3,4 @@ export * from './paginate.js'
 export * from './dsl-to-mongo.js'
 export * from './initialize-mongodb.js'
 export * from './validate-mongo-uri.js'
+export { paginate as mongoPaginate } from './paginate.js'

package/src/postgresql/index.js

@@ -1,3 +1,4 @@
+export * from './paginate.js'
 export * from './connect-to-pg.js'
 export * from './validate-schema.js'
 export * from './start-stop-postgres-docker.js'

package/src/postgresql/paginate.js

@@ -0,0 +1,61 @@
+import { toSnakeCase } from '../core/case-mapper.js'
+import { normalizeNumberOrDefault } from '../core/normalize-premitives-types-or-default.js'
+
+/**
+ * Generic pagination utility.
+ *
+ * @async
+ * @param {Object} params
+ * @param {Object} params.db
+ * @param {string} params.tableName
+ * @param {number} [params.page=1]
+ * @param {number} [params.limit=10]
+ * @param {Object} [params.filter={}]
+ * @param {Object} [params.orderBy]
+ * @param {string} params.orderBy.column
+ * @param {'asc'|'desc'} [params.orderBy.direction='asc']
+ * @returns {Promise<{
+ *   list: any[],
+ *   totalCount: number,
+ *   totalPages: number,
+ *   currentPage: number,
+ *   hasNext: boolean,
+ *   hasPrevious: boolean
+ * }>}
+ */
+
+export const sqlPaginate = async ({
+  db,
+  mapRow,
+  orderBy,
+  page = 1,
+  limit = 10,
+  tableName,
+  filter = {},
+} = {}) => {
+  const offset = (page - 1) * limit
+
+  const query = orderBy?.column
+    ? db(tableName)
+        .select('*')
+        .where(toSnakeCase(filter))
+        .orderBy(orderBy.column, orderBy.direction || 'asc')
+    : db(tableName).select('*').where(toSnakeCase(filter))
+
+  const [rows, countResult] = await Promise.all([
+    query.limit(limit).offset(offset),
+    db(tableName).where(toSnakeCase(filter)).count('* as count').first(),
+  ])
+
+  const totalCount = normalizeNumberOrDefault(countResult?.count || 0)
+  const totalPages = Math.ceil(totalCount / limit)
+
+  return {
+    list: mapRow ? rows.map(mapRow) : rows,
+    totalCount,
+    totalPages,
+    currentPage: page,
+    hasPrevious: page > 1,
+    hasNext: page < totalPages,
+  }
+}

package/src/postgresql/start-stop-postgres-docker.js

@@ -124,7 +124,7 @@ export function isPostgresReady(containerName, user, db) {
 export function waitForPostgres(containerName, user, db) {
   console.log(`[PgTest] Waiting for PostgreSQL to be ready...`)
 
-  const maxRetries = 20
+  const maxRetries = 60
   let retries = 0
   let ready = false
 

package/src/rabbit-mq/index.js

@@ -1 +1,2 @@
 export * from './rabbit-mq.js'
+export * from './start-stop-rabbitmq.js'

package/src/rabbit-mq/rabbit-mq.js

@@ -89,17 +89,97 @@ const parseMessage = (msgInfo) => {
 }
 
 /**
- * Subscribes to a queue to receive messages.
+ * Creates an unsubscribe function for a RabbitMQ consumer.
+ *
+ * This is a higher-order function that captures the RabbitMQ channel,
+ * consumerTag, and logger in a closure, and returns an async function
+ * that cancels the consumer when invoked.
+ *
+ * The returned function is idempotent and safe to call multiple times.
+ * If the channel or consumer is already closed, the call is silently ignored.
+ *
+ * Usage:
+ * const unsubscribe = createUnsubscribe({ channel, consumerTag, logger })
+ * await unsubscribe()
+ *
+ * @param {Object} params
+ * @param {import('amqplib').Channel} params.channel
+ *   The RabbitMQ channel on which the consumer was created.
+ *
+ * @param {string} params.consumerTag
+ *   The consumer tag returned by `channel.consume`, uniquely identifying
+ *   the active consumer within the channel.
+ *
+ * @param {import('pino').Logger} params.logger
+ *   Base logger instance used to create a child logger for unsubscribe logs.
+ *
+ * @returns {() => Promise<void>}
+ *   An async function that cancels this specific RabbitMQ consumer.
+ *
+ * @throws {Error}
+ *   Throws for unexpected errors during consumer cancellation.
+ *   Errors caused by an already closed channel are silently ignored.
+ */
+const unsubscribe =
+  ({ channel, consumerTag, logger }) =>
+  async () => {
+    if (!channel || channel.closed) {
+      return
+    }
+
+    const t0 = Date.now()
+    const child = logger.child({ op: 'unsubscribe', consumerTag })
+
+    try {
+      child.debug('start')
+      await channel.cancel(consumerTag)
+      child.info({ event: 'ok', ms: Date.now() - t0 })
+    } catch (err) {
+      if (err?.message?.includes('Channel closed')) {
+        child.debug({
+          event: 'already-closed',
+          reason: 'channel-already-closed',
+        })
+        return
+      }
+
+      child.error(err, {
+        event: 'error',
+        ms: Date.now() - t0,
+      })
+      throw err
+    }
+  }
+
+/**
+ * Subscribes to a RabbitMQ queue and returns an unsubscribe function
+ * that cancels this specific consumer.
+ *
+ * Each call creates an independent consumer with its own consumerTag.
+ * Calling the returned unsubscribe function affects only this consumer
+ * and does not impact other consumers or services.
  *
  * @param {Object} options
- * @param {import('amqplib').Channel} options.channel - RabbitMQ channel
- * @param {string} options.queue - Queue name to subscribe to
- * @param {(data: any, correlationId?: string) => Promise<void>} options.onReceive - Async handler
- * @param {import('pino').Logger} options.log - Base logger
- * @param {boolean} [options.nackOnError=false] - Whether to nack the message on error (default: false)
- * @param {number} [options.prefetch=1] - Max unacked messages per consumer (default: 1)
+ * @param {import('amqplib').Channel} options.channel
+ *   RabbitMQ channel used to create the consumer.
+ *
+ * @param {string} options.queue
+ *   Queue name to subscribe to.
  *
- * @returns {Promise<string>} Returns the consumer tag for later cancellation
+ * @param {(data: any, correlationId?: string) => Promise<void>} options.onReceive
+ *   Async handler invoked for each received message payload.
+ *
+ * @param {import('pino').Logger} options.log
+ *   Base logger instance.
+ *
+ * @param {boolean} [options.nackOnError=false]
+ *   Whether to nack the message on handler error instead of ack.
+ *
+ * @param {number} [options.prefetch=1]
+ *   Maximum number of unacknowledged messages for this consumer.
+ *
+ * @returns {Promise<() => Promise<void>>}
+ *   Resolves to an unsubscribe function that cancels this specific consumer.
  */
 export const subscribeToQueue = async ({
   log,
@@ -113,14 +193,17 @@ export const subscribeToQueue = async ({
 
   try {
     await channel.assertQueue(queue, { durable: true })
-    !!prefetch && (await channel.prefetch(prefetch))
+
+    if (prefetch) {
+      await channel.prefetch(prefetch)
+    }
 
     const { consumerTag } = await channel.consume(queue, async (msgInfo) => {
       if (!msgInfo) {
         return
       }
-      const t0 = Date.now()
 
+      const t0 = Date.now()
       const { msgId, data, correlationId } = parseMessage(msgInfo)
       const child = logger.child({ msgId, correlationId })
 
@@ -131,28 +214,26 @@ export const subscribeToQueue = async ({
         await onReceive(data, correlationId)
         channel.ack(msgInfo)
 
-        child.info({
-          event: 'ok',
-          ms: Date.now() - t0,
-        })
-        return
+        child.info({ event: 'ok', ms: Date.now() - t0 })
       } catch (err) {
-        nackOnError ? channel.nack(msgInfo) : channel.ack(msgInfo)
+        if (nackOnError) {
+          channel.nack(msgInfo)
+        } else {
+          channel.ack(msgInfo)
+        }
 
         child.error(err, {
           event: 'error',
           ms: Date.now() - t0,
         })
-        return
       }
     })
 
     logger.debug({ consumerTag }, 'consumer-started')
-    return consumerTag
+
+    return unsubscribe({ channel, consumerTag, logger })
   } catch (err) {
-    logger.error(err, {
-      event: 'error',
-    })
+    logger.error(err, { event: 'error' })
     throw err
   }
 }

package/src/rabbit-mq/start-stop-rabbitmq.js

@@ -0,0 +1,152 @@
+import { execSync } from 'node:child_process'
+
+/**
+ * Starts a RabbitMQ Docker container for testing purposes.
+ *
+ * If a container with the same name already exists, it will be removed first.
+ * The container is started with the RabbitMQ Management plugin enabled and
+ * waits until the health check reports the container as healthy.
+ *
+ * @param {Object} options
+ * @param {string} options.containerName
+ *   Docker container name.
+ *
+ * @param {number} options.amqpPort
+ *   Host port mapped to RabbitMQ AMQP port (5672).
+ *
+ * @param {number} options.uiPort
+ *   Host port mapped to RabbitMQ Management UI port (15672).
+ *
+ * @param {string} options.user
+ *   Default RabbitMQ username.
+ *
+ * @param {string} options.pass
+ *   Default RabbitMQ password.
+ *
+ * @returns {void}
+ *
+ * @throws {Error}
+ *   Throws if the RabbitMQ container fails to become healthy within the timeout.
+ */
+export function startRabbit({ containerName, ...rest }) {
+  console.log(`[RabbitTest] Starting RabbitMQ...`)
+
+  try {
+    execSync(`docker rm -f ${containerName}`, { stdio: 'ignore' })
+  } catch {}
+
+  execSync(
+    `docker run -d \
+        --name ${containerName} \
+        -e RABBITMQ_DEFAULT_USER=${rest.user} \
+        -e RABBITMQ_DEFAULT_PASS=${rest.pass} \
+        -p ${rest.amqpPort}:5672 \
+        -p ${rest.uiPort}:15672 \
+        --health-cmd="rabbitmq-diagnostics -q ping" \
+        --health-interval=5s \
+        --health-timeout=5s \
+        --health-retries=10 \
+        rabbitmq:3-management`,
+    { stdio: 'inherit' },
+  )
+
+  waitForRabbitHealthy(containerName)
+}
+
+/**
+ * Stops and removes a RabbitMQ Docker container.
+ *
+ * This function is safe to call even if the container does not exist.
+ *
+ * @param {string} [containerName='rabbit-test']
+ *   Docker container name.
+ *
+ * @returns {void}
+ */
+export function stopRabbit(containerName = 'rabbit-test') {
+  console.log(`[RabbitTest] Stopping RabbitMQ...`)
+  try {
+    execSync(`docker rm -f ${containerName}`, { stdio: 'ignore' })
+  } catch (error) {
+    console.error(`[RabbitTest] Failed to stop RabbitMQ: ${error}`)
+  }
+}
+
+/**
+ * Waits until the RabbitMQ Docker container reports a healthy status.
+ *
+ * Polls the container health status using `docker inspect` and retries
+ * for a fixed amount of time before failing.
+ *
+ * @param {string} containerName
+ *   Docker container name.
+ *
+ * @returns {void}
+ *
+ * @throws {Error}
+ *   Throws if the container does not become healthy within the timeout.
+ */
+function waitForRabbitHealthy(containerName) {
+  console.log(`[RabbitTest] Waiting for RabbitMQ to be healthy...`)
+
+  const maxRetries = 60
+  let retries = 0
+
+  while (retries < maxRetries) {
+    try {
+      const output = execSync(
+        `docker inspect --format='{{.State.Health.Status}}' ${containerName}`,
+        { encoding: 'utf8' },
+      ).trim()
+
+      if (output === 'healthy') {
+        console.log(`[RabbitTest] RabbitMQ is ready.`)
+        return
+      }
+
+      if (retries % 10 === 0 && retries > 0) {
+        console.log(
+          `[RabbitTest] Still waiting... Status: ${output} (${retries}/${maxRetries})`,
+        )
+      }
+    } catch {
+      if (retries % 10 === 0 && retries > 0) {
+        console.log(
+          `[RabbitTest] Container not ready yet (${retries}/${maxRetries})`,
+        )
+      }
+    }
+
+    retries++
+    execSync(`sleep 1`)
+  }
+
+  console.log('[RabbitTest] Failed to start. Container logs:')
+  try {
+    execSync(`docker logs --tail 30 ${containerName}`, { stdio: 'inherit' })
+  } catch {}
+
+  throw new Error(
+    `[RabbitTest] RabbitMQ failed to become healthy within ${maxRetries} seconds`,
+  )
+}
+
+/**
+ * Builds a RabbitMQ AMQP connection URI for local testing.
+ *
+ * @param {Object} options
+ * @param {string} options.user
+ *   RabbitMQ username.
+ *
+ * @param {string} options.pass
+ *   RabbitMQ password.
+ *
+ * @param {number} options.port
+ *   Host port mapped to RabbitMQ AMQP port.
+ *
+ * @returns {string}
+ *   RabbitMQ AMQP connection URI.
+ */
+export function buildRabbitUri({ user, pass, port }) {
+  return `amqp://${user}:${pass}@localhost:${port}`
+}

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() || {}
-  },
+  }
 }