@owlmeans/postgres 0.1.18-rc.37 → 0.1.18-rc.38

package/README.md

@@ -14,7 +14,7 @@ provisioning, and an opt-in least-privilege bootstrap path.
 ## Installation
 
 ```bash
-bun add @owlmeans/postgres@^0.1.18-rc.37 @owlmeans/postgres-resource@^0.1.18-rc.36
+bun add @owlmeans/postgres@^0.1.18-rc.38 @owlmeans/postgres-resource@^0.1.18-rc.37
 ```
 
 ## Usage
@@ -129,7 +129,7 @@ This package ships embedded agent skills under `agent-meta/`. After installing y
 your project's skill store (`.agents/skills/`):
 
 ```sh
-npx @owlmeans/agent-skills@^0.1.18-rc.40
+npx @owlmeans/agent-skills@^0.1.18-rc.41
 ```
 
 The embedded files are version-matched to this package release. Do not edit them

package/agent-meta/manifest.json

@@ -1,8 +1,8 @@
 {
   "schemaVersion": 2,
   "package": "@owlmeans/postgres",
-  "version": "0.1.18-rc.37",
-  "generatedAt": "2026-09-25T21:19:38.015Z",
+  "version": "0.1.18-rc.38",
+  "generatedAt": "2026-09-28T02:06:37.894Z",
   "canonicalRepo": "https://github.com/owlmeans/common",
   "entries": [
     {

package/agent-meta/skills/postgres/SKILL.md

@@ -8,7 +8,7 @@ user-invocable: false
 # @owlmeans/postgres
 
 **Layer:** Infra
-**Install:** `"@owlmeans/postgres": "^0.1.18-rc.37"` in `dependencies`
+**Install:** `"@owlmeans/postgres": "^0.1.18-rc.38"` in `dependencies`
 
 Pooled `pg` connections for a server context, plus the admin path that provisions the role, database
 and schema an app connects with. All DDL for application tables belongs to [[postgres-resource]] —

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@owlmeans/postgres",
-  "version": "0.1.18-rc.37",
+  "version": "0.1.18-rc.38",
   "license": "MIT",
   "type": "module",
   "scripts": {
@@ -22,9 +22,9 @@
     }
   },
   "dependencies": {
-    "@owlmeans/basic-keys": "^0.1.18-rc.40",
+    "@owlmeans/basic-keys": "^0.1.18-rc.41",
     "@owlmeans/context": "^0.1.18-rc.32",
-    "@owlmeans/postgres-resource": "^0.1.18-rc.36",
+    "@owlmeans/postgres-resource": "^0.1.18-rc.37",
     "@owlmeans/resource": "^0.1.18-rc.36",
     "@owlmeans/server-context": "^0.1.18-rc.37",
     "drizzle-orm": "~0.45.2",

package/tests/criteria.spec.ts

@@ -0,0 +1,107 @@
+import { afterAll, beforeAll, describe, expect, test } from 'bun:test'
+import { makePostgresResource } from '@owlmeans/postgres-resource'
+import type { PostgresResource } from '@owlmeans/postgres-resource'
+import { matchCriteria, UnsupportedArgumentError } from '@owlmeans/resource'
+import type { Criteria, ResourceRecord } from '@owlmeans/resource'
+
+import { gate, makeSuite } from './context.js'
+
+interface Plot extends ResourceRecord {
+  id?: string
+  garden: string
+  crops: string[]
+  soil: Record<string, unknown>
+  season?: string
+}
+
+/** A community garden: plots carry a native text[] of crops and a jsonb soil report. */
+const plotSchema = {
+  type: 'object',
+  properties: {
+    id: { type: 'string', format: 'uuid' },
+    garden: { type: 'string' },
+    crops: { type: 'array', items: { type: 'string' } },
+    soil: { type: 'object' },
+    season: { type: 'string', nullable: true }
+  },
+  required: ['id', 'garden', 'crops', 'soil']
+} as never
+
+const suite = makeSuite('criteria')
+const it = gate.skip ? test.skip : test
+
+describe('@owlmeans/postgres — criteria answer what the in-memory engine answers', () => {
+  if (gate.skip) {
+    test.skip(gate.reason ?? 'postgres gate closed', () => {})
+
+    return
+  }
+
+  let plots: PostgresResource<Plot>
+  let seeded: Plot[]
+
+  beforeAll(async () => {
+    const resource = makePostgresResource<Plot, PostgresResource<Plot>>('criteria-plots')
+    resource.schema = plotSchema
+    const booted = await suite.boot({ resources: [resource] })
+    plots = booted.context.resource<PostgresResource<Plot>>('criteria-plots')
+
+    seeded = []
+    for (const plot of [
+      { garden: 'north', crops: ['beans', 'kale'], soil: { ph: 6.5, wet: true, beds: ['a', 'b'], state: 'loam' }, season: 'spring' },
+      { garden: 'north', crops: ['kale'], soil: { ph: 7, wet: false, beds: ['c'], state: 'clay', 'a,b': 1 } },
+      { garden: 'south', crops: [], soil: { ph: 5.5, state: null, beds: [] }, season: 'autumn' },
+    ]) {
+      seeded.push(await plots.create(plot))
+    }
+  })
+
+  afterAll(async () => {
+    await suite.teardown()
+  })
+
+  const byBoth = async (criteria: Criteria<Plot>): Promise<void> => {
+    const listed = (await plots.list(criteria, { size: 0 })).items.map(plot => plot.id).sort()
+    const expected = seeded.filter(plot => matchCriteria(plot, criteria)).map(plot => plot.id).sort()
+    expect([JSON.stringify(criteria), listed]).toEqual([JSON.stringify(criteria), expected])
+  }
+
+  it('native array operators take a list or a scalar', async () => {
+    await byBoth({ crops: { $contains: 'kale' } })
+    await byBoth({ crops: { $contains: ['beans', 'kale'] } })
+    await byBoth({ crops: { $overlaps: ['beans', 'rye'] } })
+    await byBoth({ crops: { $overlaps: 'rye' } })
+    await byBoth({ crops: { $contained: ['kale', 'beans', 'rye'] } })
+  })
+
+  it('dotted jsonb paths compare typed values, lists, null and operators', async () => {
+    await byBoth({ 'soil.ph': 7 } as Criteria<Plot>)
+    await byBoth({ 'soil.wet': true } as Criteria<Plot>)
+    await byBoth({ 'soil.state': ['loam', 'clay'] } as Criteria<Plot>)
+    await byBoth({ 'soil.state': null } as Criteria<Plot>)
+    await byBoth({ 'soil.state': { $in: ['clay', null] } } as Criteria<Plot>)
+    /** `$nin` reads as it does on a column: `NOT IN`, which never matches an absent value. */
+    expect((await plots.list({ 'soil.state': { $nin: ['clay'] } } as Criteria<Plot>, { size: 0 })).items.map(plot => plot.garden))
+      .toEqual(['north'])
+    await byBoth({ 'soil.ph': { $gte: 6.5 } } as Criteria<Plot>)
+    await byBoth({ 'soil.state': { $startsWith: 'lo' } } as Criteria<Plot>)
+    await byBoth({ 'soil.state': { $exists: true } } as Criteria<Plot>)
+    await byBoth({ 'soil.beds': { $contains: 'a' } } as Criteria<Plot>)
+    await byBoth({ 'soil.beds': { $overlaps: ['c', 'z'] } } as Criteria<Plot>)
+    await byBoth({ 'soil.a,b': 1 } as Criteria<Plot>)
+  })
+
+  it('counts per group in one round trip', async () => {
+    const counts = await plots.countBy({ crops: { $contains: 'kale' } }, ['garden'])
+    expect(counts).toEqual([{ garden: 'north', count: 2 }])
+
+    const grouped = (await plots.countBy(undefined, ['garden', 'season']))
+      .sort((left, right) => `${left.garden}${left.season}`.localeCompare(`${right.garden}${right.season}`))
+    expect(grouped).toEqual([
+      { garden: 'north', season: null, count: 1 },
+      { garden: 'north', season: 'spring', count: 1 },
+      { garden: 'south', season: 'autumn', count: 1 },
+    ])
+    await expect(plots.countBy(undefined, ['nope' as never])).rejects.toThrow(UnsupportedArgumentError)
+  })
+})

package/tests/sync.spec.ts

@@ -1,5 +1,7 @@
 import { afterAll, describe, expect, test } from 'bun:test'
-import { makePostgresResource, PgAutoSync, PostgresCastRequired } from '@owlmeans/postgres-resource'
+import {
+  introspectTable, makePostgresResource, PgAutoSync, planSync, PostgresCastRequired,
+} from '@owlmeans/postgres-resource'
 import type { PostgresResource } from '@owlmeans/postgres-resource'
 import type { ResourceRecord } from '@owlmeans/resource'
 
@@ -154,3 +156,91 @@ describe('@owlmeans/postgres — structure reconciliation', () => {
     })).rejects.toThrow(PostgresCastRequired)
   })
 })
