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

package/src/utils/criteria.ts

@@ -1,6 +1,6 @@
 import { UnsupportedArgumentError } from '@owlmeans/resource'
-import type { ListCriteria, ListSort } from '@owlmeans/resource'
-import { and, asc, desc, or, sql } from 'drizzle-orm'
+import type { Criteria, FieldOperators, Sort } from '@owlmeans/resource'
+import { and, asc, desc, or, param, sql } from 'drizzle-orm'
 import type { SQL } from 'drizzle-orm'
 
 import type { ColumnSpec, PgRuntimeTable, TableSpec } from '../types.js'
@@ -19,6 +19,58 @@ const value = (raw: unknown, column: ColumnSpec): SQL => {
   return sql`${raw}`
 }
 
+/** The operand of an array operator as a list — a scalar is the list of itself. */
+const listOf = (operand: unknown): unknown[] => Array.isArray(operand) ? operand : [operand]
+
+const isPlainObject = (raw: unknown): raw is Record<string, unknown> =>
+  raw != null && typeof raw === 'object' && !Array.isArray(raw) && !(raw instanceof Date)
+
+/** A JSON value as a bound `jsonb` literal. */
+const json = (raw: unknown): SQL => sql`${JSON.stringify(raw instanceof Date ? raw.toISOString() : raw)}::jsonb`
+
+/** `ARRAY[$1, $2]::jsonb[]` — one bound JSON literal per value. */
+const jsonList = (values: unknown[]): SQL => values.length === 0
+  ? sql`ARRAY[]::jsonb[]`
+  : sql`ARRAY[${sql.join(values.map(entry => sql`${JSON.stringify(entry instanceof Date ? entry.toISOString() : entry)}`), sql`, `)}]::jsonb[]`
+
+/**
+ * `@>` / `<@` against a jsonb value: an object is contained as an object, anything else as the
+ * JSON array it is (or the array of the one value it is).
+ */
+const jsonContainment = (target: SQL, operator: '@>' | '<@', operand: unknown): SQL =>
+  sql`${target} ${sql.raw(operator)} ${json(isPlainObject(operand) ? operand : listOf(operand))}`
+
+/**
+ * `&&` has no jsonb form: an array value overlaps when one of its elements is one of the operands,
+ * and a scalar value — like every other store reads it — when it is one of them.
+ */
+const jsonOverlap = (target: SQL, operand: unknown): SQL => {
+  const values = listOf(operand)
+  return sql`(CASE WHEN jsonb_typeof(${target}) = 'array' THEN EXISTS (SELECT 1 FROM jsonb_array_elements(${target}) AS element WHERE element = ANY(${jsonList(values)})) ELSE ${target} = ANY(${jsonList(values)}) END)`
+}
+
+/**
+ * `@>` / `<@` / `&&` on a column. A native array column takes ONE bound array parameter cast to the
+ * column's own type (a bare JS array in a template would expand into a row constructor), a jsonb
+ * column takes JSON, and a scalar operand is the one-element list either way.
+ */
+const arrayOperator = (
+  table: PgRuntimeTable, column: ColumnSpec, operator: '$contains' | '$contained' | '$overlaps', operand: unknown
+): SQL => {
+  const target = columnRef(table, column)
+  if (column.jsonb) {
+    return operator === '$overlaps'
+      ? jsonOverlap(target, operand)
+      : jsonContainment(target, operator === '$contains' ? '@>' : '<@', operand)
+  }
+  const symbol = sql.raw(operator === '$contains' ? '@>' : operator === '$contained' ? '<@' : '&&')
+  if (column.array) {
+    return sql`${target} ${symbol} ${param(listOf(operand))}::${sql.raw(column.sqlType)}`
+  }
+
+  return sql`${target} ${symbol} ${value(operand, column)}`
+}
+
 const inList = (table: PgRuntimeTable, column: ColumnSpec, values: unknown[], negate: boolean): SQL => {
   const present = values.filter(entry => entry != null)
   const hasNull = present.length !== values.length
@@ -48,7 +100,7 @@ const inList = (table: PgRuntimeTable, column: ColumnSpec, values: unknown[], ne
 }
 
 const operators = (
-  table: PgRuntimeTable, column: ColumnSpec, spec: Record<string, unknown>
+  table: PgRuntimeTable, column: ColumnSpec, spec: FieldOperators<any>
 ): SQL[] => {
   const conditions: SQL[] = []
   for (const [operator, operand] of Object.entries(spec)) {
@@ -98,13 +150,112 @@ const operators = (
         break
       }
       case '$contains':
-        conditions.push(sql`${columnRef(table, column)} @> ${value(operand, column)}`)
+      case '$contained':
+      case '$overlaps':
+        conditions.push(arrayOperator(table, column, operator, operand))
+        break
+      default:
+        throw new UnsupportedArgumentError(`criteria-operator:${operator}`)
+    }
+  }
+
+  return conditions
+}
+
+const escapeLike = (value: string): string => value.replace(/[\\%_]/g, match => `\\${match}`)
+
+// ─── Dotted paths into a jsonb column ────────────────────────────────────────────────────────────
+
+/**
+ * A value at a path, as the jsonb it is (`#>`) and as text (`#>>`). The path is ONE bound `text[]`
+ * parameter, so a segment holding a comma or a brace stays one segment.
+ */
+interface PathTarget {
+  value: SQL
+  text: SQL
+  /** Absent, or a JSON `null` — what every other store reads as "no value". */
+  missing: SQL
+}
+
+const pathTarget = (table: PgRuntimeTable, column: ColumnSpec, path: string[]): PathTarget => {
+  const value = sql`(${columnRef(table, column)} #> ${param(path)}::text[])`
+
+  return {
+    value,
+    text: sql`(${columnRef(table, column)} #>> ${param(path)}::text[])`,
+    missing: sql`(${value} IS NULL OR ${value} = 'null'::jsonb)`,
+  }
+}
+
+/** `$in` / `$nin` / a bare list at a path — the column rules: a `null` entry widens to absence. */
+const pathList = (target: PathTarget, values: unknown[], negate: boolean): SQL => {
+  const present = values.filter(entry => entry != null)
+  const hasNull = present.length !== values.length
+
+  if (present.length < 1) {
+    return hasNull
+      ? negate ? sql`NOT ${target.missing}` : target.missing
+      : negate ? sql`TRUE` : sql`FALSE`
+  }
+  const membership = sql`${target.value} = ANY(${jsonList(present)})`
+  if (negate) {
+    return sql`(NOT ${target.missing} AND NOT (${membership}))`
+  }
+
+  return hasNull ? sql`(${membership} OR ${target.missing})` : membership
+}
+
+/** The operators at a path, each read as the same operator reads on a column. */
+const pathOperators = (target: PathTarget, spec: FieldOperators<any>, key: string): SQL[] => {
+  const conditions: SQL[] = []
+  for (const [operator, operand] of Object.entries(spec)) {
+    if (operator in COMPARISON) {
+      conditions.push(operand == null
+        ? operator === '$ne' ? sql`NOT ${target.missing}` : target.missing
+        : sql`${target.value} ${sql.raw(COMPARISON[operator])} ${json(operand)}`)
+      continue
+    }
+    switch (operator) {
+      case '$in':
+      case '$nin':
+        conditions.push(pathList(target, listOf(operand), operator === '$nin'))
+        break
+      case '$exists':
+        conditions.push(operand === false ? target.missing : sql`NOT ${target.missing}`)
+        break
+      case '$null':
+        conditions.push(operand === false ? sql`NOT ${target.missing}` : target.missing)
+        break
+      case '$like':
+        conditions.push(sql`${target.text} LIKE ${operand}`)
+        break
+      case '$ilike':
+        conditions.push(sql`${target.text} ILIKE ${operand}`)
+        break
+      case '$regex':
+        conditions.push(sql`${target.text} ~ ${operand}`)
+        break
+      case '$startsWith':
+        conditions.push(sql`${target.text} LIKE ${`${escapeLike(`${operand}`)}%`}`)
+        break
+      case '$endsWith':
+        conditions.push(sql`${target.text} LIKE ${`%${escapeLike(`${operand}`)}`}`)
+        break
+      case '$between': {
+        if (!Array.isArray(operand) || operand.length !== 2) {
+          throw new UnsupportedArgumentError(`criteria:$between:${key}`)
+        }
+        conditions.push(sql`${target.value} BETWEEN ${json(operand[0])} AND ${json(operand[1])}`)
+        break
+      }
+      case '$contains':
+        conditions.push(jsonContainment(target.value, '@>', operand))
         break
       case '$contained':
-        conditions.push(sql`${columnRef(table, column)} <@ ${value(operand, column)}`)
+        conditions.push(jsonContainment(target.value, '<@', operand))
         break
       case '$overlaps':
-        conditions.push(sql`${columnRef(table, column)} && ${value(operand, column)}`)
+        conditions.push(jsonOverlap(target.value, operand))
         break
       default:
         throw new UnsupportedArgumentError(`criteria-operator:${operator}`)
@@ -114,30 +265,55 @@ const operators = (
   return conditions
 }
 
-const escapeLike = (value: string): string => value.replace(/[\\%_]/g, match => `\\${match}`)
+/**
+ * A criteria value at a dotted path, with the meaning it has on a column: a bare value is typed
+ * JSON equality (a number is not its text), a bare list is membership, `null` is absence, an object
+ * of operators applies each, and a plain object is containment.
+ */
+const pathCondition = (target: PathTarget, raw: unknown, key: string): SQL[] => {
+  if (raw === null) {
+    return [target.missing]
+  }
+  if (isOperatorSpec(raw)) {
+    return pathOperators(target, raw, key)
+  }
+  if (Array.isArray(raw)) {
+    return [pathList(target, raw, false)]
+  }
+  if (isPlainObject(raw)) {
+    return [jsonContainment(target.value, '@>', raw)]
+  }
 
-const isOperatorSpec = (value: unknown): value is Record<string, unknown> =>
+  return [sql`${target.value} = ${json(raw)}`]
+}
+
+/**
+ * An object naming at least one `$` key is a spec, not a value to compare against.
+ * A Date and an array are values even though both are objects.
+ */
+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 `ListCriteria` into a WHERE clause.
+ * 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 = (
-  criteria: ListCriteria | undefined, spec: TableSpec, table: PgRuntimeTable
+export 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
 }
 
-const build = (
-  criteria: ListCriteria | undefined, spec: TableSpec, table: PgRuntimeTable
+const build = <T>(
+  criteria: Criteria<T> | undefined, spec: TableSpec, table: PgRuntimeTable
 ): SQL[] => {
   const conditions: SQL[] = []
   for (const [key, raw] of Object.entries(criteria ?? {})) {
@@ -147,7 +323,7 @@ const build = (
 
     if (key === '$and' || key === '$or') {
       const parts = (Array.isArray(raw) ? raw : [raw])
-        .map(entry => and(...build(entry as ListCriteria, spec, table)))
+        .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)
@@ -158,7 +334,7 @@ const build = (
       continue
     }
     if (key === '$not') {
-      const inner = and(...build(raw as ListCriteria, spec, table))
+      const inner = and(...build(raw as Criteria<T>, spec, table))
       if (inner != null) {
         conditions.push(sql`NOT (${inner})`)
       }
@@ -175,7 +351,7 @@ const build = (
       if (!column.jsonb) {
         throw new UnsupportedArgumentError(`criteria-path:${key}`)
       }
-      conditions.push(sql`${columnRef(table, column)} #>> ${`{${path.join(',')}}`} = ${`${raw}`}`)
+      conditions.push(...pathCondition(pathTarget(table, column, path), raw, key))
       continue
     }
 
@@ -184,7 +360,7 @@ const build = (
       continue
     }
     if (isOperatorSpec(raw)) {
-      conditions.push(...operators(table, column, raw as Record<string, unknown>))
+      conditions.push(...operators(table, column, raw))
       continue
     }
     if (Array.isArray(raw)) {
@@ -206,24 +382,27 @@ const build = (
 }
 
 /**
- * Translate `ListPager.sort` into ORDER BY. `[field, true]` is descending, matching the
- * `order ? -1 : 1` mapping mongo uses.
+ * 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 = (
-  sort: ListSort[] | undefined, spec: TableSpec, table: PgRuntimeTable
+export const sortToSql = <T>(
+  sort: Sort<T>[] | undefined, spec: TableSpec, table: PgRuntimeTable
 ): SQL[] => {
   const order: SQL[] = []
   const seen: string[] = []
 
   for (const entry of sort ?? []) {
-    /** Both `ListSort` forms are handled explicitly — destructuring a plain string yields characters. */
-    const [property, descending] = typeof entry === 'string' ? [entry, false] : [entry[0], entry[1] === true]
+    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}`)

package/src/utils/diff.ts

@@ -23,19 +23,44 @@ const defaultExpression = (column: ColumnSpec): string | undefined => {
   return undefined
 }
 
+/** A type cast as `pg_get_expr` / `pg_get_indexdef` print one: `::text`, `::character varying(64)[]`. */
+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
+
 /**
- * Postgres echoes defaults back with an explicit cast — a declared `'active'` comes back
- * as `'active'::text`. Strip a trailing cast when the literal underneath still matches, so
- * an unchanged default doesn't look like drift on every boot.
+ * Postgres echoes defaults back with explicit casts — a declared `'active'` comes back as
+ * `'active'::text`. Compare without them, so an unchanged default doesn't look like drift on
+ * every boot.
  */
 const normalizeDefault = (expression: string | null | undefined): string | null => {
   if (expression == null) return null
 
-  return expression.trim().replace(/::[a-z0-9_ ."\[\]]+$/i, '').trim().toLowerCase()
+  /**
+   * Casts anywhere (a `varchar` id's `gen_random_uuid()::text` is stored as
+   * `(gen_random_uuid())::character varying`) and the parentheses Postgres adds around them.
+   */
+  return expression.toLowerCase().replace(CAST, '').replace(/[()]/g, '').replace(/\s+/g, ' ').trim()
 }
 
-const normalizeDefinition = (definition: string): string =>
-  definition.replace(/\s+/g, ' ').replace(/ ?, ?/g, ',').trim().toLowerCase()
+/**
+ * The form an index or constraint definition is compared in, so the statement this package emits
+ * and the text Postgres reports for the object it created compare equal.
+ *
+ * Postgres deparses what it stores: it leaves an identifier unquoted when it can, casts every
+ * literal (`''::text`), casts a `varchar` column inside an expression, wraps a partial predicate and
+ * each of its operator expressions in parentheses, and rewrites `x IN (…)` as `x = ANY (ARRAY[…])`.
+ * Comparing the raw texts made every boot drop and recreate every declared index and every enum
+ * `CHECK`. So both sides lose case, quotes, casts, whitespace and parentheses, and `= ANY (ARRAY[…])`
+ * reads as `IN (…)`. What that cannot tell apart — two definitions differing only in how their
+ * operators group — is a change to make under a new name.
+ */
+export const canonicalDefinition = (definition: string): string => definition
+  .toLowerCase()
+  .replace(/"/g, '')
+  .replace(CAST, '')
+  .replace(/[\s()]/g, '')
+  .replace(/=anyarray\[([^\]]*)\]/g, 'in$1')
+
+const normalizeDefinition = canonicalDefinition
 
 const columnList = (columns: string[]): string => columns.map(quoteIdent).join(', ')
 
@@ -194,7 +219,31 @@ export const planSync = (
       continue
     }
 
+    /**
+     * A retype drops the column's default first.
+     *
+     * Postgres refuses `ALTER COLUMN … TYPE` outright when the column carries a DEFAULT it cannot
+     * cast to the new type — `42804 default for column "x" cannot be cast automatically` — and it
+     * refuses it before looking at a single row, so the `USING` clause never gets a chance to
+     * help. The whole plan runs in one transaction, so that refusal aborts the entire
+     * reconciliation: the table keeps its old shape and the resource fails every boot with an
+     * error about a column it is trying to fix. The standard remedy is to take the default out of
+     * the way, retype, and put it back — which is what the default-drift block below does, from
+     * the spec rather than from whatever the column happened to be carrying.
+     *
+     * The `id` column is the one that meets this in practice: it is created with a
+     * `gen_random_uuid()::text` default, so any change to its declared type hits this path.
+     */
+    let defaultDropped = false
     if (!additive && existing.type !== column.sqlType) {
+      if (existing.defaultExpr != null) {
+        statements.push({
+          kind: 'set-default',
+          target: column.column,
+          sql: `ALTER TABLE ${spec.qualified} ALTER COLUMN ${quoteIdent(column.column)} DROP DEFAULT`
+        })
+        defaultDropped = true
+      }
       const using = column.using ?? `${quoteIdent(column.column)}::${column.sqlType}`
       statements.push({
         kind: 'alter-type',
@@ -205,7 +254,13 @@ export const planSync = (
     }
 
     const expression = defaultExpression(column)
-    if (normalizeDefault(expression) !== normalizeDefault(existing.defaultExpr)) {
+    // Once the retype has dropped it, the default has to be re-stated even when it matches what
+    // the column used to carry: the comparison is against the pre-plan introspection, which stops
+    // describing the column the moment the plan drops its default.
+    const defaultDrifted = defaultDropped
+      ? expression != null
+      : normalizeDefault(expression) !== normalizeDefault(existing.defaultExpr)
+    if (defaultDrifted) {
       statements.push(expression != null
         ? {
           kind: 'set-default',

package/src/utils/migrations.ts

@@ -15,29 +15,32 @@ export const makeTx = (
   client,
 
   query: async <Row extends QueryResultRow = QueryResultRow>(text: string, params?: unknown[]) => {
+    const query = resolve(text)
     try {
-      const result = await client.query<Row>(resolve(text), params as never[])
+      const result = await client.query<Row>(query, params as never[])
       return result.rows
     } catch (error) {
-      throw pgErrorToResourceError(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>(resolve(text), params as never[])
+      const result = await client.query<Row>(query, params as never[])
       return result.rows[0] ?? null
     } catch (error) {
-      throw pgErrorToResourceError(error)
+      throw pgErrorToResourceError(error, query)
     }
   },
 
   execute: async (text: string, params?: unknown[]) => {
+    const query = resolve(text)
     try {
-      const result = await client.query(resolve(text), params as never[])
+      const result = await client.query(query, params as never[])
       return result.rowCount ?? 0
     } catch (error) {
-      throw pgErrorToResourceError(error)
+      throw pgErrorToResourceError(error, query)
     }
   },
 
@@ -47,8 +50,8 @@ export const makeTx = (
 /**
  * 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.
+ * It lives inside the resource's own schema, so every schema carries the ledger for the
+ * tables it holds — correct, because those tables are what the migrations changed.
  */
 export const makeMigrationStore = (
   client: PoolClient,

package/src/utils/name.ts

@@ -10,9 +10,9 @@ 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.
+ * 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, '_')

package/src/utils/table.ts

@@ -24,6 +24,10 @@ const pgRaw = customType<{ data: unknown, driverData: unknown, config: { sqlType
  * Build the Drizzle table used for CRUD query construction. Structure DDL is emitted from
  * the {@link TableSpec} directly — Drizzle exposes no runtime DDL generator (that lives in
  * drizzle-kit, which would be a second owner of the same tables).
+ *
+ * The result is stated as a {@link PgRuntimeTable}: the columns exist, keyed by schema
+ * property name, but only this function knows which ones — Drizzle's own inference has a
+ * literal column map to work from, and here that map was assembled a few lines ago.
  */
 export const specToTable = (spec: TableSpec): PgRuntimeTable => {
   const namespace = pgSchema(spec.schema)
@@ -72,5 +76,5 @@ export const specToTable = (spec: TableSpec): PgRuntimeTable => {
           .filter((column: unknown) => column != null) as [any, ...any[]]
       })]
       : [])
-  ]) as PgRuntimeTable
+  ]) as unknown as PgRuntimeTable
 }