core-services-sdk 1.3.63 → 1.3.65

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

@@ -8,11 +8,11 @@ import {
   buildPostgresUri,
 } from '../../src/postgresql/start-stop-postgres-docker.js'
 
-import { sqlPaginate } from '../../src/postgresql/paginate.js'
+import { sqlPaginate } from '../../src/postgresql/pagination/paginate.js'
 
 const PG_OPTIONS = {
-  port: 5443,
-  containerName: 'postgres-paginate-test',
+  port: 5442,
+  containerName: 'postgres-paginate-test-5442',
   user: 'testuser',
   pass: 'testpass',
   db: 'testdb',
@@ -73,8 +73,7 @@ beforeEach(async () => {
 describe('paginate integration', () => {
   it('returns first page without ordering guarantees', async () => {
     const result = await sqlPaginate({
-      db,
-      tableName: 'tenants',
+      baseQuery: db('tenants'),
       page: 1,
       limit: 2,
     })
@@ -84,14 +83,12 @@ describe('paginate integration', () => {
     expect(result.currentPage).toBe(1)
     expect(result.hasPrevious).toBe(false)
     expect(result.hasNext).toBe(true)
-
     expect(result.list).toHaveLength(2)
   })
 
   it('returns second page without ordering guarantees', async () => {
     const result = await sqlPaginate({
-      db,
-      tableName: 'tenants',
+      baseQuery: db('tenants'),
       page: 2,
       limit: 2,
     })
@@ -101,14 +98,12 @@ describe('paginate integration', () => {
     expect(result.currentPage).toBe(2)
     expect(result.hasPrevious).toBe(true)
     expect(result.hasNext).toBe(false)
-
     expect(result.list).toHaveLength(1)
   })
 
-  it('applies filters correctly without ordering guarantees', async () => {
+  it('applies filters correctly', async () => {
     const result = await sqlPaginate({
-      db,
-      tableName: 'tenants',
+      baseQuery: db('tenants'),
       filter: { type: 'business' },
       limit: 10,
     })
@@ -121,8 +116,7 @@ describe('paginate integration', () => {
 
   it('supports custom ordering', async () => {
     const result = await sqlPaginate({
-      db,
-      tableName: 'tenants',
+      baseQuery: db('tenants'),
       orderBy: {
         column: 'created_at',
         direction: 'asc',
@@ -138,8 +132,7 @@ describe('paginate integration', () => {
 
   it('supports row mapping', async () => {
     const result = await sqlPaginate({
-      db,
-      tableName: 'tenants',
+      baseQuery: db('tenants'),
       mapRow: (row) => ({
         ...row,
         mapped: true,
@@ -152,8 +145,7 @@ describe('paginate integration', () => {
 
   it('returns empty list when no records match filter', async () => {
     const result = await sqlPaginate({
-      db,
-      tableName: 'tenants',
+      baseQuery: db('tenants'),
       filter: { type: 'non-existing' },
     })
 

package/tests/postgresql/pagination/paginate.js

@@ -0,0 +1,48 @@
+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 { normalizeNumberOrDefault } from '../../core/normalize-premitives-types-or-default.js'
+
+/**
+ * Executes paginated query.
+ *
+ * @async
+ */
+export async function sqlPaginate({
+  mapRow,
+  orderBy,
+  page = 1,
+  baseQuery,
+  limit = 10,
+  filter = {},
+  snakeCase = true,
+}) {
+  const listQuery = baseQuery.clone()
+  const countQuery = baseQuery.clone()
+
+  const applyFilterFn = snakeCase ? applyFilterSnakeCase : applyFilter
+
+  applyFilterFn({ query: listQuery, filter })
+  applyFilterFn({ query: countQuery, filter })
+
+  applyOrderBy({ query: listQuery, orderBy })
+  applyPagination({ query: listQuery, page, limit })
+
+  const [rows, countResult] = await Promise.all([
+    listQuery.select('*'),
+    countQuery.count('* as count').first(),
+  ])
+
+  const totalCount = normalizeNumberOrDefault(countResult?.count || 0)
+  const totalPages = Math.ceil(totalCount / limit)
+
+  return {
+    totalCount,
+    totalPages,
+    currentPage: page,
+    hasPrevious: page > 1,
+    hasNext: page < totalPages,
+    list: mapRow ? rows.map(mapRow) : rows,
+  }
+}

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

@@ -5,12 +5,13 @@ import {
   stopPostgres,
   buildPostgresUri,
 } from '../../src/postgresql/start-stop-postgres-docker.js'
+
 import { connectToPg } from '../../src/postgresql/connect-to-pg.js'
 import { validateSchema } from '../../src/postgresql/validate-schema.js'
 
 const PG_OPTIONS = {
-  port: 5433,
-  containerName: 'postgres-validate-schema-test',
+  port: 5431,
+  containerName: 'postgres-validate-schema-test-5431',
   user: 'testuser',
   pass: 'testpass',
   db: 'testdb',
@@ -18,7 +19,7 @@ const PG_OPTIONS = {
 
 const DATABASE_URI = buildPostgresUri(PG_OPTIONS)
 
-describe('validateSchema', () => {
+describe('validateSchema integration', () => {
   beforeAll(async () => {
     startPostgres(PG_OPTIONS)
 
@@ -32,13 +33,16 @@ describe('validateSchema', () => {
     await db.destroy()
   })
 
-  afterAll(() => {
+  afterAll(async () => {
     stopPostgres(PG_OPTIONS.containerName)
   })
 
   it('does not throw when all required tables exist', async () => {
     await expect(
-      validateSchema({ connection: DATABASE_URI, tables: ['files'] }),
+      validateSchema({
+        connection: DATABASE_URI,
+        tables: ['files'],
+      }),
     ).resolves.not.toThrow()
   })
 

package/types/core/normalize-phone-number.d.ts

@@ -1,25 +1,82 @@
-/** Resolve libphonenumber regardless of interop shape */
-export function getLib(): any
-export function phoneUtil(): any
 /**
- * Parse & validate an international number (must start with '+').
- * @param {string} input
- * @returns {{e164:string,national:string,international:string,regionCode:string|undefined,type:number}}
- * @throws {Error} If the number is invalid
+ * @typedef {Object} NormalizedPhone
+ * @property {string} e164
+ * @property {number} type
+ * @property {string} national
+ * @property {number} countryCode
+ * @property {string} nationalClean
+ * @property {string} international
+ * @property {string} countryCodeE164
+ * @property {string} internationalClean
+ * @property {string | undefined} regionCode
  */
-export function normalizePhoneOrThrowIntl(input: string): {
-  e164: string
-  national: string
-  international: string
-  regionCode: string | undefined
-  type: number
+/**
+ * normalize-phone-number.js
+ *
+ * Utilities for parsing, validating, and normalizing phone numbers
+ * using google-libphonenumber.
+ *
+ * Supports both ESM and CJS interop builds.
+ * All normalization outputs are canonical and safe for persistence,
+ * comparison, indexing, and login identifiers.
+ */
+/**
+ * Resolve google-libphonenumber exports regardless of ESM / CJS shape.
+ *
+ * Some builds expose:
+ *   - raw.PhoneNumberUtil
+ * Others expose:
+ *   - raw.default.PhoneNumberUtil
+ *
+ * This helper guarantees a consistent API.
+ *
+ * @returns {{
+ *   PhoneNumberUtil: any,
+ *   PhoneNumberFormat: any
+ * }}
+ * @throws {Error} If required exports are missing
+ */
+export function getLib(): {
+  PhoneNumberUtil: any
+  PhoneNumberFormat: any
 }
 /**
- * Parse & validate a national number using a region hint.
- * @param {string} input
- * @param {string} defaultRegion
- * @returns {{e164:string,national:string,international:string,regionCode:string|undefined,type:number}}
- * @throws {Error} If the number is invalid
+ * Lazy singleton accessor for PhoneNumberUtil.
+ *
+ * Ensures:
+ * - Single instance per process
+ * - No eager initialization cost
+ *
+ * @returns {any} PhoneNumberUtil instance
+ */
+export function phoneUtil(): any
+/**
+ * Normalize and validate an international phone number.
+ *
+ * Input MUST start with '+'.
+ *
+ * @param {string} input International phone number (E.164-like)
+ * @returns {NormalizedPhone}
+ * @throws {Error} If the phone number is invalid
+ */
+export function normalizePhoneOrThrowIntl(input: string): NormalizedPhone
+/**
+ * Normalize and validate a national phone number using a region hint.
+ *
+ * Example:
+ *   input: "0523444444"
+ *   defaultRegion: "IL"
+ *
+ * @param {string} input National phone number
+ * @param {string} defaultRegion ISO 3166-1 alpha-2 country code
+ * @returns {{
+ *   e164: string,
+ *   national: string,
+ *   international: string,
+ *   regionCode: string | undefined,
+ *   type: number
+ * }}
+ * @throws {Error} If the phone number is invalid
  */
 export function normalizePhoneOrThrowWithRegion(
   input: string,
@@ -32,23 +89,36 @@ export function normalizePhoneOrThrowWithRegion(
   type: number
 }
 /**
- * Smart normalization:
- * - If input starts with '+', parse as international.
- * - Otherwise require a defaultRegion and parse as national.
- * @param {string} input
- * @param {{ defaultRegion?: string }} [opts]
- * @returns {{e164:string,national:string,international:string,regionCode:string|undefined,type:number}}
- * @throws {Error} If invalid or defaultRegion is missing for non-international input
+ * Smart normalization entry point.
+ *
+ * Behavior:
+ * - If input starts with '+', parses as international
+ * - Otherwise requires defaultRegion and parses as national
+ *
+ * This is the recommended function for login, signup, and verification flows.
+ *
+ * @param {string} input Phone number (international or national)
+ * @param {{
+ *   defaultRegion?: string
+ * }} [opts]
+ *
+ * @returns {NormalizedPhone}
+ * @throws {Error} If invalid or defaultRegion is missing
  */
 export function normalizePhoneOrThrow(
   input: string,
   opts?: {
     defaultRegion?: string
   },
-): {
+): NormalizedPhone
+export type NormalizedPhone = {
   e164: string
+  type: number
   national: string
+  countryCode: number
+  nationalClean: string
   international: string
+  countryCodeE164: string
+  internationalClean: string
   regionCode: string | undefined
-  type: number
 }

package/types/postgresql/apply-filter.d.ts

@@ -2,9 +2,10 @@
  * Builds a Knex query with MongoDB-style filter operators.
  * Pure utility function that can be used across repositories.
  *
- * This function converts camelCase filter keys to snake_case and applies
- * various filter operators to build SQL WHERE clauses. All column names
- * are automatically qualified with the provided table name.
+ * This function applies various filter operators to build SQL WHERE clauses. All column names
+ * are automatically qualified with the provided table name. Filter keys are used as-is without
+ * any case conversion. If you need automatic camelCase to snake_case conversion, use
+ * {@link applyFilterSnakeCase} instead.
  *
  * **Supported Operators:**
  * - `eq` - Equality (default for simple values)
@@ -21,15 +22,19 @@
  * - `isNotNull` - Check if field is NOT NULL
  *
  * **Key Features:**
- * - Automatic camelCase to snake_case conversion for filter keys
+ * - Filter keys are used as-is (no automatic case conversion)
  * - Qualified column names (table.column format)
  * - Multiple operators can be applied to the same field
  * - Unknown operators are silently ignored
  * - Arrays are automatically converted to IN clauses
  *
+ * **Note:** This function does NOT convert filter keys. If your database uses snake_case columns
+ * but your filter keys are in camelCase, use {@link applyFilterSnakeCase} instead, or ensure
+ * your filter keys already match your database column names.
+ *
  * @param {Object} params - Function parameters
  * @param {import('knex').Knex.QueryBuilder} params.query - Knex query builder instance to apply filters to
- * @param {Object<string, *>} params.filter - Filter object with camelCase keys (will be converted to snake_case)
+ * @param {Object<string, *>} params.filter - Filter object with keys matching database column names (used as-is)
  *   Filter values can be:
  *   - Simple values (string, number, boolean) → treated as equality
  *   - Arrays → treated as IN operator
@@ -89,9 +94,10 @@
  * })
  *
  * @example
- * // camelCase conversion - deletedAt converts to deleted_at
- * applyFilter({ query, filter: { deletedAt: { isNull: true } }, tableName: 'assets' })
+ * // Filter keys are used as-is - ensure they match your database column names
+ * applyFilter({ query, filter: { deleted_at: { isNull: true } }, tableName: 'assets' })
  * // SQL: WHERE assets.deleted_at IS NULL
+ * // Note: If you need camelCase conversion, use applyFilterSnakeCase instead
  */
 export function applyFilter({
   query,
@@ -104,17 +110,122 @@ export function applyFilter({
   }
   tableName: string
 }): import('knex').Knex.QueryBuilder
-export type OperatorFunction = {
-  /**
-   * - Knex query builder instance
-   */
+/**
+ * Applies MongoDB-style filter operators to a Knex query with automatic camelCase to snake_case conversion.
+ *
+ * This function is a convenience wrapper around {@link applyFilter} that automatically converts
+ * all filter keys from camelCase to snake_case before applying the filters. This is useful when
+ * your application code uses camelCase naming conventions but your database columns use snake_case.
+ *
+ * The function first converts all filter object keys using `toSnakeCase`, then applies the filters
+ * using the standard `applyFilter` function. This ensures that filter keys like `userId` are
+ * converted to `user_id` before being used in SQL queries.
+ *
+ * **Key Features:**
+ * - Automatic camelCase to snake_case key conversion
+ * - Same operator support as `applyFilter`
+ * - Qualified column names (table.column format)
+ * - Multiple operators can be applied to the same field
+ * - Arrays are automatically converted to IN clauses
+ *
+ * **Supported Operators:**
+ * Same as {@link applyFilter}:
+ * - `eq` - Equality (default for simple values)
+ * - `ne` / `neq` - Not equal
+ * - `in` - Array membership (or pass array directly)
+ * - `nin` - Not in array
+ * - `gt` - Greater than
+ * - `gte` - Greater than or equal
+ * - `lt` - Less than
+ * - `lte` - Less than or equal
+ * - `like` - Case-sensitive pattern matching (SQL LIKE)
+ * - `ilike` - Case-insensitive pattern matching (PostgreSQL ILIKE)
+ * - `isNull` - Check if field is NULL
+ * - `isNotNull` - Check if field is NOT NULL
+ *
+ * @param {Object} params - Function parameters
+ * @param {import('knex').Knex.QueryBuilder} params.query - Knex query builder instance to apply filters to
+ * @param {Object<string, *>} params.filter - Filter object with camelCase keys (will be converted to snake_case)
+ *   Filter values can be:
+ *   - Simple values (string, number, boolean) → treated as equality
+ *   - Arrays → treated as IN operator
+ *   - Objects with operator keys → apply specific operators
+ * @param {string} params.tableName - Table name used to qualify column names (e.g., "assets" → "assets.column_name")
+ * @returns {import('knex').Knex.QueryBuilder} Modified query builder with applied WHERE clauses (using snake_case column names)
+ *
+ * @throws {TypeError} If query is not a valid Knex QueryBuilder instance
+ *
+ * @example
+ * // Simple equality with camelCase key - converts to WHERE assets.user_id = 1
+ * const query = db('assets').select('*')
+ * applyFilterSnakeCase({ query, filter: { userId: 1 }, tableName: 'assets' })
+ * // SQL: WHERE assets.user_id = 1
+ *
+ * @example
+ * // Not equal with camelCase key - converts to WHERE assets.status != 'deleted'
+ * applyFilterSnakeCase({
+ *   query,
+ *   filter: { status: { ne: 'deleted' } },
+ *   tableName: 'assets'
+ * })
+ * // SQL: WHERE assets.status != 'deleted'
+ *
+ * @example
+ * // Array/IN operator with camelCase key - converts to WHERE assets.status IN ('active', 'pending')
+ * applyFilterSnakeCase({
+ *   query,
+ *   filter: { status: ['active', 'pending'] },
+ *   tableName: 'assets'
+ * })
+ * // SQL: WHERE assets.status IN ('active', 'pending')
+ *
+ * @example
+ * // Range operators with camelCase keys - converts to WHERE assets.price >= 100 AND assets.price <= 200
+ * applyFilterSnakeCase({
+ *   query,
+ *   filter: { price: { gte: 100, lte: 200 } },
+ *   tableName: 'assets'
+ * })
+ * // SQL: WHERE assets.price >= 100 AND assets.price <= 200
+ *
+ * @example
+ * // Null checks with camelCase key - converts to WHERE assets.deleted_at IS NULL
+ * applyFilterSnakeCase({
+ *   query,
+ *   filter: { deletedAt: { isNull: true } },
+ *   tableName: 'assets'
+ * })
+ * // SQL: WHERE assets.deleted_at IS NULL
+ *
+ * @example
+ * // Multiple filters with camelCase keys
+ * applyFilterSnakeCase({
+ *   query,
+ *   filter: {
+ *     userId: 123,              // Converts to user_id
+ *     createdAt: { gte: '2024-01-01' },  // Converts to created_at
+ *     status: 'active'
+ *   },
+ *   tableName: 'assets'
+ * })
+ * // SQL: WHERE assets.user_id = 123 AND assets.created_at >= '2024-01-01' AND assets.status = 'active'
+ *
+ * @see {@link applyFilter} For the base function without key conversion
+ * @see {@link toSnakeCase} For details on the key conversion process
+ */
+export function applyFilterSnakeCase({
+  query,
+  filter,
+  tableName,
+}: {
   query: import('knex').Knex.QueryBuilder
-  /**
-   * - Column name (qualified with table name)
-   */
-  key: string
-  /**
-   * - Value to compare against
-   */
-  value: any
-}
+  filter: {
+    [x: string]: any
+  }
+  tableName: string
+}): import('knex').Knex.QueryBuilder
+/**
+ * Type definition for filter operator functions.
+ * Each operator function applies a WHERE condition to a Knex query builder.
+ */
+export type OperatorFunction = Function

package/types/postgresql/core/get-table-name.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Extracts base table name from Knex QueryBuilder.
+ * Relies on Knex internal structure.
+ *
+ * @param {import('knex').Knex.QueryBuilder} query
+ * @returns {string|undefined}
+ */
+export function getTableNameFromQuery(
+  query: import('knex').Knex.QueryBuilder,
+): string | undefined

package/types/postgresql/filters/apply-filter-object.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Applies multiple operators on the same column.
+ *
+ * @param {import('knex').Knex.QueryBuilder} query
+ * @param {string} qualifiedKey
+ * @param {Object<string, *>} value
+ * @returns {import('knex').Knex.QueryBuilder}
+ */
+export function applyFilterObject(
+  query: import('knex').Knex.QueryBuilder,
+  qualifiedKey: string,
+  value: {
+    [x: string]: any
+  },
+): import('knex').Knex.QueryBuilder

package/types/postgresql/filters/apply-filter-snake-case.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Applies filters with automatic camelCase to snake_case conversion.
+ *
+ * @param {Object} params
+ * @param {import('knex').Knex.QueryBuilder} params.query
+ * @param {Object} params.filter
+ */
+export function applyFilterSnakeCase({
+  query,
+  filter,
+}: {
+  query: import('knex').Knex.QueryBuilder
+  filter: any
+}): import('knex').Knex.QueryBuilder<any, any>

package/types/postgresql/filters/apply-filter.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Applies MongoDB-style filters to a Knex QueryBuilder.
+ *
+ * @param {Object} params
+ * @param {import('knex').Knex.QueryBuilder} params.query
+ * @param {Object} [params.filter]
+ * @returns {import('knex').Knex.QueryBuilder}
+ */
+export function applyFilter({
+  query,
+  filter,
+}: {
+  query: import('knex').Knex.QueryBuilder
+  filter?: any
+}): import('knex').Knex.QueryBuilder

package/types/postgresql/filters/operators.d.ts

@@ -0,0 +1,14 @@
+/**
+ * @typedef {Function} OperatorFunction
+ * @param {import('knex').Knex.QueryBuilder} q
+ * @param {string} key
+ * @param {*} value
+ * @returns {import('knex').Knex.QueryBuilder}
+ */
+/**
+ * @type {Object<string, OperatorFunction>}
+ */
+export const OPERATORS: {
+  [x: string]: Function
+}
+export type OperatorFunction = Function

package/types/postgresql/index.d.ts

@@ -1,5 +1,8 @@
-export * from './paginate.js'
-export * from './apply-filter.js'
 export * from './connect-to-pg.js'
 export * from './validate-schema.js'
+export * from './pagination/paginate.js'
+export * from './filters/apply-filter.js'
+export * from './modifiers/apply-order-by.js'
 export * from './start-stop-postgres-docker.js'
+export * from './modifiers/apply-pagination.js'
+export * from './filters/apply-filter-snake-case.js'

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

@@ -0,0 +1,17 @@
+/**
+ * Applies ORDER BY clause.
+ *
+ * @param {Object} params
+ * @param {import('knex').Knex.QueryBuilder} params.query
+ * @param {{ column: string, direction?: 'asc'|'desc' }} params.orderBy
+ */
+export function applyOrderBy({
+  query,
+  orderBy,
+}: {
+  query: import('knex').Knex.QueryBuilder
+  orderBy: {
+    column: string
+    direction?: 'asc' | 'desc'
+  }
+}): import('knex').Knex.QueryBuilder<any, any>

package/types/postgresql/modifiers/apply-pagination.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Applies LIMIT and OFFSET.
+ *
+ * @param {Object} params
+ * @param {import('knex').Knex.QueryBuilder} params.query
+ * @param {number} [params.page=1]
+ * @param {number} [params.limit=10]
+ */
+export function applyPagination({
+  query,
+  page,
+  limit,
+}: {
+  query: import('knex').Knex.QueryBuilder
+  page?: number
+  limit?: number
+}): import('knex').Knex.QueryBuilder<any, any>

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

@@ -0,0 +1,29 @@
+/**
+ * Executes paginated query.
+ *
+ * @async
+ */
+export function sqlPaginate({
+  mapRow,
+  orderBy,
+  page,
+  baseQuery,
+  limit,
+  filter,
+  snakeCase,
+}: {
+  mapRow: any
+  orderBy: any
+  page?: number
+  baseQuery: any
+  limit?: number
+  filter?: {}
+  snakeCase?: boolean
+}): Promise<{
+  totalCount: number
+  totalPages: number
+  currentPage: number
+  hasPrevious: boolean
+  hasNext: boolean
+  list: any
+}>