@owlmeans/postgres 0.1.18-rc.8 → 0.1.18

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (48) hide show
  1. package/README.md +7 -6
  2. package/agent-meta/manifest.json +3 -3
  3. package/agent-meta/skills/postgres/SKILL.md +67 -16
  4. package/build/bootstrap.d.ts.map +1 -1
  5. package/build/bootstrap.js +12 -7
  6. package/build/bootstrap.js.map +1 -1
  7. package/build/index.d.ts +2 -0
  8. package/build/index.d.ts.map +1 -1
  9. package/build/index.js.map +1 -1
  10. package/build/service.d.ts +1 -5
  11. package/build/service.d.ts.map +1 -1
  12. package/build/service.js +23 -41
  13. package/build/service.js.map +1 -1
  14. package/build/types.local.d.ts +5 -0
  15. package/build/types.local.d.ts.map +1 -0
  16. package/build/types.local.js +2 -0
  17. package/build/types.local.js.map +1 -0
  18. package/build/utils/config/types.d.ts +30 -0
  19. package/build/utils/config/types.d.ts.map +1 -0
  20. package/build/utils/config/types.js +2 -0
  21. package/build/utils/config/types.js.map +1 -0
  22. package/build/utils/config.d.ts +4 -24
  23. package/build/utils/config.d.ts.map +1 -1
  24. package/build/utils/config.js +74 -87
  25. package/build/utils/config.js.map +1 -1
  26. package/build/utils/connection/types.d.ts +17 -0
  27. package/build/utils/connection/types.d.ts.map +1 -0
  28. package/build/utils/connection/types.js +2 -0
  29. package/build/utils/connection/types.js.map +1 -0
  30. package/build/utils/connection.d.ts +2 -13
  31. package/build/utils/connection.d.ts.map +1 -1
  32. package/build/utils/connection.js +33 -37
  33. package/build/utils/connection.js.map +1 -1
  34. package/package.json +14 -13
  35. package/src/bootstrap.ts +13 -11
  36. package/src/index.ts +2 -0
  37. package/src/service.ts +28 -58
  38. package/src/types.local.ts +5 -0
  39. package/src/utils/config/types.ts +28 -0
  40. package/src/utils/config.ts +80 -89
  41. package/src/utils/connection/types.ts +17 -0
  42. package/src/utils/connection.ts +36 -36
  43. package/tests/context.ts +3 -3
  44. package/tests/criteria.spec.ts +107 -0
  45. package/tests/crud.spec.ts +68 -18
  46. package/tests/custom-sql.spec.ts +3 -2
  47. package/tests/migration.spec.ts +34 -3
  48. package/tests/sync.spec.ts +91 -1
@@ -0,0 +1,28 @@
1
+ import type { DbConfig } from '@owlmeans/resource'
2
+ import type { PoolConfig } from 'pg'
3
+
4
+ /** A db config entry as the `pg` pool configuration it describes. */
5
+ export interface PgConfigHelper {
6
+ /**
7
+ * Split a `postgres://` URL into pool fields.
8
+ *
9
+ * node-postgres accepts a `connectionString` directly, but the parsed values *override*
10
+ * every sibling field — so `{ connectionString, database }` silently ignores the
11
+ * database. Parsing here instead keeps overriding possible, which the admin path needs
12
+ * to reach both the maintenance database and the target one over the same credentials.
13
+ *
14
+ * @throws {PostgresConnectionError}
15
+ */
16
+ parseUrl: (url: string) => PoolConfig
17
+ /**
18
+ * Turn a {@link DbConfig} into a `pg` pool configuration.
19
+ *
20
+ * Values that start with `/` have already been read from disk by the `fileConfigReader`
21
+ * middleware, so a file mounted secret and a literal one are indistinguishable here —
22
+ * which is what lets a deployment move from env vars to mounted files without a code
23
+ * change.
24
+ */
25
+ prepareConfig: (config: DbConfig, overrides?: PoolConfig) => PoolConfig
26
+ /** Effective database of an open pool, as `pg` resolved it. */
27
+ poolDatabase: (pool: { options?: PoolConfig }) => string
28
+ }
@@ -4,106 +4,97 @@ import type { DbConfig } from '@owlmeans/resource'
4
4
  import type { PoolConfig } from 'pg'
5
5
 
6
6
  import { DEF_POOL_SIZE, DEF_PORT } from '../consts.js'
7
+ import type { PgConfigHelper } from './config/types.js'
7
8
 