+
+interface Plot extends ResourceRecord {
+  id?: string
+  garden: string
+  bed?: string
+  crop?: string
+  season: string
+  soil?: Record<string, unknown>
+}
+
+/**
+ * A community garden's plots: a plain compound index, an expression index and two partial ones —
+ * the shapes `pg_indexes.indexdef` renders differently from the statement that created them
+ * (identifiers unquoted, literals cast, a partial predicate parenthesized), plus an enum CHECK.
+ */
+const plots = {
+  type: 'object',
+  properties: {
+    id: { type: 'string', format: 'uuid' },
+    garden: { type: 'string' },
+    bed: { type: 'string', nullable: true },
+    crop: { type: 'string', nullable: true },
+    season: { type: 'string', enum: ['spring', 'summer', 'autumn'] },
+    soil: { type: 'object', nullable: true }
+  },
+  required: ['id', 'garden', 'season'],
+  pg: {
+    indexes: [
+      { name: 'sync_plots_garden_season', columns: ['garden', 'season'] },
+      { name: 'sync_plots_scope', unique: true, expression: `"garden", COALESCE("bed", ''), "season"` },
+      { name: 'sync_plots_crop', columns: ['garden', 'crop'], where: '"crop" IS NOT NULL' },
+      { name: 'sync_plots_wet', columns: ['garden'], where: `("soil"->>'state') = 'wet'` }
+    ]
+  }
+}
+
+const plotSuite = makeSuite('sync_idx')
+
+describe('@owlmeans/postgres — reconciling a table already at its shape', () => {
+  if (gate.skip) {
+    test.skip(gate.reason ?? 'postgres gate closed', () => {})
+
+    return
+  }
+
+  afterAll(async () => {
+    await plotSuite.teardown()
+  })
+
+  const bootPlots = async (): Promise<{ pg: PostgresService, resource: PostgresResource<Plot> }> => {
+    const resource = makePostgresResource<Plot, PostgresResource<Plot>>('sync-plots')
+    resource.schema = plots as never
+    const booted = await plotSuite.boot({ resources: [resource] })
+
+    return { pg: booted.pg, resource: booted.context.resource<PostgresResource<Plot>>('sync-plots') }
+  }
+
+  const objectOids = async (pg: PostgresService): Promise<Record<string, number>> => Object.fromEntries(
+    (await pg.query<{ name: string, oid: number }>(
+      `SELECT c.relname AS name, c.oid::int AS oid FROM pg_class c JOIN pg_namespace n ON n.oid = c.relnamespace
+        WHERE n.nspname = $1 AND c.relkind = 'i' AND c.relname LIKE 'sync_plots_%'
+       UNION ALL
+       SELECT k.conname AS name, k.oid::int AS oid FROM pg_constraint k JOIN pg_namespace n ON n.oid = k.connamespace
+        WHERE n.nspname = $1 AND k.contype = 'c' AND k.conname LIKE 'sync_plots_%'`, [plotSuite.schema]
+    )).map(row => [row.name, row.oid])
+  )
+
+  it('plans nothing on a second boot — no index or check is dropped and recreated', async () => {
+    const first = await bootPlots()
+    const before = await objectOids(first.pg)
+    expect(Object.keys(before).sort()).toEqual([
+      'sync_plots_crop', 'sync_plots_garden_season', 'sync_plots_pkey', 'sync_plots_scope', 'sync_plots_season_enum',
+      'sync_plots_wet'
+    ])
+
+    const second = await bootPlots()
+    const { pool } = await second.resource.db()
+    const client = await pool.connect()
+    try {
+      const table = second.resource.table
+      const live = await introspectTable(client, table.schema, table.table, table.qualified)
+      expect(planSync(table, live).statements.map(statement => statement.sql)).toEqual([])
+    } finally {
+      client.release()
+    }
+    expect(await objectOids(second.pg)).toEqual(before)
+  })
+})