core-services-sdk 1.3.85 → 1.3.87

package/package.json

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

package/src/http/http.js

@@ -183,6 +183,45 @@ const getResponsePayload = async (response, responseType) => {
   }
 }
 
+/**
+ * Normalizes the request body before sending it via fetch.
+ *
+ * Ensures backward compatibility while allowing additional body types.
+ * - undefined/null → no body sent
+ * - string → sent as-is
+ * - URLSearchParams → sent as-is (fetch serializes automatically)
+ * - FormData → sent as-is (fetch sets multipart boundary automatically)
+ * - ArrayBuffer / Blob → sent as-is
+ * - object / array → JSON.stringify applied and Content-Type ensured
+ *
+ * @param {any} body
+ * @param {Record<string,string>} headers
+ * @returns {{ body:any, headers:Record<string,string> }}
+ */
+const prepareRequestBody = (body, headers = {}) => {
+  if (body === undefined || body === null) {
+    return { body: undefined, headers }
+  }
+
+  if (
+    typeof body === 'string' ||
+    body instanceof URLSearchParams ||
+    body instanceof FormData ||
+    body instanceof ArrayBuffer ||
+    body instanceof Blob
+  ) {
+    return { body, headers }
+  }
+
+  return {
+    body: JSON.stringify(body),
+    headers: {
+      'Content-Type': 'application/json',
+      ...headers,
+    },
+  }
+}
+
 /**
  * Sends an HTTP GET request.
  *
@@ -219,11 +258,15 @@ export const post = async ({
   extraParams = {},
   expectedType = ResponseType.json,
 }) => {
+  const { body: preparedBody, headers: preparedHeaders } = prepareRequestBody(
+    body,
+    headers,
+  )
   const response = await fetch(url, {
     ...extraParams,
     method: HTTP_METHODS.POST,
-    headers: { ...JSON_HEADER, ...headers },
-    body: JSON.stringify(body),
+    headers: { ...JSON_HEADER, ...preparedHeaders },
+    body: preparedBody,
   })
   await checkStatus(response)
   return getResponsePayload(response, expectedType)
@@ -243,11 +286,15 @@ export const put = async ({
   extraParams = {},
   expectedType = ResponseType.json,
 }) => {
+  const { body: preparedBody, headers: preparedHeaders } = prepareRequestBody(
+    body,
+    headers,
+  )
   const response = await fetch(url, {
     ...extraParams,
     method: HTTP_METHODS.PUT,
-    headers: { ...JSON_HEADER, ...headers },
-    body: expectedType === ResponseType.json ? JSON.stringify(body) : body,
+    headers: { ...JSON_HEADER, ...preparedHeaders },
+    body: preparedBody,
   })
   await checkStatus(response)
   return getResponsePayload(response, expectedType)
@@ -267,11 +314,15 @@ export const patch = async ({
   extraParams = {},
   expectedType = ResponseType.json,
 }) => {
+  const { body: preparedBody, headers: preparedHeaders } = prepareRequestBody(
+    body,
+    headers,
+  )
   const response = await fetch(url, {
     ...extraParams,
     method: HTTP_METHODS.PATCH,
-    headers: { ...JSON_HEADER, ...headers },
-    body: JSON.stringify(body),
+    headers: { ...JSON_HEADER, ...preparedHeaders },
+    body: preparedBody,
   })
   await checkStatus(response)
   return getResponsePayload(response, expectedType)
@@ -291,11 +342,15 @@ export const deleteApi = async ({
   extraParams = {},
   expectedType = ResponseType.json,
 }) => {
+  const { body: preparedBody, headers: preparedHeaders } = prepareRequestBody(
+    body,
+    headers,
+  )
   const response = await fetch(url, {
     ...extraParams,
     method: HTTP_METHODS.DELETE,
-    headers: { ...JSON_HEADER, ...headers },
-    ...(body ? { body: JSON.stringify(body) } : {}),
+    headers: { ...JSON_HEADER, ...preparedHeaders },
+    ...(preparedBody ? { body: preparedBody } : {}),
   })
   await checkStatus(response)
   return getResponsePayload(response, expectedType)
@@ -328,8 +383,9 @@ export const head = async ({ url, headers = {}, extraParams = {} }) => {
  *   put: (options: HttpPutOptions) => Promise<any>,
  *   post: (options: HttpPostOptions) => Promise<any>,
  *   patch: (options: HttpPatchOptions) => Promise<any>,
- *   deleteApi: (options: HttpDeleteOptions) => Promise<any>,
- *   head: (options: HttpHeadOptions) => Promise<Response>
+ *   head: (options: HttpHeadOptions) => Promise<Response>,
+ *   deleteApi: (options: HttpDeleteOptions) => Promise<any>
+ *
  * }}
  */
 
