@owlmeans/postgres-resource 0.1.18-rc.42 → 0.1.18-rc.43

package/src/errors.ts

@@ -1,10 +1,5 @@
 import { ResilientError } from '@owlmeans/error'
-import {
-  MisshapedRecord, RecordExists, ResourceError
-} from '@owlmeans/resource'
-
-import { PgErrorCode } from './consts.js'
-import type { PgDriverError } from './types.local.js'
+import { ResourceError } from '@owlmeans/resource'
 
 export class PostgresError extends ResourceError {
   public static override typeName = `${ResourceError.typeName}PostgresError`
@@ -107,121 +102,6 @@ export class PostgresBootstrapError extends PostgresError {
   }
 }
 
-const isDriverError = (error: unknown): error is PgDriverError =>
-  error != null && typeof error === 'object' && 'code' in error
-
-/**
- * Reach the `pg` error inside whatever wrapped it.
- *
- * Drizzle raises `DrizzleQueryError` and hangs the driver error off `cause`, so a unique
- * violation arriving through the query builder carries no `code` at the top level. Reading
- * only the outer error is what makes the whole vocabulary below collapse to one opaque
- * class on every CRUD path — and it is exactly the paths that go through Drizzle.
- *
- * The walk is bounded because `cause` chains can be circular.
- */
-const unwrap = (error: unknown): unknown => {
-  let current = error
-  for (let depth = 0; depth < 8; depth += 1) {
-    if (isDriverError(current)) {
-      return current
-    }
-    const cause = (current as { cause?: unknown } | null)?.cause
-    if (cause == null || cause === current) {
-      return error
-    }
-    current = cause
-  }
-
-  return error
-}
-
-/**
- * The framework's error marshalling preserves only type, message and stack, so the
- * Postgres diagnostics have to travel inside the message. Downstream tooling — notably
- * the viable-agent fixer, which retries on `42P01` / `42703` — classifies on exactly
- * this text, so the code always leads.
- *
- * `where` is deliberately never included: it can echo bound parameter values.
- *
- * Exported so a wrapper can quote the diagnostics without also quoting the translated error's
- * own type prefix, which would nest one error vocabulary inside another's message.
- */
-export const describePgError = (error: unknown): string => {
-  const driver = unwrap(error)
-  if (!isDriverError(driver)) {
-    return error instanceof Error ? error.message : `${error}`
-  }
-
-  return describe(driver)
-}
-
-const describe = (error: PgDriverError): string => {
-  const parts = [error.code ?? 'unknown']
-  if (error.message != null) parts.push(error.message)
-  if (error.constraint != null) parts.push(`constraint=${error.constraint}`)
-  if (error.table != null) parts.push(`table=${error.table}`)
-  if (error.column != null) parts.push(`column=${error.column}`)
-  if (error.detail != null) parts.push(`detail=${error.detail}`)
-  if (error.hint != null) parts.push(`hint=${error.hint}`)
-  if (error.severity != null) parts.push(`severity=${error.severity}`)
-
-  return parts.join(' ')
-}
-
-/**
- * Translate a raw `pg` driver error into the framework's error vocabulary, so a driver
- * type never escapes the package. Errors that already are `ResilientError`s pass through
- * untouched — the reconciler and the migration runner raise their own.
- * A migration may supply its resolved SQL; placeholders stay intact and parameter values
- * are never added. The statement travels in the message so error marshalling preserves it.
- */
-export const pgErrorToResourceError = (error: unknown, query?: string): Error => {
-  if (error instanceof ResilientError) {
-    return error
-  }
-  const driver = unwrap(error)
-  if (!isDriverError(driver)) {
-    return error instanceof Error ? error : new PostgresError(`${error}`)
-  }
-
-  const message = describe(driver) + (query == null ? '' : `\nSQL: ${query}`)
-  const produce = (): Error => {
-    switch (driver.code) {
-      case PgErrorCode.UniqueViolation:
-        return new RecordExists(message)
-      case PgErrorCode.NotNullViolation:
-        return new MisshapedRecord(message)
-      case PgErrorCode.ForeignKeyViolation:
-        return new PostgresForeignKeyError(message)
-      case PgErrorCode.CheckViolation:
-        return new PostgresCheckError(message)
-      case PgErrorCode.DatatypeMismatch:
-      case PgErrorCode.CannotCoerce:
-        return new PostgresCastRequired(message)
-      case PgErrorCode.SerializationFailure:
-      case PgErrorCode.DeadlockDetected:
-        return new PostgresDeadlockError(message)
-      default:
-        break
-    }
-    if (driver.code != null && driver.code.startsWith('08')) {
-      return new PostgresConnectionError(message)
-    }
-    if (driver.code != null && driver.code.startsWith('23')) {
-      return new PostgresConstraintError(message)
-    }
-
-    return new PostgresError(message)
-  }
-
-  const produced = produce()
-  /** The *original* error, wrapper and all — unwrapping is for classification, not for loss. */
-  produced.cause = error
-
-  return produced
-}
-
 ResilientError.registerErrorClass(PostgresError)
 ResilientError.registerErrorClass(PostgresSyncError)
 ResilientError.registerErrorClass(PostgresCastRequired)

