@revenexx/app-sdk 1.6.0 → 2.1.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.
@@ -39,6 +39,17 @@ interface Entity {
39
39
  pk: string;
40
40
  columns?: Record<string, ColumnDef>;
41
41
  ops?: Op[] | Set<Op>;
42
+ /**
43
+ * schema.json `trash: true`. Baseline then adds `deleted_at`, `deleted_by`,
44
+ * `deleted_by_id`, `trash_batch` and `purge_blocked_reason`, and a write may
45
+ * name them even when `columns` does not list them.
46
+ */
47
+ trash?: boolean;
48
+ /**
49
+ * schema.json `external_id: true`. Baseline then adds `external_id`, and a
50
+ * write may name it even when `columns` does not list it.
51
+ */
52
+ external_id?: boolean;
42
53
  }
43
54
  type Row = Record<string, unknown>;
44
55
  /** A page of rows plus the total count of matching rows (ignoring limit/offset). */
@@ -131,6 +142,12 @@ interface Adapter {
131
142
  */
132
143
  updateIf?(entity: Entity, id: string | number, where: Where, patch: Row): Promise<Row | null>;
133
144
  page?(entity: Entity, query?: Query): Promise<Page>;
145
+ /**
146
+ * Insert a non-empty list of records in one request and answer the created
147
+ * rows, in order. Optional like `page`: the entity client refuses a call on
148
+ * an adapter without it, and never emulates it as one create per record.
149
+ */
150
+ createMany?(entity: Entity, rows: Row[]): Promise<Row[]>;
134
151
  emit?(target: EmitTarget, data: Row, options: EmitOptions): Promise<EmitResult>;
135
152
  /** What this adapter recorded instead of publishing (mock only). */
136
153
  emitted?(): EmittedEvent[];
@@ -406,9 +423,10 @@ interface BackdatingOptions {
406
423
  /** Routes (`METHOD /template`) that are never backdated. Wins over `routes`. */
407
424
  exclude?: readonly string[];
408
425
  /**
409
- * Remove the moment's fields from `c.body` before the handler runs, on a
410
- * backdated request only. Default false: the body is left as it came. Set it
411
- * when a handler spreads its body into a row and no table has an `at` column.
426
+ * Remove the moment's fields from `c.body` before the handler runs, on every
427
+ * request to a backdatable route — whether the gate opened or not. Default
428
+ * false: the body is left as it came. Set it when a handler spreads its body
429
+ * into a row: the data client refuses a key that is not a column.
412
430
  */
413
431
  strip?: boolean;
414
432
  }
package/dist/index.cjs CHANGED
@@ -183,6 +183,126 @@ function compare(a, op, b) {
183
183
  }
184
184
  }
185
185
 
