core-services-sdk 1.3.84 → 1.3.86

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "core-services-sdk",
-  "version": "1.3.84",
+  "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,32 +67,42 @@ 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,
   page = 1,
   baseQuery,
   limit = 10,
+  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('*'),
-    distinctOn
-      ? countQuery.countDistinct(`${distinctOn} as count`).first()
-      : countQuery.count('* as count').first(),
+    listQuery.select(columns),
+    wrappedCountQuery,
   ])
 
   const totalCount = normalizeNumberOrDefault(countResult?.count || 0)

package/src/postgresql/repositories/BaseRepository.js

@@ -14,13 +14,14 @@ import { toSnakeCase } from '../../core/case-mapper.js'
  */
 
 export class BaseRepository {
-  constructor({ db, log, baseQueryBuilder } = {}) {
+  constructor({ db, log, columns, baseQueryBuilder } = {}) {
     if (!db) {
       throw new Error('BaseRepository requires db instance')
     }
 
     this.db = db
     this.log = log
+    this._columns = columns ?? '*'
     this._baseQueryBuilder = baseQueryBuilder
   }
 
@@ -48,7 +49,7 @@ export class BaseRepository {
 
     if (this._baseQueryBuilder) {
       // Pass full params for optional dynamic shaping
-      return this._baseQueryBuilder(qb, params)
+      this._baseQueryBuilder(qb, params)
     }
 
     return qb
@@ -59,11 +60,12 @@ export class BaseRepository {
    */
   async find({
     page = 1,
+    columns,
     limit = 10,
     filter = {},
-    orderBy = { column: 'created_at', direction: 'desc' },
     options = {},
     mapRow = (row) => row,
+    orderBy = { column: 'created_at', direction: 'desc' },
     ...restParams
   }) {
     try {
@@ -79,10 +81,11 @@ export class BaseRepository {
       return await sqlPaginate({
         page,
         limit,
+        mapRow,
         orderBy,
         baseQuery: qb,
-        mapRow,
         filter: toSnakeCase(filter),
+        columns: columns ?? this._columns,
       })
     } catch (error) {
       if (this.log) {

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/repositories/BaseRepository.int.test.js

@@ -0,0 +1,172 @@
+// @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 { BaseRepository } from '../../src/postgresql/repositories/BaseRepository.js'
+
+const PG_OPTIONS = {
+  port: 5445,
+  db: 'testdb',
+  user: 'testuser',
+  pass: 'testpass',
+  containerName: 'postgres-base-repo-test-5445',
+}
+
+const DATABASE_URI = buildPostgresUri(PG_OPTIONS)
+
+let db
+
+beforeAll(async () => {
+  startPostgres(PG_OPTIONS)
+
+  db = knex({
+    client: 'pg',
+    connection: DATABASE_URI,
+  })
+
+  await db.schema.createTable('customers', (table) => {
+    table.uuid('id').primary()
+    table.string('name').notNullable()
+    table.timestamp('created_at').notNullable()
+  })
+
+  await db.schema.createTable('orders', (table) => {
+    table.uuid('id').primary()
+    table.uuid('customer_id').notNullable()
+    table.decimal('amount', 10, 2)
+    table.timestamp('created_at').notNullable()
+  })
+})
+
+afterAll(async () => {
+  if (db) {
+    await db.destroy()
+  }
+
+  stopPostgres(PG_OPTIONS.containerName)
+})
+
+beforeEach(async () => {
+  await db('orders').truncate()
+  await db('customers').truncate()
+
+  await db('customers').insert([
+    {
+      id: '00000000-0000-0000-0000-000000000001',
+      name: 'Alice',
+      created_at: new Date('2024-01-01'),
+    },
+    {
+      id: '00000000-0000-0000-0000-000000000002',
+      name: 'Bob',
+      created_at: new Date('2024-01-02'),
+    },
+  ])
+
+  await db('orders').insert([
+    {
+      id: '00000000-0000-0000-0000-000000000101',
+      customer_id: '00000000-0000-0000-0000-000000000001',
+      amount: 100,
+      created_at: new Date('2024-01-10'),
+    },
+    {
+      id: '00000000-0000-0000-0000-000000000102',
+      customer_id: '00000000-0000-0000-0000-000000000001',
+      amount: 200,
+      created_at: new Date('2024-01-11'),
+    },
+    {
+      id: '00000000-0000-0000-0000-000000000103',
+      customer_id: '00000000-0000-0000-0000-000000000002',
+      amount: 300,
+      created_at: new Date('2024-01-12'),
+    },
+  ])
+})
+
+class OrdersRepository extends BaseRepository {
+  static tableName = 'orders'
+
+  constructor(deps) {
+    super({
+      ...deps,
+      baseQueryBuilder(qb) {
+        qb.innerJoin('customers', 'customers.id', 'orders.customer_id')
+      },
+    })
+  }
+}
+
+describe('BaseRepository integration', () => {
+  it('baseQueryBuilder applies JOIN correctly', async () => {
+    const repo = new OrdersRepository({ db })
+
+    const qb = repo.baseQuery()
+
+    const rows = await qb.select('orders.id', 'customers.name')
+
+    expect(rows).toHaveLength(3)
+    expect(rows[0]).toHaveProperty('name')
+  })
+
+  it('find returns joined data using columns', async () => {
+    const repo = new OrdersRepository({ db })
+
+    const result = await repo.find({
+      columns: ['orders.id', 'orders.amount', 'customers.name'],
+      limit: 10,
+    })
+
+    expect(result.list.length).toBe(3)
+
+    const row = result.list[0]
+
+    expect(row).toHaveProperty('amount')
+    expect(row).toHaveProperty('name')
+  })
+
+  it('pagination works with joins', async () => {
+    const repo = new OrdersRepository({ db })
+
+    const result = await repo.find({
+      columns: ['orders.id', 'customers.name'],
+      limit: 2,
+      page: 1,
+    })
+
+    expect(result.list.length).toBe(2)
+    expect(result.totalCount).toBe(3)
+    expect(result.pages).toBe(2)
+  })
+
+  it('constructor default columns are used', async () => {
+    class RepoWithColumns extends BaseRepository {
+      static tableName = 'orders'
+
+      constructor(deps) {
+        super({
+          ...deps,
+          columns: ['orders.id'],
+          baseQueryBuilder(qb) {
+            qb.innerJoin('customers', 'customers.id', 'orders.customer_id')
+          },
+        })
+      }
+    }
+
+    const repo = new RepoWithColumns({ db })
+
+    const result = await repo.find({})
+
+    const row = result.list[0]
+
+    expect(Object.keys(row)).toEqual(['id'])
+  })
+})

package/tests/repositories/BaseRepository.test.js

@@ -1,21 +1,14 @@
-import { describe, it, expect, vi, beforeEach } from 'vitest'
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest'
 import { BaseRepository } from '../../src/postgresql/repositories/BaseRepository.js'
 
-// 🔥 mock dependencies
+// mock paginate
 vi.mock('../../src/postgresql/pagination/paginate.js', () => ({
-  sqlPaginate: vi.fn().mockResolvedValue({ page: 1 }),
+  sqlPaginate: vi.fn(),
 }))
 
-vi.mock('../../filters/apply-filter-snake-case.js', () => ({
-  applyFilterSnakeCase: vi.fn(),
-}))
-
-vi.mock('../../filters/apply-filter.js', () => ({
-  applyFilter: vi.fn(),
-}))
-
-vi.mock('../../core/normalize-premitives-types-or-default.js', () => ({
-  normalizeNumberOrDefault: vi.fn((v) => Number(v)),
+// mock snakeCase mapper
+vi.mock('../../src/core/case-mapper.js', () => ({
+  toSnakeCase: vi.fn((v) => v),
 }))
 
 // import AFTER mocks
@@ -24,6 +17,7 @@ import { toSnakeCase } from '../../src/core/case-mapper.js'
 
 describe('BaseRepository', () => {
   let dbMock
+  let qbMock
   let logMock
 
   class TestRepo extends BaseRepository {
@@ -31,13 +25,21 @@ describe('BaseRepository', () => {
   }
 
   beforeEach(() => {
-    dbMock = vi.fn(() => ({
-      clone: vi.fn(),
-    }))
+    qbMock = {
+      clone: vi.fn().mockReturnThis(),
+    }
+
+    dbMock = vi.fn(() => qbMock)
 
     logMock = {
       error: vi.fn(),
     }
+
+    sqlPaginate.mockResolvedValue({ page: 1 })
+  })
+
+  afterEach(() => {
+    vi.clearAllMocks()
   })
 
   it('throws if db not provided', () => {
@@ -58,7 +60,7 @@ describe('BaseRepository', () => {
   })
 
   it('baseQuery uses trx when provided', () => {
-    const trxMock = vi.fn()
+    const trxMock = vi.fn(() => qbMock)
     const repo = new TestRepo({ db: dbMock })
 
     repo.baseQuery({ trx: trxMock })
@@ -68,7 +70,8 @@ describe('BaseRepository', () => {
   })
 
   it('baseQuery applies baseQueryBuilder', () => {
-    const builderMock = vi.fn((qb) => qb)
+    const builderMock = vi.fn()
+
     const repo = new TestRepo({
       db: dbMock,
       baseQueryBuilder: builderMock,
@@ -76,7 +79,7 @@ describe('BaseRepository', () => {
 
     repo.baseQuery({}, { some: 'param' })
 
-    expect(builderMock).toHaveBeenCalled()
+    expect(builderMock).toHaveBeenCalledWith(qbMock, { some: 'param' })
   })
 
   it('find calls sqlPaginate with correct params', async () => {
@@ -88,17 +91,65 @@ describe('BaseRepository', () => {
       filter: { a: 1 },
     })
 
-    expect(sqlPaginate).toHaveBeenCalled()
+    expect(toSnakeCase).toHaveBeenCalledWith({ a: 1 })
+
+    expect(sqlPaginate).toHaveBeenCalledWith(
+      expect.objectContaining({
+        page: 2,
+        limit: 5,
+        baseQuery: qbMock,
+      }),
+    )
   })
 
   it('logs error if sqlPaginate throws', async () => {
-    // @ts-ignore
     sqlPaginate.mockRejectedValueOnce(new Error('fail'))
 
     const repo = new TestRepo({ db: dbMock, log: logMock })
 
-    await expect(repo.find({ filter: {} })).rejects.toThrow()
+    await expect(repo.find({ filter: {} })).rejects.toThrow('fail')
 
     expect(logMock.error).toHaveBeenCalled()
   })
+
+  it('find uses columns passed to find()', async () => {
+    const repo = new TestRepo({ db: dbMock })
+
+    await repo.find({
+      columns: ['id', 'name'],
+    })
+
+    expect(sqlPaginate).toHaveBeenCalledWith(
+      expect.objectContaining({
+        columns: ['id', 'name'],
+      }),
+    )
+  })
+
+  it('find falls back to constructor columns', async () => {
+    const repo = new TestRepo({
+      db: dbMock,
+      columns: ['id', 'email'],
+    })
+
+    await repo.find({})
+
+    expect(sqlPaginate).toHaveBeenCalledWith(
+      expect.objectContaining({
+        columns: ['id', 'email'],
+      }),
+    )
+  })
+
+  it('find falls back to "*" when no columns provided', async () => {
+    const repo = new TestRepo({ db: dbMock })
+
+    await repo.find({})
+
+    expect(sqlPaginate).toHaveBeenCalledWith(
+      expect.objectContaining({
+        columns: '*',
+      }),
+    )
+  })
 })

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

@@ -0,0 +1,173 @@
+// @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 { TenantScopedRepository } from '../../src/postgresql/repositories/TenantScopedRepository.js'
+
+const PG_OPTIONS = {
+  port: 5446,
+  db: 'testdb',
+  user: 'testuser',
+  pass: 'testpass',
+  containerName: 'postgres-tenant-repo-test-5446',
+}
+
+const DATABASE_URI = buildPostgresUri(PG_OPTIONS)
+
+const TENANT_A = '00000000-0000-0000-0000-000000000010'
+const TENANT_B = '00000000-0000-0000-0000-000000000020'
+
+let db
+
+beforeAll(async () => {
+  startPostgres(PG_OPTIONS)
+
+  db = knex({
+    client: 'pg',
+    connection: DATABASE_URI,
+  })
+
+  await db.schema.createTable('customers', (table) => {
+    table.uuid('id').primary()
+    table.uuid('tenant_id').notNullable()
+    table.string('name')
+    table.timestamp('created_at').notNullable()
+  })
+
+  await db.schema.createTable('orders', (table) => {
+    table.uuid('id').primary()
+    table.uuid('tenant_id').notNullable()
+    table.uuid('customer_id')
+    table.decimal('amount', 10, 2)
+    table.timestamp('created_at').notNullable()
+  })
+})
+
+afterAll(async () => {
+  if (db) {
+    await db.destroy()
+  }
+
+  stopPostgres(PG_OPTIONS.containerName)
+})
+
+beforeEach(async () => {
+  await db('orders').truncate()
+  await db('customers').truncate()
+
+  await db('customers').insert([
+    {
+      id: '00000000-0000-0000-0000-000000000001',
+      tenant_id: TENANT_A,
+      name: 'Alice',
+      created_at: new Date('2024-01-01'),
+    },
+    {
+      id: '00000000-0000-0000-0000-000000000002',
+      tenant_id: TENANT_B,
+      name: 'Bob',
+      created_at: new Date('2024-01-02'),
+    },
+  ])
+
+  await db('orders').insert([
+    {
+      id: '00000000-0000-0000-0000-000000000101',
+      tenant_id: TENANT_A,
+      customer_id: '00000000-0000-0000-0000-000000000001',
+      amount: 100,
+      created_at: new Date('2024-01-10'),
+    },
+    {
+      id: '00000000-0000-0000-0000-000000000102',
+      tenant_id: TENANT_A,
+      customer_id: '00000000-0000-0000-0000-000000000001',
+      amount: 200,
+      created_at: new Date('2024-01-11'),
+    },
+    {
+      id: '00000000-0000-0000-0000-000000000103',
+      tenant_id: TENANT_B,
+      customer_id: '00000000-0000-0000-0000-000000000002',
+      amount: 300,
+      created_at: new Date('2024-01-12'),
+    },
+  ])
+})
+
+class OrdersRepository extends TenantScopedRepository {
+  static tableName = 'orders'
+
+  constructor(deps) {
+    super({
+      ...deps,
+      baseQueryBuilder(qb) {
+        qb.innerJoin('customers', 'customers.id', 'orders.customer_id')
+      },
+    })
+  }
+}
+
+describe('TenantScopedRepository integration', () => {
+  it('throws if tenantId missing', async () => {
+    const repo = new OrdersRepository({ db })
+
+    await expect(
+      repo.find({
+        filter: {},
+      }),
+    ).rejects.toThrow('tenantId is required')
+  })
+
+  it('returns only rows for tenant', async () => {
+    const repo = new OrdersRepository({ db })
+
+    const result = await repo.find({
+      filter: {
+        tenantId: TENANT_A,
+      },
+      columns: ['orders.id', 'orders.amount'],
+    })
+
+    expect(result.list.length).toBe(2)
+  })
+
+  it('works with join and columns', async () => {
+    const repo = new OrdersRepository({ db })
+
+    const result = await repo.find({
+      filter: {
+        tenantId: TENANT_A,
+      },
+      columns: ['orders.id', 'orders.amount', 'customers.name'],
+    })
+
+    const row = result.list[0]
+
+    expect(row).toHaveProperty('amount')
+    expect(row).toHaveProperty('name')
+  })
+
+  it('pagination respects tenant scope', async () => {
+    const repo = new OrdersRepository({ db })
+
+    const result = await repo.find({
+      filter: {
+        tenantId: TENANT_A,
+      },
+      limit: 1,
+      page: 1,
+      columns: ['orders.id'],
+    })
+
+    expect(result.list.length).toBe(1)
+    expect(result.totalCount).toBe(2)
+    expect(result.pages).toBe(2)
+  })
+})

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,21 +61,34 @@
  *   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,
   page,
   baseQuery,
   limit,
+  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

@@ -10,9 +10,10 @@
  * Does NOT enforce tenant isolation.
  */
 export class BaseRepository {
-  constructor({ db, log, baseQueryBuilder }?: {})
+  constructor({ db, log, columns, baseQueryBuilder }?: {})
   db: any
   log: any
+  _columns: any
   _baseQueryBuilder: any
   /**
    * Each concrete repository must define:
@@ -29,22 +30,31 @@ export class BaseRepository {
    */
   find({
     page,
+    columns,
     limit,
     filter,
-    orderBy,
     options,
     mapRow,
+    orderBy,
     ...restParams
   }: {
     [x: string]: any
     page?: number
+    columns: any
     limit?: number
     filter?: {}
+    options?: {}
+    mapRow?: (row: any) => any
     orderBy?: {
       column: string
       direction: string
     }
-    options?: {}
-    mapRow?: (row: any) => any
-  }): 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'