pg-codegen 5.17.0 → 5.18.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
@@ -57,6 +57,7 @@ One `create<Schema>Db(db, options?)` factory per schema, one client per table:
57
57
  | `findFirstOrThrow(args?)` | `SelectResult`, else `RowNotFoundError` |
58
58
  | `count(where?)` | `number` |
59
59
  | `create({ data, select? })` | the inserted row |
60
+ | `upsert({ conflict, create, update?, select? })` | the inserted or reconciled row, else `null` |
60
61
  | `update({ where, data, select? })` | the updated rows |
61
62
  | `updateOrThrow({ where, data, select? })` | one updated row, else `RowNotFoundError` |
62
63
  | `delete({ where, select? })` | the deleted rows |
@@ -89,6 +90,23 @@ await db.resources.update({
89
90
 
90
91
  An expression is deparsed in place — never bound as a value, never serialized as one.
91
92
 
93
+ ### Upsert
94
+
95
+ `upsert` states the unique fields it conflicts on, the row to insert, and what to set when one already exists:
96
+
97
+ ```ts
98
+ import { fn } from '@constructive-io/query-builder';
99
+
100
+ await db.appConfigs.upsert({
101
+ conflict: ['namespaceId', 'name'],
102
+ create: { name, value, namespaceId },
103
+ update: { value, updatedAt: fn('now') }
104
+ });
105
+ // INSERT INTO … ON CONFLICT (namespace_id, name) DO UPDATE SET value = $1, updated_at = now() RETURNING …
106
+ ```
107
+
108
+ Stating no `update` leaves a conflicting row as it is (`ON CONFLICT DO NOTHING`), and then there is no row to return — the result is `null`. An empty `conflict` throws, since it names no unique constraint.
109
+
92
110
  ### Selections type the result
93
111
 
94
112
  `select` is the only projection, stated either way round, and the return type follows it with nothing to annotate:
@@ -133,6 +133,31 @@ export interface CreateArgs<App, S extends SelectShape<App> | undefined> {
133
133
  data: Data<App>;
134
134
  select?: S;
135
135
  }
136
+ /**
137
+ * An upsert states the unique columns it conflicts on, the row to insert, and
138
+ * what to set when one already exists. No `update` means an existing row is
139
+ * left as it is (`ON CONFLICT DO NOTHING`), and then there may be no row to
140
+ * return.
141
+ *
142
+ * ```ts
143
+ * await db.appConfigs.upsert({
144
+ * conflict: ['namespaceId', 'name'],
145
+ * create: { name, value, namespaceId },
146
+ * update: { value, updatedAt: fn('now') }
147
+ * });
148
+ * ```
149
+ */
150
+ export interface UpsertArgs<App, S extends SelectShape<App> | undefined> {
151
+ /**
152
+ * The unique fields to conflict on. Generated fields autocomplete and map to
153
+ * their columns; a runtime-configured column (a scope key this binding's
154
+ * table carries) is named as the column it is.
155
+ */
156
+ conflict: readonly (keyof App & string)[] | readonly string[];
157
+ create: Data<App>;
158
+ update?: Data<App>;
159
+ select?: S;
160
+ }
136
161
  export interface UpdateArgs<App, S extends SelectShape<App> | undefined> {
137
162
  where: Where<App>;
138
163
  data: Data<App>;
@@ -157,6 +182,12 @@ export declare class TableClient<App> {
157
182
  findFirstOrThrow<S extends SelectShape<App> | undefined = undefined>(args?: FindFirstArgs<App, S>): Promise<SelectResult<App, S>>;
158
183
  count(where?: Where<App>): Promise<number>;
159
184
  create<S extends SelectShape<App> | undefined = undefined>(args: CreateArgs<App, S>): Promise<SelectResult<App, S>>;
185
+ /**
186
+ * Insert a row, or reconcile the one the conflict target already matches.
187
+ * Returns the resulting row, or null when a conflicting row was left as it
188
+ * is by an upsert that states no `update`.
189
+ */
190
+ upsert<S extends SelectShape<App> | undefined = undefined>(args: UpsertArgs<App, S>): Promise<SelectResult<App, S> | null>;
160
191
  update<S extends SelectShape<App> | undefined = undefined>(args: UpdateArgs<App, S>): Promise<SelectResult<App, S>[]>;
161
192
  updateOrThrow<S extends SelectShape<App> | undefined = undefined>(args: UpdateArgs<App, S>): Promise<SelectResult<App, S>>;
162
193
  delete<S extends SelectShape<App> | undefined = undefined>(args: DeleteArgs<App, S>): Promise<SelectResult<App, S>[]>;
@@ -96,6 +96,28 @@ class TableClient {
96
96
  const { rows } = await this.db.query(text, values);
97
97
  return this.decodeRow(rows[0], fields);
98
98
  }
99
+ /**
100
+ * Insert a row, or reconcile the one the conflict target already matches.
101
+ * Returns the resulting row, or null when a conflicting row was left as it
102
+ * is by an upsert that states no `update`.
103
+ */
104
+ async upsert(args) {
105
+ if (args.conflict.length === 0) {
106
+ throw new Error(`${this.spec.table}.upsert: refusing an empty conflict target, which names no unique constraint`);
107
+ }
108
+ const fields = this.selectedFields(args.select);
109
+ const columns = args.conflict.map(field => this.column(field));
110
+ const updateColumns = args.update ? this.encodeData(args.update) : {};
111
+ const query = this.baseQuery()
112
+ .insert(this.encodeData(args.create))
113
+ .onConflict(Object.keys(updateColumns).length > 0
114
+ ? { columns, action: 'update', updateColumns }
115
+ : { columns, action: 'nothing' })
116
+ .returning(fields.map(field => this.column(field)));
117
+ const { text, values } = query.build();
118
+ const { rows } = await this.db.query(text, values);
119
+ return rows.length > 0 ? this.decodeRow(rows[0], fields) : null;
120
+ }
99
121
  async update(args) {
100
122
  const fields = this.selectedFields(args.select);
101
123
  const query = this.baseQuery()
@@ -171,6 +171,32 @@ export interface CreateArgs<App, S extends SelectShape<App> | undefined> {
171
171
  select?: S;
172
172
  }
173
173
 
174
+ /**
175
+ * An upsert states the unique columns it conflicts on, the row to insert, and
176
+ * what to set when one already exists. No `update` means an existing row is
177
+ * left as it is (`ON CONFLICT DO NOTHING`), and then there may be no row to
178
+ * return.
179
+ *
180
+ * ```ts
181
+ * await db.appConfigs.upsert({
182
+ * conflict: ['namespaceId', 'name'],
183
+ * create: { name, value, namespaceId },
184
+ * update: { value, updatedAt: fn('now') }
185
+ * });
186
+ * ```
187
+ */
188
+ export interface UpsertArgs<App, S extends SelectShape<App> | undefined> {
189
+ /**
190
+ * The unique fields to conflict on. Generated fields autocomplete and map to
191
+ * their columns; a runtime-configured column (a scope key this binding's
192
+ * table carries) is named as the column it is.
193
+ */
194
+ conflict: readonly (keyof App & string)[] | readonly string[];
195
+ create: Data<App>;
196
+ update?: Data<App>;
197
+ select?: S;
198
+ }
199
+
174
200
  export interface UpdateArgs<App, S extends SelectShape<App> | undefined> {
175
201
  where: Where<App>;
176
202
  data: Data<App>;
@@ -258,6 +284,35 @@ export class TableClient<App> {
258
284
  return this.decodeRow(rows[0], fields);
259
285
  }
260
286
 
287
+ /**
288
+ * Insert a row, or reconcile the one the conflict target already matches.
289
+ * Returns the resulting row, or null when a conflicting row was left as it
290
+ * is by an upsert that states no `update`.
291
+ */
292
+ async upsert<S extends SelectShape<App> | undefined = undefined>(
293
+ args: UpsertArgs<App, S>
294
+ ): Promise<SelectResult<App, S> | null> {
295
+ if (args.conflict.length === 0) {
296
+ throw new Error(
297
+ `${this.spec.table}.upsert: refusing an empty conflict target, which names no unique constraint`
298
+ );
299
+ }
300
+ const fields = this.selectedFields(args.select);
301
+ const columns = args.conflict.map(field => this.column(field));
302
+ const updateColumns = args.update ? this.encodeData(args.update) : {};
303
+ const query = this.baseQuery()
304
+ .insert(this.encodeData(args.create))
305
+ .onConflict(
306
+ Object.keys(updateColumns).length > 0
307
+ ? { columns, action: 'update', updateColumns }
308
+ : { columns, action: 'nothing' }
309
+ )
310
+ .returning(fields.map(field => this.column(field)));
311
+ const { text, values } = query.build();
312
+ const { rows } = await this.db.query(text, values);
313
+ return rows.length > 0 ? this.decodeRow(rows[0], fields) : null;
314
+ }
315
+
261
316
  async update<S extends SelectShape<App> | undefined = undefined>(
262
317
  args: UpdateArgs<App, S>
263
318
  ): Promise<SelectResult<App, S>[]> {
@@ -92,6 +92,28 @@ export class TableClient {
92
92
  const { rows } = await this.db.query(text, values);
93
93
  return this.decodeRow(rows[0], fields);
94
94
  }
95
+ /**
96
+ * Insert a row, or reconcile the one the conflict target already matches.
97
+ * Returns the resulting row, or null when a conflicting row was left as it
98
+ * is by an upsert that states no `update`.
99
+ */
100
+ async upsert(args) {
101
+ if (args.conflict.length === 0) {
102
+ throw new Error(`${this.spec.table}.upsert: refusing an empty conflict target, which names no unique constraint`);
103
+ }
104
+ const fields = this.selectedFields(args.select);
105
+ const columns = args.conflict.map(field => this.column(field));
106
+ const updateColumns = args.update ? this.encodeData(args.update) : {};
107
+ const query = this.baseQuery()
108
+ .insert(this.encodeData(args.create))
109
+ .onConflict(Object.keys(updateColumns).length > 0
110
+ ? { columns, action: 'update', updateColumns }
111
+ : { columns, action: 'nothing' })
112
+ .returning(fields.map(field => this.column(field)));
113
+ const { text, values } = query.build();
114
+ const { rows } = await this.db.query(text, values);
115
+ return rows.length > 0 ? this.decodeRow(rows[0], fields) : null;
116
+ }
95
117
  async update(args) {
96
118
  const fields = this.selectedFields(args.select);
97
119
  const query = this.baseQuery()
@@ -171,6 +171,32 @@ export interface CreateArgs<App, S extends SelectShape<App> | undefined> {
171
171
  select?: S;
172
172
  }
173
173
 
174
+ /**
175
+ * An upsert states the unique columns it conflicts on, the row to insert, and
176
+ * what to set when one already exists. No `update` means an existing row is
177
+ * left as it is (`ON CONFLICT DO NOTHING`), and then there may be no row to
178
+ * return.
179
+ *
180
+ * ```ts
181
+ * await db.appConfigs.upsert({
182
+ * conflict: ['namespaceId', 'name'],
183
+ * create: { name, value, namespaceId },
184
+ * update: { value, updatedAt: fn('now') }
185
+ * });
186
+ * ```
187
+ */
188
+ export interface UpsertArgs<App, S extends SelectShape<App> | undefined> {
189
+ /**
190
+ * The unique fields to conflict on. Generated fields autocomplete and map to
191
+ * their columns; a runtime-configured column (a scope key this binding's
192
+ * table carries) is named as the column it is.
193
+ */
194
+ conflict: readonly (keyof App & string)[] | readonly string[];
195
+ create: Data<App>;
196
+ update?: Data<App>;
197
+ select?: S;
198
+ }
199
+
174
200
  export interface UpdateArgs<App, S extends SelectShape<App> | undefined> {
175
201
  where: Where<App>;
176
202
  data: Data<App>;
@@ -258,6 +284,35 @@ export class TableClient<App> {
258
284
  return this.decodeRow(rows[0], fields);
259
285
  }
260
286
 
287
+ /**
288
+ * Insert a row, or reconcile the one the conflict target already matches.
289
+ * Returns the resulting row, or null when a conflicting row was left as it
290
+ * is by an upsert that states no `update`.
291
+ */
292
+ async upsert<S extends SelectShape<App> | undefined = undefined>(
293
+ args: UpsertArgs<App, S>
294
+ ): Promise<SelectResult<App, S> | null> {
295
+ if (args.conflict.length === 0) {
296
+ throw new Error(
297
+ `${this.spec.table}.upsert: refusing an empty conflict target, which names no unique constraint`
298
+ );
299
+ }
300
+ const fields = this.selectedFields(args.select);
301
+ const columns = args.conflict.map(field => this.column(field));
302
+ const updateColumns = args.update ? this.encodeData(args.update) : {};
303
+ const query = this.baseQuery()
304
+ .insert(this.encodeData(args.create))
305
+ .onConflict(
306
+ Object.keys(updateColumns).length > 0
307
+ ? { columns, action: 'update', updateColumns }
308
+ : { columns, action: 'nothing' }
309
+ )
310
+ .returning(fields.map(field => this.column(field)));
311
+ const { text, values } = query.build();
312
+ const { rows } = await this.db.query(text, values);
313
+ return rows.length > 0 ? this.decodeRow(rows[0], fields) : null;
314
+ }
315
+
261
316
  async update<S extends SelectShape<App> | undefined = undefined>(
262
317
  args: UpdateArgs<App, S>
263
318
  ): Promise<SelectResult<App, S>[]> {
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "pg-codegen",
3
- "version": "5.17.0",
3
+ "version": "5.18.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",
@@ -58,5 +58,5 @@
58
58
  "makage": "^0.3.0",
59
59
  "pgsql-test": "^5.11.1"
60
60
  },
61
- "gitHead": "ce544846eafd96280fac2607f873960392ae2c89"
61
+ "gitHead": "fa46a8b1cceb187c59f9c64e3a69e94dc9171f88"
62
62
  }