186
+ // src/patch.ts
187
+ var EMPTY_UPDATE_MESSAGE = "request body must contain at least one field to update";
188
+ function updateFields(patch) {
189
+ if (!patch || typeof patch !== "object" || Array.isArray(patch)) return [];
190
+ return Object.keys(patch).filter(
191
+ (key) => patch[key] !== void 0
192
+ );
193
+ }
194
+ var EMPTY_CREATE_MESSAGE = "request body must contain at least one field to create";
195
+ function assertCreatable(data) {
196
+ if (updateFields(data).length === 0) throw badRequest(EMPTY_CREATE_MESSAGE, void 0, { code: "empty_create" });
197
+ }
198
+ function assertUpdatable(patch) {
199
+ if (updateFields(patch).length === 0) throw badRequest(EMPTY_UPDATE_MESSAGE, void 0, { code: "empty_update" });
200
+ }
201
+ var EMPTY_CONDITION_MESSAGE = "a conditional update needs at least one condition in where";
202
+ function assertCondition(where) {
203
+ if (!where || typeof where !== "object" || Array.isArray(where) || Object.keys(where).length === 0) {
204
+ throw badRequest(EMPTY_CONDITION_MESSAGE, void 0, { code: "empty_condition" });
205
+ }
206
+ assertDefined(where);
207
+ }
208
+ function assertDefined(where) {
209
+ if (!where || typeof where !== "object") return;
210
+ for (const [col, cond] of Object.entries(where)) {
211
+ if (cond === void 0) {
212
+ throw badRequest(`where.${col} is undefined \u2014 a condition needs a value`, void 0, { code: "undefined_condition" });
213
+ }
214
+ }
215
+ }
216
+ var IMPLICIT_COLUMNS = ["tenant_id"];
217
+ var TRASH_FLAG_COLUMNS = [
218
+ "deleted_at",
219
+ "deleted_by",
220
+ "deleted_by_id",
221
+ "trash_batch",
222
+ "purge_blocked_reason"
223
+ ];
224
+ var EXTERNAL_ID_FLAG_COLUMNS = ["external_id"];
225
+ function flagColumns(entity) {
226
+ return [
227
+ ...entity.trash === true ? TRASH_FLAG_COLUMNS : [],
228
+ ...entity.external_id === true ? EXTERNAL_ID_FLAG_COLUMNS : []
229
+ ];
230
+ }
231
+ function writableColumns(entity) {
232
+ return [.../* @__PURE__ */ new Set([...Object.keys(entity.columns ?? {}), ...flagColumns(entity)])].sort();
233
+ }
234
+ function unknownFields(entity, data) {
235
+ if (!checksFields(entity)) return [];
236
+ if (!data || typeof data !== "object" || Array.isArray(data)) return [];
237
+ const row = data;
238
+ const writable = /* @__PURE__ */ new Set([...writableColumns(entity), ...IMPLICIT_COLUMNS]);
239
+ return Object.keys(row).filter((key) => row[key] !== void 0 && !writable.has(key)).sort();
240
+ }
241
+ function checksFields(entity) {
242
+ return !!entity.columns && Object.keys(entity.columns).length > 0;
243
+ }
244
+ var ONE_RECORD_MESSAGE = "a write takes one record, as a JSON object \u2014 not a list";
245
+ function assertOneRecord(entity, data) {
246
+ if (checksFields(entity) && isList(data)) throw oneRecordRefusal();
247
+ }
248
+ var INDEX = /^(?:0|[1-9]\d*)$/;
249
+ function isList(data) {
250
+ if (!data || typeof data !== "object") return false;
251
+ if (Array.isArray(data)) return data.length > 0;
252
+ const keys = Object.keys(data);
253
+ return keys.length > 0 && keys.every((k) => INDEX.test(k) && Number(k) < keys.length);
254
+ }
255
+ var ENTITY_DESCRIPTOR = /* @__PURE__ */ Symbol.for("revenexx.app-sdk.entity");
256
+ var MANY_RECORDS_MESSAGE = "createMany takes a list of records";
257
+ function bulkRecords(entity, data) {
258
+ if (Array.isArray(data) && data.length === 0) throw badRequest(EMPTY_CREATE_MESSAGE, void 0, { code: "empty_create" });
259
+ if (!isList(data)) throw badRequest(MANY_RECORDS_MESSAGE, void 0, { code: "bad_request" });
260
+ const records = Array.isArray(data) ? data : Object.keys(data).sort((a, b) => Number(a) - Number(b)).map((k) => data[k]);
261
+ let shape2;
262
+ records.forEach((record, index) => {
263
+ if (!record || typeof record !== "object" || isList(record)) {
264
+ throw badRequest(`record ${index} of a bulk create is not an object \u2014 each element is one record`, { index }, { code: "bad_request" });
265
+ }
266
+ const fields = updateFields(record);
267
+ if (fields.length === 0) {
268
+ throw badRequest(`record ${index} of a bulk create has no field \u2014 ${EMPTY_CREATE_MESSAGE}`, { index }, { code: "empty_create" });
269
+ }
270
+ const unknown = unknownFields(entity, record);
271
+ if (unknown.length > 0) {
272
+ const quoted = unknown.map((k) => `'${k}'`).join(", ");
273
+ throw badRequest(
274
+ `unknown field${unknown.length > 1 ? "s" : ""} ${quoted} in record ${index} \u2014 not a column of '${entity.name}'. A field that cannot be written is refused rather than dropped; see details.allowed.`,
275
+ { index, unknown, allowed: writableColumns(entity) },
276
+ { code: "unknown_field" }
277
+ );
278
+ }
279
+ const key = [...fields].sort().join("\0");
280
+ if (shape2 === void 0) shape2 = key;
281
+ else if (key !== shape2) {
282
+ throw badRequest(
283
+ `record ${index} of a bulk create names other fields than record 0 \u2014 every record of a bulk create names the same fields`,
284
+ { index },
285
+ { code: "bad_request" }
286
+ );
287
+ }
288
+ });
289
+ return records;
290
+ }
291
+ function oneRecordRefusal() {
292
+ return badRequest(ONE_RECORD_MESSAGE, void 0, { code: "bad_request" });
293
+ }
294
+ function assertKnownFields(entity, data) {
295
+ assertOneRecord(entity, data);
296
+ const unknown = unknownFields(entity, data);
297
+ if (unknown.length === 0) return;
298
+ const quoted = unknown.map((k) => `'${k}'`).join(", ");
299
+ throw badRequest(
300
+ `unknown field${unknown.length > 1 ? "s" : ""} ${quoted} \u2014 not a column of '${entity.name}'. A field that cannot be written is refused rather than dropped; see details.allowed.`,
301
+ { unknown, allowed: writableColumns(entity) },
302
+ { code: "unknown_field" }
303
+ );
304
+ }
305
+
186
306
  // src/adapters/mock.ts
