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

package/src/utils/index.ts

@@ -1,12 +1,21 @@
 export * from './criteria.js'
+export type * from './criteria/types.js'
 export * from './diff.js'
+export type * from './diff/types.js'
 export * from './introspect.js'
+export type * from './introspect/types.js'
 export * from './life-cycle.js'
+export type * from './life-cycle/types.js'
 export type * from './types.js'
 export * from './marshal.js'
+export type * from './marshal/types.js'
 export * from './migrations.js'
 export * from './name.js'
+export type * from './name/types.js'
 export * from './schema.js'
+export type * from './schema/types.js'
 export * from './sql.js'
+export type * from './sql/types.js'
 export * from './sync.js'
+export type * from './sync/types.js'
 export * from './table.js'

package/src/utils/introspect/types.ts

@@ -0,0 +1,9 @@
+import type { LiveTable } from '../../types.js'
+
+/** Catalog reads over one checked out connection. */
+export interface PgIntrospectHelper {
+  /** Read the table exactly as Postgres currently holds it. */
+  introspectTable: (schema: string, table: string, qualified: string) => Promise<LiveTable>
+  /** Count the rows a destructive step would lose, so the boot log can say how much. */
+  countNonNull: (qualified: string, column: string) => Promise<number>
+}

package/src/utils/introspect.ts

@@ -2,55 +2,61 @@ import type { PoolClient } from 'pg'
 
 import type { LiveColumn, LiveConstraint, LiveIndex, LiveTable } from '../types.js'
 import { COLUMNS, CONSTRAINTS, INDEXES } from './consts.local.js'
+import type { PgIntrospectHelper } from './introspect/types.js'
 
