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

package/src/declarations.ts

@@ -1,14 +1,7 @@
 import { createMigrationRegistry } from '@owlmeans/resource'
-import type { MigrationRegistry } from '@owlmeans/resource'
-import type { AnySchema } from 'ajv'
 
-import type { PgIndexSpec, PostgresTx } from './types.js'
-
-export interface PostgresDeclaration {
-  schema?: AnySchema
-  indexes: PgIndexSpec[]
-  migrations: MigrationRegistry<PostgresTx>
-}
+import type { PgDeclarationHelper } from './declarations/types.js'
+import type { PostgresTx, PostgresDeclaration } from './types.js'
 
 /**
  * Per-alias declaration store, held at module scope rather than on the resource object.
@@ -18,24 +11,38 @@ export interface PostgresDeclaration {
  * a no-op: every run reads and extends the same schema, indexes and migrations, so nothing a
  * caller chained onto an earlier resource object is lost. Losing a migration is silent — the
  * data transformation simply never runs — which is why the store cannot live on the object.
+ *
+ * Process-wide for the same reason: it stays outside the factory, so every helper built from it
+ * reads the one store.
  */
 const declarations: Map<string, PostgresDeclaration> = new Map()
 
-export const getDeclaration = (alias: string): PostgresDeclaration => {
-  let declaration = declarations.get(alias)
-  if (declaration == null) {
-    declaration = { indexes: [], migrations: createMigrationRegistry<PostgresTx>() }
-    declarations.set(alias, declaration)
-  }
+export const createPgDeclarationHelper = (): PgDeclarationHelper => {
+  const getDeclaration = (alias: string): PostgresDeclaration => {
+    let declaration = declarations.get(alias)
+    if (declaration == null) {
+      declaration = { indexes: [], migrations: createMigrationRegistry<PostgresTx>() }
+      declarations.set(alias, declaration)
+    }
 
-  return declaration
-}
+    return declaration
+  }
 
-/** Testing seam — drops every declaration so a spec can redeclare a resource from scratch. */
-export const resetDeclarations = (alias?: string): void => {
-  if (alias == null) {
-    declarations.clear()
-    return
+  const resetDeclarations = (alias?: string): void => {
+    if (alias == null) {
+      declarations.clear()
+      return
+    }
+    declarations.delete(alias)
   }
-  declarations.delete(alias)
+
+  return { getDeclaration, resetDeclarations }
 }
+
+export const pgDeclarationHelper = createPgDeclarationHelper()
+
+/** @deprecated compat:factory-refactor — use `pgDeclarationHelper.getDeclaration(…)` */
+export const getDeclaration = (alias: string): PostgresDeclaration => pgDeclarationHelper.getDeclaration(alias)
+
+/** @deprecated compat:factory-refactor — use `pgDeclarationHelper.resetDeclarations(…)` */
+export const resetDeclarations = (alias?: string): void => pgDeclarationHelper.resetDeclarations(alias)

package/src/errors.ts

@@ -1,9 +1,5 @@
 import { ResilientError } from '@owlmeans/error'
-import {
-  MisshapedRecord, RecordExists, ResourceError
-} from '@owlmeans/resource'
-
-import { PgErrorCode } from './consts.js'
+import { ResourceError } from '@owlmeans/resource'
 
 export class PostgresError extends ResourceError {
   public static override typeName = `${ResourceError.typeName}PostgresError`
@@ -106,132 +102,6 @@ export class PostgresBootstrapError extends PostgresError {
   }
 }
 
-interface PgDriverError {
-  code?: string
-  detail?: string
-  hint?: string
-  severity?: string
-  constraint?: string
-  table?: string
-  column?: string
-  message?: string
-}
-
-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

@@ -1,32 +1,24 @@
 import { appendContextual, assertContext } from '@owlmeans/context'
-import {
-  MisshapedRecord, RecordExists, RecordUpdateFailed, UnknownRecordError, UnsupportedArgumentError
-} from '@owlmeans/resource'
-import type {
-  Criteria, FirstOptions, ListOptions, ListResult, MigrationStage, ResourceRecord, WriteOptions
-} from '@owlmeans/resource'
-import type { ServerConfig, ServerContext } from '@owlmeans/server-context'
+import { MisshapedRecord, RecordExists, RecordUpdateFailed, UnknownRecordError, UnsupportedArgumentError, type Criteria, type FirstOptions, type ListOptions, type ListResult, type MigrationStage, type ResourceRecord, type WriteOptions } from '@owlmeans/resource'
 import type { AnySchema, JSONSchemaType } from 'ajv'
-import { eq, sql } from 'drizzle-orm'
-import type { SQL } from 'drizzle-orm'
+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'
 
-type Config = ServerConfig
-type Context<C extends Config = Config> = ServerContext<C>
 
 /** Postgres has no row expiry — silently ignoring a TTL would lose data. */
 const refuseTtl = (opts?: WriteOptions): void => {
@@ -42,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
@@ -115,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 }
@@ -405,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')
 
@@ -512,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.local.ts

@@ -0,0 +1,16 @@
+import type { ServerConfig, ServerContext } from '@owlmeans/server-context'
+
+export interface PgDriverError {
+  code?: string
+  detail?: string
+  hint?: string
+  severity?: string
+  constraint?: string
+  table?: string
+  column?: string
+  message?: string
+}
+
+export type Config = ServerConfig
+
+export type Context<C extends Config = Config> = ServerContext<C>

package/src/types.ts

@@ -1,7 +1,4 @@
-import type {
-  Criteria, DbLocker, LockableResource, MigratableResource, Resource,
-  ResourceDbService, ResourceRecord, WriteOptions
-} from '@owlmeans/resource'
+import type { Criteria, DbLocker, LockableResource, MigratableResource, Resource, ResourceDbService, ResourceRecord, WriteOptions, MigrationRegistry } from '@owlmeans/resource'
 import type { AnySchema } from 'ajv'
 import type { Pool, PoolClient, QueryResultRow } from 'pg'
 import type { NodePgDatabase } from 'drizzle-orm/node-postgres'
@@ -258,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}.
  *
@@ -321,3 +319,9 @@ export interface DdlPlan {
   fresh: boolean
   statements: DdlStatement[]
 }
+
+export interface PostgresDeclaration {
+  schema?: AnySchema
+  indexes: PgIndexSpec[]
+  migrations: MigrationRegistry<PostgresTx>
+}

package/src/utils/consts.local.ts

@@ -0,0 +1,71 @@
+import { PgErrorCode } from '../consts.js'
+
+export const COMPARISON: Record<string, string> = {
+  $eq: '=', $ne: '<>', $gt: '>', $gte: '>=', $lt: '<', $lte: '<='
+}
+
+/** A type cast as `pg_get_expr` / `pg_get_indexdef` print one: `::text`, `::character varying(64)[]`. */
+export const CAST = /::(?:character varying|double precision|bit varying|timestamp with(?:out)? time zone|time with(?:out)? time zone|[a-z_][a-z0-9_]*)(?:\(\d+(?:\s*,\s*\d+)?\))?(?:\[\])?/g
+
+/**
+ * `pg_attribute` + `format_type` rather than `information_schema.columns`, because it
+ * returns one canonical type string with the typmod already baked in
+ * (`character varying(320)`). `information_schema` splits the same information across
+ * four columns and reports every array as `ARRAY`, which no comparison can use.
+ */
+export const COLUMNS = `
+  SELECT a.attname                            AS name,
+         format_type(a.atttypid, a.atttypmod) AS type,
+         a.attnotnull                         AS not_null,
+         pg_get_expr(d.adbin, d.adrelid)      AS default_expr,
+         a.attidentity                        AS identity,
+         a.attgenerated                       AS generated,
+         a.attnum                             AS ordinal
+    FROM pg_attribute a
+    LEFT JOIN pg_attrdef d ON d.adrelid = a.attrelid AND d.adnum = a.attnum
+   WHERE a.attrelid = to_regclass($1) AND a.attnum > 0 AND NOT a.attisdropped
+   ORDER BY a.attnum
+`
+
+export const INDEXES = `
+  SELECT indexname AS name, indexdef AS definition
+    FROM pg_indexes
+   WHERE schemaname = $1 AND tablename = $2
+`
+
+export const CONSTRAINTS = `
+  SELECT c.conname AS name, c.contype AS type, pg_get_constraintdef(c.oid) AS definition
+    FROM pg_constraint c
+   WHERE c.conrelid = to_regclass($1)
+     AND c.contype <> 'n'
+`
+
+export const SAFE_IDENTIFIER = /^[A-Za-z_][A-Za-z0-9_$]*$/
+
+/**
+ * `{{ }}` / `{{self}}`      — the owning resource's qualified table
+ * `{{alias}}`               — another registered postgres resource's qualified table
+ * `{{alias.property}}`      — a qualified column of that resource
+ * `{{#alias}}`              — the bare quoted table name, for `ON CONFLICT ON CONSTRAINT`
+ * `{{$}}`                   — the owning resource's quoted schema
+ *
+ * Resource aliases in this codebase use `-` and `:` but never `.`, so `.` is unambiguous
+ * as the column separator.
+ */
+export const PLACEHOLDER = /\{\{\s*([#$]?)([A-Za-z0-9_:-]*)(?:\.([A-Za-z0-9_]+))?\s*\}\}/g
+
+/**
+ * Codes that mean "the cast is legal, the data isn't": a `text` column holding `'a'` retyped to
+ * `integer`, a value too wide for the new length, a number past the new range. Postgres refuses
+ * each of these rather than truncating, and the remedy is the same one a refused cast needs — so
+ * they are only read as a cast problem here, inside DDL. On the CRUD path the identical code means
+ * a caller passed a bad value, which is a different bug with a different fix.
+ */
+export const CAST_DATA_CODES: string[] = [
+  PgErrorCode.InvalidTextRepresentation,
+  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[]
+}