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

package/tests/criteria.spec.ts

@@ -0,0 +1,237 @@
+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, compared as typed JSON', () => {
+    const clause = where({ 'profile.city': 'Kyiv' })
+
+    /** The path is a bound text[] and the value a bound jsonb literal — neither is statement text. */
+    expect(clause.sql).toContain('#> $1::text[]')
+    expect(clause.sql).toContain('$2::jsonb')
+    expect(clause.params).toEqual([['city'], '"Kyiv"'])
+
+    /** A number or a boolean is compared as itself, never as its text. */
+    expect(where({ 'profile.age': 30 } as Criteria<Thing>).params).toEqual([['age'], '30'])
+    expect(where({ 'profile.verified': true } as Criteria<Thing>).params).toEqual([['verified'], 'true'])
+  })
+
+  test('reads a dotted array as membership, null as absence, and operators as they read on a column', () => {
+    const list = where({ 'profile.tier': ['gold', 'silver'] } as Criteria<Thing>)
+    expect(list.sql).toContain('= ANY(ARRAY[')
+    expect(list.sql).toContain(']::jsonb[])')
+    expect(list.params).toEqual([['tier'], '"gold"', '"silver"'])
+
+    const absent = where({ 'profile.tier': null } as Criteria<Thing>)
+    expect(absent.sql).toContain('IS NULL')
+    expect(absent.sql).toContain(`'null'::jsonb`)
+
+    const widened = where({ 'profile.tier': { $in: ['gold', null] } } as Criteria<Thing>)
+    expect(widened.sql).toContain('= ANY(ARRAY[')
+    expect(widened.sql).toContain('IS NULL')
+
+    expect(where({ 'profile.age': { $gte: 18 } } as Criteria<Thing>).sql).toContain('>= $2::jsonb')
+    expect(where({ 'profile.city': { $ilike: 'ky%' } } as Criteria<Thing>).sql).toContain('#>> $1::text[]) ILIKE')
+    expect(where({ 'profile.city': { $exists: true } } as Criteria<Thing>).sql).toMatch(/^NOT \(.* IS NULL OR .* = 'null'::jsonb\)$/)
+    expect(where({ 'profile.tags': { $contains: 'a' } } as Criteria<Thing>).params).toEqual([['tags'], '["a"]'])
+    /** A path segment holding a comma or a brace stays one segment. */
+    expect(where({ 'profile.a,b': 1 } as Criteria<Thing>).params).toEqual([['a,b'], '1'])
+  })
+
+  test('binds an array operand of a native array column as ONE array parameter, wrapping a scalar', () => {
+    const scalar = where({ tags: { $contains: 'rare' } })
+    expect(scalar.sql).toContain('"tags" @> $1::text[]')
+    expect(scalar.params).toEqual([['rare']])
+
+    const many = where({ tags: { $overlaps: ['rare', 'new'] } })
+    expect(many.sql).toContain('"tags" && $1::text[]')
+    expect(many.params).toEqual([['rare', 'new']])
+
+    expect(where({ tags: { $contained: ['rare', 'new'] } }).sql).toContain('<@ $1::text[]')
+  })
+
+  test('reads jsonb array operators as JSON containment, and overlap element by element', () => {
+    const contains = where({ profile: { $contains: 'rare' } })
+    expect(contains.sql).toContain('"profile" @> $1::jsonb')
+    expect(contains.params).toEqual(['["rare"]'])
+
+    const overlaps = where({ profile: { $overlaps: ['rare', 2] } })
+    expect(overlaps.sql).toContain('jsonb_array_elements')
+    expect(overlaps.params).toEqual(['"rare"', '2', '"rare"', '2'])
+  })
+
+  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,111 @@
+import { describe, expect, test } from 'bun:test'
+
+import { canonicalDefinition, 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([])
+  })
+})
+
+/**
+ * What Postgres reports (`pg_indexes.indexdef`, `pg_get_constraintdef`) for objects created from the
+ * statements the plan emits — captured from a live server. Each pair must compare equal, or every
+ * boot drops and recreates the object.
+ */
+const RENDERED: Array<[string, string]> = [
+  ['CREATE INDEX "t_a" ON "app"."t" USING btree ("garden", "season")', 'CREATE INDEX t_a ON app.t USING btree (garden, season)'],
+  ['CREATE UNIQUE INDEX "t_b" ON "app"."t" USING btree ("garden", COALESCE("bed", \'\'), "season")',
+    'CREATE UNIQUE INDEX t_b ON app.t USING btree (garden, COALESCE(bed, \'\'::text), season)'],
+  ['CREATE INDEX "t_c" ON "app"."t" USING btree ("garden", "crop") WHERE "crop" IS NOT NULL',
+    'CREATE INDEX t_c ON app.t USING btree (garden, crop) WHERE (crop IS NOT NULL)'],
+  ['CREATE INDEX "t_d" ON "app"."t" USING btree ("garden") WHERE ("soil"->>\'state\') = \'wet\'',
+    'CREATE INDEX t_d ON app.t USING btree (garden) WHERE ((soil ->> \'state\'::text) = \'wet\'::text)'],
+  ['CREATE INDEX "t_f" ON "app"."t" USING btree ("entityId", "crop") WHERE "kind" = \'a\'',
+    'CREATE INDEX t_f ON app.t USING btree ("entityId", crop) WHERE (kind = \'a\'::text)'],
+  ['CREATE INDEX "t_g" ON "app"."t" USING btree (lower("crop"))', 'CREATE INDEX t_g ON app.t USING btree (lower((crop)::text))'],
+  ['CHECK (("season" IN (\'spring\', \'summer\')))', 'CHECK ((season = ANY (ARRAY[\'spring\'::text, \'summer\'::text])))'],
+  ['CHECK (("kind" IS NULL OR "kind" IN (\'a\', \'b\')))', 'CHECK (((kind IS NULL) OR (kind = ANY (ARRAY[\'a\'::text, \'b\'::text]))))'],
+]
+
+describe('@owlmeans/postgres-resource — comparing a declared default with the live one', () => {
+  test('a varchar id\'s generated default, stored with its casts, is no drift', () => {
+    const spec = schemaToTableSpec('shelves', {
+      type: 'object', properties: { id: { type: 'string', maxLength: 128 } }, required: ['id'],
+    } as never, 'app', 'shelf', true)
+    const live = liveOf([columnOf({ name: 'id', type: 'character varying(128)', defaultExpr: '(gen_random_uuid())::character varying' })])
+
+    expect(planSync(spec, live).statements).toEqual([])
+  })
+})
+
+describe('@owlmeans/postgres-resource — comparing a declared definition with the live one', () => {
+  test('a definition Postgres re-rendered compares equal to the statement that created it', () => {
+    for (const [declared, live] of RENDERED) {
+      expect([declared, canonicalDefinition(declared)]).toEqual([declared, canonicalDefinition(live)])
+    }
+  })
+
+  test('a real change still differs: columns, uniqueness, method and predicate', () => {
+    const base = 'CREATE INDEX t_a ON app.t USING btree (garden, season)'
+    for (const changed of [
+      'CREATE INDEX t_a ON app.t USING btree (season, garden)',
+      'CREATE UNIQUE INDEX t_a ON app.t USING btree (garden, season)',
+      'CREATE INDEX t_a ON app.t USING gin (garden, season)',
+      'CREATE INDEX t_a ON app.t USING btree (garden, season) WHERE (season IS NOT NULL)',
+    ]) {
+      expect(canonicalDefinition(changed)).not.toBe(canonicalDefinition(base))
+    }
+  })
+})

package/tests/errors.spec.ts

@@ -97,6 +97,17 @@ describe('@owlmeans/postgres-resource — driver error translation', () => {
     expect(pgErrorToResourceError(original)).toBe(original)
   })
 
+  test('preserves the executed SQL and driver cause for migration diagnostics', () => {
+    const original = driver({ code: '42703', message: 'column o.enquiryId does not exist' })
+    const query = 'UPDATE "app"."opportunity" o SET "enquiryId" = $1 WHERE o."enquiryId" IS NULL'
+    const failure = pgErrorToResourceError(original, query)
+
+    expect(failure).toBeInstanceOf(PostgresError)
+    expect(failure.message).toContain('42703')
+    expect(failure.message).toContain(`SQL: ${query}`)
+    expect(failure.cause).toBe(original)
+  })
+
   test('leaves an error that is not from the driver alone', () => {
     const plain = new Error('not postgres at all')
 

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') })