pg-codegen 5.18.0 → 5.20.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
@@ -63,6 +63,8 @@ One `create<Schema>Db(db, options?)` factory per schema, one client per table:
63
63
  | `delete({ where, select? })` | the deleted rows |
64
64
  | `$with(db)` | the same clients bound to another connection |
65
65
 
66
+ A read also takes `lock` — `FOR UPDATE` and friends, see [Transactions](#transactions).
67
+
66
68
  `where` / `select` / `orderBy` are keyed by camelCase field names and mapped to physical columns for you. `where` speaks the same query-spec grammar as the GraphQL side — `equalTo`, `notEqualTo`, `in`, `notIn`, `lessThan`, `greaterThanOrEqualTo`, `like`, `likeInsensitive`, `startsWith`, `includes`, `isNull`, … — and a bare value means `equalTo` (`null` means `isNull`):
67
69
 
68
70
  ```ts
@@ -155,6 +157,23 @@ try {
155
157
  }
156
158
  ```
157
159
 
160
+ A read that decides a write states the lock it needs, so two concurrent workers cannot both act on the same row:
161
+
162
+ ```ts
163
+ const run = await tx.agentRuns.findFirstOrThrow({ where: { id }, lock: 'update' });
164
+ // FOR UPDATE — the other transaction waits here
165
+ await tx.agentRuns.update({ where: { id: run.id }, data: { status: 'running' } });
166
+
167
+ // a queue claim would rather move on than wait
168
+ const next = await tx.jobs.findFirst({
169
+ where: { status: 'pending' },
170
+ orderBy: { createdAt: 'ASC' },
171
+ lock: { strength: 'update', skipLocked: true }
172
+ });
173
+ ```
174
+
175
+ `lock` takes `'update'`, `'noKeyUpdate'`, `'share'` or `'keyShare'`, and the object form adds `skipLocked` or `noWait`.
176
+
158
177
  ### Tables provisioned under a different name
159
178
 
160
179
  The schema and physical table names are runtime arguments, so one generated client serves a per-tenant or per-scope deployment of the same tables:
@@ -10,7 +10,7 @@
10
10
  * NOTE: This file is read at codegen time and written to output.
11
11
  * Any changes here will affect all generated clients.
12
12
  */
13
- import type { Expr } from '@constructive-io/query-builder';
13
+ import type { Expr, LockOptions, LockStrength } from '@constructive-io/query-builder';
14
14
  /** Anything with pg's `query(text, values)` shape: Pool, PoolClient, Client. */
15
15
  export interface Queryable {
16
16
  query(text: string, values?: unknown[]): Promise<{
@@ -113,6 +113,22 @@ export type Data<App> = {
113
113
  [column: string]: unknown;
114
114
  };
115
115
  export type OrderDirection = 'ASC' | 'DESC';
116
+ /**
117
+ * Row-level lock the read takes, so a read-then-write stays serialized against
118
+ * a concurrent one: `'update'` is `FOR UPDATE`, and the object form states what
119
+ * to do about a row someone else holds.
120
+ *
121
+ * ```ts
122
+ * const run = await runs.$with(tx).findFirst({ where: { id }, lock: 'update' });
123
+ * const job = await jobs.$with(tx).findFirst({
124
+ * where: { status: 'pending' },
125
+ * lock: { strength: 'update', skipLocked: true }
126
+ * });
127
+ * ```
128
+ */
129
+ export type Lock = LockStrength | ({
130
+ strength: LockStrength;
131
+ } & LockOptions);
116
132
  /** Order spec keyed by camelCase field names, e.g. `{ createdAt: 'DESC' }`. */
117
133
  export type OrderBy<App> = {
118
134
  [K in keyof App]?: OrderDirection;
@@ -123,11 +139,13 @@ export interface FindManyArgs<App, S extends SelectShape<App> | undefined> {
123
139
  orderBy?: OrderBy<App> | OrderBy<App>[];
124
140
  limit?: number;
125
141
  offset?: number;
142
+ lock?: Lock;
126
143
  }
127
144
  export interface FindFirstArgs<App, S extends SelectShape<App> | undefined> {
128
145
  where?: Where<App>;
129
146
  select?: S;
130
147
  orderBy?: OrderBy<App> | OrderBy<App>[];
148
+ lock?: Lock;
131
149
  }
132
150
  export interface CreateArgs<App, S extends SelectShape<App> | undefined> {
133
151
  data: Data<App>;
@@ -63,6 +63,10 @@ class TableClient {
63
63
  query.limit(args.limit);
64
64
  if (args.offset !== undefined)
65
65
  query.offset(args.offset);
66
+ if (args.lock) {
67
+ const lock = typeof args.lock === 'string' ? { strength: args.lock } : args.lock;
68
+ query.lock(lock.strength, { skipLocked: lock.skipLocked, noWait: lock.noWait });
69
+ }
66
70
  const { text, values } = query.build();
67
71
  const { rows } = await this.db.query(text, values);
68
72
  return rows.map(row => this.decodeRow(row, fields));
@@ -10,7 +10,7 @@
10
10
  * NOTE: This file is read at codegen time and written to output.
11
11
  * Any changes here will affect all generated clients.
12
12
  */
13
- import type { Expr, Filter, Operand, SqlValue } from '@constructive-io/query-builder';
13
+ import type { Expr, Filter, LockOptions, LockStrength, Operand, SqlValue } from '@constructive-io/query-builder';
14
14
  import { fn, lit, QueryBuilder } from '@constructive-io/query-builder';
15
15
 
16
16
  /** Anything with pg's `query(text, values)` shape: Pool, PoolClient, Client. */
@@ -149,6 +149,21 @@ export type Data<App> = { [K in keyof App]?: App[K] | Expr } & {
149
149
 
150
150
  export type OrderDirection = 'ASC' | 'DESC';
151
151
 
152
+ /**
153
+ * Row-level lock the read takes, so a read-then-write stays serialized against
154
+ * a concurrent one: `'update'` is `FOR UPDATE`, and the object form states what
155
+ * to do about a row someone else holds.
156
+ *
157
+ * ```ts
158
+ * const run = await runs.$with(tx).findFirst({ where: { id }, lock: 'update' });
159
+ * const job = await jobs.$with(tx).findFirst({
160
+ * where: { status: 'pending' },
161
+ * lock: { strength: 'update', skipLocked: true }
162
+ * });
163
+ * ```
164
+ */
165
+ export type Lock = LockStrength | ({ strength: LockStrength } & LockOptions);
166
+
152
167
  /** Order spec keyed by camelCase field names, e.g. `{ createdAt: 'DESC' }`. */
153
168
  export type OrderBy<App> = { [K in keyof App]?: OrderDirection };
154
169
 
@@ -158,12 +173,14 @@ export interface FindManyArgs<App, S extends SelectShape<App> | undefined> {
158
173
  orderBy?: OrderBy<App> | OrderBy<App>[];
159
174
  limit?: number;
160
175
  offset?: number;
176
+ lock?: Lock;
161
177
  }
162
178
 
163
179
  export interface FindFirstArgs<App, S extends SelectShape<App> | undefined> {
164
180
  where?: Where<App>;
165
181
  select?: S;
166
182
  orderBy?: OrderBy<App> | OrderBy<App>[];
183
+ lock?: Lock;
167
184
  }
168
185
 
169
186
  export interface CreateArgs<App, S extends SelectShape<App> | undefined> {
@@ -242,6 +259,10 @@ export class TableClient<App> {
242
259
  this.applyOrderBy(query, args.orderBy);
243
260
  if (args.limit !== undefined) query.limit(args.limit);
244
261
  if (args.offset !== undefined) query.offset(args.offset);
262
+ if (args.lock) {
263
+ const lock = typeof args.lock === 'string' ? { strength: args.lock } : args.lock;
264
+ query.lock(lock.strength, { skipLocked: lock.skipLocked, noWait: lock.noWait });
265
+ }
245
266
  const { text, values } = query.build();
246
267
  const { rows } = await this.db.query(text, values);
247
268
  return rows.map(row => this.decodeRow(row, fields));
@@ -59,6 +59,10 @@ export class TableClient {
59
59
  query.limit(args.limit);
60
60
  if (args.offset !== undefined)
61
61
  query.offset(args.offset);
62
+ if (args.lock) {
63
+ const lock = typeof args.lock === 'string' ? { strength: args.lock } : args.lock;
64
+ query.lock(lock.strength, { skipLocked: lock.skipLocked, noWait: lock.noWait });
65
+ }
62
66
  const { text, values } = query.build();
63
67
  const { rows } = await this.db.query(text, values);
64
68
  return rows.map(row => this.decodeRow(row, fields));
@@ -10,7 +10,7 @@
10
10
  * NOTE: This file is read at codegen time and written to output.
11
11
  * Any changes here will affect all generated clients.
12
12
  */
13
- import type { Expr, Filter, Operand, SqlValue } from '@constructive-io/query-builder';
13
+ import type { Expr, Filter, LockOptions, LockStrength, Operand, SqlValue } from '@constructive-io/query-builder';
14
14
  import { fn, lit, QueryBuilder } from '@constructive-io/query-builder';
15
15
 
16
16
  /** Anything with pg's `query(text, values)` shape: Pool, PoolClient, Client. */
@@ -149,6 +149,21 @@ export type Data<App> = { [K in keyof App]?: App[K] | Expr } & {
149
149
 
150
150
  export type OrderDirection = 'ASC' | 'DESC';
151
151
 
152
+ /**
153
+ * Row-level lock the read takes, so a read-then-write stays serialized against
154
+ * a concurrent one: `'update'` is `FOR UPDATE`, and the object form states what
155
+ * to do about a row someone else holds.
156
+ *
157
+ * ```ts
158
+ * const run = await runs.$with(tx).findFirst({ where: { id }, lock: 'update' });
159
+ * const job = await jobs.$with(tx).findFirst({
160
+ * where: { status: 'pending' },
161
+ * lock: { strength: 'update', skipLocked: true }
162
+ * });
163
+ * ```
164
+ */
165
+ export type Lock = LockStrength | ({ strength: LockStrength } & LockOptions);
166
+
152
167
  /** Order spec keyed by camelCase field names, e.g. `{ createdAt: 'DESC' }`. */
153
168
  export type OrderBy<App> = { [K in keyof App]?: OrderDirection };
154
169
 
@@ -158,12 +173,14 @@ export interface FindManyArgs<App, S extends SelectShape<App> | undefined> {
158
173
  orderBy?: OrderBy<App> | OrderBy<App>[];
159
174
  limit?: number;
160
175
  offset?: number;
176
+ lock?: Lock;
161
177
  }
162
178
 
163
179
  export interface FindFirstArgs<App, S extends SelectShape<App> | undefined> {
164
180
  where?: Where<App>;
165
181
  select?: S;
166
182
  orderBy?: OrderBy<App> | OrderBy<App>[];
183
+ lock?: Lock;
167
184
  }
168
185
 
169
186
  export interface CreateArgs<App, S extends SelectShape<App> | undefined> {
@@ -242,6 +259,10 @@ export class TableClient<App> {
242
259
  this.applyOrderBy(query, args.orderBy);
243
260
  if (args.limit !== undefined) query.limit(args.limit);
244
261
  if (args.offset !== undefined) query.offset(args.offset);
262
+ if (args.lock) {
263
+ const lock = typeof args.lock === 'string' ? { strength: args.lock } : args.lock;
264
+ query.lock(lock.strength, { skipLocked: lock.skipLocked, noWait: lock.noWait });
265
+ }
245
266
  const { text, values } = query.build();
246
267
  const { rows } = await this.db.query(text, values);
247
268
  return rows.map(row => this.decodeRow(row, fields));
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "pg-codegen",
3
- "version": "5.18.0",
3
+ "version": "5.20.0",
4
4
  "author": "Constructive <developers@constructive.io>",
5
5
  "description": "Type-safe TypeScript codegen from live PostgreSQL schemas: row types, coerce-backed decoders, serializers, table metadata, and enum unions",
6
6
  "main": "index.js",
@@ -45,18 +45,18 @@
45
45
  "dependencies": {
46
46
  "@babel/generator": "^7.29.1",
47
47
  "@babel/types": "^7.29.0",
48
- "@constructive-io/coerce": "^0.3.1",
49
- "@constructive-io/query-builder": "^3.10.6",
48
+ "@constructive-io/coerce": "^0.4.0",
49
+ "@constructive-io/query-builder": "^3.12.0",
50
50
  "inflekt": "^0.8.1",
51
- "introspectron": "^5.13.1",
51
+ "introspectron": "^5.14.0",
52
52
  "pg": "^8.21.0",
53
- "pg-env": "^1.30.1"
53
+ "pg-env": "^1.31.0"
54
54
  },
55
55
  "devDependencies": {
56
56
  "@types/babel__generator": "^7.6.8",
57
57
  "@types/pg": "^8.20.4",
58
58
  "makage": "^0.3.0",
59
- "pgsql-test": "^5.11.1"
59
+ "pgsql-test": "^5.12.0"
60
60
  },
61
- "gitHead": "fa46a8b1cceb187c59f9c64e3a69e94dc9171f88"
61
+ "gitHead": "b5b6b9f05276b7e9cbd3d1f4acd31dd315c353ea"
62
62
  }