@n8io/baseline-postgres 5.1.0 → 5.3.0

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.
package/README.md CHANGED
@@ -1,6 +1,6 @@
1
1
  # @n8io/baseline-postgres
2
2
 
3
- Postgres on [pg](https://node-postgres.com) and [Drizzle](https://orm.drizzle.team): one pool, Result-aware transactions, migrations under a lock, and columns that store prefixed ids as `uuid`.
3
+ Postgres on [pg](https://node-postgres.com) and [Drizzle](https://orm.drizzle.team): one pool, Result-aware transactions, migrations under a lock, columns that store prefixed ids as `uuid`, keyset paging, advisory locks, and a helper that forces the interleaving a race test needs.
4
4
 
5
5
  ```sh
6
6
  pnpm add @n8io/baseline-postgres
@@ -12,8 +12,12 @@ pnpm add @n8io/baseline-postgres
12
12
  - `PostgresPool`, `PostgresClient`: the pool and a checked-out connection. `await using` calls the pool's `end()` when its block ends. Name these in your own signatures, not `pg`'s types. They are pg's own pool and client, because Drizzle's `drizzle({ client })` needs the real ones.
13
13
  - `postgresTransactionRun({ pgPool, work, timeoutMs? })`: runs `work(pgClient)` in one transaction; COMMIT on `ok`, ROLLBACK on `err` or a throw. It ends after `timeoutMs` (default 5 s).
14
14
  - `postgresMigrate({ databaseUrl, migrationsFolder, lockWaitMs?, vendor? })`: applies pending Drizzle migrations under an advisory lock, so concurrent starts apply each one once. A run waits up to `lockWaitMs` (default 60 s) for the lock, then fails with an error that names it. The lock belongs to the session, so `databaseUrl` must reach Postgres itself: through a connection pooler such as PgBouncer the run refuses before it changes anything. Queries here have no time limit. `vendor` takes pg's settings for its one connection, under the same rules as the pool's.
15
+ - `@n8io/baseline-postgres/testing`: `postgresTestInterleave` for race tests (below). Import it from tests only.
15
16
  - `postgresIdColumnCreate(prefix)`: a Drizzle `uuid` column that reads and writes `Id<prefix>`.
16
17
  - `postgresUniqueViolationIs(error, constraint)`: true when a unique violation on that constraint is anywhere in the `cause` chain.
18
+ - `postgresUniqueViolationRead(error)`: the first unique violation in the `cause` chain as `{ constraint, columns, values }`, or `undefined`. `columns` and `values` come from Postgres's detail (`Key (league_id, name)=(7, Eagles)`), so a value is text as Postgres printed it. Postgres quotes nothing there, so when a key of two or more columns holds a value with `", "` in it, both lists are empty rather than misaligned; an expression key such as `lower(name)` comes back as Postgres printed it, and one with `", "` inside may not split cleanly. Read `constraint` when you need certainty.
19
+ - `postgresKeysetCreate({ after?, descending, idColumn, kind, sortColumn })`: keyset paging on `(sortColumn, idColumn)`. Returns `{ where, orderBy }` for a Drizzle `select`; `where` is `undefined` on the first page. `after` is the last row of the previous page, `{ id, value }`, with `id` written through `idColumn` (a prefixed id works). `kind` says how the sort compares: `text` by byte order (`COLLATE "C"`, the same in every locale, so give the column a `COLLATE "C"` index); `number` as the column's own type, so its index is used (for `integer`, `real` and `double precision` columns; a `numeric` or `bigint` column reads as a string or a bigint and is not supported); `integer` the same, for an `integer` or `serial` column only (any other column throws), taking only a whole number from -2147483648 to 2147483647; `date` as an instant, with `value` an ISO string with an offset (`toISOString()`). The sort column must be `NOT NULL`, because a NULL never compares, and a `date` column must hold no more than milliseconds (`timestamp({ precision: 3, withTimezone: true })`, or written only from a JS `Date`): a cursor made from a `Date` drops the microseconds a `now()` default stores, and pages would repeat or skip rows. A `value` of the wrong type for `kind`, a date that is not an ISO instant, or a number an `integer` or `smallint` sort column cannot hold (a fraction, or past its range), throws a `TypeError`: decode and check a cursor before you pass it.
20
+ - `postgresAdvisoryLockTake(db, key)`: waits for and takes a transaction-scoped advisory lock on the string `key`; Postgres drops it at COMMIT or ROLLBACK. Use it to serialize work that has no row to lock, such as counting a League's Teams before inserting one. `db` is anything with Drizzle's `execute` (`PostgresExecutor`). Call it inside `postgresTransactionRun`: outside a transaction the lock ends with the statement.
17
21
 
18
22
  ## Example
19
23
 
@@ -46,6 +50,82 @@ const result = await postgresTransactionRun({
46
50
  });
47
51
  ```
48
52
 
53
+ ## Keyset paging
54
+
55
+ ```ts
56
+ import { postgresKeysetCreate } from "@n8io/baseline-postgres";
57
+
58
+ const keyset = postgresKeysetCreate({
59
+ after: cursor ? { id: cursor.id, value: cursor.value } : null,
60
+ descending: true,
61
+ idColumn: fooTable.id,
62
+ kind: "date",
63
+ sortColumn: fooTable.createdAt,
64
+ });
65
+ const rows = await db
66
+ .select()
67
+ .from(fooTable)
68
+ .where(and(isNull(fooTable.archivedAt), keyset.where))
69
+ .orderBy(...keyset.orderBy)
70
+ .limit(limit + 1);
71
+ const page = rows.slice(0, limit);
72
+ const last = page.at(-1);
73
+ const nextCursor =
74
+ rows.length > limit && last
75
+ ? { id: last.id, value: last.createdAt.toISOString() }
76
+ : null;
77
+ ```
78
+
79
+ ## Advisory locks
80
+
81
+ ```ts
82
+ import { postgresAdvisoryLockTake } from "@n8io/baseline-postgres";
83
+
84
+ // In a transaction: two Team creates in one League count one after the other.
85
+ await postgresAdvisoryLockTake(db, `team-count:${leagueId}`);
86
+ const [counted] = await db
87
+ .select({ total: count() })
88
+ .from(teamTable)
89
+ .where(eq(teamTable.leagueId, leagueId));
90
+ ```
91
+
92
+ ## Race tests
93
+
94
+ `@n8io/baseline-postgres/testing` exports `postgresTestInterleave({ first, second, pgPool, timeoutMs? })`, for tests only. `first(pause)` runs until it awaits `pause()`, typically right after it read and locked what it will write. Then `second()` starts, and `first` resumes once `second` waits on a lock (`pg_stat_activity`) or has finished. It returns `{ first, second, secondWaited }`; `secondWaited` is false when no lock made `second` wait. It fails when `first` never pauses, or when `second` neither waits nor finishes within `timeoutMs` (default 5 s). A connection that already waited on a lock before `second` started does not count; any other one in the same database does, so keep other work off that database while it runs. It needs three connections from `pgPool` at once: `first`'s, `second`'s, and one to watch `pg_stat_activity`.
95
+
96
+ ```ts
97
+ import { postgresTestInterleave } from "@n8io/baseline-postgres/testing";
98
+
99
+ // Reads a count, then writes it back plus one: a read-modify-write Use case.
100
+ const increment = (pause?: () => Promise<void>) =>
101
+ postgresTransactionRun({
102
+ pgPool,
103
+ work: async (pgClient) => {
104
+ const db = drizzle({ client: pgClient });
105
+ const [row] = await db
106
+ .select()
107
+ .from(counterTable)
108
+ .where(eq(counterTable.id, id))
109
+ .for("update"); // remove it and the test below must fail
110
+ await pause?.();
111
+ await db
112
+ .update(counterTable)
113
+ .set({ n: (row?.n ?? 0) + 1 })
114
+ .where(eq(counterTable.id, id));
115
+ return ok(undefined);
116
+ },
117
+ });
118
+
119
+ const result = await postgresTestInterleave({
120
+ first: (pause) => increment(pause),
121
+ pgPool,
122
+ second: () => increment(),
123
+ });
124
+ expect(result.secondWaited).toBe(true);
125
+ ```
126
+
127
+ A race test must fail with the lock removed. Before you trust one, take the lock out (`FOR UPDATE`, the advisory lock), see the test go red for the right reason, and put it back. A plain `Promise.all` of two writes usually passes either way, because one finishes before the other starts.
128
+
49
129
  ## Needs
50
130
 
51
131
  - Peers: `pg`, `drizzle-orm` (`1.0.0-rc.5`, pinned until 1.0 is out) and, for types, `@types/pg`.
package/dist/index.d.ts CHANGED
@@ -1,13 +1,40 @@
1
+ import { AnyColumn, SQL } from "drizzle-orm";
1
2
  import { Id } from "@n8io/baseline-id";
2
3
  import { PgCustomColumnBuilder } from "drizzle-orm/pg-core";
3
4
  import pg from "pg";
4
5
  import { Result } from "@n8io/baseline-result";
6
+ /** Anything that runs a Drizzle query: a Drizzle database or transaction. */
7
+ type PostgresExecutor = {
8
+ execute(query: SQL): Promise<unknown>;
9
+ };
10
+ export declare const postgresAdvisoryLockTake: (db: PostgresExecutor, key: string) => Promise<void>;
5
11
  type PostgresIdColumnBuilder<P extends string> = PgCustomColumnBuilder<{
6
12
  data: Id<P>;
7
13
  dataType: "custom";
8
14
  driverParam: string;
9
15
  }>;
10
16
  export declare const postgresIdColumnCreate: <P extends string>(prefix: P) => ((name?: string) => PostgresIdColumnBuilder<P>);
17
+ /**
18
+ * How the sort column compares: `text` by byte order (`COLLATE "C"`), `date` as an instant,
19
+ * `integer` and `number` as numbers (`integer` takes only a whole number).
20
+ */
21
+ type PostgresKeysetKind = "date" | "integer" | "number" | "text";
22
+ type PostgresKeysetOptions = {
23
+ /** The last row of the previous page; none for the first page. */
24
+ after?: {
25
+ id: string;
26
+ value: string | number;
27
+ } | null;
28
+ descending: boolean;
29
+ /** The tie-breaker, unique per row. The cursor's id goes through its encoder. */
30
+ idColumn: AnyColumn;
31
+ kind: PostgresKeysetKind;
32
+ sortColumn: AnyColumn;
33
+ };
34
+ export declare const postgresKeysetCreate: ({ after, descending, idColumn, kind, sortColumn }: PostgresKeysetOptions) => {
35
+ orderBy: SQL[];
36
+ where: SQL | undefined;
37
+ };
11
38
  declare const postgresVendorOwnedKeys: {
12
39
  readonly connectionString: "databaseUrl";
13
40
  readonly connectionTimeoutMillis: "connectTimeoutMs";
@@ -64,5 +91,13 @@ export declare const postgresTransactionRun: <T, E>({ pgPool, timeoutMs: timeout
64
91
  timeoutMs?: number | null;
65
92
  work: (pgClient: PostgresClient) => Promise<Result<T, E>>;
66
93
  }) => Promise<Result<T, E>>;
94
+ type PostgresUniqueViolation = {
95
+ /** The key's columns, or expressions for an expression index. Empty when Postgres sent no detail. */
96
+ columns: string[];
97
+ constraint: string;
98
+ /** The clashing values as Postgres printed them, in column order. Empty when unreadable. */
99
+ values: string[];
100
+ };
67
101
  export declare const postgresUniqueViolationIs: (error: unknown, constraint: string) => boolean;
68
- export type { PostgresClient, PostgresMigrateVendorOptions, PostgresPool, PostgresPoolOptions, PostgresPoolVendorOptions };
102
+ export declare const postgresUniqueViolationRead: (error: unknown) => PostgresUniqueViolation | undefined;
103
+ export type { PostgresClient, PostgresExecutor, PostgresKeysetKind, PostgresKeysetOptions, PostgresMigrateVendorOptions, PostgresPool, PostgresPoolOptions, PostgresPoolVendorOptions, PostgresUniqueViolation };
package/dist/index.js CHANGED
@@ -1,3 +1,4 @@
1
+ import { sql } from "drizzle-orm";
1
2
  import { idFromUuid, idToUuid } from "@n8io/baseline-id";
2
3
  import { customType } from "drizzle-orm/pg-core";
3
4
  import { createHash } from "node:crypto";
@@ -5,6 +6,10 @@ import { drizzle } from "drizzle-orm/node-postgres";
5
6
  import { migrate } from "drizzle-orm/node-postgres/migrator";
6
7
  import pg from "pg";
7
8
  import { logger } from "@n8io/baseline-logger";
9
+ // src/postgres-advisory-lock-take.ts
10
+ const postgresAdvisoryLockTake = async (db, key) => {
11
+ await db.execute(sql`SELECT pg_advisory_xact_lock(hashtextextended(${key}, 0))`);
12
+ };
8
13
  // src/postgres-id-column.ts
9
14
  const postgresIdColumnCreate = (prefix) => {
10
15
  const column = customType({
@@ -17,6 +22,50 @@ const postgresIdColumnCreate = (prefix) => {
17
22
  });
18
23
  return (name) => name === void 0 ? column() : column(name);
19
24
  };
25
+ // src/postgres-keyset.ts
26
+ const isoInstantPattern = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d{1,6})?(Z|[+-]\d{2}:\d{2})$/;
27
+ const isoInstantIs = (value) => {
28
+ if (!isoInstantPattern.test(value) || Number.isNaN(Date.parse(value))) return false;
29
+ const [year = 0, month = 0, day = 0] = value.slice(0, 10).split("-").map(Number);
30
+ return new Date(Date.UTC(year, month - 1, day)).getUTCDate() === day;
31
+ };
32
+ const INT4 = [-(2 ** 31), 2 ** 31 - 1];
33
+ const INT2 = [-(2 ** 15), 2 ** 15 - 1];
34
+ const integerRanges = {
35
+ integer: INT4,
36
+ serial: INT4,
37
+ smallint: INT2,
38
+ smallserial: INT2
39
+ };
40
+ const integerKindAssert = (sortColumn) => {
41
+ const type = sortColumn.getSQLType();
42
+ if (integerRanges[type] !== INT4) throw new TypeError(`An integer keyset needs an integer or serial column, got ${type}`);
43
+ };
44
+ const afterValueAssert = ({ kind, sortColumn, value }) => {
45
+ const numeric = kind === "integer" || kind === "number";
46
+ const range = numeric ? integerRanges[sortColumn.getSQLType()] : void 0;
47
+ if (!(numeric ? typeof value === "number" && (range ? Number.isInteger(value) && value >= range[0] && value <= range[1] : Number.isFinite(value)) : typeof value === "string" && (kind === "text" || isoInstantIs(value)))) throw new TypeError(`${kind === "integer" ? "An" : "A"} ${kind} keyset needs ${range ? `an integer from ${range[0]} to ${range[1]}` : kind === "number" ? "a finite number" : kind === "date" ? "an ISO instant such as 2026-01-01T00:00:00.000Z" : "a string"}, got ${JSON.stringify(value)}`);
48
+ };
49
+ const postgresKeysetCreate = ({ after, descending, idColumn, kind, sortColumn }) => {
50
+ if (kind === "integer") integerKindAssert(sortColumn);
51
+ const sortBy = kind === "text" ? sql`${sortColumn} COLLATE "C"` : sql`${sortColumn}`;
52
+ const direction = descending ? sql`DESC` : sql`ASC`;
53
+ const orderBy = [sql`${sortBy} ${direction}`, sql`${idColumn} ${direction}`];
54
+ if (!after) return {
55
+ orderBy,
56
+ where: void 0
57
+ };
58
+ afterValueAssert({
59
+ kind,
60
+ sortColumn,
61
+ value: after.value
62
+ });
63
+ const value = kind === "date" ? sql`${after.value}::timestamptz` : sql`${after.value}`;
64
+ return {
65
+ orderBy,
66
+ where: sql`(${sortBy}, ${idColumn}) ${descending ? sql`<` : sql`>`} (${value}, ${sql.param(after.id, idColumn)})`
67
+ };
68
+ };
20
69
  // src/postgres-url-assert.ts
21
70
  const postgresUrlAssert = (databaseUrl) => {
22
71
  if (/^postgres(ql)?:\/\//.test(databaseUrl)) return;
@@ -151,15 +200,35 @@ const postgresTransactionRun = async ({ pgPool, timeoutMs: timeoutMsGiven, work
151
200
  pgClient.release(broken || void 0);
152
201
  }
153
202
  };
154
- // src/postgres-unique-violation-is.ts
155
- const postgresUniqueViolationIs = (error, constraint) => {
203
+ // src/postgres-unique-violation.ts
204
+ const violationFind = (error) => {
156
205
  const seen = /* @__PURE__ */ new Set();
157
206
  let current = error;
158
207
  while (typeof current === "object" && current !== null && !seen.has(current)) {
159
208
  seen.add(current);
160
- if ("code" in current && current.code === "23505" && "constraint" in current && current.constraint === constraint) return true;
209
+ if ("code" in current && current.code === "23505" && "constraint" in current && typeof current.constraint === "string") return {
210
+ constraint: current.constraint,
211
+ detail: "detail" in current ? current.detail : void 0
212
+ };
161
213
  current = "cause" in current ? current.cause : void 0;
162
214
  }
163
- return false;
164
215
  };
165
- export { postgresIdColumnCreate, postgresMigrate, postgresPoolCreate, postgresTransactionRun, postgresUniqueViolationIs };
216
+ const postgresUniqueViolationIs = (error, constraint) => violationFind(error)?.constraint === constraint;
217
+ const postgresUniqueViolationRead = (error) => {
218
+ const found = violationFind(error);
219
+ if (!found) return void 0;
220
+ const match = typeof found.detail === "string" ? /^Key \((.*?)\)=\((.*)\) already exists\.$/s.exec(found.detail) : null;
221
+ const columns = match?.[1]?.split(", ") ?? [];
222
+ const printed = match?.[2];
223
+ const values = printed === void 0 ? [] : columns.length === 1 ? [printed] : printed.split(", ");
224
+ return columns.length === values.length ? {
225
+ columns,
226
+ constraint: found.constraint,
227
+ values
228
+ } : {
229
+ columns: [],
230
+ constraint: found.constraint,
231
+ values: []
232
+ };
233
+ };
234
+ export { postgresAdvisoryLockTake, postgresIdColumnCreate, postgresKeysetCreate, postgresMigrate, postgresPoolCreate, postgresTransactionRun, postgresUniqueViolationIs, postgresUniqueViolationRead };
@@ -0,0 +1,21 @@
1
+ /** The pool the helper watches `pg_stat_activity` through: a `PostgresPool` fits. */
2
+ type PostgresTestInterleavePool = {
3
+ query(text: string): Promise<{
4
+ rows: unknown[];
5
+ }>;
6
+ };
7
+ type PostgresTestInterleaveOptions<A, B> = {
8
+ /** Runs until it awaits `pause()`, typically right after it took a lock. */
9
+ first: (pause: () => Promise<void>) => Promise<A>;
10
+ pgPool: PostgresTestInterleavePool;
11
+ /** Starts once `first` paused. */
12
+ second: () => Promise<B>;
13
+ /** How long `second` may run without waiting on a lock or finishing. Default 5 s. */
14
+ timeoutMs?: number | null;
15
+ };
16
+ export declare const postgresTestInterleave: <A, B>({ first, pgPool, second, timeoutMs: timeoutMsGiven }: PostgresTestInterleaveOptions<A, B>) => Promise<{
17
+ first: A;
18
+ second: B;
19
+ secondWaited: boolean;
20
+ }>;
21
+ export type { PostgresTestInterleaveOptions, PostgresTestInterleavePool };
@@ -0,0 +1,57 @@
1
+ import { setTimeout } from "node:timers/promises";
2
+ // src/postgres-test-interleave.ts
3
+ const lockWaitersRead = async (pgPool) => {
4
+ const { rows } = await pgPool.query(`SELECT pid FROM pg_stat_activity
5
+ WHERE datname = current_database() AND wait_event_type = 'Lock' AND pid <> pg_backend_pid()`);
6
+ return new Set(rows.map((row) => typeof row === "object" && row !== null && "pid" in row ? row.pid : void 0));
7
+ };
8
+ const postgresTestInterleave = async ({ first, pgPool, second, timeoutMs: timeoutMsGiven }) => {
9
+ const timeoutMs = timeoutMsGiven ?? 5e3;
10
+ const { promise: paused, resolve: pausedResolve } = Promise.withResolvers();
11
+ const { promise: resumed, resolve: resume } = Promise.withResolvers();
12
+ let pauseCalled = false;
13
+ let resumeCalled = false;
14
+ const firstRun = Promise.try(() => first(() => {
15
+ if (pauseCalled) throw new Error("first called pause() twice");
16
+ pauseCalled = true;
17
+ pausedResolve();
18
+ return resumed;
19
+ })).then((value) => {
20
+ if (!resumeCalled) throw new Error("first finished before it was resumed; await pause()");
21
+ return value;
22
+ });
23
+ if (await Promise.race([paused.then(() => false), firstRun.then(() => true, () => true)]) && !pauseCalled) await firstRun.catch((error) => {
24
+ throw error instanceof Error && error.message.startsWith("first finished before") ? /* @__PURE__ */ new Error("first finished without calling pause()") : error;
25
+ });
26
+ let secondWaited = false;
27
+ try {
28
+ const waitingBefore = await lockWaitersRead(pgPool);
29
+ let secondDone = false;
30
+ const secondRun = Promise.try(second).finally(() => {
31
+ secondDone = true;
32
+ });
33
+ secondRun.catch(() => void 0);
34
+ const deadline = Date.now() + timeoutMs;
35
+ for (;;) {
36
+ if ([...await lockWaitersRead(pgPool)].some((pid) => !waitingBefore.has(pid))) {
37
+ secondWaited = true;
38
+ break;
39
+ }
40
+ if (secondDone) break;
41
+ if (Date.now() > deadline) throw new Error(`second neither waited on a lock nor finished within ${timeoutMs} ms`);
42
+ await setTimeout(10);
43
+ }
44
+ resumeCalled = true;
45
+ resume();
46
+ const [firstResult, secondResult] = await Promise.all([firstRun, secondRun]);
47
+ return {
48
+ first: firstResult,
49
+ second: secondResult,
50
+ secondWaited
51
+ };
52
+ } finally {
53
+ resumeCalled = true;
54
+ resume();
55
+ }
56
+ };
57
+ export { postgresTestInterleave };
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@n8io/baseline-postgres",
3
- "version": "5.1.0",
3
+ "version": "5.3.0",
4
4
  "description": "Postgres pool, Result-aware transactions, migrations and prefixed-id columns on pg and Drizzle.",
5
5
  "type": "module",
6
6
  "license": "MIT",
@@ -20,6 +20,10 @@
20
20
  ".": {
21
21
  "types": "./dist/index.d.ts",
22
22
  "default": "./dist/index.js"
23
+ },
24
+ "./testing": {
25
+ "types": "./dist/testing.d.ts",
26
+ "default": "./dist/testing.js"
23
27
  }
24
28
  },
25
29
  "publishConfig": {