core-services-sdk 1.3.65 → 1.3.67

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "core-services-sdk",
-  "version": "1.3.65",
+  "version": "1.3.67",
   "main": "src/index.js",
   "type": "module",
   "types": "types/index.d.ts",
@@ -31,6 +31,7 @@
     "@aws-sdk/credential-provider-node": "^3.862.0",
     "@sendgrid/mail": "^8.1.5",
     "amqplib": "^0.10.8",
+    "date-fns": "^4.1.0",
     "dot": "^1.1.3",
     "fastify": "^5.4.0",
     "google-libphonenumber": "^3.2.42",

package/src/postgresql/pagination/paginate.js

@@ -1,13 +1,71 @@
 import { applyFilter } from '../filters/apply-filter.js'
-import { applyFilterSnakeCase } from '../filters/apply-filter-snake-case.js'
 import { applyOrderBy } from '../modifiers/apply-order-by.js'
 import { applyPagination } from '../modifiers/apply-pagination.js'
+import { applyFilterSnakeCase } from '../filters/apply-filter-snake-case.js'
 import { normalizeNumberOrDefault } from '../../core/normalize-premitives-types-or-default.js'
 
 /**
- * Executes paginated query.
+ * Executes a paginated SQL query using a Knex query builder.
+ *
+ * This helper clones the provided base query twice:
+ * one query is used to fetch the paginated list of rows,
+ * and the second query is used to calculate the total count
+ * of records matching the same filters.
+ *
+ * Filters are applied consistently to both queries.
+ * Ordering and pagination are applied only to the list query.
+ *
+ * The function supports both camelCase and snake_case filters,
+ * controlled by the `snakeCase` flag.
  *
  * @async
+ * @param {Object} params
+ * @param {import('knex').Knex.QueryBuilder} params.baseQuery
+ *   A prepared Knex query builder representing the base query.
+ *   It should not include pagination or ordering.
+ *
+ * @param {Object} [params.filter={}]
+ *   An object describing filter conditions to apply.
+ *   The structure is expected to be compatible with `applyFilter`
+ *   or `applyFilterSnakeCase`.
+ *
+ * @param {boolean} [params.snakeCase=true]
+ *   When true, applies filters assuming database columns
+ *   are in snake_case. When false, camelCase is assumed.
+ *
+ * @param {Object|Array} [params.orderBy]
+ *   Ordering definition passed directly to `applyOrderBy`.
+ *   Can be a single order definition or an array of them.
+ *
+ * @param {number} [params.page=1]
+ *   The current page number. Pages are 1-based.
+ *
+ * @param {number} [params.limit=10]
+ *   The maximum number of rows per page.
+ *
+ * @param {Function} [params.mapRow]
+ *   Optional mapping function applied to each returned row.
+ *   Useful for transforming DB rows into domain entities.
+ *
+ * @returns {Promise<Object>} Pagination result object
+ * @returns {number} return.page
+ *   The current page number.
+ *
+ * @returns {number} return.pages
+ *   Total number of available pages.
+ *
+ * @returns {number} return.totalCount
+ *   Total number of records matching the filters.
+ *
+ * @returns {boolean} return.hasPrevious
+ *   Indicates whether a previous page exists.
+ *
+ * @returns {boolean} return.hasNext
+ *   Indicates whether a next page exists.
+ *
+ * @returns {Array<Object>} return.list
+ *   The list of records for the current page.
+ *   Rows are mapped using `mapRow` if provided.
  */
 export async function sqlPaginate({
   mapRow,
@@ -35,14 +93,14 @@ export async function sqlPaginate({
   ])
 
   const totalCount = normalizeNumberOrDefault(countResult?.count || 0)
-  const totalPages = Math.ceil(totalCount / limit)
+  const pages = Math.ceil(totalCount / limit)
 
   return {
+    page,
+    pages,
     totalCount,
-    totalPages,
-    currentPage: page,
     hasPrevious: page > 1,
-    hasNext: page < totalPages,
+    hasNext: page < pages,
     list: mapRow ? rows.map(mapRow) : rows,
   }
 }

package/tests/postgresql/apply-filter-snake-case.integration.test.js

@@ -12,10 +12,10 @@ import { applyFilterSnakeCase } from '../../src/postgresql/filters/apply-filter-
 
 const PG_OPTIONS = {
   port: 5444,
-  containerName: 'postgres-apply-filter-test-5444',
+  db: 'testdb',
   user: 'testuser',
   pass: 'testpass',
-  db: 'testdb',
+  containerName: 'postgres-apply-filter-test-5444',
 }
 
 const DATABASE_URI = buildPostgresUri(PG_OPTIONS)

package/tests/postgresql/apply-filter.integration.test.js

@@ -3,8 +3,8 @@ import { describe, it, beforeAll, afterAll, beforeEach, expect } from 'vitest'
 import knex from 'knex'
 
 import {
-  startPostgres,
   stopPostgres,
+  startPostgres,
   buildPostgresUri,
 } from '../../src/postgresql/start-stop-postgres-docker.js'
 
@@ -12,10 +12,10 @@ import { applyFilter } from '../../src/postgresql/filters/apply-filter.js'
 
 const PG_OPTIONS = {
   port: 5443,
-  containerName: 'postgres-apply-filter-test',
+  db: 'testdb',
   user: 'testuser',
   pass: 'testpass',
-  db: 'testdb',
+  containerName: 'postgres-apply-filter-test',
 }
 
 const DATABASE_URI = buildPostgresUri(PG_OPTIONS)

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

@@ -9,13 +9,14 @@ import {
 } from '../../src/postgresql/start-stop-postgres-docker.js'
 
 import { sqlPaginate } from '../../src/postgresql/pagination/paginate.js'
+import { sub } from 'date-fns'
 
 const PG_OPTIONS = {
   port: 5442,
-  containerName: 'postgres-paginate-test-5442',
+  db: 'testdb',
   user: 'testuser',
   pass: 'testpass',
-  db: 'testdb',
+  containerName: 'postgres-paginate-test-5442',
 }
 
 const DATABASE_URI = buildPostgresUri(PG_OPTIONS)
@@ -34,6 +35,7 @@ beforeAll(async () => {
     table.uuid('id').primary()
     table.string('name').notNullable()
     table.string('type').notNullable()
+    table.bigInteger('age').notNullable()
     table.timestamp('created_at').notNullable()
   })
 })