package/src/index.ts

@@ -1,7 +1,10 @@
 export type * from './types.js'
 export * from './consts.js'
 export * from './declarations.js'
+export type * from './declarations/types.js'
 export * from './errors.js'
+export * from './pg-error.js'
+export type * from './pg-error/types.js'
 export * from './helper.js'
 export * from './resource.js'
 export * from './utils/index.js'

package/src/pg-error/types.ts

@@ -0,0 +1,23 @@
+/** Reading and translating the errors the `pg` driver raises. */
+export interface PgErrorHelper {
+  /**
+   * The framework's error marshalling preserves only type, message and stack, so the
+   * Postgres diagnostics have to travel inside the message. Downstream tooling — notably
+   * the viable-agent fixer, which retries on `42P01` / `42703` — classifies on exactly
+   * this text, so the code always leads.
+   *
+   * `where` is deliberately never included: it can echo bound parameter values.
+   *
+   * Exported so a wrapper can quote the diagnostics without also quoting the translated error's
+   * own type prefix, which would nest one error vocabulary inside another's message.
+   */
+  describePgError: (error: unknown) => string
+  /**
+   * Translate a raw `pg` driver error into the framework's error vocabulary, so a driver
+   * type never escapes the package. Errors that already are `ResilientError`s pass through
+   * untouched — the reconciler and the migration runner raise their own.
+   * A migration may supply its resolved SQL; placeholders stay intact and parameter values
+   * are never added. The statement travels in the message so error marshalling preserves it.
+   */
+  pgErrorToResourceError: (error: unknown, query?: string) => Error
+}

package/src/pg-error.ts

