core-services-sdk 1.3.57 → 1.3.60

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.57",
+  "version": "1.3.60",
   "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/core/index.js

@@ -4,6 +4,7 @@ export * from './otp-generators.js'
 export * from './sanitize-objects.js'
 export * from './normalize-min-max.js'
 export * from './normalize-to-array.js'
+export * from './parse-json-if-string.js'
 export * from './combine-unique-arrays.js'
 export * from './normalize-phone-number.js'
 export * from './normalize-array-operators.js'

package/src/core/parse-json-if-string.js

@@ -0,0 +1,19 @@
+/**
+ * Parses a value that may be a JSON string or already a parsed object.
+ *
+ * @param {any} value
+ *   The value to parse.
+ *
+ * @returns {any}
+ *   Parsed JSON if value is a string, otherwise the original value.
+ *
+ * @throws {Error}
+ *   Throws if the string is not valid JSON.
+ */
+export const parseJsonIfString = (value) => {
+  if (typeof value === 'string') {
+    return JSON.parse(value)
+  }
+
+  return value
+}

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.
+ *
+ * @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.
  *
- * @returns {Promise<string>} Returns the consumer tag for later cancellation
+ * @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,
@@ -111,16 +191,31 @@ export const subscribeToQueue = async ({
 }) => {
   const logger = log.child({ op: 'subscribeToQueue', queue })
 
+  if (!queue || !queue.trim()) {
+    const message = 'Cannot subscribe to RabbitMQ with an empty queue name'
+    logger.error({ error: message })
+    throw new Error(message)
+  }
+
+  if (typeof onReceive !== 'function') {
+    const message = `Cannot subscribe to queue "${queue}" because onReceive is not a function`
+    logger.error({ error: message })
+    throw new Error(message)
+  }
+
   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 +226,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/tests/core/parse-json-if-string.unit.test.js

@@ -0,0 +1,51 @@
+import { describe, it, expect } from 'vitest'
+
+import { parseJsonIfString } from '../../src/core/parse-json-if-string.js'
+
+describe('parseJsonIfString', () => {
+  it('parses a valid JSON string', () => {
+    const value = '{"a":1,"b":"test"}'
+
+    const result = parseJsonIfString(value)
+
+    expect(result).toEqual({ a: 1, b: 'test' })
+  })
+
+  it('returns an object as-is', () => {
+    const value = { a: 1, b: 'test' }
+
+    const result = parseJsonIfString(value)
+
+    expect(result).toBe(value)
+  })
+
+  it('returns an array as-is', () => {
+    const value = [1, 2, 3]
+
+    const result = parseJsonIfString(value)
+
+    expect(result).toBe(value)
+  })
+
+  it('returns null as-is', () => {
+    const value = null
+
+    const result = parseJsonIfString(value)
+
+    expect(result).toBeNull()
+  })
+
+  it('returns a number as-is', () => {
+    const value = 42
+
+    const result = parseJsonIfString(value)
+
+    expect(result).toBe(42)
+  })
+
+  it('throws when JSON string is invalid', () => {
+    const value = '{"a":1,'
+
+    expect(() => parseJsonIfString(value)).toThrow(SyntaxError)
+  })
+})

package/tests/postgresql/paginate.integration.test.js

@@ -0,0 +1,166 @@
+// @ts-nocheck
+import { describe, it, beforeAll, afterAll, beforeEach, expect } from 'vitest'
+import knex from 'knex'
+
+import {
+  stopPostgres,
+  startPostgres,
+  buildPostgresUri,
+} from '../../src/postgresql/start-stop-postgres-docker.js'
+
+import { sqlPaginate } from '../../src/postgresql/paginate.js'
+
+const PG_OPTIONS = {
+  port: 5443,
+  containerName: 'postgres-paginate-test',
+  user: 'testuser',
+  pass: 'testpass',
+  db: 'testdb',
+}
+
+const DATABASE_URI = buildPostgresUri(PG_OPTIONS)
+
+let db
+
+beforeAll(async () => {
+  startPostgres(PG_OPTIONS)
+
+  db = knex({
+    client: 'pg',
+    connection: DATABASE_URI,
+  })
+
+  await db.schema.createTable('tenants', (table) => {
+    table.uuid('id').primary()
+    table.string('name').notNullable()
+    table.string('type').notNullable()
+    table.timestamp('created_at').notNullable()
+  })
+})
+
+afterAll(async () => {
+  if (db) {
+    await db.destroy()
+  }
+  stopPostgres(PG_OPTIONS.containerName)
+})
+
+beforeEach(async () => {
+  await db('tenants').truncate()
+
+  await db('tenants').insert([
+    {
+      id: '00000000-0000-0000-0000-000000000001',
+      name: 'Tenant A',
+      type: 'business',
+      created_at: new Date('2024-01-01'),
+    },
+    {
+      id: '00000000-0000-0000-0000-000000000002',
+      name: 'Tenant B',
+      type: 'business',
+      created_at: new Date('2024-01-02'),
+    },
+    {
+      id: '00000000-0000-0000-0000-000000000003',
+      name: 'Tenant C',
+      type: 'cpa',
+      created_at: new Date('2024-01-03'),
+    },
+  ])
+})
+
+describe('paginate integration', () => {
+  it('returns first page without ordering guarantees', async () => {
+    const result = await sqlPaginate({
+      db,
+      tableName: 'tenants',
+      page: 1,
+      limit: 2,
+    })
+
+    expect(result.totalCount).toBe(3)
+    expect(result.totalPages).toBe(2)
+    expect(result.currentPage).toBe(1)
+    expect(result.hasPrevious).toBe(false)
+    expect(result.hasNext).toBe(true)
+
+    expect(result.list).toHaveLength(2)
+  })
+
+  it('returns second page without ordering guarantees', async () => {
+    const result = await sqlPaginate({
+      db,
+      tableName: 'tenants',
+      page: 2,
+      limit: 2,
+    })
+
+    expect(result.totalCount).toBe(3)
+    expect(result.totalPages).toBe(2)
+    expect(result.currentPage).toBe(2)
+    expect(result.hasPrevious).toBe(true)
+    expect(result.hasNext).toBe(false)
+
+    expect(result.list).toHaveLength(1)
+  })
+
+  it('applies filters correctly without ordering guarantees', async () => {
+    const result = await sqlPaginate({
+      db,
+      tableName: 'tenants',
+      filter: { type: 'business' },
+      limit: 10,
+    })
+
+    expect(result.totalCount).toBe(2)
+
+    const names = result.list.map((t) => t.name).sort()
+    expect(names).toEqual(['Tenant A', 'Tenant B'])
+  })
+
+  it('supports custom ordering', async () => {
+    const result = await sqlPaginate({
+      db,
+      tableName: 'tenants',
+      orderBy: {
+        column: 'created_at',
+        direction: 'asc',
+      },
+    })
+
+    expect(result.list.map((t) => t.name)).toEqual([
+      'Tenant A',
+      'Tenant B',
+      'Tenant C',
+    ])
+  })
+
+  it('supports row mapping', async () => {
+    const result = await sqlPaginate({
+      db,
+      tableName: 'tenants',
+      mapRow: (row) => ({
+        ...row,
+        mapped: true,
+      }),
+    })
+
+    expect(result.list.length).toBeGreaterThan(0)
+    expect(result.list[0].mapped).toBe(true)
+  })
+
+  it('returns empty list when no records match filter', async () => {
+    const result = await sqlPaginate({
+      db,
+      tableName: 'tenants',
+      filter: { type: 'non-existing' },
+    })
+
+    expect(result.totalCount).toBe(0)
+    expect(result.totalPages).toBe(0)
+    expect(result.list).toEqual([])
+    expect(result.hasNext).toBe(false)
+    expect(result.hasPrevious).toBe(false)
+  })
+})

package/tests/rabbit-mq/rabbit-mq.test.js

@@ -1,69 +1,139 @@
-import { describe, it, expect, beforeAll } from 'vitest'
+import pino from 'pino'
+import { describe, it, beforeAll, afterAll, expect } from 'vitest'
 
-import { initializeQueue, rabbitUriFromEnv } from '../../src/rabbit-mq/index.js'
+import {
+  stopRabbit,
+  startRabbit,
+  buildRabbitUri,
+} from '../../src/rabbit-mq/start-stop-rabbitmq.js'
 
-const sleep = (ms) => new Promise((res) => setTimeout(res, ms))
+import { initializeQueue } from '../../src/rabbit-mq/index.js'
 
-const testLog = {
-  info: () => {},
-  error: console.error,
-  debug: console.debug,
-  child() {
-    return testLog
-  },
-}
+const RABBIT_CONTAINER = 'rabbit-test'
+const AMQP_PORT = 5679
+const UI_PORT = 15679
+const USER = 'test'
+const PASS = 'test'
+const QUEUE = 'integration-test-queue'
 
-describe('RabbitMQ SDK', () => {
-  const testQueue = 'testQueue'
-  const host = 'amqp://botq:botq@0.0.0.0:5672'
-  const testMessage = { text: 'Hello Rabbit' }
+const log = pino({
+  level: 'silent',
+})
+// @ts-ignore
+async function waitForRabbitConnection({ uri, log, timeoutMs = 10000 }) {
+  const start = Date.now()
 
-  let sdk
-  let received = null
+  while (Date.now() - start < timeoutMs) {
+    try {
+      const rabbit = await initializeQueue({ host: uri, log })
+      return rabbit
+    } catch {
+      await sleep(300)
+    }
+  }
+
+  throw new Error('RabbitMQ AMQP endpoint did not become ready in time')
+}
+
+describe('RabbitMQ integration', () => {
+  // @ts-ignore
+  let rabbit
+  // @ts-ignore
+  let unsubscribe
+  // @ts-ignore
+  let receivedMessages
 
   beforeAll(async () => {
-    // @ts-ignore
-    sdk = await initializeQueue({ host, log: testLog })
+    startRabbit({
+      containerName: RABBIT_CONTAINER,
+      amqpPort: AMQP_PORT,
+      uiPort: UI_PORT,
+      user: USER,
+      pass: PASS,
+    })
+
+    const uri = buildRabbitUri({
+      user: USER,
+      pass: PASS,
+      port: AMQP_PORT,
+    })
+
+    rabbit = await waitForRabbitConnection({
+      uri,
+      log,
+    })
+  }, 60_000)
 
-    await sdk.subscribe({
-      queue: testQueue,
+  afterAll(async () => {
+    try {
+      // @ts-ignore
+      if (unsubscribe) {
+        await unsubscribe()
+      }
+      // @ts-ignore
+      if (rabbit) {
+        await rabbit.close()
+      }
+    } finally {
+      stopRabbit(RABBIT_CONTAINER)
+    }
+  })
+
+  it('should publish, consume, unsubscribe, and stop consuming', async () => {
+    receivedMessages = []
+
+    // @ts-ignore
+    unsubscribe = await rabbit.subscribe({
+      queue: QUEUE,
+      // @ts-ignore
       onReceive: async (data) => {
-        received = data
+        receivedMessages.push(data)
       },
     })
-  })
 
-  it('should publish and receive message from queue', async () => {
-    await sdk.publish(testQueue, testMessage)
-    await sleep(300) // let the consumer process the message
-    expect(received).toEqual(testMessage)
-  })
-})
+    // @ts-ignore
+    await rabbit.publish(QUEUE, { step: 1 })
+    await waitFor(() => receivedMessages.length === 1)
 
-describe('rabbitUriFromEnv', () => {
-  it('should build valid amqp URI from env', () => {
-    const env = {
-      RABBIT_PORT: 5672,
-      RABBIT_HOST: '0.0.0.0',
-      RABBIT_USERNAME: 'botq',
-      RABBIT_PASSWORD: 'botq',
-      _RABBIT_HOST: '0.0.0.0',
-      RABBIT_PROTOCOL: 'amqp',
-    }
+    // @ts-ignore
+    expect(receivedMessages).toEqual([{ step: 1 }])
 
-    const uri = rabbitUriFromEnv(env)
-    expect(uri).toBe('amqp://botq:botq@0.0.0.0:5672')
-  })
+    await unsubscribe()
 
-  it('should fallback to amqp when protocol is missing', () => {
-    const env = {
-      RABBIT_HOST: '0.0.0.0',
-      RABBIT_PORT: 5672,
-      RABBIT_USERNAME: 'botq',
-      RABBIT_PASSWORD: 'botq',
-    }
+    // @ts-ignore
+    await rabbit.publish(QUEUE, { step: 2 })
+
+    await sleep(1000)
 
-    const uri = rabbitUriFromEnv(env)
-    expect(uri).toBe('amqp://botq:botq@0.0.0.0:5672')
+    // @ts-ignore
+    expect(receivedMessages).toEqual([{ step: 1 }])
   })
 })
+
+/**
+ * Waits until a condition becomes true or times out.
+ *
+ * @param {() => boolean} predicate
+ * @param {number} timeoutMs
+ */
+async function waitFor(predicate, timeoutMs = 5000) {
+  const start = Date.now()
+
+  while (Date.now() - start < timeoutMs) {
+    if (predicate()) {
+      return
+    }
+    await sleep(50)
+  }
+
+  throw new Error('Condition not met within timeout')
+}
+
+/**
+ * Sleeps for the given number of milliseconds.
+ *
+ * @param {number} ms
+ */
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms))
+}

package/tests/resources/docker-mongo-test.js

@@ -80,15 +80,13 @@ function isConnected(port) {
  */
 function waitForMongo(port) {
   console.log(`[MongoTest] Waiting for MongoDB to be ready...`)
-  const maxRetries = 20
+  const maxRetries = 60
   let retries = 0
   let connected = false
 
   while (!connected && retries < maxRetries) {
-    try {
-      connected = isConnected(port)
-      retries++
-    } catch {
+    connected = isConnected(port)
+    if (!connected) {
       retries++
       execSync(`sleep 1`)
     }

package/types/mongodb/index.d.ts

@@ -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/types/postgresql/index.d.ts

@@ -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/types/postgresql/paginate.d.ts

@@ -0,0 +1,26 @@
+export function sqlPaginate({
+  db,
+  mapRow,
+  orderBy,
+  page,
+  limit,
+  tableName,
+  filter,
+}?: {
+  db: any
+  tableName: string
+  page?: number
+  limit?: number
+  filter?: any
+  orderBy?: {
+    column: string
+    direction?: 'asc' | 'desc'
+  }
+}): Promise<{
+  list: any[]
+  totalCount: number
+  totalPages: number
+  currentPage: number
+  hasNext: boolean
+  hasPrevious: boolean
+}>

package/types/rabbit-mq/index.d.ts

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

package/types/rabbit-mq/rabbit-mq.d.ts

@@ -29,7 +29,7 @@ export function subscribeToQueue({
   log: import('pino').Logger
   nackOnError?: boolean
   prefetch?: number
-}): Promise<string>
+}): Promise<() => Promise<void>>
 export function initializeQueue({
   host,
   log,

package/types/rabbit-mq/start-stop-rabbitmq.d.ts

@@ -0,0 +1,74 @@
+/**
+ * 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
+}: {
+  containerName: string
+  amqpPort: number
+  uiPort: number
+  user: string
+  pass: string
+}): void
+/**
+ * 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?: string): void
+/**
+ * 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,
+}: {
+  user: string
+  pass: string
+  port: number
+}): string