@@ -47,41 +49,60 @@ afterAll(async () => {
 
 beforeEach(async () => {
   await db('tenants').truncate()
-
-  await db('tenants').insert([
+  const records = [
     {
       id: '00000000-0000-0000-0000-000000000001',
       name: 'Tenant A',
       type: 'business',
-      created_at: new Date('2024-01-01'),
+      age: 2,
+      created_at: new Date('2025-01-01'),
     },
     {
       id: '00000000-0000-0000-0000-000000000002',
       name: 'Tenant B',
+      age: 3,
       type: 'business',
       created_at: new Date('2024-01-02'),
     },
     {
       id: '00000000-0000-0000-0000-000000000003',
       name: 'Tenant C',
+      age: 1,
+      type: 'cpa',
+      created_at: new Date('2023-01-03'),
+    },
+
+    {
+      id: '00000000-0000-0000-0000-000000000004',
+      name: 'Tenant D',
+      age: 7,
+      type: 'cpa',
+      created_at: new Date('2022-01-03'),
+    },
+
+    {
+      id: '00000000-0000-0000-0000-000000000005',
+      name: 'Tenant E',
+      age: 0,
       type: 'cpa',
-      created_at: new Date('2024-01-03'),
+      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: 1,
+      page: 2,
       limit: 2,
     })
 
-    expect(result.totalCount).toBe(3)
-    expect(result.totalPages).toBe(2)
-    expect(result.currentPage).toBe(1)
-    expect(result.hasPrevious).toBe(false)
+    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)
   })
@@ -93,19 +114,23 @@ describe('paginate integration', () => {
       limit: 2,
     })
 
-    expect(result.totalCount).toBe(3)
-    expect(result.totalPages).toBe(2)
-    expect(result.currentPage).toBe(2)
+    expect(result.totalCount).toBe(5)
+    expect(result.pages).toBe(3)
+    expect(result.page).toBe(2)
     expect(result.hasPrevious).toBe(true)
-    expect(result.hasNext).toBe(false)
-    expect(result.list).toHaveLength(1)
+    expect(result.hasNext).toBe(true)
+    expect(result.list).toHaveLength(2)
   })
 
   it('applies filters correctly', async () => {
+    const minDate = sub(new Date(), { years: 2 })
     const result = await sqlPaginate({
       baseQuery: db('tenants'),
-      filter: { type: 'business' },
+      filter: {
+        createdAt: { lte: new Date(), gte: minDate },
+      },
       limit: 10,
+      page: 1,
     })
 
     expect(result.totalCount).toBe(2)
@@ -118,7 +143,7 @@ describe('paginate integration', () => {
     const result = await sqlPaginate({
       baseQuery: db('tenants'),
       orderBy: {
-        column: 'created_at',
+        column: 'name',
         direction: 'asc',
       },
     })
@@ -127,6 +152,8 @@ describe('paginate integration', () => {
       'Tenant A',
       'Tenant B',
       'Tenant C',
+      'Tenant D',
+      'Tenant E',
     ])
   })
 
@@ -150,7 +177,7 @@ describe('paginate integration', () => {
     })
 
     expect(result.totalCount).toBe(0)
-    expect(result.totalPages).toBe(0)
+    expect(result.pages).toBe(0)
     expect(result.list).toEqual([])
     expect(result.hasNext).toBe(false)
     expect(result.hasPrevious).toBe(false)

package/tests/postgresql/pagination/paginate.js

@@ -1,3 +1,4 @@
+// @ts-nocheck
 import { applyFilter } from '../filters/apply-filter.js'
 import { applyFilterSnakeCase } from '../filters/apply-filter-snake-case.js'
 import { applyOrderBy } from '../modifiers/apply-order-by.js'
@@ -35,14 +36,14 @@ export async function sqlPaginate({
   ])
 
   const totalCount = normalizeNumberOrDefault(countResult?.count || 0)
-  const totalPages = Math.ceil(totalCount / limit)
+  const pages = Math.ceil(totalCount / limit)
 
   return {
     totalCount,
-    totalPages,
+    pages,
     currentPage: page,
     hasPrevious: page > 1,
-    hasNext: page < totalPages,
+    hasNext: page < pages,
     list: mapRow ? rows.map(mapRow) : rows,
   }
 }

package/tests/postgresql/validate-schema.integration.test.js

@@ -11,10 +11,10 @@ import { validateSchema } from '../../src/postgresql/validate-schema.js'
 
 const PG_OPTIONS = {
   port: 5431,
-  containerName: 'postgres-validate-schema-test-5431',
+  db: 'testdb',
   user: 'testuser',
   pass: 'testpass',
-  db: 'testdb',
+  containerName: 'postgres-validate-schema-test-5431',
 }
 
 const DATABASE_URI = buildPostgresUri(PG_OPTIONS)

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

@@ -1,7 +1,65 @@
 /**
- * Executes paginated query.
+ * Executes a paginated SQL query using a Knex query builder.
+ *
+ * This helper clones the provided base query twice:
+ * one query is used to fetch the paginated list of rows,
+ * and the second query is used to calculate the total count
+ * of records matching the same filters.
+ *
+ * Filters are applied consistently to both queries.
+ * Ordering and pagination are applied only to the list query.
+ *
+ * The function supports both camelCase and snake_case filters,
+ * controlled by the `snakeCase` flag.
  *
  * @async
+ * @param {Object} params
+ * @param {import('knex').Knex.QueryBuilder} params.baseQuery
+ *   A prepared Knex query builder representing the base query.
+ *   It should not include pagination or ordering.
+ *
+ * @param {Object} [params.filter={}]
+ *   An object describing filter conditions to apply.
+ *   The structure is expected to be compatible with `applyFilter`
+ *   or `applyFilterSnakeCase`.
+ *
+ * @param {boolean} [params.snakeCase=true]
+ *   When true, applies filters assuming database columns
+ *   are in snake_case. When false, camelCase is assumed.
+ *
+ * @param {Object|Array} [params.orderBy]
+ *   Ordering definition passed directly to `applyOrderBy`.
+ *   Can be a single order definition or an array of them.
+ *
+ * @param {number} [params.page=1]
+ *   The current page number. Pages are 1-based.
+ *
+ * @param {number} [params.limit=10]
+ *   The maximum number of rows per page.
+ *
+ * @param {Function} [params.mapRow]
+ *   Optional mapping function applied to each returned row.
+ *   Useful for transforming DB rows into domain entities.
+ *
+ * @returns {Promise<Object>} Pagination result object
+ * @returns {number} return.page
+ *   The current page number.
+ *
+ * @returns {number} return.pages
+ *   Total number of available pages.
+ *
+ * @returns {number} return.totalCount
+ *   Total number of records matching the filters.
+ *
+ * @returns {boolean} return.hasPrevious
+ *   Indicates whether a previous page exists.
+ *
+ * @returns {boolean} return.hasNext
+ *   Indicates whether a next page exists.
+ *
+ * @returns {Array<Object>} return.list
+ *   The list of records for the current page.
+ *   Rows are mapped using `mapRow` if provided.
  */
 export function sqlPaginate({
   mapRow,
@@ -12,18 +70,11 @@ export function sqlPaginate({
   filter,
   snakeCase,
 }: {
-  mapRow: any
-  orderBy: any
+  baseQuery: import('knex').Knex.QueryBuilder
+  filter?: any
+  snakeCase?: boolean
+  orderBy?: any | any[]
   page?: number
-  baseQuery: any
   limit?: number
-  filter?: {}
-  snakeCase?: boolean
-}): Promise<{
-  totalCount: number
-  totalPages: number
-  currentPage: number
-  hasPrevious: boolean
-  hasNext: boolean
-  list: any
-}>
+  mapRow?: Function
+}): Promise<any>