@owlmeans/postgres-resource 0.1.18-rc.3 → 0.1.18-rc.31

package/src/utils/criteria.ts

@@ -1,5 +1,5 @@
 import { UnsupportedArgumentError } from '@owlmeans/resource'
-import type { ListCriteria, ListSort } from '@owlmeans/resource'
+import type { Criteria, FieldOperators, Sort } from '@owlmeans/resource'
 import { and, asc, desc, or, sql } from 'drizzle-orm'
 import type { SQL } from 'drizzle-orm'
 
@@ -48,7 +48,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)) {
@@ -116,28 +116,33 @@ const operators = (
 
 const escapeLike = (value: string): string => value.replace(/[\\%_]/g, match => `\\${match}`)
 
-const isOperatorSpec = (value: unknown): value is Record<string, unknown> =>
+/**
+ * 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 +152,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 +163,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})`)
       }
@@ -184,7 +189,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 +211,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

@@ -194,7 +194,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 +229,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

@@ -47,8 +47,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
 }

package/tests/criteria.spec.ts

@@ -0,0 +1,187 @@
+import { describe, expect, test } from 'bun:test'
+import { UnsupportedArgumentError } from '@owlmeans/resource'
+import type { Criteria, Sort } from '@owlmeans/resource'
+import type { AnySchema } from 'ajv'
+import { sql } from 'drizzle-orm'
+import type { SQL } from 'drizzle-orm'
+import { PgDialect } from 'drizzle-orm/pg-core'
+
+import { criteriaToSql, schemaToTableSpec, sortToSql, specToTable } from '@owlmeans/postgres-resource'
+import type { PgRuntimeTable, TableSpec } from '@owlmeans/postgres-resource'
+
+/**
+ * Criteria translation is where a typo becomes either an error or a whole-table scan, and
+ * where a value has to stay a bound parameter instead of becoming statement text. Neither
+ * question needs a database: the dialect renders a clause exactly as the driver would
+ * receive it, so these specs assert on that rendering rather than on query results.
+ */
+
+interface Thing {
+  id?: string
+  email: string
+  status?: string
+  age?: number
+  tags?: string[]
+  profile?: Record<string, unknown>
+}
+
+/** `email` is renamed on purpose — a clause must name the physical column, never the property. */
+const schema = {
+  type: 'object',
+  properties: {
+    id: { type: 'string', format: 'uuid' },
+    email: { type: 'string', pg: { column: 'email_address' } },
+    status: { type: 'string', nullable: true },
+    age: { type: 'integer', nullable: true },
+    tags: { type: 'array', items: { type: 'string' }, nullable: true },
+    profile: { type: 'object', nullable: true }
+  },
+  required: ['id', 'email']
+} as AnySchema
+
+const spec: TableSpec = schemaToTableSpec('things', schema, 'app', 'things', true)
+const table: PgRuntimeTable = specToTable(spec)
+const dialect = new PgDialect()
+
+const render = (statement: SQL): { sql: string, params: unknown[] } => {
+  const query = dialect.sqlToQuery(statement)
+
+  return { sql: query.sql, params: query.params }
+}
+
+const where = (criteria: Criteria<Thing>): { sql: string, params: unknown[] } => {
+  const clause = criteriaToSql(criteria, spec, table)
+  expect(clause).not.toBeUndefined()
+
+  return render(clause as SQL)
+}
+
+const order = (sort?: Sort<Thing>[]): string =>
+  render(sql.join(sortToSql(sort, spec, table), sql`, `)).sql
+
+describe('@owlmeans/postgres-resource — criteriaToSql', () => {
+  test('reads a bare value as equality, against the physical column', () => {
+    const clause = where({ email: 'a@b.c' })
+
+    expect(clause.sql).toContain('"email_address"')
+    expect(clause.sql).toContain('=')
+    /** The value never reaches the statement text. */
+    expect(clause.sql).not.toContain('a@b.c')
+    expect(clause.params).toEqual(['a@b.c'])
+  })
+
+  test('reads a bare array as membership and null as absence', () => {
+    const list = where({ status: ['open', 'done'] })
+    expect(list.sql).toContain('IN')
+    expect(list.params).toEqual(['open', 'done'])
+
+    expect(where({ status: null }).sql).toContain('IS NULL')
+  })
+
+  /** `IN` never matches NULL, so a list carrying one has to be widened explicitly. */
+  test('widens a membership list that carries a null', () => {
+    const clause = where({ status: { $in: ['open', null] } })
+
+    expect(clause.sql).toContain('IN')
+    expect(clause.sql).toContain('IS NULL')
+    expect(clause.params).toEqual(['open'])
+  })
+
+  /** Postgres rejects an empty `IN ()`, and an empty set matches nothing — or everything, negated. */
+  test('collapses a membership list Postgres would reject', () => {
+    expect(where({ status: { $in: [] } }).sql).toContain('FALSE')
+    expect(where({ status: { $nin: [] } }).sql).toContain('TRUE')
+  })
+
+  test('translates the comparison and text operators', () => {
+    expect(where({ age: { $gte: 18 } }).params).toEqual([18])
+    expect(where({ age: { $between: [18, 65] } }).sql).toContain('BETWEEN')
+    expect(where({ email: { $ilike: '%@b.c' } }).sql).toContain('ILIKE')
+    expect(where({ email: { $regex: '^a' } }).sql).toContain('~')
+    expect(where({ status: { $exists: false } }).sql).toContain('IS NULL')
+    expect(where({ status: { $null: false } }).sql).toContain('IS NOT NULL')
+  })
+
+  /** A wildcard inside the operand is data, not a pattern the caller wrote. */
+  test('escapes the LIKE wildcards in startsWith and endsWith', () => {
+    expect(where({ email: { $startsWith: 'a_b' } }).params).toEqual(['a\\_b%'])
+    expect(where({ email: { $endsWith: '100%' } }).params).toEqual(['%100\\%'])
+  })
+
+  test('composes with $or and $not', () => {
+    const clause = where({
+      $or: [{ status: 'open' }, { age: { $lt: 18 } }],
+      $not: { email: 'a@b.c' }
+    })
+
+    expect(clause.sql).toContain(' or ')
+    expect(clause.sql).toContain('NOT')
+    expect(clause.params).toEqual(['open', 18, 'a@b.c'])
+  })
+
+  test('reaches into a jsonb column through a dotted path', () => {
+    const clause = where({ 'profile.city': 'Kyiv' })
+
+    expect(clause.sql).toContain('#>>')
+    expect(clause.params).toEqual(['{city}', 'Kyiv'])
+  })
+
+  test('matches a jsonb column against a whole object with containment', () => {
+    const bare = where({ profile: { city: 'Kyiv' } })
+    expect(bare.sql).toContain('@>')
+    /** A jsonb operand is stringified on the way out; the driver would send an object as text. */
+    expect(bare.params).toEqual(['{"city":"Kyiv"}'])
+
+    expect(where({ profile: { $contains: { city: 'Kyiv' } } }).sql).toContain('@>')
+  })
+
+  /** An unset filter must not empty the list it filters. */
+  test('skips an undefined value and answers nothing at all for an empty criteria', () => {
+    expect(criteriaToSql({ status: undefined }, spec, table)).toBeUndefined()
+    expect(criteriaToSql({}, spec, table)).toBeUndefined()
+    expect(criteriaToSql(undefined, spec, table)).toBeUndefined()
+  })
+
+  /** A typo silently widening a query to the whole table is worth being loud about. */
+  test('refuses an unknown key, an unknown operator and a path into a plain column', () => {
+    expect(() => criteriaToSql({ nope: 'x' } as unknown as Criteria<Thing>, spec, table))
+      .toThrow(UnsupportedArgumentError)
+    expect(() => criteriaToSql({ status: { $near: 'x' } } as unknown as Criteria<Thing>, spec, table))
+      .toThrow(UnsupportedArgumentError)
+    expect(() => criteriaToSql({ 'email.local': 'a' }, spec, table))
+      .toThrow(UnsupportedArgumentError)
+  })
+})
+
+describe('@owlmeans/postgres-resource — sortToSql', () => {
+  test('sorts a bare field name ascending', () => {
+    expect(order(['email'])).toContain('"email_address" asc')
+  })
+
+  test('reverses on order: desc', () => {
+    expect(order([{ field: 'email', order: 'desc' }])).toContain('"email_address" desc')
+    /** `{ field }` alone means the same as the bare name. */
+    expect(order([{ field: 'email' }])).toContain('"email_address" asc')
+  })
+
+  /**
+   * Postgres has no implicit row order, so paginating on a non-unique key would silently
+   * duplicate and skip rows between pages.
+   */
+  test('appends the primary key as a tiebreak, exactly once', () => {
+    const byStatus = order(['status'])
+    expect(byStatus).toContain('"status" asc')
+    expect(byStatus.split('"id" asc')).toHaveLength(2)
+
+    expect(order()).toContain('"id" asc')
+    /** Naming the key itself must not order by it twice. */
+    expect(order(['id']).split('"id" asc')).toHaveLength(2)
+  })
+
+  test('refuses a field the table does not have', () => {
+    expect(() => sortToSql(['nope'] as unknown as Sort<Thing>[], spec, table))
+      .toThrow(UnsupportedArgumentError)
+    /** ORDER BY cannot reach into jsonb the way a criteria path can. */
+    expect(() => sortToSql(['profile.city'], spec, table)).toThrow(UnsupportedArgumentError)
+  })
+})

package/tests/diff.spec.ts

@@ -0,0 +1,60 @@
+import { describe, expect, test } from 'bun:test'
+
+import { planSync, schemaToTableSpec } from '@owlmeans/postgres-resource'
+import type { LiveColumn, LiveTable, TableSpec } from '@owlmeans/postgres-resource'
+
+const specOf = (idType: 'string' | 'integer'): TableSpec =>
+  schemaToTableSpec('tasks', {
+    type: 'object',
+    properties: {
+      id: idType === 'string' ? { type: 'string' } : { type: 'integer' },
+      title: { type: 'string' },
+    },
+    required: ['id'],
+  } as never, 'app', 'task_entry', true)
+
+const columnOf = (over: Partial<LiveColumn> & { name: string, type: string }): LiveColumn => ({
+  notNull: true, defaultExpr: null, identity: '', generated: '', ordinal: 1, ...over,
+})
+
+const liveOf = (columns: LiveColumn[]): LiveTable =>
+  ({ exists: true, columns, indexes: [], constraints: [] })
+
+const kinds = (spec: TableSpec, live: LiveTable): string[] =>
+  planSync(spec, live).statements
+    .filter(statement => statement.target === 'id')
+    .map(statement => `${statement.kind}:${statement.sql.includes('DROP DEFAULT') ? 'drop' : statement.sql.includes('SET DEFAULT') ? 'set' : ''}`)
+
+describe('@owlmeans/postgres-resource — retyping a column that carries a default', () => {
+  test('drops the default before the type change and restores it after', () => {
+    // Postgres refuses `ALTER COLUMN … TYPE` while the column has a DEFAULT it cannot cast, and
+    // the whole plan is one transaction — so without the drop the entire reconciliation aborts and
+    // the resource fails every boot.
+    const live = liveOf([
+      columnOf({ name: 'id', type: 'integer', defaultExpr: `gen_random_uuid()::text` }),
+      columnOf({ name: 'title', type: 'text', notNull: false }),
+    ])
+
+    expect(kinds(specOf('string'), live)).toEqual(['set-default:drop', 'alter-type:', 'set-default:set'])
+  })
+
+  test('a retype of a column without a default emits no default statements', () => {
+    const live = liveOf([
+      columnOf({ name: 'id', type: 'integer', defaultExpr: null }),
+      columnOf({ name: 'title', type: 'text', notNull: false }),
+    ])
+
+    expect(kinds(specOf('string'), live)).toEqual(['alter-type:', 'set-default:set'])
+  })
+
+  test('a column already on the right type keeps its default untouched', () => {
+    const spec = specOf('string')
+    const desired = spec.columns.find(column => column.column === 'id')!
+    const live = liveOf([
+      columnOf({ name: 'id', type: desired.sqlType, defaultExpr: desired.defaultRaw ?? null }),
+      columnOf({ name: 'title', type: 'text', notNull: false }),
+    ])
+
+    expect(kinds(spec, live)).toEqual([])
+  })
+})

package/tests/name.spec.ts

@@ -19,9 +19,9 @@ describe('@owlmeans/postgres-resource — identifiers', () => {
   })
 
   /**
-   * Postgres truncates past `NAMEDATALEN - 1` server side and says nothing. Truncating here
-   * instead keeps the hash that made the name unique — the shared `dbName()` overflow path
-   * appends its disambiguator past byte 63, where the server would cut it off.
+   * Postgres truncates past `NAMEDATALEN - 1` server side and says nothing, which would let
+   * two names differing only beyond byte 63 collapse into one identifier. Clamping here
+   * instead keeps the hash suffix that tells them apart inside the limit.
    */
   test('keeps an overlong name unique inside the 63 byte limit', () => {
     const long = 'a'.repeat(200)

package/tests/sql.spec.ts

@@ -82,9 +82,10 @@ describe('@owlmeans/postgres-resource — placeholder resolution', () => {
   })
 
   /**
-   * The cache is keyed by context because a layer switch rebuilds every resource against a
-   * different Postgres schema. A service level query has no owning table to key on, so a
-   * process wide cache would hand the next tenant the previous one's table names.
+   * The cache is keyed by context because a context is what owns a set of database handles:
+   * a different context resolves the same alias against a different Postgres schema. A
+   * service level query has no owning table to key on, so a process wide cache would hand
+   * one context the other's table names.
    */
   test('does not leak resolved table names between contexts', () => {
     const tenantA = contextOf({ users: specOf('users', 'tenant_a', 'users') })