8
- /**
9
- * Split a `postgres://` URL into pool fields.
10
- *
11
- * node-postgres accepts a `connectionString` directly, but the parsed values *override*
12
- * every sibling field — so `{ connectionString, database }` silently ignores the
13
- * database. Parsing here instead keeps overriding possible, which the admin path needs
14
- * to reach both the maintenance database and the target one over the same credentials.
15
- *
16
- * @throws {PostgresConnectionError}
17
- */
18
- export const parseUrl = (url: string): PoolConfig => {
19
- let parsed: URL
20
- try {
21
- parsed = new URL(url)
22
- } catch {
23
- throw new PostgresConnectionError('malformed-url')
24
- }
25
- if (!/^postgres(ql)?:$/.test(parsed.protocol)) {
26
- throw new PostgresConnectionError(`unexpected-protocol:${parsed.protocol.replace(':', '')}`)
27
- }
9
+ export const createPgConfigHelper = (): PgConfigHelper => {
10
+ const parseUrl = (url: string): PoolConfig => {
11
+ let parsed: URL
12
+ try {
13
+ parsed = new URL(url)
14
+ } catch {
15
+ throw new PostgresConnectionError('malformed-url')
16
+ }
17
+ if (!/^postgres(ql)?:$/.test(parsed.protocol)) {
18
+ throw new PostgresConnectionError(`unexpected-protocol:${parsed.protocol.replace(':', '')}`)
19
+ }
28
20
 
29
- const database = decodeURIComponent(parsed.pathname.replace(/^\//, ''))
30
- /** IPv6 literals arrive bracketed from `URL`; `pg` wants the bare address. */
31
- const host = decodeURIComponent(parsed.hostname).replace(/^\[|\]$/g, '')
32
- const mode = parsed.searchParams.get('sslmode')
21
+ const database = decodeURIComponent(parsed.pathname.replace(/^\//, ''))
22
+ /** IPv6 literals arrive bracketed from `URL`; `pg` wants the bare address. */
23
+ const host = decodeURIComponent(parsed.hostname).replace(/^\[|\]$/g, '')
24
+ const mode = parsed.searchParams.get('sslmode')
33
25
 
34
- const config: PoolConfig = {
35
- host,
36
- port: parsed.port !== '' ? parseInt(parsed.port, 10) : DEF_PORT
37
- }
38
- if (parsed.username !== '') {
39
- config.user = decodeURIComponent(parsed.username)
40
- }
41
- if (parsed.password !== '') {
42
- config.password = decodeURIComponent(parsed.password)
43
- }
44
- if (database !== '') {
45
- config.database = database
46
- }
47
- if (mode != null && mode !== 'disable') {
48
- /**
49
- * `no-verify` is what a self signed in-cluster certificate needs, and is the only
50
- * mode that may skip verification — anything else keeps the chain checked.
51
- */
52
- config.ssl = mode === 'no-verify' ? { rejectUnauthorized: false } : true
26
+ const config: PoolConfig = {
27
+ host,
28
+ port: parsed.port !== '' ? parseInt(parsed.port, 10) : DEF_PORT
29
+ }
30
+ if (parsed.username !== '') {
31
+ config.user = decodeURIComponent(parsed.username)
32
+ }
33
+ if (parsed.password !== '') {
34
+ config.password = decodeURIComponent(parsed.password)
35
+ }
36
+ if (database !== '') {
37
+ config.database = database
38
+ }
39
+ if (mode != null && mode !== 'disable') {
40
+ /**
41
+ * `no-verify` is what a self signed in-cluster certificate needs, and is the only
42
+ * mode that may skip verification — anything else keeps the chain checked.
43
+ */
44
+ config.ssl = mode === 'no-verify' ? { rejectUnauthorized: false } : true
45
+ }
46
+
47
+ return config
53
48
  }
54
49
 
55
- return config
56
- }
50
+ const prepareConfig = (config: DbConfig, overrides?: PoolConfig): PoolConfig => {
51
+ const meta = (config.meta ?? {}) as PostgresMeta
57
52
 
58
- /**
59
- * Turn a {@link DbConfig} into a `pg` pool configuration.
60
- *
61
- * Values that start with `/` have already been read from disk by the `fileConfigReader`
62
- * middleware, so a file mounted secret and a literal one are indistinguishable here —
63
- * which is what lets a deployment move from env vars to mounted files without a code
64
- * change.
65
- */
66
- export const prepareConfig = (config: DbConfig, overrides?: PoolConfig): PoolConfig => {
67
- const meta = (config.meta ?? {}) as PostgresMeta
53
+ /**
54
+ * `DbConfig.host` is an array for Mongo's replica sets. Postgres has no client side
55
+ * equivalent — multi-host failover is the pooler's job — so only the first is used.
56
+ */
57
+ const host = Array.isArray(config.host) ? config.host[0] : config.host
68
58
 
69
- /**
70
- * `DbConfig.host` is an array for Mongo's replica sets. Postgres has no client side
71
- * equivalent — multi-host failover is the pooler's job — so only the first is used.
72
- */
73
- const host = Array.isArray(config.host) ? config.host[0] : config.host
59
+ const base: PoolConfig = meta.url != null
60
+ ? parseUrl(meta.url)
61
+ : {
62
+ host,
63
+ port: config.port ?? DEF_PORT,
64
+ ...(config.user != null ? { user: config.user } : {}),
65
+ ...(config.secret != null ? { password: config.secret } : {}),
66
+ /** Absent, libpq falls back to the connection user's name. */
67
+ ...(meta.database != null ? { database: meta.database } : {})
68
+ }
74
69
 
75
- const base: PoolConfig = meta.url != null
76
- ? parseUrl(meta.url)
77
- : {
78
- host,
79
- port: config.port ?? DEF_PORT,
80
- ...(config.user != null ? { user: config.user } : {}),
81
- ...(config.secret != null ? { password: config.secret } : {}),
82
- /** Absent, libpq falls back to the connection user's name. */
83
- ...(meta.database != null ? { database: meta.database } : {})
70
+ const prepared: PoolConfig = {
71
+ ...base,
72
+ max: meta.max ?? DEF_POOL_SIZE,
73
+ ...(meta.ssl != null ? { ssl: meta.ssl as PoolConfig['ssl'] } : {}),
74
+ ...(meta.idleTimeoutMillis != null ? { idleTimeoutMillis: meta.idleTimeoutMillis } : {}),
75
+ ...(meta.connectionTimeoutMillis != null
76
+ ? { connectionTimeoutMillis: meta.connectionTimeoutMillis }
77
+ : {}),
78
+ /**
79
+ * A server side cap, so a query that outlives its caller stops holding a connection
80
+ * and its locks — the failure mode that turns one slow statement into a stuck pool.
81
+ */
82
+ ...(meta.statementTimeoutMillis != null
83
+ ? { statement_timeout: meta.statementTimeoutMillis }
84
+ : {}),
85
+ ...overrides
84
86
  }
85
87
 
86
- const prepared: PoolConfig = {
87
- ...base,
88
- max: meta.max ?? DEF_POOL_SIZE,
89
- ...(meta.ssl != null ? { ssl: meta.ssl as PoolConfig['ssl'] } : {}),
90
- ...(meta.idleTimeoutMillis != null ? { idleTimeoutMillis: meta.idleTimeoutMillis } : {}),
91
- ...(meta.connectionTimeoutMillis != null
92
- ? { connectionTimeoutMillis: meta.connectionTimeoutMillis }
93
- : {}),
94
- /**
95
- * A server side cap, so a query that outlives its caller stops holding a connection
96
- * and its locks — the failure mode that turns one slow statement into a stuck pool.
97
- */
98
- ...(meta.statementTimeoutMillis != null
99
- ? { statement_timeout: meta.statementTimeoutMillis }
100
- : {}),
101
- ...overrides
88
+ return prepared
102
89
  }
103
90
 
104
- return prepared
91
+ const poolDatabase = (pool: { options?: PoolConfig }): string =>
92
+ pool.options?.database ?? pool.options?.user ?? ''
93
+
94
+ return { parseUrl, prepareConfig, poolDatabase }
105
95
  }
106
96
 
107
- /** Effective database of an open pool, as `pg` resolved it. */
108
- export const poolDatabase = (pool: { options?: PoolConfig }): string =>
109
- pool.options?.database ?? pool.options?.user ?? ''
97
+ export const pgConfigHelper = createPgConfigHelper()
98
+
99
+ /** @deprecated compat:factory-refactor — use `pgConfigHelper.parseUrl(…)` */
100
+ export const parseUrl = (url: string): PoolConfig => pgConfigHelper.parseUrl(url)
@@ -0,0 +1,17 @@
1
+ import type { PostgresMeta } from '@owlmeans/postgres-resource'
2
+
3
+ /** Readiness and namespace setup over one pool. */
4
+ export interface PgConnectionHelper {
5
+ /**
6
+ * Wait for the server to answer a query, not merely to accept a socket.
7
+ *
8
+ * Postgres binds its port before it finishes recovery, so a sidecar or an operator managed
9
+ * instance routinely accepts a connection and then refuses to run anything. Every OwlMeans
10
+ * deployment grew its own copy of this loop; this is the one.
11
+ *
12
+ * @throws {PostgresConnectionError}
13
+ */
14
+ probe: (meta: PostgresMeta, location: string) => Promise<void>
15
+ /** `CREATE SCHEMA IF NOT EXISTS` on a pooled connection. */
16
+ ensureSchema: (schema: string) => Promise<void>
17
+ }
@@ -1,8 +1,12 @@
1
- import { pgErrorToResourceError, PostgresConnectionError, quoteIdent } from '@owlmeans/postgres-resource'
1
+ import { pgErrorHelper, pgNameHelper, PostgresConnectionError } from '@owlmeans/postgres-resource'
2
2
  import type { PostgresMeta } from '@owlmeans/postgres-resource'
3
+ import { logger } from '@owlmeans/log'
3
4
  import type { Pool } from 'pg'
4
5
 
5
6
  import { DEF_RETRIES, DEF_RETRY_DELAY, TERMINAL_CONNECT_CODES } from '../consts.js'
7
+ import type { PgConnectionHelper } from './connection/types.js'
8
+
9
+ const log = logger('postgres')
6
10
 
7
11
  /**
8
12
  * Retryable means "the server isn't up yet". A driver level failure carries no `code` at
@@ -18,47 +22,43 @@ const isTransient = (error: unknown): boolean => {
18
22
  return !TERMINAL_CONNECT_CODES.includes(code)
19
23
  }
20
24
 
21
- /**
22
- * Wait for the server to answer a query, not merely to accept a socket.
23
- *
24
- * Postgres binds its port before it finishes recovery, so a sidecar or an operator managed
25
- * instance routinely accepts a connection and then refuses to run anything. Every OwlMeans
26
- * deployment grew its own copy of this loop; this is the one.
27
- *
28
- * @throws {PostgresConnectionError}
29
- */
30
- export const probe = async (pool: Pool, meta: PostgresMeta, location: string): Promise<void> => {
31
- const retries = Math.max(1, meta.retries ?? DEF_RETRIES)
32
- const delay = meta.retryDelayMillis ?? DEF_RETRY_DELAY
33
- let last: unknown
25
+ export const makePgConnectionHelper = (pool: Pool): PgConnectionHelper => {
26
+ const { pgErrorToResourceError } = pgErrorHelper
34
27
 
35
- for (let attempt = 1; attempt <= retries; ++attempt) {
36
- try {
37
- await pool.query('SELECT 1')
28
+ const probe = async (meta: PostgresMeta, location: string): Promise<void> => {
29
+ const retries = Math.max(1, meta.retries ?? DEF_RETRIES)
30
+ const delay = meta.retryDelayMillis ?? DEF_RETRY_DELAY
31
+ let last: unknown
38
32
 
39
- return
40
- } catch (error) {
41
- last = error
42
- if (attempt === retries || !isTransient(error)) {
43
- break
33
+ for (let attempt = 1; attempt <= retries; ++attempt) {
34
+ try {
35
+ await pool.query('SELECT 1')
36
+
37
+ return
38
+ } catch (error) {
39
+ last = error
40
+ if (attempt === retries || !isTransient(error)) {
41
+ break
42
+ }
43
+ log.debug('Postgres not ready, retrying', { location, attempt, retries, delay })
44
+ await new Promise(resolve => setTimeout(resolve, delay))
44
45
  }
45
- console.log(`${location}: not ready (${attempt}/${retries}), retrying in ${delay}ms…`)
46
- await new Promise(resolve => setTimeout(resolve, delay))
47
46
  }
48
- }
49
47
 
50
- const translated = pgErrorToResourceError(last)
51
- const failure = new PostgresConnectionError(`unreachable:${location}:${translated.message}`)
52
- failure.cause = last
48
+ const translated = pgErrorToResourceError(last)
49
+ const failure = new PostgresConnectionError(`unreachable:${location}:${translated.message}`)
50
+ failure.cause = last
53
51
 
54
- throw failure
55
- }
52
+ throw failure
53
+ }
56
54
 
57
- /** `CREATE SCHEMA IF NOT EXISTS` on a pooled connection. */
58
- export const ensureSchema = async (pool: Pool, schema: string): Promise<void> => {
59
- try {
60
- await pool.query(`CREATE SCHEMA IF NOT EXISTS ${quoteIdent(schema)}`)
61
- } catch (error) {
62
- throw pgErrorToResourceError(error)
55
+ const ensureSchema = async (schema: string): Promise<void> => {
56
+ try {
57
+ await pool.query(`CREATE SCHEMA IF NOT EXISTS ${pgNameHelper.quoteIdent(schema)}`)
58
+ } catch (error) {
59
+ throw pgErrorToResourceError(error)
60
+ }
63
61
  }
62
+
63
+ return { probe, ensureSchema }
64
64
  }
package/tests/context.ts CHANGED
@@ -1,4 +1,4 @@
1
- import { postgresGate, randomNamespace } from '@owlmeans/test-integration'
1
+ import { randomNamespace, gateHelper } from '@owlmeans/test-integration'
2
2
  import type { IntegrationGate, PostgresEnv } from '@owlmeans/test-integration'
3
3
  import { PgAutoSync, resetPlaceholderCache } from '@owlmeans/postgres-resource'
4
4
  import type { PostgresResource } from '@owlmeans/postgres-resource'
@@ -19,7 +19,7 @@ import type { PostgresService } from '@owlmeans/postgres'
19
19
  * that backs it, which is why the specs live in this package rather than the resource one
20
20
  * (the reverse would make `@owlmeans/postgres-resource` dev-depend on its own dependent).
21
21
  */
22
- export const gate: IntegrationGate<PostgresEnv> = postgresGate()
22
+ export const gate: IntegrationGate<PostgresEnv> = gateHelper.postgresGate()
23
23
 
24
24
  const url = (): string => gate.env.POSTGRES_URL as string
25
25
 
@@ -103,7 +103,7 @@ export const makeSuite = (label: string): PgSuite => {
103
103
  * Declarations are deliberately *not* reset here. They survive a context switch on
104
104
  * purpose (that is the whole point of keying them by alias), and a `.migration()`
105
105
  * registered before `boot()` would be silently dropped. A spec that wants a clean
106
- * slate calls `resetDeclarations(alias)` itself, which is exactly what a spec
106
+ * slate calls `pgDeclarationHelper.resetDeclarations(alias)` itself, which is exactly what a spec
107
107
  * simulating a restarted process should have to say out loud.
108
108
  */
109
109
  resetPlaceholderCache()
@@ -0,0 +1,107 @@
1
+ import { afterAll, beforeAll, describe, expect, test } from 'bun:test'
2
+ import { makePostgresResource } from '@owlmeans/postgres-resource'
3
+ import type { PostgresResource } from '@owlmeans/postgres-resource'
4
+ import { recordQueryHelper, UnsupportedArgumentError } from '@owlmeans/resource'
5
+ import type { Criteria, ResourceRecord } from '@owlmeans/resource'
6
+
7
+ import { gate, makeSuite } from './context.js'
8
+
9
+ interface Plot extends ResourceRecord {
10
+ id?: string
11
+ garden: string
12
+ crops: string[]
13
+ soil: Record<string, unknown>
14
+ season?: string
15
+ }
16
+
17
+ /** A community garden: plots carry a native text[] of crops and a jsonb soil report. */
18
+ const plotSchema = {
19
+ type: 'object',
20
+ properties: {
21
+ id: { type: 'string', format: 'uuid' },
22
+ garden: { type: 'string' },
23
+ crops: { type: 'array', items: { type: 'string' } },
24
+ soil: { type: 'object' },
25
+ season: { type: 'string', nullable: true }
26
+ },
27
+ required: ['id', 'garden', 'crops', 'soil']
28
+ } as never
29
+
30
+ const suite = makeSuite('criteria')
31
+ const it = gate.skip ? test.skip : test
32
+
33
+ describe('@owlmeans/postgres — criteria answer what the in-memory engine answers', () => {
34
+ if (gate.skip) {
35
+ test.skip(gate.reason ?? 'postgres gate closed', () => {})
36
+
37
+ return
38
+ }
39
+
40
+ let plots: PostgresResource<Plot>
41
+ let seeded: Plot[]
42
+
43
+ beforeAll(async () => {
44
+ const resource = makePostgresResource<Plot, PostgresResource<Plot>>('criteria-plots')
45
+ resource.schema = plotSchema
46
+ const booted = await suite.boot({ resources: [resource] })
47
+ plots = booted.context.resource<PostgresResource<Plot>>('criteria-plots')
48
+
49
+ seeded = []
50
+ for (const plot of [
51
+ { garden: 'north', crops: ['beans', 'kale'], soil: { ph: 6.5, wet: true, beds: ['a', 'b'], state: 'loam' }, season: 'spring' },
52
+ { garden: 'north', crops: ['kale'], soil: { ph: 7, wet: false, beds: ['c'], state: 'clay', 'a,b': 1 } },
53
+ { garden: 'south', crops: [], soil: { ph: 5.5, state: null, beds: [] }, season: 'autumn' },
54
+ ]) {
55
+ seeded.push(await plots.create(plot))
56
+ }
57
+ })
58
+
59
+ afterAll(async () => {
60
+ await suite.teardown()
61
+ })
62
+
63
+ const byBoth = async (criteria: Criteria<Plot>): Promise<void> => {
64
+ const listed = (await plots.list(criteria, { size: 0 })).items.map(plot => plot.id).sort()
65
+ const expected = seeded.filter(plot => recordQueryHelper.matchCriteria(plot, criteria)).map(plot => plot.id).sort()
66
+ expect([JSON.stringify(criteria), listed]).toEqual([JSON.stringify(criteria), expected])
67
+ }
68
+
69
+ it('native array operators take a list or a scalar', async () => {
70
+ await byBoth({ crops: { $contains: 'kale' } })
71
+ await byBoth({ crops: { $contains: ['beans', 'kale'] } })
72
+ await byBoth({ crops: { $overlaps: ['beans', 'rye'] } })
73
+ await byBoth({ crops: { $overlaps: 'rye' } })
74
+ await byBoth({ crops: { $contained: ['kale', 'beans', 'rye'] } })
75
+ })
76
+
77
+ it('dotted jsonb paths compare typed values, lists, null and operators', async () => {
78
+ await byBoth({ 'soil.ph': 7 } as Criteria<Plot>)
79
+ await byBoth({ 'soil.wet': true } as Criteria<Plot>)
80
+ await byBoth({ 'soil.state': ['loam', 'clay'] } as Criteria<Plot>)
81
+ await byBoth({ 'soil.state': null } as Criteria<Plot>)
82
+ await byBoth({ 'soil.state': { $in: ['clay', null] } } as Criteria<Plot>)
83
+ /** `$nin` reads as it does on a column: `NOT IN`, which never matches an absent value. */
84
+ expect((await plots.list({ 'soil.state': { $nin: ['clay'] } } as Criteria<Plot>, { size: 0 })).items.map(plot => plot.garden))
85
+ .toEqual(['north'])
86
+ await byBoth({ 'soil.ph': { $gte: 6.5 } } as Criteria<Plot>)
87
+ await byBoth({ 'soil.state': { $startsWith: 'lo' } } as Criteria<Plot>)
88
+ await byBoth({ 'soil.state': { $exists: true } } as Criteria<Plot>)
89
+ await byBoth({ 'soil.beds': { $contains: 'a' } } as Criteria<Plot>)
90
+ await byBoth({ 'soil.beds': { $overlaps: ['c', 'z'] } } as Criteria<Plot>)
91
+ await byBoth({ 'soil.a,b': 1 } as Criteria<Plot>)
92
+ })
93
+
94
+ it('counts per group in one round trip', async () => {
95
+ const counts = await plots.countBy({ crops: { $contains: 'kale' } }, ['garden'])
96
+ expect(counts).toEqual([{ garden: 'north', count: 2 }])
97
+
98
+ const grouped = (await plots.countBy(undefined, ['garden', 'season']))
99
+ .sort((left, right) => `${left.garden}${left.season}`.localeCompare(`${right.garden}${right.season}`))
100
+ expect(grouped).toEqual([
101
+ { garden: 'north', season: null, count: 1 },
102
+ { garden: 'north', season: 'spring', count: 1 },
103
+ { garden: 'south', season: 'autumn', count: 1 },
104
+ ])
105
+ await expect(plots.countBy(undefined, ['nope' as never])).rejects.toThrow(UnsupportedArgumentError)
106
+ })
107
+ })
@@ -1,7 +1,7 @@
1
1
  import { afterAll, beforeAll, describe, expect, test } from 'bun:test'
2
- import { makePostgresResource } from '@owlmeans/postgres-resource'
2
+ import { DEFAULT_PAGE_SIZE, makePostgresResource } from '@owlmeans/postgres-resource'
3
3
  import type { PostgresResource } from '@owlmeans/postgres-resource'
4
- import { RecordExists, UnknownRecordError } from '@owlmeans/resource'
4
+ import { RecordExists, UnknownRecordError, UnsupportedArgumentError } from '@owlmeans/resource'
5
5
  import type { ResourceRecord } from '@owlmeans/resource'
6
6
 
7
7
  import { gate, makeSuite, shapeOf } from './context.js'
@@ -146,16 +146,23 @@ describe('@owlmeans/postgres — resource CRUD against a real context', () => {
146
146
  expect(loaded.createdAt).toBeInstanceOf(Date)
147
147
  })
148
148
 
149
- it('loads by a field other than the primary key, and refuses an unknown record', async () => {
150
- const byEmail = await users.load('a@b.c', 'email')
149
+ /**
150
+ * One call, several fields — the shape a list-then-take-the-first was standing in for.
151
+ * `load` answers with a record or `null`; `get` answers or raises.
152
+ */
153
+ it('reads one record by criteria rather than by id, and refuses an unknown one', async () => {
154
+ const byEmail = await users.load({ email: 'a@b.c' })
151
155
  expect(byEmail?.id).toBe(seeded.id as string)
152
156
 
153
- expect(await users.load('nobody@nowhere', 'email')).toBeNull()
154
- await expect(users.get('nobody@nowhere', 'email')).rejects.toThrow(UnknownRecordError)
157
+ expect(await users.load({ email: 'a@b.c', status: 'active', age: 21 })).not.toBeNull()
158
+ expect(await users.load({ email: 'a@b.c', status: 'banned' })).toBeNull()
159
+
160
+ expect(await users.load({ email: 'nobody@nowhere' })).toBeNull()
161
+ await expect(users.get({ email: 'nobody@nowhere' })).rejects.toThrow(UnknownRecordError)
155
162
  })
156
163
 
157
164
  it('patches by merge where update replaces the whole record', async () => {
158
- const patched = await users.patch<User>({ id: seeded.id, age: 22 })
165
+ const patched = await users.patch({ id: seeded.id, age: 22 })
159
166
  expect(patched.age).toBe(22)
160
167
  expect(patched.email).toBe('a@b.c')
161
168
 
@@ -170,21 +177,55 @@ describe('@owlmeans/postgres — resource CRUD against a real context', () => {
170
177
  await users.create({ email: 'third@b.c', status: 'active' })
171
178
 
172
179
  const banned = await users.list({ status: 'banned' })
173
- expect(banned.pager?.total).toBe(2)
180
+ expect(banned.total).toBe(2)
174
181
  expect(banned.items.every(item => item.status === 'banned')).toBe(true)
175
182
 
176
- const paged = await users.list({}, { pager: { page: 0, size: 2 } })
183
+ const paged = await users.list({}, { page: 0, size: 2 })
177
184
  expect(paged.items).toHaveLength(2)
178
- expect(paged.pager?.total).toBe(3)
185
+ expect(paged.total).toBe(3)
186
+ expect(paged.page).toBe(0)
187
+ expect(paged.size).toBe(2)
188
+
189
+ /** A page past the end is empty, and the total still describes the whole match. */
190
+ const beyond = await users.list({}, { page: 5, size: 2 })
191
+ expect(beyond.items).toHaveLength(0)
192
+ expect(beyond.total).toBe(3)
179
193
 
180
- const sorted = await users.list({}, { pager: { sort: [['email', false]] } })
194
+ const sorted = await users.list({}, { sort: ['email'] })
181
195
  expect(sorted.items.map(item => item.email)).toEqual(['a@b.c', 'second@b.c', 'third@b.c'])
196
+
197
+ const descending = await users.list({}, { sort: [{ field: 'email', order: 'desc' }] })
198
+ expect(descending.items.map(item => item.email)).toEqual(['third@b.c', 'second@b.c', 'a@b.c'])
199
+
200
+ /** The same sort narrows a multi-record criteria down to one record in a single read. */
201
+ const last = await users.get({ status: 'banned' }, { sort: [{ field: 'email', order: 'desc' }] })
202
+ expect(last.email).toBe('second@b.c')
182
203
  })
183
204
 
184
- it('counts and purges by criteria', async () => {
205
+ /**
206
+ * A relational table is unbounded, so an unasked-for read is capped. Reading everything
207
+ * stays possible, but only by saying so.
208
+ */
209
+ it('caps an unpaged list at the default size and lifts the cap on size 0', async () => {
210
+ const capped = await users.list()
211
+ expect(capped.size).toBe(DEFAULT_PAGE_SIZE)
212
+ expect(capped.page).toBe(0)
213
+ expect(capped.items).toHaveLength(3)
214
+
215
+ const everything = await users.list({}, { size: 0 })
216
+ expect(everything.items).toHaveLength(3)
217
+ expect(everything.total).toBe(3)
218
+ expect(everything.size).toBeUndefined()
219
+ expect(everything.page).toBeUndefined()
220
+ })
221
+
222
+ it('counts and purges by criteria, and refuses to purge everything', async () => {
185
223
  expect(await users.count()).toBe(3)
186
224
  expect(await users.count({ status: 'banned' })).toBe(2)
187
225
 
226
+ /** An empty criteria object would truncate the table — it has to be said in SQL instead. */
227
+ await expect(users.purge({})).rejects.toThrow(UnsupportedArgumentError)
228
+
188
229
  expect(await users.purge({ email: 'third@b.c' })).toBe(1)
189
230
  expect(await users.count()).toBe(2)
190
231
  })
@@ -193,15 +234,22 @@ describe('@owlmeans/postgres — resource CRUD against a real context', () => {
193
234
  await expect(users.create({ id: '00000000-0000-4000-8000-000000000001', email: 'no@b.c' }))
194
235
  .rejects.toThrow(RecordExists)
195
236
 
196
- const inserted = await users.insert<User>({
237
+ const inserted = await users.insert({
197
238
  id: '00000000-0000-4000-8000-000000000002', email: 'explicit@b.c'
198
239
  })
199
240
  expect(inserted.id).toBe('00000000-0000-4000-8000-000000000002')
200
241
  await users.delete(inserted.id as string)
201
242
  })
202
243
 
244
+ it('refuses a TTL rather than dropping it — Postgres has no row expiry', async () => {
245
+ await expect(users.create({ email: 'ttl@b.c' }, { ttl: 60 }))
246
+ .rejects.toThrow(UnsupportedArgumentError)
247
+ await expect(users.save({ id: seeded.id, email: 'a@b.c' }, { ttl: 60 }))
248
+ .rejects.toThrow(UnsupportedArgumentError)
249
+ })
250
+
203
251
  it('upserts on an arbiter that is not the primary key', async () => {
204
- const upserted = await users.upsert<User>({ email: 'a@b.c', age: 44 }, ['email'])
252
+ const upserted = await users.upsert({ email: 'a@b.c', age: 44 }, ['email'])
205
253
 
206
254
  expect(upserted.id).toBe(seeded.id as string)
207
255
  expect(upserted.age).toBe(44)
@@ -212,16 +260,18 @@ describe('@owlmeans/postgres — resource CRUD against a real context', () => {
212
260
  await expect(users.create({ email: 'a@b.c' })).rejects.toThrow(RecordExists)
213
261
  })
214
262
 
215
- it('picks a record by deleting it, atomically', async () => {
263
+ it('takes a record by deleting it, atomically', async () => {
216
264
  const before = await users.count()
217
265
  expect(await posts.count()).toBe(1)
218
266
 
219
- const picked = await users.pick(seeded.id as string)
267
+ const taken = await users.take(seeded.id as string)
220
268
 
221
- expect(picked.email).toBe('a@b.c')
269
+ expect(taken.email).toBe('a@b.c')
222
270
  expect(await users.count()).toBe(before - 1)
223
271
  /** The cascade is the database's, not the resource's — the post goes with its owner. */
224
272
  expect(await posts.count()).toBe(0)
225
- await expect(users.pick(seeded.id as string)).rejects.toThrow(UnknownRecordError)
273
+ /** `delete` reports absence, `take` raises on it. */
274
+ expect(await users.delete(seeded.id as string)).toBeNull()
275
+ await expect(users.take(seeded.id as string)).rejects.toThrow(UnknownRecordError)
226
276
  })
227
277
  })
@@ -140,12 +140,13 @@ describe('@owlmeans/postgres — custom SQL with alias placeholders', () => {
140
140
  expect(raw?.email_address).toBe('jrr@shire.me')
141
141
  expect(raw?.email).toBeUndefined()
142
142
 
143
- const record = await authors.selectOne<Author>('SELECT * FROM {{}} WHERE "name" = $1', ['Tolkien'])
143
+ /** The resource is typed once, at the call to `resource()` — never per method. */
144
+ const record = await authors.selectOne('SELECT * FROM {{}} WHERE "name" = $1', ['Tolkien'])
144
145
  expect(record?.email).toBe('jrr@shire.me')
145
146
  expect(record?.id).toBe(tolkien.id as string)
146
147
 
147
148
  /** jsonb comes back parsed, not as a string, on both routes. */
148
- const [book] = await books.select<Book>(`SELECT * FROM {{}} WHERE "title" = $1`, ['The Silmarillion'])
149
+ const [book] = await books.select(`SELECT * FROM {{}} WHERE "title" = $1`, ['The Silmarillion'])
149
150
  expect(book.meta).toEqual({ posthumous: true })
150
151
  })
151
152