@@ -0,0 +1,114 @@
+import { ResilientError } from '@owlmeans/error'
+import { MisshapedRecord, RecordExists } from '@owlmeans/resource'
+
+import { PgErrorCode } from './consts.js'
+import {
+  PostgresCastRequired, PostgresCheckError, PostgresConnectionError, PostgresConstraintError,
+  PostgresDeadlockError, PostgresError, PostgresForeignKeyError
+} from './errors.js'
+import type { PgErrorHelper } from './pg-error/types.js'
+import type { PgDriverError } from './types.local.js'
+
+export const createPgErrorHelper = (): PgErrorHelper => {
+  const isDriverError = (error: unknown): error is PgDriverError =>
+    error != null && typeof error === 'object' && 'code' in error
+
+  /**
+   * Reach the `pg` error inside whatever wrapped it.
+   *
+   * Drizzle raises `DrizzleQueryError` and hangs the driver error off `cause`, so a unique
+   * violation arriving through the query builder carries no `code` at the top level. Reading
+   * only the outer error is what makes the whole vocabulary below collapse to one opaque
+   * class on every CRUD path — and it is exactly the paths that go through Drizzle.
+   *
+   * The walk is bounded because `cause` chains can be circular.
+   */
+  const unwrap = (error: unknown): unknown => {
+    let current = error
+    for (let depth = 0; depth < 8; depth += 1) {
+      if (isDriverError(current)) {
+        return current
+      }
+      const cause = (current as { cause?: unknown } | null)?.cause
+      if (cause == null || cause === current) {
+        return error
+      }
+      current = cause
+    }
+
+    return error
+  }
+
+  const describePgError = (error: unknown): string => {
+    const driver = unwrap(error)
+    if (!isDriverError(driver)) {
+      return error instanceof Error ? error.message : `${error}`
+    }
+
+    return describe(driver)
+  }
+
+  const describe = (error: PgDriverError): string => {
+    const parts = [error.code ?? 'unknown']
+    if (error.message != null) parts.push(error.message)
+    if (error.constraint != null) parts.push(`constraint=${error.constraint}`)
+    if (error.table != null) parts.push(`table=${error.table}`)
+    if (error.column != null) parts.push(`column=${error.column}`)
+    if (error.detail != null) parts.push(`detail=${error.detail}`)
+    if (error.hint != null) parts.push(`hint=${error.hint}`)
+    if (error.severity != null) parts.push(`severity=${error.severity}`)
+
+    return parts.join(' ')
+  }
+
+  const pgErrorToResourceError = (error: unknown, query?: string): Error => {
+    if (error instanceof ResilientError) {
+      return error
+    }
+    const driver = unwrap(error)
+    if (!isDriverError(driver)) {
+      return error instanceof Error ? error : new PostgresError(`${error}`)
+    }
+
+    const message = describe(driver) + (query == null ? '' : `\nSQL: ${query}`)
+    const produce = (): Error => {
+      switch (driver.code) {
+        case PgErrorCode.UniqueViolation:
+          return new RecordExists(message)
+        case PgErrorCode.NotNullViolation:
+          return new MisshapedRecord(message)
+        case PgErrorCode.ForeignKeyViolation:
+          return new PostgresForeignKeyError(message)
+        case PgErrorCode.CheckViolation:
+          return new PostgresCheckError(message)
+        case PgErrorCode.DatatypeMismatch:
+        case PgErrorCode.CannotCoerce:
+          return new PostgresCastRequired(message)
+        case PgErrorCode.SerializationFailure:
+        case PgErrorCode.DeadlockDetected:
+          return new PostgresDeadlockError(message)
+        default:
+          break
+      }
+      if (driver.code != null && driver.code.startsWith('08')) {
+        return new PostgresConnectionError(message)
+      }
+      if (driver.code != null && driver.code.startsWith('23')) {
+        return new PostgresConstraintError(message)
+      }
+
+      return new PostgresError(message)
+    }
+
+    const produced = produce()
+    /** The *original* error, wrapper and all — unwrapping is for classification, not for loss. */
+    produced.cause = error
+
+    return produced
+  }
+
+  return { describePgError, pgErrorToResourceError }
+}
+
+export const pgErrorHelper = createPgErrorHelper()
+

package/src/resource.ts

@@ -5,18 +5,18 @@ import { eq, sql, type SQL } from 'drizzle-orm'
 import type { PoolClient, QueryResultRow } from 'pg'
 
 import { DEFAULT_DB_ALIAS, DEFAULT_PAGE_SIZE, ID_FIELD } from './consts.js'
-import { getDeclaration } from './declarations.js'
-import { pgErrorToResourceError } from './errors.js'
+import { pgDeclarationHelper } from './declarations.js'
 import { getSchemaSecureFeilds } from './helper.js'
+import { pgErrorHelper } from './pg-error.js'
 import type {
   ColumnSpec, PgIndexSpec, PgRuntimeTable, PostgresDb, PostgresDbService, PostgresResource,
   PostgresTx, TableSpec
 } from './types.js'
-import { criteriaToSql, sortToSql } from './utils/criteria.js'
-import { initializeTable } from './utils/life-cycle.js'
-import { recordToFullValues, recordToValues, resultToRecord, rowToRecord } from './utils/marshal.js'
+import { pgCriteriaHelper } from './utils/criteria.js'
+import { makePgLifeCycleHelper } from './utils/life-cycle.js'
+import { pgMarshalHelper } from './utils/marshal.js'
 import { makeTx } from './utils/migrations.js'
-import { refOf, resolvePlaceholders } from './utils/sql.js'
+import { pgPlaceholdersOf } from './utils/sql.js'
 import type { Config, Context } from './types.local.js'
 
 