@@ -337,7 +393,7 @@ export const http = {
   get,
   put,
   post,
+  head,
   patch,
   deleteApi,
-  head,
 }

package/src/postgresql/modifiers/apply-order-by.js

@@ -2,22 +2,53 @@ import { getTableNameFromQuery } from '../core/get-table-name.js'
 
 /**
  * @typedef {Object} OrderByItem
- * @property {string} column - Column name to order by
- * @property {'asc' | 'desc'} [direction='asc'] - Order direction
+ * @property {string} column
+ * @property {'asc' | 'desc'} [direction='asc']
  */
 
 const ALLOWED_DIRECTIONS = ['asc', 'desc']
 
+/**
+ * Returns true if the column is a SQL expression or aggregate function call.
+ * These must be passed to orderByRaw — Knex's .orderBy() would quote them.
+ *
+ * Examples:  "count(*)", "lower(name)", "max(created_at)"
+ *
+ * @param {string} column
+ * @returns {boolean}
+ */
+function isSqlExpression(column) {
+  return column.includes('(') || column.includes(')')
+}
+
+/**
+ * Returns true if the column is already table-qualified.
+ * These should be passed as-is to .orderBy() — no auto-prefix needed.
+ *
+ * Examples:  "tenants.name", "roles.role_type"
+ *
+ * @param {string} column
+ * @returns {boolean}
+ */
+function isQualified(column) {
+  return column.includes('.')
+}
+
 /**
  * Applies ORDER BY clause(s) to a Knex query builder.
  *
- * Supports a single orderBy object or an array of orderBy objects.
- * Validates order direction to prevent invalid SQL.
+ * Supports single or multiple order definitions.
+ *
+ * Column handling:
+ *   - SQL expressions (e.g. "lower(name)", "count(*)") → orderByRaw, never quoted
+ *   - Already-qualified columns (e.g. "tenants.name") → orderBy as-is
+ *   - Plain column names (e.g. "name") → auto-prefixed with base table name
+ *     to avoid ambiguity in joined queries, matching applyFilter behaviour
  *
  * @param {Object} params
- * @param {import('knex').Knex.QueryBuilder} params.query - Knex query builder instance
- * @param {OrderByItem | OrderByItem[]} params.orderBy - Order by definition(s)
- * @returns {import('knex').Knex.QueryBuilder} The modified query builder
+ * @param {import('knex').Knex.QueryBuilder} params.query
+ * @param {OrderByItem | OrderByItem[]} params.orderBy
+ * @returns {import('knex').Knex.QueryBuilder}
  */
 export function applyOrderBy({ query, orderBy }) {
   if (!orderBy) {
@@ -27,19 +58,27 @@ export function applyOrderBy({ query, orderBy }) {
   const tableName = getTableNameFromQuery(query)
   const orderByArray = [].concat(orderBy)
 
-  return orderByArray.reduce((query, item) => {
-    if (!item?.column) {
-      return query
+  return orderByArray.reduce((queryBuilder, item) => {
+    if (!item || !item.column) {
+      return queryBuilder
     }
 
-    const direction = item.direction || 'asc'
+    const direction = (item.direction || 'asc').toLowerCase()
 
     if (!ALLOWED_DIRECTIONS.includes(direction)) {
       throw new Error(`Invalid order direction: ${direction}`)
     }
 
-    const column = tableName ? `${tableName}.${item.column}` : item.column
+    // SQL expressions must bypass Knex's column quoting
+    if (isSqlExpression(item.column)) {
+      return queryBuilder.orderByRaw(`${item.column} ${direction}`)
+    }
+
+    const column =
+      tableName && !isQualified(item.column)
+        ? `${tableName}.${item.column}`
+        : item.column
 
-    return query.orderBy(column, direction)
+    return queryBuilder.orderBy(column, direction)
   }, query)
 }

package/src/postgresql/pagination/paginate.js

@@ -67,6 +67,11 @@ import { normalizeNumberOrDefault } from '../../core/normalize-premitives-types-
  *   The list of records for the current page.
  *   Rows are mapped using `mapRow` if provided.
  */
+/**
+ * Generic SQL pagination helper that works with joins.
+ *
+ * @async
+ */
 export async function sqlPaginate({
   mapRow,
   orderBy,
@@ -76,24 +81,28 @@ export async function sqlPaginate({
   columns = '*',
   filter = {},
   snakeCase = true,
-  distinctOn,
 }) {
-  const listQuery = baseQuery.clone()
-  const countQuery = baseQuery.clone()
-
   const applyFilterFn = snakeCase ? applyFilterSnakeCase : applyFilter
 
-  applyFilterFn({ query: listQuery, filter })
-  applyFilterFn({ query: countQuery, filter })
+  const filteredQuery = baseQuery.clone()
+
+  applyFilterFn({ query: filteredQuery, filter })
+
+  const listQuery = filteredQuery.clone()
+  const countQuery = filteredQuery.clone()
 
   applyOrderBy({ query: listQuery, orderBy })
   applyPagination({ query: listQuery, page, limit })
 
+  const wrappedCountQuery = baseQuery.client
+    .queryBuilder()
+    .count('* as count')
+    .from(countQuery.as('t'))
+    .first()
+
   const [rows, countResult] = await Promise.all([
     listQuery.select(columns),
-    distinctOn
-      ? countQuery.countDistinct(`${distinctOn} as count`).first()
-      : countQuery.count('* as count').first(),
+    wrappedCountQuery,
   ])
 
   const totalCount = normalizeNumberOrDefault(countResult?.count || 0)

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

@@ -39,6 +39,16 @@ export function startPostgres({
 
   stopPostgres(containerName)
 
+  // Kill any container that might still be holding the port
+  try {
+    const containerId = execSync(`docker ps -q --filter "publish=${port}"`, {
+      encoding: 'utf8',
+    }).trim()
+    if (containerId) {
+      execSync(`docker rm -f ${containerId}`, { stdio: 'ignore' })
+    }
+  } catch {}
+
   execSync(
     `docker run -d \
       --name ${containerName} \

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

@@ -35,6 +35,18 @@ export function startRabbit({ containerName, ...rest }) {
     execSync(`docker rm -f ${containerName}`, { stdio: 'ignore' })
   } catch {}
 
+  // Kill any containers that might still be holding the ports
+  for (const port of [rest.amqpPort, rest.uiPort]) {
+    try {
+      const id = execSync(`docker ps -q --filter "publish=${port}"`, {
+        encoding: 'utf8',
+      }).trim()
+      if (id) {
+        execSync(`docker rm -f ${id}`, { stdio: 'ignore' })
+      }
+    } catch {}
+  }
+
   execSync(
     `docker run -d \
         --name ${containerName} \
@@ -42,6 +54,7 @@ export function startRabbit({ containerName, ...rest }) {
         -e RABBITMQ_DEFAULT_PASS=${rest.pass} \
         -p ${rest.amqpPort}:5672 \
         -p ${rest.uiPort}:15672 \
+        --tmpfs /var/lib/rabbitmq \
         --health-cmd="rabbitmq-diagnostics -q ping" \
         --health-interval=5s \
         --health-timeout=5s \

package/tests/http/http.int.test.js

@@ -0,0 +1,141 @@
+// @ts-nocheck
+import { describe, it, expect, beforeAll, afterAll } from 'vitest'
+import httpServer from 'node:http'
+import { http } from '../../src/http/http.js'
+
+let server
+let baseUrl
+
+function collectBody(req) {
+  return new Promise((resolve) => {
+    const chunks = []
+
+    req.on('data', (chunk) => {
+      chunks.push(chunk)
+    })
+
+    req.on('end', () => {
+      resolve(Buffer.concat(chunks).toString())
+    })
+  })
+}
+
+beforeAll(async () => {
+  server = httpServer.createServer(async (req, res) => {
+    const body = await collectBody(req)
+
+    res.setHeader('content-type', 'application/json')
+
+    res.end(
+      JSON.stringify({
+        method: req.method,
+        headers: req.headers,
+        body,
+      }),
+    )
+  })
+
+  await new Promise((resolve) => {
+    server.listen(0, () => {
+      const { port } = server.address()
+      baseUrl = `http://localhost:${port}`
+      resolve()
+    })
+  })
+})
+
+afterAll(async () => {
+  await new Promise((resolve) => server.close(resolve))
+})
+
+describe('http util integration', () => {
+  it('should send JSON body', async () => {
+    const result = await http.post({
+      url: `${baseUrl}/json`,
+      body: { hello: 'world' },
+    })
+
+    expect(result.method).toBe('POST')
+    expect(result.body).toBe(JSON.stringify({ hello: 'world' }))
+  })
+
+  it('should send string body without stringify', async () => {
+    const result = await http.post({
+      url: `${baseUrl}/string`,
+      body: 'plain-text',
+    })
+
+    expect(result.body).toBe('plain-text')
+  })
+
+  it('should support base64 string', async () => {
+    const base64 = Buffer.from('hello').toString('base64')
+
+    const result = await http.post({
+      url: `${baseUrl}/base64`,
+      body: base64,
+    })
+
+    expect(result.body).toBe(base64)
+  })
+
+  it('should support URLSearchParams', async () => {
+    const params = new URLSearchParams({
+      grant_type: 'client_credentials',
+      scope: 'read',
+    })
+
+    const result = await http.post({
+      url: `${baseUrl}/form`,
+      body: params,
+    })
+
+    expect(result.body).toBe(params.toString())
+  })
+
+  it('should support PUT with JSON', async () => {
+    const result = await http.put({
+      url: `${baseUrl}/put`,
+      body: { a: 1 },
+    })
+
+    expect(result.method).toBe('PUT')
+    expect(result.body).toBe(JSON.stringify({ a: 1 }))
+  })
+
+  it('should support PATCH with JSON', async () => {
+    const result = await http.patch({
+      url: `${baseUrl}/patch`,
+      body: { b: 2 },
+    })
+
+    expect(result.method).toBe('PATCH')
+    expect(result.body).toBe(JSON.stringify({ b: 2 }))
+  })
+
+  it('should support DELETE with body', async () => {
+    const result = await http.deleteApi({
+      url: `${baseUrl}/delete`,
+      body: { remove: true },
+    })
+
+    expect(result.method).toBe('DELETE')
+    expect(result.body).toBe(JSON.stringify({ remove: true }))
+  })
+
+  it('should support GET request', async () => {
+    const result = await http.get({
+      url: `${baseUrl}/get`,
+    })
+
+    expect(result.method).toBe('GET')
+  })
+
+  it('should support HEAD request', async () => {
+    const response = await http.head({
+      url: `${baseUrl}/head`,
+    })
+
+    expect(response.status).toBe(200)
+  })
+})

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

@@ -34,21 +34,37 @@ beforeAll(async () => {
     table.uuid('id').primary()
     table.string('name').notNullable()
     table.string('type').notNullable()
-    table.bigInteger('age').notNullable()
+    table.integer('age').notNullable()
     table.timestamp('created_at').notNullable()
   })
+
+  await db.schema.createTable('roles', (table) => {
+    table.increments('id').primary()
+    table.uuid('tenant_id').notNullable()
+    table.string('role_type').notNullable()
+  })
+
+  await db.schema.createTable('tenant_tags', (table) => {
+    table.increments('id').primary()
+    table.uuid('tenant_id').notNullable()
+    table.string('tag').notNullable()
+  })
 })
 
 afterAll(async () => {
   if (db) {
     await db.destroy()
   }
+
   stopPostgres(PG_OPTIONS.containerName)
 })
 
 beforeEach(async () => {
+  await db('tenant_tags').truncate()
+  await db('roles').truncate()
   await db('tenants').truncate()
-  const records = [
+
+  await db('tenants').insert([
     {
       id: '00000000-0000-0000-0000-000000000001',
       name: 'Tenant A',
@@ -59,54 +75,61 @@ beforeEach(async () => {
     {
       id: '00000000-0000-0000-0000-000000000002',
       name: 'Tenant B',
-      age: 3,
       type: 'business',
+      age: 3,
       created_at: new Date('2024-01-02'),
     },
     {
       id: '00000000-0000-0000-0000-000000000003',
       name: 'Tenant C',
-      age: 1,
       type: 'cpa',
+      age: 1,
       created_at: new Date('2023-01-03'),
     },
-
     {
       id: '00000000-0000-0000-0000-000000000004',
       name: 'Tenant D',
-      age: 7,
       type: 'cpa',
+      age: 7,
       created_at: new Date('2022-01-03'),
     },
-
     {
       id: '00000000-0000-0000-0000-000000000005',
       name: 'Tenant E',
-      age: 0,
       type: 'cpa',
+      age: 0,
       created_at: new Date('2021-01-03'),
     },
-  ]
-  await db('tenants').insert(records)
-})
+  ])
 
-describe('paginate integration', () => {
-  it('returns first page without ordering guarantees', async () => {
-    const result = await sqlPaginate({
-      baseQuery: db('tenants'),
-      page: 2,
-      limit: 2,
-    })
+  await db('roles').insert([
+    {
+      tenant_id: '00000000-0000-0000-0000-000000000001',
+      role_type: 'customer',
+    },
+    {
+      tenant_id: '00000000-0000-0000-0000-000000000001',
+      role_type: 'supplier',
+    },
+    {
+      tenant_id: '00000000-0000-0000-0000-000000000002',
+      role_type: 'customer',
+    },
+    {
+      tenant_id: '00000000-0000-0000-0000-000000000003',
+      role_type: 'supplier',
+    },
+  ])
 
-    expect(result.totalCount).toBe(5)
-    expect(result.pages).toBe(3)
-    expect(result.page).toBe(2)
-    expect(result.hasPrevious).toBe(true)
-    expect(result.hasNext).toBe(true)
-    expect(result.list).toHaveLength(2)
-  })
+  await db('tenant_tags').insert([
+    { tenant_id: '00000000-0000-0000-0000-000000000001', tag: 'vip' },
+    { tenant_id: '00000000-0000-0000-0000-000000000001', tag: 'active' },
+    { tenant_id: '00000000-0000-0000-0000-000000000002', tag: 'active' },
+  ])
+})
 
-  it('returns second page without ordering guarantees', async () => {
+describe('sqlPaginate integration', () => {
+  it('basic pagination works', async () => {
     const result = await sqlPaginate({
       baseQuery: db('tenants'),
       page: 2,
@@ -116,29 +139,19 @@ describe('paginate integration', () => {
     expect(result.totalCount).toBe(5)
     expect(result.pages).toBe(3)
     expect(result.page).toBe(2)
-    expect(result.hasPrevious).toBe(true)
-    expect(result.hasNext).toBe(true)
     expect(result.list).toHaveLength(2)
   })
 
-  it('applies filters correctly', async () => {
-    const minDate = new Date('2024-01-01')
+  it('filters correctly', async () => {
     const result = await sqlPaginate({
       baseQuery: db('tenants'),
-      filter: {
-        createdAt: { lte: new Date(), gte: minDate },
-      },
-      limit: 10,
-      page: 1,
+      filter: { type: 'business' },
     })
 
     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 () => {
+  it('orders correctly', async () => {
     const result = await sqlPaginate({
       baseQuery: db('tenants'),
       orderBy: {
@@ -147,13 +160,7 @@ describe('paginate integration', () => {
       },
     })
 
-    expect(result.list.map((t) => t.name)).toEqual([
-      'Tenant A',
-      'Tenant B',
-      'Tenant C',
-      'Tenant D',
-      'Tenant E',
-    ])
+    expect(result.list[0].name).toBe('Tenant A')
   })
 
   it('supports row mapping', async () => {
@@ -165,20 +172,245 @@ describe('paginate integration', () => {
       }),
     })
 
-    expect(result.list.length).toBeGreaterThan(0)
     expect(result.list[0].mapped).toBe(true)
   })
 
-  it('returns empty list when no records match filter', async () => {
+  it('works with join', async () => {
+    const baseQuery = db('tenants').innerJoin(
+      'roles',
+      'roles.tenant_id',
+      'tenants.id',
+    )
+
+    const result = await sqlPaginate({
+      baseQuery,
+      limit: 10,
+    })
+
+    expect(result.totalCount).toBeGreaterThan(0)
+  })
+
+  it('filters on joined table', async () => {
+    // Joined-table column filters are applied directly to baseQuery,
+    // not through the filter param (which is scoped to the base table).
+    const baseQuery = db('tenants')
+      .innerJoin('roles', 'roles.tenant_id', 'tenants.id')
+      .where('roles.role_type', 'customer')
+
+    const result = await sqlPaginate({
+      baseQuery,
+      limit: 10,
+    })
+
+    const names = result.list.map((t) => t.name).sort()
+
+    expect(names).toEqual(['Tenant A', 'Tenant B'])
+  })
+
+  it('handles duplicate rows from join', async () => {
+    const baseQuery = db('tenants').innerJoin(
+      'tenant_tags',
+      'tenant_tags.tenant_id',
+      'tenants.id',
+    )
+
+    const result = await sqlPaginate({
+      baseQuery,
+      limit: 10,
+    })
+
+    expect(result.totalCount).toBeGreaterThan(0)
+  })
+
+  it('paginates correctly with join', async () => {
+    const baseQuery = db('tenants').innerJoin(
+      'roles',
+      'roles.tenant_id',
+      'tenants.id',
+    )
+
+    const result = await sqlPaginate({
+      baseQuery,
+      limit: 1,
+      page: 2,
+    })
+
+    expect(result.page).toBe(2)
+    expect(result.list.length).toBe(1)
+  })
+
+  it('orders correctly with join', async () => {
+    const baseQuery = db('tenants').innerJoin(
+      'roles',
+      'roles.tenant_id',
+      'tenants.id',
+    )
+
+    const result = await sqlPaginate({
+      baseQuery,
+      orderBy: {
+        column: 'tenants.name',
+        direction: 'asc',
+      },
+    })
+
+    expect(result.list[0].name).toBe('Tenant A')
+  })
+
+  it('works with double join (3 tables)', async () => {
+    const baseQuery = db('tenants')
+      .innerJoin('roles', 'roles.tenant_id', 'tenants.id')
+      .innerJoin('tenant_tags', 'tenant_tags.tenant_id', 'tenants.id')
+
+    const result = await sqlPaginate({
+      baseQuery,
+      limit: 10,
+    })
+
+    expect(result.totalCount).toBeGreaterThan(0)
+  })
+
+  it('returns empty result correctly', async () => {
     const result = await sqlPaginate({
       baseQuery: db('tenants'),
-      filter: { type: 'non-existing' },
+      filter: { name: 'does-not-exist' },
     })
 
     expect(result.totalCount).toBe(0)
-    expect(result.pages).toBe(0)
     expect(result.list).toEqual([])
-    expect(result.hasNext).toBe(false)
-    expect(result.hasPrevious).toBe(false)
+    expect(result.pages).toBe(0)
+  })
+
+  it('exact count is correct when join produces duplicate rows', async () => {
+    // tenant A has 2 tags, tenant B has 1 tag → join produces 3 rows total
+    const baseQuery = db('tenants').innerJoin(
+      'tenant_tags',
+      'tenant_tags.tenant_id',
+      'tenants.id',
+    )
+
+    const result = await sqlPaginate({
+      baseQuery,
+      limit: 10,
+    })
+
+    expect(result.totalCount).toBe(3)
+  })
+
+  it('orders correctly with plain column on join (auto-prefix)', async () => {
+    // plain 'name' should be auto-prefixed to 'tenants.name' to avoid ambiguity
+    const baseQuery = db('tenants').innerJoin(
+      'roles',
+      'roles.tenant_id',
+      'tenants.id',
+    )
+
+    const result = await sqlPaginate({
+      baseQuery,
+      orderBy: { column: 'name', direction: 'asc' },
+    })
+
+    expect(result.list[0].name).toBe('Tenant A')
+  })
+
+  it('orders correctly with multiple columns (array)', async () => {
+    // sort by type asc, then name desc → business: B, A then cpa: E, D, C
+    const result = await sqlPaginate({
+      baseQuery: db('tenants'),
+      orderBy: [
+        { column: 'type', direction: 'asc' },
+        { column: 'name', direction: 'desc' },
+      ],
+    })
+
+    expect(result.list[0].name).toBe('Tenant B')
+    expect(result.list[1].name).toBe('Tenant A')
+    expect(result.list[4].name).toBe('Tenant C')
+  })
+
+  it('orders correctly with SQL expression (skips auto-prefix)', async () => {
+    // lower(name) is a SQL expression — must not be prefixed
+    const result = await sqlPaginate({
+      baseQuery: db('tenants'),
+      orderBy: { column: 'lower(name)', direction: 'asc' },
+    })
+
+    expect(result.list[0].name).toBe('Tenant A')
+    expect(result.list[4].name).toBe('Tenant E')
+  })
+
+  it('returns only requested columns', async () => {
+    const baseQuery = db('tenants').innerJoin(
+      'roles',
+      'roles.tenant_id',
+      'tenants.id',
+    )
+
+    // columns must be an array — a comma-separated string is not valid for Knex select
+    const result = await sqlPaginate({
+      baseQuery,
+      columns: ['tenants.name', 'tenants.type'],
+      limit: 10,
+    })
+
+    const row = result.list[0]
+
+    expect(row).toHaveProperty('name')
+    expect(row).toHaveProperty('type')
+    expect(row).not.toHaveProperty('id')
+    expect(row).not.toHaveProperty('role_type')
+  })
+
+  it('hasPrevious and hasNext are correct', async () => {
+    // 5 tenants, limit 2 → 3 pages
+    const page1 = await sqlPaginate({
+      baseQuery: db('tenants'),
+      page: 1,
+      limit: 2,
+    })
+
+    expect(page1.hasPrevious).toBe(false)
+    expect(page1.hasNext).toBe(true)
+
+    const page2 = await sqlPaginate({
+      baseQuery: db('tenants'),
+      page: 2,
+      limit: 2,
+    })
+
+    expect(page2.hasPrevious).toBe(true)
+    expect(page2.hasNext).toBe(true)
+
+    const page3 = await sqlPaginate({
+      baseQuery: db('tenants'),
+      page: 3,
+      limit: 2,
+    })
+
+    expect(page3.hasPrevious).toBe(true)
+    expect(page3.hasNext).toBe(false)
+  })
+
+  it('filters with multiple conditions', async () => {
+    const result = await sqlPaginate({
+      baseQuery: db('tenants'),
+      filter: { type: 'cpa', name: 'Tenant C' },
+    })
+
+    expect(result.totalCount).toBe(1)
+    expect(result.list[0].name).toBe('Tenant C')
+  })
+
+  it('filters with array values (IN operator)', async () => {
+    const result = await sqlPaginate({
+      baseQuery: db('tenants'),
+      filter: { name: ['Tenant A', 'Tenant C'] },
+    })
+
+    expect(result.totalCount).toBe(2)
+
+    const names = result.list.map((r) => r.name).sort()
+
+    expect(names).toEqual(['Tenant A', 'Tenant C'])
   })
 })

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

@@ -20,7 +20,7 @@ const log = pino({
   level: 'silent',
 })
 // @ts-ignore
-async function waitForRabbitConnection({ uri, log, timeoutMs = 10000 }) {
+async function waitForRabbitConnection({ uri, log, timeoutMs = 30000 }) {
   const start = Date.now()
 
   while (Date.now() - start < timeoutMs) {

package/tests/repositories/BaseRepository.int.test.js

@@ -11,11 +11,11 @@ import {
 import { BaseRepository } from '../../src/postgresql/repositories/BaseRepository.js'
 
 const PG_OPTIONS = {
-  port: 5445,
+  port: 5449,
   db: 'testdb',
   user: 'testuser',
   pass: 'testpass',
-  containerName: 'postgres-base-repo-test-5445',
+  containerName: 'postgres-base-repo-test-5449',
 }
 
 const DATABASE_URI = buildPostgresUri(PG_OPTIONS)

package/tests/repositories/TenantScopedRepository.int.test.js

@@ -11,11 +11,11 @@ import {
 import { TenantScopedRepository } from '../../src/postgresql/repositories/TenantScopedRepository.js'
 
 const PG_OPTIONS = {
-  port: 5446,
+  port: 5448,
   db: 'testdb',
   user: 'testuser',
   pass: 'testpass',
-  containerName: 'postgres-tenant-repo-test-5446',
+  containerName: 'postgres-tenant-repo-test-5448',
 }
 
 const DATABASE_URI = buildPostgresUri(PG_OPTIONS)

package/types/http/http.d.ts

@@ -45,8 +45,9 @@ export function head({
  *   put: (options: HttpPutOptions) => Promise<any>,
  *   post: (options: HttpPostOptions) => Promise<any>,
  *   patch: (options: HttpPatchOptions) => Promise<any>,
- *   deleteApi: (options: HttpDeleteOptions) => Promise<any>,
- *   head: (options: HttpHeadOptions) => Promise<Response>
+ *   head: (options: HttpHeadOptions) => Promise<Response>,
+ *   deleteApi: (options: HttpDeleteOptions) => Promise<any>
+ *
  * }}
  */
 export const http: {
@@ -54,8 +55,8 @@ export const http: {
   put: (options: HttpPutOptions) => Promise<any>
   post: (options: HttpPostOptions) => Promise<any>
   patch: (options: HttpPatchOptions) => Promise<any>
-  deleteApi: (options: HttpDeleteOptions) => Promise<any>
   head: (options: HttpHeadOptions) => Promise<Response>
+  deleteApi: (options: HttpDeleteOptions) => Promise<any>
 }
 export type ResponseTypeValue = 'json' | 'xml' | 'text' | 'raw' | 'file'
 export type HttpGetOptions = {

package/types/postgresql/modifiers/apply-order-by.d.ts

@@ -1,13 +1,18 @@
 /**
  * Applies ORDER BY clause(s) to a Knex query builder.
  *
- * Supports a single orderBy object or an array of orderBy objects.
- * Validates order direction to prevent invalid SQL.
+ * Supports single or multiple order definitions.
+ *
+ * Column handling:
+ *   - SQL expressions (e.g. "lower(name)", "count(*)") → orderByRaw, never quoted
+ *   - Already-qualified columns (e.g. "tenants.name") → orderBy as-is
+ *   - Plain column names (e.g. "name") → auto-prefixed with base table name
+ *     to avoid ambiguity in joined queries, matching applyFilter behaviour
  *
  * @param {Object} params
- * @param {import('knex').Knex.QueryBuilder} params.query - Knex query builder instance
- * @param {OrderByItem | OrderByItem[]} params.orderBy - Order by definition(s)
- * @returns {import('knex').Knex.QueryBuilder} The modified query builder
+ * @param {import('knex').Knex.QueryBuilder} params.query
+ * @param {OrderByItem | OrderByItem[]} params.orderBy
+ * @returns {import('knex').Knex.QueryBuilder}
  */
 export function applyOrderBy({
   query,
@@ -17,12 +22,6 @@ export function applyOrderBy({
   orderBy: OrderByItem | OrderByItem[]
 }): import('knex').Knex.QueryBuilder
 export type OrderByItem = {
-  /**
-   * - Column name to order by
-   */
   column: string
-  /**
-   * - Order direction
-   */
   direction?: 'asc' | 'desc'
 }

package/types/postgresql/pagination/paginate.d.ts

@@ -61,6 +61,11 @@
  *   The list of records for the current page.
  *   Rows are mapped using `mapRow` if provided.
  */
+/**
+ * Generic SQL pagination helper that works with joins.
+ *
+ * @async
+ */
 export function sqlPaginate({
   mapRow,
   orderBy,
@@ -70,13 +75,20 @@ export function sqlPaginate({
   columns,
   filter,
   snakeCase,
-  distinctOn,
 }: {
-  baseQuery: import('knex').Knex.QueryBuilder
-  filter?: any
-  snakeCase?: boolean
-  orderBy?: any | any[]
+  mapRow: any
+  orderBy: any
   page?: number
+  baseQuery: any
   limit?: number
-  mapRow?: Function
-}): Promise<any>
+  columns?: string
+  filter?: {}
+  snakeCase?: boolean
+}): Promise<{
+  page: number
+  pages: number
+  totalCount: number
+  hasPrevious: boolean
+  hasNext: boolean
+  list: any
+}>

package/types/postgresql/repositories/BaseRepository.d.ts

@@ -49,5 +49,12 @@ export class BaseRepository {
       column: string
       direction: string
     }
-  }): Promise<any>
+  }): Promise<{
+    page: number
+    pages: number
+    totalCount: number
+    hasPrevious: boolean
+    hasNext: boolean
+    list: any
+  }>
 }

package/types/postgresql/repositories/TenantScopedRepository.d.ts

@@ -6,6 +6,13 @@ export class TenantScopedRepository extends BaseRepository {
   /**
    * Overrides find to enforce tenant presence
    */
-  find(params?: {}): Promise<any>
+  find(params?: {}): Promise<{
+    page: number
+    pages: number
+    totalCount: number
+    hasPrevious: boolean
+    hasNext: boolean
+    list: any
+  }>
 }
 import { BaseRepository } from './BaseRepository.js'

package/vitest.config.js

@@ -3,7 +3,7 @@ import { defineConfig } from 'vitest/config'
 export default defineConfig({
   test: {
     testTimeout: 30000,
-    hookTimeout: 30000,
+    hookTimeout: 90000,
     exclude: [
       'node_modules',
       'types/**',