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

package/src/utils/marshal.ts

@@ -1,175 +1,162 @@
 import type { ResourceRecord } from '@owlmeans/resource'
+import { logThrottle, logger } from '@owlmeans/log'
 import { types as pgTypes } from 'pg'
 
 import { ID_FIELD, PgTypeOid } from '../consts.js'
 import type { ColumnSpec, TableSpec } from '../types.js'
-
-/**
- * Parse a temporal value the way the driver would have.
- *
- * Drizzle's node-postgres session installs its own `getTypeParser` that hands date and
- * timestamp columns back as raw text, because its own statically declared column types do
- * the conversion. Ours are compiled at runtime and can't, so the driver's parser is called
- * directly — the same function, just later. Raw SQL never comes through here, since that
- * path keeps the driver's default parsers.
- */
-const toDate = (value: string, column: ColumnSpec): unknown => {
-  const oid = column.sqlType.startsWith('timestamp with time zone')
-    ? PgTypeOid.TimestampTz
-    : column.sqlType.startsWith('timestamp')
-      ? PgTypeOid.Timestamp
-      : PgTypeOid.Date
-
-  return (pgTypes.getTypeParser(oid as never) as (raw: string) => unknown)(value)
-}
-
-const fromDriver = (value: unknown, column: ColumnSpec): unknown => {
-  if (value == null) {
-    return value
-  }
-  /** Ciphertext is opaque — coercing it would corrupt it. */
-  if (column.secure) {
-    return value
+import type { PgMarshalHelper } from './marshal/types.js'
+
+const log = logger('postgres-resource')
+
+export const createPgMarshalHelper = (): PgMarshalHelper => {
+  /**
+   * Parse a temporal value the way the driver would have.
+   *
+   * Drizzle's node-postgres session installs its own `getTypeParser` that hands date and
+   * timestamp columns back as raw text, because its own statically declared column types do
+   * the conversion. Ours are compiled at runtime and can't, so the driver's parser is called
+   * directly — the same function, just later. Raw SQL never comes through here, since that
+   * path keeps the driver's default parsers.
+   */
+  const toDate = (value: string, column: ColumnSpec): unknown => {
+    const oid = column.sqlType.startsWith('timestamp with time zone')
+      ? PgTypeOid.TimestampTz
+      : column.sqlType.startsWith('timestamp')
+        ? PgTypeOid.Timestamp
+        : PgTypeOid.Date
+
+    return (pgTypes.getTypeParser(oid as never) as (raw: string) => unknown)(value)
   }
 
-  switch (column.jsonType) {
-    case 'number':
-      /** Postgres returns `numeric` as a string to protect precision the JS number can't hold. */
-      return typeof value === 'string' ? parseFloat(value) : value
-    case 'integer':
-      return typeof value === 'string' ? parseInt(value, 10) : value
-    case 'bigint': {
-      if (typeof value !== 'string' && typeof value !== 'bigint') {
-        return value
-      }
-      const parsed = Number(value)
-      if (!Number.isSafeInteger(parsed)) {
-        console.warn(
-          `@owlmeans/postgres-resource: "${column.column}" holds ${value}, which exceeds the safe`
-          + ' integer range — the value read back is imprecise.'
-        )
+  const fromDriver = (value: unknown, column: ColumnSpec, table?: string): unknown => {
+    if (value == null) {
+      return value
+    }
+    /** Ciphertext is opaque — coercing it would corrupt it. */
+    if (column.secure) {
+      return value
+    }
+
+    switch (column.jsonType) {
+      case 'number':
+        /** Postgres returns `numeric` as a string to protect precision the JS number can't hold. */
+        return typeof value === 'string' ? parseFloat(value) : value
+      case 'integer':
+        return typeof value === 'string' ? parseInt(value, 10) : value
+      case 'bigint': {
+        if (typeof value !== 'string' && typeof value !== 'bigint') {
+          return value
+        }
+        const parsed = Number(value)
+        if (!Number.isSafeInteger(parsed)) {
+          // Fires per row read: one line per window per column is enough.
+          if (logThrottle(`postgres-resource:${table ?? ''}:${column.column}:unsafe-bigint`, 300_000)) {
+            log.warn('Bigint column value exceeds the safe integer range; the value read back is imprecise', {
+              table, column: column.column,
+            })
+          }
+        }
+
+        return parsed
       }
+      case 'binary':
+        return Buffer.isBuffer(value) ? value.toString('base64') : value
+      case 'date':
+        return typeof value === 'string' ? toDate(value, column) : value
+      default:
+        return value
+    }
+  }
 
-      return parsed
+  const toDriver = (value: unknown, column: ColumnSpec): unknown => {
+    if (value == null) {
+      return value
     }
-    case 'binary':
-      return Buffer.isBuffer(value) ? value.toString('base64') : value
-    case 'date':
-      return typeof value === 'string' ? toDate(value, column) : value
-    default:
+    if (column.secure) {
       return value
-  }
-}
+    }
+    if (column.jsonb) {
+      /**
+       * node-postgres stringifies plain objects on its own but turns arrays into Postgres
+       * array literals, which a jsonb column rejects. Stringifying here covers both.
+       */
+      return typeof value === 'string' ? value : JSON.stringify(value)
+    }
+    if (column.jsonType === 'date' && !(value instanceof Date)) {
+      return new Date(value as string | number)
+    }
+    if (column.jsonType === 'binary' && typeof value === 'string') {
+      return Buffer.from(value, 'base64')
+    }
 
-const toDriver = (value: unknown, column: ColumnSpec): unknown => {
-  if (value == null) {
-    return value
-  }
-  if (column.secure) {
     return value
   }
-  if (column.jsonb) {
-    /**
-     * node-postgres stringifies plain objects on its own but turns arrays into Postgres
-     * array literals, which a jsonb column rejects. Stringifying here covers both.
-     */
-    return typeof value === 'string' ? value : JSON.stringify(value)
-  }
-  if (column.jsonType === 'date' && !(value instanceof Date)) {
-    return new Date(value as string | number)
-  }
-  if (column.jsonType === 'binary' && typeof value === 'string') {
-    return Buffer.from(value, 'base64')
-  }
-
-  return value
-}
 
-/**
- * Turn a driver row into a record: physical column names back to schema property names,
- * plus the coercions node-postgres leaves to the caller.
- *
- * Columns the spec doesn't know about — computed expressions, joined columns from custom
- * SQL — are kept verbatim. A join result is more useful than a lossy projection.
- */
-export const rowToRecord = <T extends ResourceRecord>(row: Record<string, unknown>, spec: TableSpec): T => {
-  const record: Record<string, unknown> = {}
-  for (const [key, value] of Object.entries(row)) {
-    const column = spec.byColumn[key]
-    if (column == null) {
-      record[key] = value
-      continue
+  const rowToRecord = <T extends ResourceRecord>(row: Record<string, unknown>, spec: TableSpec): T => {
+    const record: Record<string, unknown> = {}
+    for (const [key, value] of Object.entries(row)) {
+      const column = spec.byColumn[key]
+      if (column == null) {
+        record[key] = value
+        continue
+      }
+      record[column.property] = fromDriver(value, column, spec.qualified)
     }
-    record[column.property] = fromDriver(value, column)
-  }
-  if (record[ID_FIELD] != null) {
-    record[ID_FIELD] = `${record[ID_FIELD]}`
+    if (record[ID_FIELD] != null) {
+      record[ID_FIELD] = `${record[ID_FIELD]}`
+    }
+
+    return record as T
   }
 
-  return record as T
-}
+  const resultToRecord = <T extends ResourceRecord>(
+    row: Record<string, unknown>, spec: TableSpec
+  ): T => {
+    const record: Record<string, unknown> = {}
+    for (const [key, value] of Object.entries(row)) {
+      const column = spec.byProperty[key]
+      record[key] = column == null ? value : fromDriver(value, column, spec.qualified)
+    }
+    if (record[ID_FIELD] != null) {
+      record[ID_FIELD] = `${record[ID_FIELD]}`
+    }
 
-/**
- * Same coercion as {@link rowToRecord}, for rows Drizzle produced.
- *
- * Drizzle keys its results by the table object's JS property names — which are the schema
- * property names — where raw SQL returns physical column names. Two functions rather than
- * one lookup that tries both, because a schema that renames `a` to column `b` while another
- * property is itself named `b` would make the combined lookup pick the wrong spec.
- */
-export const resultToRecord = <T extends ResourceRecord>(
-  row: Record<string, unknown>, spec: TableSpec
-): T => {
-  const record: Record<string, unknown> = {}
-  for (const [key, value] of Object.entries(row)) {
-    const column = spec.byProperty[key]
-    record[key] = column == null ? value : fromDriver(value, column)
-  }
-  if (record[ID_FIELD] != null) {
-    record[ID_FIELD] = `${record[ID_FIELD]}`
+    return record as T
   }
 
-  return record as T
-}
-
-/**
- * Turn a record into the values Drizzle inserts, keyed by property name (Drizzle owns the
- * property to column mapping).
- *
- * `undefined` properties are dropped so a partial write touches only what was supplied;
- * an explicit `null` is kept, because nulling a column is a real intent.
- */
-export const recordToValues = (record: Record<string, unknown>, spec: TableSpec): Record<string, unknown> => {
-  const values: Record<string, unknown> = {}
-  for (const [key, value] of Object.entries(record)) {
-    const column = spec.byProperty[key]
-    if (column == null || value === undefined) {
-      continue
+  const recordToValues = (record: Record<string, unknown>, spec: TableSpec): Record<string, unknown> => {
+    const values: Record<string, unknown> = {}
+    for (const [key, value] of Object.entries(record)) {
+      const column = spec.byProperty[key]
+      if (column == null || value === undefined) {
+        continue
+      }
+      values[column.property] = toDriver(value, column)
     }
-    values[column.property] = toDriver(value, column)
-  }
 
-  return values
-}
+    return values
+  }
 
-/**
- * Every managed column, with anything the record omits explicitly nulled.
- *
- * This is what makes `update()` a replace rather than a merge — the semantics mongo's
- * `replaceOne` gives, kept identical so a resource behaves the same on either backend.
- * The primary key and unmanaged columns are never nulled.
- */
-export const recordToFullValues = (
-  record: Record<string, unknown>, spec: TableSpec
-): Record<string, unknown> => {
-  const values: Record<string, unknown> = {}
-  for (const column of spec.columns) {
-    if (spec.primaryKey.includes(column.column) || spec.unmanaged.includes(column.column)) {
-      continue
+  const recordToFullValues = (
+    record: Record<string, unknown>, spec: TableSpec
+  ): Record<string, unknown> => {
+    const values: Record<string, unknown> = {}
+    for (const column of spec.columns) {
+      if (spec.primaryKey.includes(column.column) || spec.unmanaged.includes(column.column)) {
+        continue
+      }
+      const value = record[column.property]
+      values[column.property] = value === undefined ? null : toDriver(value, column)
     }
-    const value = record[column.property]
-    values[column.property] = value === undefined ? null : toDriver(value, column)
+
+    return values
   }
 
-  return values
+  return { rowToRecord, resultToRecord, recordToValues, recordToFullValues }
 }
+
+export const pgMarshalHelper = createPgMarshalHelper()
+
+/** @deprecated compat:factory-refactor — use `pgMarshalHelper.rowToRecord(…)` */
+export const rowToRecord = <T extends ResourceRecord>(row: Record<string, unknown>, spec: TableSpec): T =>
+  pgMarshalHelper.rowToRecord<T>(row, spec)

package/src/utils/migrations.ts

@@ -1,9 +1,9 @@
 import type { Migration, MigrationStore } from '@owlmeans/resource'
 import type { PoolClient, QueryResultRow } from 'pg'
 
-import { pgErrorToResourceError } from '../errors.js'
+import { pgErrorHelper } from '../pg-error.js'
 import type { PostgresTx, TableSpec } from '../types.js'
-import { qualify, quoteIdent } from './name.js'
+import { pgNameHelper } from './name.js'
 
 /**
  * A transaction façade over a checked out client. `{{alias}}` resolution is injected so
@@ -11,41 +11,45 @@ import { qualify, quoteIdent } from './name.js'
  */
 export const makeTx = (
   client: PoolClient, resolve: (text: string) => string, ref: (alias?: string) => string
-): PostgresTx => ({
-  client,
+): PostgresTx => {
+  const { pgErrorToResourceError } = pgErrorHelper
 
-  query: async <Row extends QueryResultRow = QueryResultRow>(text: string, params?: unknown[]) => {
-    const query = resolve(text)
-    try {
-      const result = await client.query<Row>(query, params as never[])
-      return result.rows
-    } catch (error) {
-      throw pgErrorToResourceError(error, query)
-    }
-  },
+  return {
+    client,
 
-  queryOne: async <Row extends QueryResultRow = QueryResultRow>(text: string, params?: unknown[]) => {
-    const query = resolve(text)
-    try {
-      const result = await client.query<Row>(query, params as never[])
-      return result.rows[0] ?? null
-    } catch (error) {
-      throw pgErrorToResourceError(error, query)
-    }
-  },
+    query: async <Row extends QueryResultRow = QueryResultRow>(text: string, params?: unknown[]) => {
+      const query = resolve(text)
+      try {
+        const result = await client.query<Row>(query, params as never[])
+        return result.rows
+      } catch (error) {
+        throw pgErrorToResourceError(error, query)
+      }
+    },
 
-  execute: async (text: string, params?: unknown[]) => {
-    const query = resolve(text)
-    try {
-      const result = await client.query(query, params as never[])
-      return result.rowCount ?? 0
-    } catch (error) {
-      throw pgErrorToResourceError(error, query)
-    }
-  },
+    queryOne: async <Row extends QueryResultRow = QueryResultRow>(text: string, params?: unknown[]) => {
+      const query = resolve(text)
+      try {
+        const result = await client.query<Row>(query, params as never[])
+        return result.rows[0] ?? null
+      } catch (error) {
+        throw pgErrorToResourceError(error, query)
+      }
+    },
 
-  ref
-})
+    execute: async (text: string, params?: unknown[]) => {
+      const query = resolve(text)
+      try {
+        const result = await client.query(query, params as never[])
+        return result.rowCount ?? 0
+      } catch (error) {
+        throw pgErrorToResourceError(error, query)
+      }
+    },
+
+    ref
+  }
+}
 
 /**
  * Migration ledger, one table per Postgres schema.
@@ -60,6 +64,8 @@ export const makeMigrationStore = (
   resolve: (text: string) => string,
   ref: (alias?: string) => string
 ): MigrationStore<PostgresTx> => {
+  const { pgErrorToResourceError } = pgErrorHelper
+  const { qualify, quoteIdent } = pgNameHelper
   const ledger = qualify(spec.schema, table)
 
   return {

package/src/utils/name/types.ts

@@ -0,0 +1,44 @@
+import type { DbConfig, ResourceRecord } from '@owlmeans/resource'
+
+import type { PostgresResource } from '../../types.js'
+
+/** Postgres identifiers and literals: sanitizing, asserting, quoting and naming. */
+export interface PgNameHelper {
+  /**
+   * Coerce an arbitrary name into a legal Postgres identifier of at most 63 bytes.
+   *
+   * Postgres cuts anything past `NAMEDATALEN - 1` off server side and says nothing about
+   * it, so two names that differ only beyond byte 63 would collapse into one identifier.
+   * Clamping here instead leaves room for a hash suffix that keeps them apart.
+   */
+  pgIdentifier: (name: string) => string
+  /**
+   * Assert a value is safe to interpolate as an identifier. Postgres can't bind identifiers
+   * as parameters, so every one of them reaches the server as text — which makes this the
+   * only thing standing between a config value and injection.
+   *
+   * @throws {SyntaxError}
+   */
+  assertSqlIdentifier: (value: string, what?: string) => string
+  /** Quote an identifier for emission, doubling any interior quote. */
+  quoteIdent: (value: string) => string
+  /**
+   * Quote a string literal. Only ever used for values Postgres refuses to bind — notably
+   * the password in `CREATE ROLE`.
+   *
+   * @throws {SyntaxError} on a NUL byte, which no escaping makes safe.
+   */
+  quoteLiteral: (value: string) => string
+  /** `"schema"."table"`, each part quoted. */
+  qualify: (schema: string, table: string) => string
+  /**
+   * Physical table name of a resource: the explicit `name`, else the resource alias,
+   * prefixed per `DbConfig.resourcePrefix` and sanitized.
+   */
+  pgTableName: (config: DbConfig, resource: PostgresResource<ResourceRecord>) => string
+  /**
+   * Derive a pair of int32s for `pg_advisory_lock` from a qualified table name, so every
+   * replica booting against the same table serializes on the same key.
+   */
+  advisoryKey: (qualified: string) => [number, number]
+}

package/src/utils/name.ts

@@ -1,79 +1,65 @@
-import { sha256 } from '@noble/hashes/sha2'
+import { sha256 } from '@noble/hashes/sha2.js'
 import { hex } from '@scure/base'
 import type { DbConfig, ResourceRecord } from '@owlmeans/resource'
 
 import { PG_MAX_IDENTIFIER } from '../consts.js'
 import type { PostgresResource } from '../types.js'
+import { SAFE_IDENTIFIER } from './consts.local.js'
+import type { PgNameHelper } from './name/types.js'
 
-const SAFE_IDENTIFIER = /^[A-Za-z_][A-Za-z0-9_$]*$/
-
-/**
- * Coerce an arbitrary name into a legal Postgres identifier of at most 63 bytes.
- *
- * Postgres cuts anything past `NAMEDATALEN - 1` off server side and says nothing about
- * it, so two names that differ only beyond byte 63 would collapse into one identifier.
- * Clamping here instead leaves room for a hash suffix that keeps them apart.
- */
-export const pgIdentifier = (name: string): string => {
-  const sanitized = name.replace(/[^A-Za-z0-9_$]/g, '_')
-  const prefixed = /^[A-Za-z_]/.test(sanitized) ? sanitized : `_${sanitized}`
-  if (Buffer.byteLength(prefixed, 'utf8') <= PG_MAX_IDENTIFIER) {
-    return prefixed
+export const createPgNameHelper = (): PgNameHelper => {
+  const pgIdentifier = (name: string): string => {
+    const sanitized = name.replace(/[^A-Za-z0-9_$]/g, '_')
+    const prefixed = /^[A-Za-z_]/.test(sanitized) ? sanitized : `_${sanitized}`
+    if (Buffer.byteLength(prefixed, 'utf8') <= PG_MAX_IDENTIFIER) {
+      return prefixed
+    }
+    const digest = hex.encode(sha256(new TextEncoder().encode(name))).substring(0, 32)
+
+    return `${prefixed.substring(0, 30)}_${digest}`
   }
-  const digest = hex.encode(sha256(new TextEncoder().encode(name))).substring(0, 32)
 
-  return `${prefixed.substring(0, 30)}_${digest}`
-}
+  const assertSqlIdentifier = (value: string, what: string = 'identifier'): string => {
+    if (!SAFE_IDENTIFIER.test(value) || Buffer.byteLength(value, 'utf8') > PG_MAX_IDENTIFIER) {
+      throw new SyntaxError(`postgres:unsafe-${what}:${value}`)
+    }
 
-/**
- * Assert a value is safe to interpolate as an identifier. Postgres can't bind identifiers
- * as parameters, so every one of them reaches the server as text — which makes this the
- * only thing standing between a config value and injection.
- *
- * @throws {SyntaxError}
- */
-export const assertSqlIdentifier = (value: string, what: string = 'identifier'): string => {
-  if (!SAFE_IDENTIFIER.test(value) || Buffer.byteLength(value, 'utf8') > PG_MAX_IDENTIFIER) {
-    throw new SyntaxError(`postgres:unsafe-${what}:${value}`)
+    return value
   }
 
-  return value
-}
+  const quoteIdent = (value: string): string => `"${value.replace(/"/g, '""')}"`
+
+  const quoteLiteral = (value: string): string => {
+    if (value.includes('\0')) {
+      throw new SyntaxError('postgres:unsafe-literal:nul-byte')
+    }
 
-/** Quote an identifier for emission, doubling any interior quote. */
-export const quoteIdent = (value: string): string => `"${value.replace(/"/g, '""')}"`
-
-/**
- * Quote a string literal. Only ever used for values Postgres refuses to bind — notably
- * the password in `CREATE ROLE`.
- *
- * @throws {SyntaxError} on a NUL byte, which no escaping makes safe.
- */
-export const quoteLiteral = (value: string): string => {
-  if (value.includes('\0')) {
-    throw new SyntaxError('postgres:unsafe-literal:nul-byte')
+    return `'${value.replace(/'/g, "''")}'`
   }
 
-  return `'${value.replace(/'/g, "''")}'`
-}
+  const qualify = (schema: string, table: string): string =>
+    `${quoteIdent(schema)}.${quoteIdent(table)}`
+
+  const pgTableName = (config: DbConfig, resource: PostgresResource<ResourceRecord>): string =>
+    pgIdentifier(`${config.resourcePrefix ?? ''}${resource.name ?? resource.alias}`)
+
+  const advisoryKey = (qualified: string): [number, number] => {
+    const digest = sha256(new TextEncoder().encode(`owlmeans:${qualified}`))
+    const view = new DataView(digest.buffer, digest.byteOffset, digest.byteLength)
 
-export const qualify = (schema: string, table: string): string =>
-  `${quoteIdent(schema)}.${quoteIdent(table)}`
-
-/**
- * Physical table name of a resource: the explicit `name`, else the resource alias,
- * prefixed per `DbConfig.resourcePrefix` and sanitized.
- */
-export const pgTableName = (config: DbConfig, resource: PostgresResource<ResourceRecord>): string =>
-  pgIdentifier(`${config.resourcePrefix ?? ''}${resource.name ?? resource.alias}`)
-
-/**
- * Derive a pair of int32s for `pg_advisory_lock` from a qualified table name, so every
- * replica booting against the same table serializes on the same key.
- */
-export const advisoryKey = (qualified: string): [number, number] => {
-  const digest = sha256(new TextEncoder().encode(`owlmeans:${qualified}`))
-  const view = new DataView(digest.buffer, digest.byteOffset, digest.byteLength)
-
-  return [view.getInt32(0, false), view.getInt32(4, false)]
+    return [view.getInt32(0, false), view.getInt32(4, false)]
+  }
+
+  return { pgIdentifier, assertSqlIdentifier, quoteIdent, quoteLiteral, qualify, pgTableName, advisoryKey }
 }
+
+export const pgNameHelper = createPgNameHelper()
+
+/** @deprecated compat:factory-refactor — use `pgNameHelper.pgIdentifier(…)` */
+export const pgIdentifier = (name: string): string => pgNameHelper.pgIdentifier(name)
+
+/** @deprecated compat:factory-refactor — use `pgNameHelper.quoteIdent(…)` */
+export const quoteIdent = (value: string): string => pgNameHelper.quoteIdent(value)
+
+/** @deprecated compat:factory-refactor — use `pgNameHelper.advisoryKey(…)` */
+export const advisoryKey = (qualified: string): [number, number] => pgNameHelper.advisoryKey(qualified)

package/src/utils/schema/types.ts

@@ -0,0 +1,26 @@
+import type { AnySchema } from 'ajv'
+
+import type { PgIndexSpec, TableSpec } from '../../types.js'
+
+/** The JSON Schema → table specification compiler. */
+export interface PgSchemaHelper {
+  /**
+   * Normalize a Postgres type name to the spelling `format_type()` reports, so the drift
+   * comparison against a live table is an exact string match instead of a fuzzy one.
+   */
+  toFormatType: (type: string) => string
+  /**
+   * Compile a resource's AJV schema into the table specification that drives both DDL
+   * emission and drift detection.
+   *
+   * `extraIndexes` carries what `resource.index()` declared. It's compiled here rather than
+   * merged afterwards so chained declarations get the same property-to-column mapping and
+   * the same generated names as schema-borne ones.
+   *
+   * @throws {UnsupportedArgumentError} when an override asks for something unrepresentable.
+   */
+  schemaToTableSpec: (
+    alias: string, schema: AnySchema | undefined, pgSchema: string, table: string,
+    autoSync: boolean, extraIndexes?: PgIndexSpec[]
+  ) => TableSpec
+}