@owlmeans/postgres-resource 0.1.15

package/src/utils/marshal.ts

@@ -0,0 +1,175 @@
+import type { ResourceRecord } from '@owlmeans/resource'
+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
+  }
+
+  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.'
+        )
+      }
+
+      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
+  }
+}
+
+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
+    }
+    record[column.property] = fromDriver(value, column)
+  }
+  if (record[ID_FIELD] != null) {
+    record[ID_FIELD] = `${record[ID_FIELD]}`
+  }
+
+  return record as T
+}
+
+/**
+ * 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
+}
+
+/**
+ * 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
+    }
+    values[column.property] = toDriver(value, column)
+  }
+
+  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 value = record[column.property]
+    values[column.property] = value === undefined ? null : toDriver(value, column)
+  }
+
+  return values
+}

package/src/utils/migrations.ts

@@ -0,0 +1,135 @@
+import type { Migration, MigrationStore } from '@owlmeans/resource'
+import type { PoolClient, QueryResultRow } from 'pg'
+
+import { pgErrorToResourceError } from '../errors.js'
+import type { PostgresTx, TableSpec } from '../types.js'
+import { qualify, quoteIdent } from './name.js'
+
+/**
+ * A transaction façade over a checked out client. `{{alias}}` resolution is injected so
+ * migrations can address other resources by alias without importing the context.
+ */
+export const makeTx = (
+  client: PoolClient, resolve: (text: string) => string, ref: (alias?: string) => string
+): PostgresTx => ({
+  client,
+
+  query: async <Row extends QueryResultRow = QueryResultRow>(text: string, params?: unknown[]) => {
+    try {
+      const result = await client.query<Row>(resolve(text), params as never[])
+      return result.rows
+    } catch (error) {
+      throw pgErrorToResourceError(error)
+    }
+  },
+
+  queryOne: async <Row extends QueryResultRow = QueryResultRow>(text: string, params?: unknown[]) => {
+    try {
+      const result = await client.query<Row>(resolve(text), params as never[])
+      return result.rows[0] ?? null
+    } catch (error) {
+      throw pgErrorToResourceError(error)
+    }
+  },
+
+  execute: async (text: string, params?: unknown[]) => {
+    try {
+      const result = await client.query(resolve(text), params as never[])
+      return result.rowCount ?? 0
+    } catch (error) {
+      throw pgErrorToResourceError(error)
+    }
+  },
+
+  ref
+})
+
+/**
+ * Migration ledger, one table per Postgres schema.
+ *
+ * It lives inside the resource's own schema, so an Entity layer schema carries its own
+ * ledger — correct, because it also carries its own tables.
+ */
+export const makeMigrationStore = (
+  client: PoolClient,
+  spec: TableSpec,
+  table: string,
+  resolve: (text: string) => string,
+  ref: (alias?: string) => string
+): MigrationStore<PostgresTx> => {
+  const ledger = qualify(spec.schema, table)
+
+  return {
+    ensure: async () => {
+      try {
+        await client.query(
+          `CREATE TABLE IF NOT EXISTS ${ledger} (`
+          + `  ${quoteIdent('alias')} text NOT NULL,`
+          + `  ${quoteIdent('name')} text NOT NULL,`
+          + `  ${quoteIdent('stage')} text NOT NULL DEFAULT 'pre',`
+          + `  ${quoteIdent('checksum')} text,`
+          + `  ${quoteIdent('baseline')} boolean NOT NULL DEFAULT false,`
+          + `  ${quoteIdent('applied_at')} timestamptz NOT NULL DEFAULT now(),`
+          + `  ${quoteIdent('duration_ms')} integer,`
+          + `  CONSTRAINT ${quoteIdent(`${table}_pkey`)} PRIMARY KEY (${quoteIdent('alias')}, ${quoteIdent('name')})`
+          + ')'
+        )
+      } catch (error) {
+        throw pgErrorToResourceError(error)
+      }
+    },
+
+    applied: async alias => {
+      const result = await client.query<{ name: string, checksum: string | null }>(
+        `SELECT ${quoteIdent('name')}, ${quoteIdent('checksum')} FROM ${ledger} WHERE ${quoteIdent('alias')} = $1`,
+        [alias]
+      )
+
+      return result.rows.reduce<Record<string, string | null>>((applied, row) => {
+        applied[row.name] = row.checksum
+        return applied
+      }, {})
+    },
+
+    baseline: async (alias, migrations) => {
+      const values = migrations
+        .map((_, position) => `($1, $${position * 3 + 2}, $${position * 3 + 3}, $${position * 3 + 4}, true)`)
+        .join(', ')
+      const params: unknown[] = [alias]
+      for (const migration of migrations) {
+        params.push(migration.name, migration.stage, migration.checksum)
+      }
+      try {
+        await client.query(
+          `INSERT INTO ${ledger} (${quoteIdent('alias')}, ${quoteIdent('name')}, ${quoteIdent('stage')},`
+          + ` ${quoteIdent('checksum')}, ${quoteIdent('baseline')}) VALUES ${values}`
+          + ` ON CONFLICT (${quoteIdent('alias')}, ${quoteIdent('name')}) DO NOTHING`,
+          params as never[]
+        )
+      } catch (error) {
+        throw pgErrorToResourceError(error)
+      }
+    },
+
+    run: async (alias: string, migration: Migration<PostgresTx>) => {
+      const started = Date.now()
+      await client.query('BEGIN')
+      try {
+        await migration.apply(makeTx(client, resolve, ref))
+        /**
+         * The ledger row commits with the migration itself, so a migration is never left
+         * half applied and recorded — the pair is atomic or neither happened.
+         */
+        await client.query(
+          `INSERT INTO ${ledger} (${quoteIdent('alias')}, ${quoteIdent('name')}, ${quoteIdent('stage')},`
+          + ` ${quoteIdent('checksum')}, ${quoteIdent('duration_ms')}) VALUES ($1, $2, $3, $4, $5)`,
+          [alias, migration.name, migration.stage, migration.checksum, Date.now() - started] as never[]
+        )
+        await client.query('COMMIT')
+      } catch (error) {
+        await client.query('ROLLBACK').catch(() => undefined)
+        throw pgErrorToResourceError(error)
+      }
+    }
+  }
+}

package/src/utils/name.ts

@@ -0,0 +1,79 @@
+import { sha256 } from '@noble/hashes/sha2'
+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'
+
+const SAFE_IDENTIFIER = /^[A-Za-z_][A-Za-z0-9_$]*$/
+
+/**
+ * Coerce an arbitrary name into a legal Postgres identifier of at most 63 bytes.
+ *
+ * The shared `dbName()` helper's own overflow fallback emits 96 characters, which the
+ * server would silently truncate — losing the hash suffix that made the name unique in
+ * the first place. Truncating here keeps the disambiguator inside the limit.
+ */
+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
+  }
+  const digest = hex.encode(sha256(new TextEncoder().encode(name))).substring(0, 32)
+
+  return `${prefixed.substring(0, 30)}_${digest}`
+}
+
+/**
+ * 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
+}
+
+/** 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, "''")}'`
+}
+
+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)]
+}