-/** Read the table exactly as Postgres currently holds it. */
-export const introspectTable = async (
-  client: PoolClient, schema: string, table: string, qualified: string
-): Promise<LiveTable> => {
-  const exists = await client.query<{ present: boolean }>(
-    'SELECT to_regclass($1) IS NOT NULL AS present', [qualified]
-  )
-  if (exists.rows[0]?.present !== true) {
-    return { exists: false, columns: [], indexes: [], constraints: [] }
-  }
+export const makePgIntrospectHelper = (client: PoolClient): PgIntrospectHelper => {
+  const introspectTable = async (
+    schema: string, table: string, qualified: string
+  ): Promise<LiveTable> => {
+    const exists = await client.query<{ present: boolean }>(
+      'SELECT to_regclass($1) IS NOT NULL AS present', [qualified]
+    )
+    if (exists.rows[0]?.present !== true) {
+      return { exists: false, columns: [], indexes: [], constraints: [] }
+    }
+
+    /**
+     * Sequential, not `Promise.all`: this is one checked out connection, and a connection
+     * runs one statement at a time. Overlapping them only queues them behind each other —
+     * and node-postgres deprecated tolerating it.
+     */
+    const columns = await client.query<LiveColumn>(COLUMNS, [qualified])
+    const indexes = await client.query<LiveIndex>(INDEXES, [schema, table])
+    const constraints = await client.query<LiveConstraint>(CONSTRAINTS, [qualified])
 
-  /**
-   * Sequential, not `Promise.all`: this is one checked out connection, and a connection
-   * runs one statement at a time. Overlapping them only queues them behind each other —
-   * and node-postgres deprecated tolerating it.
-   */
-  const columns = await client.query<LiveColumn>(COLUMNS, [qualified])
-  const indexes = await client.query<LiveIndex>(INDEXES, [schema, table])
-  const constraints = await client.query<LiveConstraint>(CONSTRAINTS, [qualified])
-
-  return {
-    exists: true,
-    columns: columns.rows.map(row => ({
-      name: row.name,
-      type: row.type,
-      notNull: (row as unknown as { not_null: boolean }).not_null,
-      defaultExpr: (row as unknown as { default_expr: string | null }).default_expr,
-      identity: row.identity ?? '',
-      generated: row.generated ?? '',
-      ordinal: row.ordinal
-    })),
-    indexes: indexes.rows,
-    constraints: constraints.rows
+    return {
+      exists: true,
+      columns: columns.rows.map(row => ({
+        name: row.name,
+        type: row.type,
+        notNull: (row as unknown as { not_null: boolean }).not_null,
+        defaultExpr: (row as unknown as { default_expr: string | null }).default_expr,
+        identity: row.identity ?? '',
+        generated: row.generated ?? '',
+        ordinal: row.ordinal
+      })),
+      indexes: indexes.rows,
+      constraints: constraints.rows
+    }
   }
-}
 
-/** Count the rows a destructive step would lose, so the boot log can say how much. */
-export const countNonNull = async (
-  client: PoolClient, qualified: string, column: string
-): Promise<number> => {
-  try {
-    const result = await client.query<{ count: string }>(
-      `SELECT count(*)::text AS count FROM ${qualified} WHERE "${column.replace(/"/g, '""')}" IS NOT NULL`
-    )
+  const countNonNull = async (qualified: string, column: string): Promise<number> => {
+    try {
+      const result = await client.query<{ count: string }>(
+        `SELECT count(*)::text AS count FROM ${qualified} WHERE "${column.replace(/"/g, '""')}" IS NOT NULL`
+      )
 
-    return parseInt(result.rows[0]?.count ?? '0', 10)
-  } catch {
-    /** Never let a diagnostic read break reconciliation. */
-    return -1
+      return parseInt(result.rows[0]?.count ?? '0', 10)
+    } catch {
+      /** Never let a diagnostic read break reconciliation. */
+      return -1
+    }
   }
+
+  return { introspectTable, countNonNull }
 }
+
+/** @deprecated compat:factory-refactor — use `makePgIntrospectHelper(client).introspectTable(…)` */
+export const introspectTable = async (
+  client: PoolClient, schema: string, table: string, qualified: string
+): Promise<LiveTable> => makePgIntrospectHelper(client).introspectTable(schema, table, qualified)

package/src/utils/life-cycle/types.ts

@@ -0,0 +1,41 @@
+import type { BasicContext } from '@owlmeans/context'
+import type { DbConfig, ResourceRecord } from '@owlmeans/resource'
+
+import type { PostgresResource, TableSpec } from '../../types.js'
+import type { TableInit } from '../types.js'
+
+/** A resource table's initialization over one database handle. */
+export interface PgLifeCycleHelper {
+  /**
+   * Bring a resource's table to the shape its schema declares, then hand back everything the
+   * resource needs to query it. The Postgres counterpart of mongo's `initializeCollection`.
+   *
+   * The whole sequence runs inside a session level advisory lock keyed on the qualified table
+   * name, so replicas booting simultaneously converge one at a time instead of racing each
+   * other's DDL — a race mongo's converge-on-boot leaves open.
+   *
+   * Order is deliberate:
+   *
+   *  1. probe for the table
+   *  2. absent → *baseline* every registered migration; present → run the `pre` ones
+   *  3. reconcile structure against the schema
+   *  4. present → run the `post` migrations
+   *  5. queue foreign keys for after every resource has initialized
+   *
+   * Step 2 is what stops the two mechanisms colliding. On a fresh deployment the table is
+   * created directly to its final shape, so migrations that would have produced that shape
+   * are recorded as satisfied rather than replayed against a table that already matches.
+   */
+  initializeTable: (
+    config: DbConfig, resource: PostgresResource<ResourceRecord>,
+    context: BasicContext<any>, defer: (task: () => Promise<void>) => void
+  ) => Promise<TableInit>
+  /**
+   * Add the foreign keys the schema declares, skipping any Postgres already holds.
+   *
+   * Constraints are compared by name only. A key whose *definition* drifted has to be dropped
+   * by hand or in a migration: `ALTER TABLE ... DROP CONSTRAINT` on a foreign key is not a
+   * change worth making on a boot nobody is watching.
+   */
+  applyForeignKeys: (spec: TableSpec, context: BasicContext<any>) => Promise<void>
+}

package/src/utils/life-cycle.ts

@@ -4,145 +4,126 @@ import { logger } from '@owlmeans/log'
 import type { PoolClient } from 'pg'
 
 import { DEF_MIGRATIONS_TABLE, PgAutoSync } from '../consts.js'
-import { getDeclaration } from '../declarations.js'
-import { describePgError, pgErrorToResourceError } from '../errors.js'
+import { pgDeclarationHelper } from '../declarations.js'
+import { pgErrorHelper } from '../pg-error.js'
 import type { PostgresDb, PostgresMeta, PostgresResource, TableSpec } from '../types.js'
-import { planForeignKeys, planSync } from './diff.js'
-import { introspectTable } from './introspect.js'
+import { pgDiffHelper } from './diff.js'
+import { makePgIntrospectHelper } from './introspect.js'
+import type { PgLifeCycleHelper } from './life-cycle/types.js'
 import { makeMigrationStore } from './migrations.js'
-import { pgTableName } from './name.js'
-import { schemaToTableSpec } from './schema.js'
-import { refOf, resolvePlaceholders } from './sql.js'
-import { acquireLock, applyPlan, ensureSchema, releaseLock } from './sync.js'
+import { pgNameHelper } from './name.js'
+import { pgSchemaHelper } from './schema.js'
+import { pgPlaceholdersOf } from './sql.js'
+import { makePgSyncHelper } from './sync.js'
 import { specToTable } from './table.js'
 import type { TableInit } from './types.js'
 
 const log = logger('postgres-resource')
 
-/**
- * Bring a resource's table to the shape its schema declares, then hand back everything the
- * resource needs to query it. The Postgres counterpart of mongo's `initializeCollection`.
- *
- * The whole sequence runs inside a session level advisory lock keyed on the qualified table
- * name, so replicas booting simultaneously converge one at a time instead of racing each
- * other's DDL — a race mongo's converge-on-boot leaves open.
- *
- * Order is deliberate:
- *
- *  1. probe for the table
- *  2. absent → *baseline* every registered migration; present → run the `pre` ones
- *  3. reconcile structure against the schema
- *  4. present → run the `post` migrations
- *  5. queue foreign keys for after every resource has initialized
- *
- * Step 2 is what stops the two mechanisms colliding. On a fresh deployment the table is
- * created directly to its final shape, so migrations that would have produced that shape
- * are recorded as satisfied rather than replayed against a table that already matches.
- */
-export const initializeTable = async (
-  db: PostgresDb, config: DbConfig, resource: PostgresResource<ResourceRecord>,
-  context: BasicContext<any>, defer: (task: () => Promise<void>) => void
-): Promise<TableInit> => {
-  const declaration = getDeclaration(resource.alias)
-  const meta = (config.meta ?? {}) as PostgresMeta
-  const mode = meta.autoSync ?? PgAutoSync.Full
-
-  const spec = schemaToTableSpec(
-    resource.alias, resource.schema ?? declaration.schema, db.schema,
-    pgTableName(config, resource), mode !== PgAutoSync.Off, declaration.indexes
-  )
-  const entity = specToTable(spec)
-  const reports: MigrationReport[] = []
-
-  const client = await db.pool.connect()
-  try {
-    await acquireLock(client, spec.qualified)
-    await ensureSchema(client, spec.schema)
-
-    const resolve = (text: string): string => resolvePlaceholders(text, context, spec)
-    const ref = (alias?: string): string => refOf(context, spec, alias)
-    const store = makeMigrationStore(client, spec, DEF_MIGRATIONS_TABLE, resolve, ref)
-
-    const fresh = !(await introspectTable(client, spec.schema, spec.table, spec.qualified)).exists
-
-    reports.push(await runMigrations(resource.alias, declaration.migrations, store, fresh
-      ? { baseline: true }
-      : { stage: MigrationStage.Pre }))
-
-    if (spec.autoSync) {
-      /** Re-read: a `pre` migration may have reshaped exactly what the diff is about to compare. */
-      const live = await introspectTable(client, spec.schema, spec.table, spec.qualified)
-      const plan = planSync(spec, live, mode === PgAutoSync.Additive)
-      await applyPlan(client, spec, plan)
-    }
+export const makePgLifeCycleHelper = (db: PostgresDb): PgLifeCycleHelper => {
+  const { describePgError, pgErrorToResourceError } = pgErrorHelper
+
+  const initializeTable = async (
+    config: DbConfig, resource: PostgresResource<ResourceRecord>,
+    context: BasicContext<any>, defer: (task: () => Promise<void>) => void
+  ): Promise<TableInit> => {
+    const declaration = pgDeclarationHelper.getDeclaration(resource.alias)
+    const meta = (config.meta ?? {}) as PostgresMeta
+    const mode = meta.autoSync ?? PgAutoSync.Full
+
+    const spec = pgSchemaHelper.schemaToTableSpec(
+      resource.alias, resource.schema ?? declaration.schema, db.schema,
+      pgNameHelper.pgTableName(config, resource), mode !== PgAutoSync.Off, declaration.indexes
+    )
+    const entity = specToTable(spec)
+    const reports: MigrationReport[] = []
+
+    const client = await db.pool.connect()
+    const sync = makePgSyncHelper(client)
+    const introspect = makePgIntrospectHelper(client)
+    try {
+      await sync.acquireLock(spec.qualified)
+      await sync.ensureSchema(spec.schema)
+
+      const placeholders = pgPlaceholdersOf(context)
+      const resolve = (text: string): string => placeholders.resolvePlaceholders(text, spec)
+      const ref = (alias?: string): string => placeholders.refOf(spec, alias)
+      const store = makeMigrationStore(client, spec, DEF_MIGRATIONS_TABLE, resolve, ref)
+
+      const fresh = !(await introspect.introspectTable(spec.schema, spec.table, spec.qualified)).exists
+
+      reports.push(await runMigrations(resource.alias, declaration.migrations, store, fresh
+        ? { baseline: true }
+        : { stage: MigrationStage.Pre }))
+
+      if (spec.autoSync) {
+        /** Re-read: a `pre` migration may have reshaped exactly what the diff is about to compare. */
+        const live = await introspect.introspectTable(spec.schema, spec.table, spec.qualified)
+        const plan = pgDiffHelper.planSync(spec, live, mode === PgAutoSync.Additive)
+        await sync.applyPlan(spec, plan)
+      }
 
-    if (!fresh) {
-      reports.push(await runMigrations(
-        resource.alias, declaration.migrations, store, { stage: MigrationStage.Post }
-      ))
-    }
+      if (!fresh) {
+        reports.push(await runMigrations(
+          resource.alias, declaration.migrations, store, { stage: MigrationStage.Post }
+        ))
+      }
 
-    for (const report of reports) {
-      if (report.applied.length > 0) {
-        log.info('Migrations applied', {
-          resource: resource.alias, table: spec.qualified, stage: report.stage, applied: report.applied,
-        }, { event: 'migration.applied' })
+      for (const report of reports) {
+        if (report.applied.length > 0) {
+          log.info('Migrations applied', {
+            resource: resource.alias, table: spec.qualified, stage: report.stage, applied: report.applied,
+          }, { event: 'migration.applied' })
+        }
       }
+    } finally {
+      await sync.releaseLock(spec.qualified)
+      client.release()
     }
-  } finally {
-    await releaseLock(client, spec.qualified)
-    client.release()
-  }
 
-  if (spec.references.length > 0) {
-    defer(async () => { await applyForeignKeys(db, spec, context) })
-  }
+    if (spec.references.length > 0) {
+      defer(async () => { await applyForeignKeys(spec, context) })
+    }
 
-  return { spec, entity, reports }
-}
+    return { spec, entity, reports }
+  }
 
-/**
- * Add the foreign keys the schema declares, skipping any Postgres already holds.
- *
- * Constraints are compared by name only. A key whose *definition* drifted has to be dropped
- * by hand or in a migration: `ALTER TABLE ... DROP CONSTRAINT` on a foreign key is not a
- * change worth making on a boot nobody is watching.
- */
-export const applyForeignKeys = async (
-  db: PostgresDb, spec: TableSpec, context: BasicContext<any>
-): Promise<void> => {
-  const client = await db.pool.connect()
-  try {
-    const statements = planForeignKeys(spec, context)
-    const live = await introspectTable(client, spec.schema, spec.table, spec.qualified)
-    if (!live.exists) {
-      return
-    }
-    const present = live.constraints.map(constraint => constraint.name)
+  const applyForeignKeys = async (spec: TableSpec, context: BasicContext<any>): Promise<void> => {
+    const client = await db.pool.connect()
+    try {
+      const statements = pgDiffHelper.planForeignKeys(spec, context)
+      const live = await makePgIntrospectHelper(client).introspectTable(spec.schema, spec.table, spec.qualified)
+      if (!live.exists) {
+        return
+      }
+      const present = live.constraints.map(constraint => constraint.name)
 
-    for (const statement of statements) {
-      if (present.includes(statement.target)) {
-        continue
+      for (const statement of statements) {
+        if (present.includes(statement.target)) {
+          continue
+        }
+        await apply(client, spec, statement.sql)
       }
-      await apply(client, spec, statement.sql)
+    } finally {
+      client.release()
     }
-  } finally {
-    client.release()
   }
-}
 
-const apply = async (client: PoolClient, spec: TableSpec, statement: string): Promise<void> => {
-  try {
-    await client.query(statement)
-  } catch (error) {
-    const translated = pgErrorToResourceError(error)
-    /**
-     * A foreign key failing means live rows point at nothing. That's a data problem the
-     * boot can't fix, and refusing to start is better than starting with the constraint
-     * quietly missing.
-     */
-    throw Object.assign(translated, {
-      message: `${spec.qualified}: ${describePgError(error)} — statement: ${statement}`
-    })
+  const apply = async (client: PoolClient, spec: TableSpec, statement: string): Promise<void> => {
+    try {
+      await client.query(statement)
+    } catch (error) {
+      const translated = pgErrorToResourceError(error)
+      /**
+       * A foreign key failing means live rows point at nothing. That's a data problem the
+       * boot can't fix, and refusing to start is better than starting with the constraint
+       * quietly missing.
+       */
+      throw Object.assign(translated, {
+        message: `${spec.qualified}: ${describePgError(error)} — statement: ${statement}`
+      })
+    }
   }
+
+  return { initializeTable, applyForeignKeys }
 }

package/src/utils/marshal/types.ts

@@ -0,0 +1,40 @@
+import type { ResourceRecord } from '@owlmeans/resource'
+
+import type { TableSpec } from '../../types.js'
+
+/** Records to driver values and back, driven by a compiled table spec. */
+export interface PgMarshalHelper {
+  /**
+   * 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.
+   */
+  rowToRecord: <T extends ResourceRecord>(row: Record<string, unknown>, spec: TableSpec) => T
+  /**
+   * Same coercion as {@link PgMarshalHelper.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.
+   */
+  resultToRecord: <T extends ResourceRecord>(row: Record<string, unknown>, spec: TableSpec) => 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.
+   */
+  recordToValues: (record: Record<string, unknown>, spec: TableSpec) => Record<string, unknown>
+  /**
+   * 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.
+   */
+  recordToFullValues: (record: Record<string, unknown>, spec: TableSpec) => Record<string, unknown>
+}