@@ -34,7 +34,10 @@ export const makePostgresResource = <
   tableName?: string
 ): T => {
   const location = `postgres-resource:${alias}`
-  const declaration = getDeclaration(alias)
+  const declaration = pgDeclarationHelper.getDeclaration(alias)
+  const { pgErrorToResourceError } = pgErrorHelper
+  const { criteriaToSql, sortToSql } = pgCriteriaHelper
+  const { recordToFullValues, recordToValues, resultToRecord, rowToRecord } = pgMarshalHelper
 
   /** Set by `init()`; every data method goes through `ensure()`, which guarantees them. */
   let spec: TableSpec | undefined
@@ -107,7 +110,7 @@ export const makePostgresResource = <
     const context = assertContext<Config, Context>(resource.ctx as Context, location)
     try {
       const result = await db.pool.query<Row>(
-        resolvePlaceholders(text, context, table), params as never[]
+        pgPlaceholdersOf(context).resolvePlaceholders(text, table), params as never[]
       )
 
       return { rows: result.rows, count: result.rowCount ?? 0 }
@@ -397,19 +400,20 @@ export const makePostgresResource = <
         throw new SyntaxError(`Postgres resource not initialized: ${alias}`)
       }
 
-      return refOf(context, spec, resourceAlias)
+      return pgPlaceholdersOf(context).refOf(spec, resourceAlias)
     },
 
     transaction: async fn => {
       const { db, spec: table } = await ensure()
       const context = assertContext<Config, Context>(resource.ctx as Context, location)
+      const placeholders = pgPlaceholdersOf(context)
       const client: PoolClient = await db.pool.connect()
       try {
         await client.query('BEGIN')
         const result = await fn(makeTx(
           client,
-          text => resolvePlaceholders(text, context, table),
-          resourceAlias => refOf(context, table, resourceAlias)
+          text => placeholders.resolvePlaceholders(text, table),
+          resourceAlias => placeholders.refOf(table, resourceAlias)
         ))
         await client.query('COMMIT')
 
@@ -504,8 +508,8 @@ export const makePostgresResource = <
     const db = await postgres.db(dbAlias)
     const config = postgres.config(dbAlias)
 
-    const initialized = await initializeTable(
-      db, config, resource as unknown as PostgresResource<ResourceRecord>, context,
+    const initialized = await makePgLifeCycleHelper(db).initializeTable(
+      config, resource as unknown as PostgresResource<ResourceRecord>, context,
       task => postgres.defer(dbAlias, task)
     )
     spec = initialized.spec

package/src/types.ts

@@ -255,6 +255,7 @@ export interface PgReferenceSpec {
   onUpdate?: PgReferentialAction | `${PgReferentialAction}`
 }
 
+// Kept as a type: it merges an index signature over the table's own members, which an interface refuses.
 /**
  * The Drizzle table `specToTable` compiles from a {@link TableSpec}.
  *

package/src/utils/consts.local.ts

@@ -66,3 +66,6 @@ export const CAST_DATA_CODES: string[] = [
   PgErrorCode.StringDataRightTruncation,
   PgErrorCode.NumericValueOutOfRange
 ]
+
+/** The largest `integer` column value; a schema `maximum` past it needs `bigint`. */
+export const INT32_MAX = 2147483647

package/src/utils/criteria/types.ts

@@ -0,0 +1,32 @@
+import type { Criteria, Sort } from '@owlmeans/resource'
+import type { SQL } from 'drizzle-orm'
+
+import type { PgRuntimeTable, TableSpec } from '../../types.js'
+
+/** The portable criteria and sort vocabulary, as Drizzle SQL over one compiled table. */
+export interface PgCriteriaHelper {
+  /**
+   * Translate a {@link Criteria} into a WHERE clause. `undefined` means "no constraint at
+   * all" — the caller decides whether that is a full scan or a refusal.
+   *
+   * An unknown key raises rather than being skipped: a typo silently widening a query to
+   * the whole table is the failure mode worth being loud about.
+   *
+   * @throws {UnsupportedArgumentError}
+   */
+  criteriaToSql: <T>(criteria: Criteria<T> | undefined, spec: TableSpec, table: PgRuntimeTable) => SQL | undefined
+  /**
+   * Translate a {@link Sort} list into ORDER BY. A bare field name is ascending;
+   * `{ field, order: 'desc' }` reverses it — the same meaning every backend gives it.
+   *
+   * The primary key is always appended as a tiebreak. Postgres has no implicit row order, so
+   * paginating on a non-unique sort key silently duplicates and skips rows between pages —
+   * a difference from mongo that would otherwise surface as a data bug rather than an error.
+   *
+   * A dotted path is a column this table does not have: criteria can reach into jsonb, ORDER BY
+   * cannot, and refusing is better than ordering by something the caller did not name.
+   *
+   * @throws {UnsupportedArgumentError}
+   */
+  sortToSql: <T>(sort: Sort<T>[] | undefined, spec: TableSpec, table: PgRuntimeTable) => SQL[]
+}

package/src/utils/criteria.ts

@@ -4,6 +4,7 @@ import { and, asc, desc, or, param, sql, type SQL } from 'drizzle-orm'
 import type { ColumnSpec, PgRuntimeTable, TableSpec } from '../types.js'
 import { COMPARISON } from './consts.local.js'
 import type { PathTarget } from './types.local.js'
+import type { PgCriteriaHelper } from './criteria/types.js'
 
 const columnRef = (table: PgRuntimeTable, column: ColumnSpec): SQL => sql`${table[column.property]}`
 
@@ -280,131 +281,115 @@ const isOperatorSpec = (value: unknown): value is FieldOperators<any> =>
   value != null && typeof value === 'object' && !Array.isArray(value) && !(value instanceof Date)
   && Object.keys(value).some(key => key.startsWith('$'))
 
-/**
- * Translate a {@link Criteria} into a WHERE clause. `undefined` means "no constraint at
- * all" — the caller decides whether that is a full scan or a refusal.
- *
- * An unknown key raises rather than being skipped: a typo silently widening a query to
- * the whole table is the failure mode worth being loud about.
- *
- * @throws {UnsupportedArgumentError}
- */
-export const criteriaToSql = <T>(
-  criteria: Criteria<T> | undefined, spec: TableSpec, table: PgRuntimeTable
-): SQL | undefined => {
-  const conditions = build(criteria, spec, table)
+export const createPgCriteriaHelper = (): PgCriteriaHelper => {
+  const criteriaToSql = <T>(
+    criteria: Criteria<T> | undefined, spec: TableSpec, table: PgRuntimeTable
+  ): SQL | undefined => {
+    const conditions = build(criteria, spec, table)
 
-  return conditions.length > 0 ? and(...conditions) : undefined
-}
+    return conditions.length > 0 ? and(...conditions) : undefined
+  }
 
-const build = <T>(
-  criteria: Criteria<T> | undefined, spec: TableSpec, table: PgRuntimeTable
-): SQL[] => {
-  const conditions: SQL[] = []
-  for (const [key, raw] of Object.entries(criteria ?? {})) {
-    if (raw === undefined) {
-      continue
-    }
+  const build = <T>(
+    criteria: Criteria<T> | undefined, spec: TableSpec, table: PgRuntimeTable
+  ): SQL[] => {
+    const conditions: SQL[] = []
+    for (const [key, raw] of Object.entries(criteria ?? {})) {
+      if (raw === undefined) {
+        continue
+      }
 
-    if (key === '$and' || key === '$or') {
-      const parts = (Array.isArray(raw) ? raw : [raw])
-        .map(entry => and(...build(entry as Criteria<T>, spec, table)))
-        .filter((entry): entry is SQL => entry != null)
-      if (parts.length > 0) {
-        const combined = key === '$and' ? and(...parts) : or(...parts)
-        if (combined != null) {
-          conditions.push(combined)
+      if (key === '$and' || key === '$or') {
+        const parts = (Array.isArray(raw) ? raw : [raw])
+          .map(entry => and(...build(entry as Criteria<T>, spec, table)))
+          .filter((entry): entry is SQL => entry != null)
+        if (parts.length > 0) {
+          const combined = key === '$and' ? and(...parts) : or(...parts)
+          if (combined != null) {
+            conditions.push(combined)
+          }
         }
+        continue
       }
-      continue
-    }
-    if (key === '$not') {
-      const inner = and(...build(raw as Criteria<T>, spec, table))
-      if (inner != null) {
-        conditions.push(sql`NOT (${inner})`)
+      if (key === '$not') {
+        const inner = and(...build(raw as Criteria<T>, spec, table))
+        if (inner != null) {
+          conditions.push(sql`NOT (${inner})`)
+        }
+        continue
       }
-      continue
-    }
 
-    /** `profile.city` reaches into a jsonb column rather than naming a column. */
-    const [head, ...path] = key.split('.')
-    const column = spec.byProperty[head]
-    if (column == null) {
-      throw new UnsupportedArgumentError(`criteria:${key}`)
-    }
-    if (path.length > 0) {
-      if (!column.jsonb) {
-        throw new UnsupportedArgumentError(`criteria-path:${key}`)
+      /** `profile.city` reaches into a jsonb column rather than naming a column. */
+      const [head, ...path] = key.split('.')
+      const column = spec.byProperty[head]
+      if (column == null) {
+        throw new UnsupportedArgumentError(`criteria:${key}`)
+      }
+      if (path.length > 0) {
+        if (!column.jsonb) {
+          throw new UnsupportedArgumentError(`criteria-path:${key}`)
+        }
+        conditions.push(...pathCondition(pathTarget(table, column, path), raw, key))
+        continue
       }
-      conditions.push(...pathCondition(pathTarget(table, column, path), raw, key))
-      continue
-    }
 
-    if (raw === null) {
-      conditions.push(sql`${columnRef(table, column)} IS NULL`)
-      continue
-    }
-    if (isOperatorSpec(raw)) {
-      conditions.push(...operators(table, column, raw))
-      continue
-    }
-    if (Array.isArray(raw)) {
-      /**
-       * A bare array means `IN` for a relational store, which is overwhelmingly the intent.
-       * Exact array equality against a `text[]` column stays available as `{ $eq: [...] }`.
-       */
-      conditions.push(inList(table, column, raw, false))
-      continue
-    }
-    if (column.jsonb && typeof raw === 'object') {
-      conditions.push(sql`${columnRef(table, column)} @> ${JSON.stringify(raw)}`)
-      continue
+      if (raw === null) {
+        conditions.push(sql`${columnRef(table, column)} IS NULL`)
+        continue
+      }
+      if (isOperatorSpec(raw)) {
+        conditions.push(...operators(table, column, raw))
+        continue
+      }
+      if (Array.isArray(raw)) {
+        /**
+         * A bare array means `IN` for a relational store, which is overwhelmingly the intent.
+         * Exact array equality against a `text[]` column stays available as `{ $eq: [...] }`.
+         */
+        conditions.push(inList(table, column, raw, false))
+        continue
+      }
+      if (column.jsonb && typeof raw === 'object') {
+        conditions.push(sql`${columnRef(table, column)} @> ${JSON.stringify(raw)}`)
+        continue
+      }
+      conditions.push(sql`${columnRef(table, column)} = ${value(raw, column)}`)
     }
-    conditions.push(sql`${columnRef(table, column)} = ${value(raw, column)}`)
-  }
-
-  return conditions
-}
 
-/**
- * Translate a {@link Sort} list into ORDER BY. A bare field name is ascending;
- * `{ field, order: 'desc' }` reverses it — the same meaning every backend gives it.
- *
- * The primary key is always appended as a tiebreak. Postgres has no implicit row order, so
- * paginating on a non-unique sort key silently duplicates and skips rows between pages —
- * a difference from mongo that would otherwise surface as a data bug rather than an error.
- *
- * A dotted path is a column this table does not have: criteria can reach into jsonb, ORDER BY
- * cannot, and refusing is better than ordering by something the caller did not name.
- *
- * @throws {UnsupportedArgumentError}
- */
-export const sortToSql = <T>(
-  sort: Sort<T>[] | undefined, spec: TableSpec, table: PgRuntimeTable
-): SQL[] => {
-  const order: SQL[] = []
-  const seen: string[] = []
-
-  for (const entry of sort ?? []) {
-    const property = typeof entry === 'string' ? entry : entry.field
-    const descending = typeof entry !== 'string' && entry.order === 'desc'
-    const column = spec.byProperty[property]
-    if (column == null) {
-      throw new UnsupportedArgumentError(`sort:${property}`)
-    }
-    seen.push(column.column)
-    order.push(descending ? desc(table[column.property]) : asc(table[column.property]))
+    return conditions
   }
 
-  for (const key of spec.primaryKey) {
-    if (seen.includes(key)) {
-      continue
+  const sortToSql = <T>(
+    sort: Sort<T>[] | undefined, spec: TableSpec, table: PgRuntimeTable
+  ): SQL[] => {
+    const order: SQL[] = []
+    const seen: string[] = []
+
+    for (const entry of sort ?? []) {
+      const property = typeof entry === 'string' ? entry : entry.field
+      const descending = typeof entry !== 'string' && entry.order === 'desc'
+      const column = spec.byProperty[property]
+      if (column == null) {
+        throw new UnsupportedArgumentError(`sort:${property}`)
+      }
+      seen.push(column.column)
+      order.push(descending ? desc(table[column.property]) : asc(table[column.property]))
     }
-    const column = spec.byColumn[key]
-    if (column != null) {
-      order.push(asc(table[column.property]))
+
+    for (const key of spec.primaryKey) {
+      if (seen.includes(key)) {
+        continue
+      }
+      const column = spec.byColumn[key]
+      if (column != null) {
+        order.push(asc(table[column.property]))
+      }
     }
+
+    return order
   }
 
-  return order
+  return { criteriaToSql, sortToSql }
 }
+
+export const pgCriteriaHelper = createPgCriteriaHelper()