187
307
  function shape(rows, query) {
188
308
  let out = rows;
@@ -200,12 +320,13 @@ function shape(rows, query) {
200
320
  }
201
321
  return out.map((r) => ({ ...r }));
202
322
  }
203
- var IMPLICIT_COLUMNS = /* @__PURE__ */ new Set(["tenant_id"]);
323
+ var IMPLICIT_COLUMNS2 = new Set(IMPLICIT_COLUMNS);
204
324
  function assertWhereColumns(entity, where) {
205
325
  const columns = entity.columns;
206
326
  if (!columns || Object.keys(columns).length === 0 || !where) return;
327
+ const flagged = new Set(flagColumns(entity));
207
328
  const unknown = Object.keys(where).filter(
208
- (k) => !Object.prototype.hasOwnProperty.call(columns, k) && !IMPLICIT_COLUMNS.has(k)
329
+ (k) => !Object.prototype.hasOwnProperty.call(columns, k) && !IMPLICIT_COLUMNS2.has(k) && !flagged.has(k)
209
330
  );
210
331
  if (unknown.length === 0) return;
211
332
  throw new HttpError(400, "the request could not be processed", void 0, {
@@ -262,13 +383,43 @@ function createMockAdapter(seed = {}) {
262
383
  const r = tbl(entity).get(id);
263
384
  return r ? { ...r } : null;
264
385
  },
386
+ // A key that is not a declared column is the same 400 `unknown_field` the
387
+ // remote adapter raises, so a test cannot pass on a write production
388
+ // refuses.
265
389
  async create(entity, data) {
390
+ assertKnownFields(entity, data);
391
+ assertCreatable(data);
266
392
  const row = applyDefaults(entity, data);
267
393
  if (row[entity.pk] === void 0) row[entity.pk] = (0, import_node_crypto.randomUUID)();
268
394
  tbl(entity).set(row[entity.pk], row);
269
395
  return { ...row };
270
396
  },
397
+ // One statement in Postgres: a primary key twice in the batch, or one the
398
+ // table already holds, is the 409 the remote adapter maps from 23505, and
399
+ // nothing is stored.
400
+ async createMany(entity, data) {
401
+ const rows = bulkRecords(entity, data).map((record) => {
402
+ const row = applyDefaults(entity, record);
403
+ if (row[entity.pk] === void 0) row[entity.pk] = (0, import_node_crypto.randomUUID)();
404
+ return row;
405
+ });
406
+ const table = tbl(entity);
407
+ const seen = /* @__PURE__ */ new Set();
408
+ for (const row of rows) {
409
+ const id = row[entity.pk];
410
+ if (seen.has(id) || table.has(id)) {
411
+ throw new HttpError(409, "a record with this value already exists", void 0, {
412
+ code: "unique_violation",
413
+ serverDetail: { source: "mock", entity: entity.name, duplicate: id }
414
+ });
415
+ }
416
+ seen.add(id);
417
+ }
418
+ for (const row of rows) table.set(row[entity.pk], row);
419
+ return rows.map((row) => ({ ...row }));
420
+ },
271
421
  async update(entity, id, patch) {
422
+ assertKnownFields(entity, patch);
272
423
  const cur = tbl(entity).get(id);
273
424
  if (!cur) throw notFound(`mock: ${entity.name}/${String(id)} not found`);
274
425
  return write(entity, id, cur, patch);
@@ -280,6 +431,7 @@ function createMockAdapter(seed = {}) {
280
431
  // a lost race: answering `null` would read as "somebody else moved it".
281
432
  async updateIf(entity, id, where, patch) {
282
433
  assertWhereColumns(entity, where);
434
+ assertKnownFields(entity, patch);
283
435
  const cur = tbl(entity).get(id);
284
436
  if (!cur || !matches(cur, where)) return null;
285
437
  return write(entity, id, cur, patch);
@@ -461,7 +613,12 @@ function createRemoteAdapter(config) {
461
613
  });
462
614
  return rows?.[0] ?? null;
463
615
  },
616
+ // Every write is checked against the entity's declared columns here as
617
+ // well as in the client, so the adapter used on its own refuses the same
618
+ // keys (see ../patch.ts `unknownFields`).
464
619
  async create(entity, data) {
620
+ assertKnownFields(entity, data);
621
+ assertCreatable(data);
465
622
  const rows = await req("POST", `/${entity.table}`, {
466
623
  body: data,
467
624
  prefer: "return=representation",
@@ -475,7 +632,25 @@ function createRemoteAdapter(config) {
475
632
  })
476
633
  );
477
634
  },
635
+ // One POST of the whole list: PostgREST inserts it in one statement and
636
+ // answers every row, in order. Checked here as well as in the client.
637
+ async createMany(entity, data) {
638
+ const records = bulkRecords(entity, data);
639
+ const rows = await req("POST", `/${entity.table}`, {
640
+ body: records,
641
+ prefer: "return=representation",
642
+ table: entity.table
643
+ });
644
+ if (!Array.isArray(rows) || rows.length < records.length) {
645
+ throw new HttpError(500, "the records were created but could not be read back", void 0, {
646
+ code: "empty_representation",
647
+ serverDetail: { source: "postgrest", method: "POST", table: entity.table, sent: records.length }
648
+ });
649
+ }
650
+ return rows;
651
+ },
478
652
  async update(entity, id, patch) {
653
+ assertKnownFields(entity, patch);
479
654
  const rows = await req("PATCH", `/${entity.table}?${entity.pk}=eq.${encodeURIComponent(String(id))}`, {
480
655
  body: patch,
481
656
  prefer: "return=representation",
@@ -484,6 +659,7 @@ function createRemoteAdapter(config) {
484
659
  return oneRow(rows, () => notFound());
485
660
  },
486
661
  async updateIf(entity, id, where, patch) {
662
+ assertKnownFields(entity, patch);
487
663
  const cond = toParams({ where }).toString();
488
664
  const rows = await req("PATCH", `/${entity.table}?${entity.pk}=eq.${encodeURIComponent(String(id))}&${cond}`, {
489
665
  body: patch,
@@ -613,33 +789,6 @@ registerAdapter("mock", (c) => createMockAdapter(c.seed));
613
789
  registerAdapter("remote", (c) => createRemoteAdapter(c));
614
790
  registerAdapter("runtime", (c) => createRuntimeAdapter(c));
615
791
 
616
- // src/patch.ts
617
- var EMPTY_UPDATE_MESSAGE = "request body must contain at least one field to update";
618
- function updateFields(patch) {
619
- if (!patch || typeof patch !== "object" || Array.isArray(patch)) return [];
620
- return Object.keys(patch).filter(
621
- (key) => patch[key] !== void 0
622
- );
623
- }
624
- function assertUpdatable(patch) {
625
- if (updateFields(patch).length === 0) throw badRequest(EMPTY_UPDATE_MESSAGE, void 0, { code: "empty_update" });
626
- }
627
- var EMPTY_CONDITION_MESSAGE = "a conditional update needs at least one condition in where";
628
- function assertCondition(where) {
629
- if (!where || typeof where !== "object" || Array.isArray(where) || Object.keys(where).length === 0) {
630
- throw badRequest(EMPTY_CONDITION_MESSAGE, void 0, { code: "empty_condition" });
631
- }
632
- assertDefined(where);
633
- }
634
- function assertDefined(where) {
635
- if (!where || typeof where !== "object") return;
636
- for (const [col, cond] of Object.entries(where)) {
637
- if (cond === void 0) {
638
- throw badRequest(`where.${col} is undefined \u2014 a condition needs a value`, void 0, { code: "undefined_condition" });
639
- }
640
- }
641
- }
642
-
643
792
  // src/client.ts
644
793
  var ACCESS_TO_OPS = {
645
794
  read: ["list", "get"],
@@ -662,7 +811,7 @@ function entityClient(adapter, entity) {
662
811
  { code: "not_permitted" }
663
812
  );
664
813
  });
665
- return {
814
+ const client = {
666
815
  list: guard("list", async (query) => {
667
816
  assertDefined(query?.where);
668
817
  return adapter.list(entity, query ?? {});
@@ -675,7 +824,25 @@ function entityClient(adapter, entity) {
675
824
  return adapter.page(entity, query ?? {});
676
825
  }),
677
826
  get: guard("get", (id) => adapter.get(entity, id)),
678
- create: guard("create", (data) => adapter.create(entity, data)),
827
+ // A key that is not a column this version declares is refused before the
828
+ // request (see ./patch.ts `unknownFields`): the database cannot tell an
829
+ // old version's stray key from a new version's column. `async` so the
830
+ // refusal is a rejection like every other write failure; the permission
831
+ // refusal above stays synchronous.
832
+ create: guard("create", async (data) => {
833
+ assertKnownFields(entity, data);
834
+ assertCreatable(data);
835
+ return adapter.create(entity, data);
836
+ }),
837
+ // A bulk create is its own call: checked whole before the one request
838
+ // (./patch.ts `bulkRecords`), never emulated as one create per record.
839
+ createMany: guard("create", async (rows) => {
840
+ const records = bulkRecords(entity, rows);
841
+ if (!adapter.createMany) {
842
+ throw new Error(`${entity.name}.createMany() is not supported by the '${adapter.kind}' adapter`);
843
+ }
844
+ return adapter.createMany(entity, records);
845
+ }, "createMany"),
679
846
  // A patch with no fields is a malformed request, not a write: PostgREST
680
847
  // performs no update and returns no row, which used to leave the App
681
848
  // serialising `undefined` and answering 500 (see ./patch.ts). Rejected here
@@ -686,14 +853,18 @@ function entityClient(adapter, entity) {
686
853
  // patch is handled like any other data-plane failure (`await` / `.catch()`)
687
854
  // and the declared `Promise<T>` stays honest.
688
855
  update: guard("update", async (id, patch) => {
856
+ assertOneRecord(entity, patch);
689
857
  assertUpdatable(patch);
858
+ assertKnownFields(entity, patch);
690
859
  return adapter.update(entity, id, patch);
691
860
  }),
692
861
  // Validated in the same order and at the same layer as `update`, so every
693
862
  // adapter refuses a missing condition identically, before any request.
694
863
  updateIf: guard("update", async (id, where, patch) => {
695
864
  assertCondition(where);
865
+ assertOneRecord(entity, patch);
696
866
  assertUpdatable(patch);
867
+ assertKnownFields(entity, patch);
697
868
  if (!adapter.updateIf) {
698
869
  throw new Error(`${entity.name}.updateIf() is not supported by the '${adapter.kind}' adapter`);
699
870
  }
@@ -701,6 +872,8 @@ function entityClient(adapter, entity) {
701
872
  }, "updateIf"),
702
873
  delete: guard("delete", (id) => adapter.remove(entity, id))
703
874
  };
875
+ Object.defineProperty(client, ENTITY_DESCRIPTOR, { value: entity, enumerable: true });
876
+ return client;
704
877
  }
705
878
  function eventsClient(adapter, config) {
706
879
  const names = () => Object.keys(config.declared).sort().join(", ") || "(none)";
@@ -1006,17 +1179,23 @@ function backdatingDb(db, entities) {
1006
1179
  new Proxy(repo, {
1007
1180
  get(r, key, rr) {
1008
1181
  const member = Reflect.get(r, key, rr);
1009
- if (key !== "create" || typeof member !== "function") return member;
1010
- return (data, ...rest) => {
1011
- if (!backdated() || !data || typeof data !== "object" || Array.isArray(data)) {
1012
- return member.call(r, data, ...rest);
1013
- }
1014
- const at = now();
1182
+ if (key !== "create" && key !== "createMany" || typeof member !== "function") return member;
1183
+ const call = (data, rest) => member.call(r, data, ...rest);
1184
+ const stamp = (data, at) => {
1185
+ if (!data || typeof data !== "object" || Array.isArray(data) || isList(data)) return data;
1015
1186
  const row = { ...data };
1016
1187
  if (row.created_at === void 0) row.created_at = at;
1017
1188
  if ("updated_at" in columns && row.updated_at === void 0) row.updated_at = at;
1018
- return member.call(r, row, ...rest);
1189
+ return row;
1019
1190
  };
1191
+ if (key === "createMany") {
1192
+ return (data, ...rest) => {
1193
+ if (!backdated() || !Array.isArray(data)) return call(data, rest);
1194
+ const at = now();
1195
+ return call(data.map((record) => stamp(record, at)), rest);
1196
+ };
1197
+ }
1198
+ return (data, ...rest) => backdated() ? call(stamp(data, now()), rest) : call(data, rest);
1020
1199
  }
1021
1200
  })
1022
1201
  );