core-services-sdk 1.3.85 → 1.3.86

package/package.json

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

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/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/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'