@inferencebureau/apps-sdk 0.11.0 → 0.12.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/dist/index.d.ts CHANGED
@@ -189,6 +189,12 @@ export interface AppRecord {
189
189
  /**
190
190
  * Which records a list returns: `{ field: { equals: x } }`, with AND, OR and NOT lists. `F` is a model's fields and
191
191
  * their filters, from the app's generated client types (`web/ib-client.d.ts`); any field without them.
192
+ *
193
+ * Filters reach through relationships, up to 3 deep, to the related records the call can read: a belongsTo or hasOne
194
+ * takes a filter on its record's fields, a hasMany or hasManyThrough `{ some | every | none: filter }` (RelatedListFilter).
195
+ *
196
+ * api.review.findMany({ filter: { product: { vendor: { equals: "Acme" } } } });
197
+ * api.product.findMany({ filter: { reviews: { some: { rating: { lessThan: 3 } } } } });
192
198
  */
193
199
  export type Filter<F extends object = {
194
200
  [field: string]: unknown;
@@ -197,14 +203,20 @@ export type Filter<F extends object = {
197
203
  OR?: Filter<F>[];
198
204
  NOT?: Filter<F>[];
199
205
  } & F;
200
- /** A list's order: the field to sort by, or several in turn. `K` is a model's sortable fields once the client is generated. */
201
- export type Sort<K extends string = string> = string extends K ? Record<string, SortDirection> : {
206
+ /**
207
+ * A list's order: the field to sort by, or several in turn. A belongsTo sorts by its record's fields,
208
+ * `{ product: { title: "Ascending" } }`, records without one last. `K` is a model's sortable fields once the client is
209
+ * generated, which types the belongsTo's too (SortOf).
210
+ */
211
+ export type Sort<K extends string = string> = string extends K ? {
212
+ [field: string]: SortDirection | Sort;
213
+ } : {
202
214
  [P in K]?: SortDirection;
203
215
  };
204
216
  export type SortDirection = "Ascending" | "Descending";
205
217
  export interface FindManyOptions<M extends ModelTypes = UntypedModel, S extends SelectOf<M> | undefined = undefined> {
206
218
  filter?: Filter<M["filter"]>;
207
- sort?: Sort<M["sortable"]> | Sort<M["sortable"]>[];
219
+ sort?: SortOf<M> | SortOf<M>[];
208
220
  first?: number;
209
221
  after?: string | null;
210
222
  /** Words to find in the model's text fields: records holding every one (any case, part of a word counts), those holding the whole phrase first unless sorted. */
@@ -240,9 +252,13 @@ type RelatedSelectOf<R extends RelationTypes> = {
240
252
  select?: SelectOf<ModelOf<R["model"]>>;
241
253
  } & (R["many"] extends true ? {
242
254
  filter?: Filter<ModelOf<R["model"]>["filter"]>;
243
- sort?: Sort<ModelOf<R["model"]>["sortable"]> | Sort<ModelOf<R["model"]>["sortable"]>[];
255
+ sort?: SortOf<ModelOf<R["model"]>> | SortOf<ModelOf<R["model"]>>[];
244
256
  first?: number;
245
257
  } : {});
258
+ /** A model's sort: the generated file's, else by its sortable fields. */
259
+ export type SortOf<M extends ModelTypes> = M extends {
260
+ sort: infer S extends object;
261
+ } ? S : Sort<M["sortable"]>;
246
262
  type RelationsOf<M extends ModelTypes> = M extends {
247
263
  relations: infer R extends {
248
264
  [field: string]: RelationTypes;
@@ -291,6 +307,14 @@ export interface StringFilter<V extends string = string> extends OrderedFilter<V
291
307
  }
292
308
  /** Dates as ISO 8601 text or a Date. */
293
309
  export type DateTimeFilter = OrderedFilter<string | Date>;
310
+ /** A hasMany or hasManyThrough's filter: records with `some` of its records matching, `every` one (or none at all), or `none`. */
311
+ export interface RelatedListFilter<F extends object = {
312
+ [field: string]: unknown;
313
+ }> {
314
+ some?: Filter<F>;
315
+ every?: Filter<F>;
316
+ none?: Filter<F>;
317
+ }
294
318
  /**
295
319
  * The app's models, filled in by `web/ib-client.d.ts`: Inference Bureau writes that file into development whenever a
296
320
  * schema or an action changes, `ib-apps dev` and `ib-apps pull` bring it down, and deploys carry it to production.
@@ -312,6 +336,8 @@ export interface ModelTypes {
312
336
  filter: object;
313
337
  /** The fields it can sort on. */
314
338
  sortable: string;
339
+ /** Its sort, a belongsTo's through to its record's fields; `Sort<sortable>` when the generated file has none. */
340
+ sort?: object;
315
341
  /** Its vector fields (`search`), file fields (`createUpload`, `upload`) and password fields (`checkPassword`). */
316
342
  vectors: string;
317
343
  files: string;
@@ -473,6 +499,42 @@ export interface CheckPasswordOptions {
473
499
  email?: string;
474
500
  ip?: string;
475
501
  }
502
+ /** The most records one bulk call takes. */
503
+ export declare const MAX_BULK = 250;
504
+ /** Why one record of a batch was refused: as a single write's ApiError says it, with `problems` for invalid values and `event` and `logs` for an action that threw. */
505
+ export interface BulkFailure {
506
+ index: number;
507
+ id?: string;
508
+ error: {
509
+ code: string;
510
+ message: string;
511
+ problems?: {
512
+ field: string;
513
+ message: string;
514
+ }[];
515
+ event?: string;
516
+ logs?: unknown[];
517
+ };
518
+ }
519
+ export interface BulkCounts {
520
+ succeeded: number;
521
+ failed: number;
522
+ created?: number;
523
+ updated?: number;
524
+ }
525
+ /** A batch's outcome: the records as written, null in a refused one's place; which failed and why; and counts. The rest are saved. */
526
+ export interface BulkResult<T = AppRecord> {
527
+ records: (T | null)[];
528
+ failed: BulkFailure[];
529
+ counts: BulkCounts;
530
+ }
531
+ export interface BulkDeleteResult {
532
+ deleted: string[];
533
+ failed: BulkFailure[];
534
+ counts: BulkCounts;
535
+ }
536
+ /** The field (or fields) an upsert finds its record by: a stored field with a value in `values`, or `id`. */
537
+ export type UpsertOn<M extends ModelTypes = UntypedModel> = (keyof M["input"] & string) | "id";
476
538
  export interface ModelClient<M extends ModelTypes = UntypedModel> {
477
539
  findOne<S extends SelectOf<M> | undefined = undefined>(id: string, o?: {
478
540
  select?: S;
@@ -487,6 +549,32 @@ export interface ModelClient<M extends ModelTypes = UntypedModel> {
487
549
  create(values: M["input"]): Promise<M["record"]>;
488
550
  update(id: string, values: M["input"]): Promise<M["record"]>;
489
551
  delete(id: string): Promise<void>;
552
+ /**
553
+ * Updates the record whose `on` field (or fields) hold the values' values, or creates one when there's none, the
554
+ * way `update` and `create` go. A unique validation on the field keeps two upserts at once from both creating.
555
+ */
556
+ upsert(o: {
557
+ on: UpsertOn<M> | UpsertOn<M>[];
558
+ values: M["input"];
559
+ }): Promise<{
560
+ record: M["record"];
561
+ created: boolean;
562
+ }>;
563
+ /**
564
+ * Up to 250 records in one call, each the way a single write goes (the model's action when it has one). Direct
565
+ * writes share one transaction, each rolled back alone when refused; the answer names which failed and why, and
566
+ * the rest are saved.
567
+ */
568
+ bulkCreate(values: M["input"][]): Promise<BulkResult<M["record"]>>;
569
+ bulkUpdate(records: {
570
+ id: string;
571
+ values: M["input"];
572
+ }[]): Promise<BulkResult<M["record"]>>;
573
+ bulkDelete(ids: string[]): Promise<BulkDeleteResult>;
574
+ bulkUpsert(o: {
575
+ on: UpsertOn<M> | UpsertOn<M>[];
576
+ records: M["input"][];
577
+ }): Promise<BulkResult<M["record"]>>;
490
578
  /**
491
579
  * A new record for an action's `run` to `save()`, written with the action's own record in one transaction. It has
492
580
  * its id already, so other records can point at it. Only an action's `api` builds records.
@@ -542,6 +630,15 @@ export type Api = ModelClients & {
542
630
  * it fails.
543
631
  */
544
632
  enqueue<A extends ActionName>(action: A, params?: ParamsOf<A>, options?: EnqueueOptions): Promise<Job>;
633
+ /**
634
+ * Queues up to 250 jobs for one action in one call, the options shared: one per entry, with its record's `id` and
635
+ * `params`. Every entry is checked before any is queued; the jobs come back in order. For one job over a whole
636
+ * batch, pass the batch as a global action's params instead.
637
+ */
638
+ enqueueMany<A extends ActionName>(action: A, jobs: {
639
+ id?: string;
640
+ params?: ParamsOf<A>;
641
+ }[], options?: Omit<EnqueueOptions, "id">): Promise<Job[]>;
545
642
  /**
546
643
  * The same API for one store: store-owned models (Shopify's, and any with a text field named `shop`) show only that
547
644
  * store's records, new ones are made as its, and actions run for it. An action's `api` is already its run's store's.
package/dist/index.js CHANGED
@@ -100,6 +100,8 @@ export class ApiError extends Error {
100
100
  this.problems = problems;
101
101
  }
102
102
  }
103
+ /** The most records one bulk call takes. */
104
+ export const MAX_BULK = 250;
103
105
  const envVar = (name) => globalThis.process?.env?.[name];
104
106
  /** The app's API. In an app's deployment every option comes from its environment variables. */
105
107
  export function createClient(o = {}) {
@@ -153,6 +155,11 @@ export function createClient(o = {}) {
153
155
  create: (values) => call("POST", `${m}/records`, values),
154
156
  update: (id, values) => call("PATCH", `${m}/records/${encodeURIComponent(id)}`, values),
155
157
  delete: (id) => call("DELETE", `${m}/records/${encodeURIComponent(id)}`),
158
+ upsert: (o) => call("POST", `${m}/records/upsert`, { on: o.on, values: o.values }),
159
+ bulkCreate: (values) => call("POST", `${m}/bulk`, { op: "create", records: values }),
160
+ bulkUpdate: (records) => call("POST", `${m}/bulk`, { op: "update", records }),
161
+ bulkDelete: (ids) => call("POST", `${m}/bulk`, { op: "delete", ids }),
162
+ bulkUpsert: (o) => call("POST", `${m}/bulk`, { op: "upsert", on: o.on, records: o.records }),
156
163
  build: () => { throw new Error("build() makes a record for an action's run to save(); outside an action, use create()."); },
157
164
  checkPassword: async (id, password, field) => {
158
165
  const o = typeof field === "string" ? { field } : field ?? {};
@@ -177,6 +184,7 @@ export function createClient(o = {}) {
177
184
  cache.set(name, model(name)); return cache.get(name); };
178
185
  const $global = (action, params = {}) => call("POST", `/actions/${encodeURIComponent(action)}`, { params });
179
186
  const enqueue = (action, params = {}, o = {}) => call("POST", "/jobs", { action, params, ...o, ...(o.runAt instanceof Date ? { runAt: o.runAt.toISOString() } : {}) });
187
+ const enqueueMany = async (action, jobs, o = {}) => (await call("POST", "/jobs/bulk", { action, jobs, ...o, ...(o.runAt instanceof Date ? { runAt: o.runAt.toISOString() } : {}) })).jobs;
180
188
  const sync = "/shopify/sync";
181
189
  const getRun = async (id) => {
182
190
  try {
@@ -214,6 +222,8 @@ export function createClient(o = {}) {
214
222
  return modelNamed;
215
223
  if (prop === "enqueue")
216
224
  return enqueue;
225
+ if (prop === "enqueueMany")
226
+ return enqueueMany;
217
227
  if (prop === "forShop")
218
228
  return forShop;
219
229
  if (prop === "asRole")
package/dist/runtime.js CHANGED
@@ -178,7 +178,7 @@ function stagingApi(api, handed) {
178
178
  return (...args) => stagingApi(v.apply(target, args), handed);
179
179
  if (prop === "$model")
180
180
  return (name) => receiver[name];
181
- if (typeof prop !== "string" || prop.startsWith("$") || prop === "then" || prop === "enqueue" || prop === "shopifySync" || !v || typeof v !== "object")
181
+ if (typeof prop !== "string" || prop.startsWith("$") || prop === "then" || prop === "enqueue" || prop === "enqueueMany" || prop === "shopifySync" || !v || typeof v !== "object")
182
182
  return v;
183
183
  if (!models.has(prop))
184
184
  models.set(prop, wrap(prop, v));
package/dist/test.js CHANGED
@@ -18,7 +18,7 @@
18
18
  * File fields keep their files in memory: `base64` reads back as a `data:` URL, `copyURL` as the URL itself (not
19
19
  * fetched, size 0), and `upload`/`createUpload` tokens as the upload (a `createUpload` needs no PUT here).
20
20
  */
21
- import { ApiError, ShopifyError, createAiClient, newRecordId } from "./index.js";
21
+ import { ApiError, MAX_BULK, ShopifyError, createAiClient, newRecordId } from "./index.js";
22
22
  import { runAction as runPhase } from "./runtime.js";
23
23
  /** Kept in `data`; the rest are a vector, the other side of a relationship, or worked out (computed). */
24
24
  const STORED = new Set(["string", "richText", "email", "url", "color", "number", "dateTime", "enum", "boolean", "roleList", "json", "belongsTo", "password", "encryptedString", "file"]);
@@ -26,6 +26,17 @@ const SYSTEM = ["id", "createdAt", "updatedAt"];
26
26
  const MAX_PAGE = 250;
27
27
  const MAX_RECORD_BYTES = 256 * 1024;
28
28
  const invalid = (problems) => new ApiError(problems.map((p) => `${p.field}: ${p.message}`).join("; "), 400, "invalid_request", problems);
29
+ /** A related filter's or sort's problems, named from the relationship: `product.vendor`. */
30
+ function under(at, f) {
31
+ try {
32
+ return f();
33
+ }
34
+ catch (e) {
35
+ if (e instanceof ApiError && e.problems.length)
36
+ throw invalid(e.problems.map((p) => ({ field: `${at}.${p.field}`, message: p.message })));
37
+ throw e;
38
+ }
39
+ }
29
40
  const notFound = (message) => new ApiError(message, 404, "not_found");
30
41
  const isObj = (v) => !!v && typeof v === "object" && !Array.isArray(v);
31
42
  /** What crosses the wire between Inference Bureau and the app: JSON (a Date arrives as its ISO string). */
@@ -38,6 +49,7 @@ function modelOf(name, schema) {
38
49
  return { name, fields, byName: new Map(fields.map((f) => [f.name, f])) };
39
50
  }
40
51
  const RELATIONSHIPS = new Set(["belongsTo", "hasOne", "hasMany", "hasManyThrough"]);
52
+ const LIST_OPS = ["some", "every", "none"];
41
53
  const both = (a, b) => (a && b ? { AND: [a, b] } : a ?? b);
42
54
  const ok = (value) => ({ ok: true, value });
43
55
  const bad = (message) => ({ ok: false, message });
@@ -850,28 +862,83 @@ class Records {
850
862
  }
851
863
  if (!isObj(v))
852
864
  throw invalid([{ field: k, message: "needs an operator, like { equals: … }" }]);
865
+ const f = m.byName.get(k);
866
+ // A belongsTo with operators filters on the id it holds; with fields, on its record.
867
+ if (f && RELATIONSHIPS.has(f.type) && (f.type !== "belongsTo" || !Object.keys(v).some((op) => OPS.includes(op)))) {
868
+ if (!this.relatedMatches(m, row, f, v, ctx))
869
+ return false;
870
+ continue;
871
+ }
853
872
  for (const [op, arg] of Object.entries(v)) {
854
873
  if (!OPS.includes(op))
855
- throw invalid([{ field: k, message: `${op} isn't a filter; use ${OPS.join(", ")}` }]);
874
+ throw invalid([{ field: k, message: f?.type === "belongsTo" ? `${op} isn't a filter; use ${OPS.join(", ")} on the id it holds, or only its record's fields` : `${op} isn't a filter; use ${OPS.join(", ")}` }]);
856
875
  if (!this.test(m, row, k, op, arg, ctx))
857
876
  return false;
858
877
  }
859
878
  }
860
879
  return true;
861
880
  }
862
- sorted(m, rows, sort) {
863
- const list = (Array.isArray(sort) ? sort : sort ? [sort] : []).flatMap((s) => Object.entries(s));
864
- const keys = list.map(([name, dir]) => {
865
- if (dir !== "Ascending" && dir !== "Descending")
866
- throw invalid([{ field: name, message: "sorts Ascending or Descending" }]);
867
- return { t: this.target(m, name), desc: dir === "Descending" };
868
- });
881
+ /** A relationship's records for a row (records.ts: relatedCondition), only those the caller can read, one deeper. */
882
+ reached(m, row, f, ctx) {
883
+ let rel;
884
+ try {
885
+ rel = this.relatedOf(m, f);
886
+ }
887
+ catch (e) {
888
+ throw invalid([{ field: f.name, message: e.message }]);
889
+ }
890
+ if (ctx.depth >= 3)
891
+ throw invalid([{ field: f.name, message: "filters and sorts can reach at most 3 relationships deep" }]);
892
+ const inner = { seen: ctx.seen, depth: ctx.depth + 1, readable: ctx.readable };
893
+ const t = rel.target;
894
+ const can = (x, r) => this.matches(x, r, ctx.readable?.(x), inner);
895
+ let rows;
896
+ if (f.type === "belongsTo") {
897
+ const r = typeof row.data[f.key] === "string" ? this.table(t).get(row.data[f.key]) : undefined;
898
+ rows = r ? [r] : [];
899
+ }
900
+ else if (rel.link)
901
+ rows = [...this.table(t).values()].filter((r) => r.data[rel.link.key] === row.id);
902
+ else {
903
+ const { model: jm, self, sibling } = rel.join;
904
+ rows = [...this.table(jm).values()].filter((j) => j.data[self.key] === row.id && can(jm, j)).map((j) => this.table(t).get(j.data[sibling.key])).filter((r) => !!r);
905
+ }
906
+ return { target: t, inner, rows: rows.filter((r) => can(t, r)) };
907
+ }
908
+ /**
909
+ * A filter through a relationship: a belongsTo or hasOne's record matching it, or a hasMany or hasManyThrough's
910
+ * records, `some`, `every` (none that doesn't) or `none` matching. Checked on a blank record first, as the API's SQL
911
+ * is checked whether or not there are records to try it on.
912
+ */
913
+ relatedMatches(m, row, f, v, ctx) {
914
+ const { target, inner, rows } = this.reached(m, row, f, ctx);
915
+ const probe = { id: "", createdAt: "", updatedAt: "", data: {}, vectors: new Map() };
916
+ if (f.type === "belongsTo" || f.type === "hasOne") {
917
+ under(f.name, () => this.matches(target, probe, v, inner));
918
+ return rows.some((r) => this.matches(target, r, v, inner));
919
+ }
920
+ let ok = true;
921
+ for (const [op, arg] of Object.entries(v)) {
922
+ if (!LIST_OPS.includes(op))
923
+ throw invalid([{ field: f.name, message: `${op} isn't a filter; a ${f.type} takes ${LIST_OPS.join(", ")}, like { some: { status: { equals: … } } }` }]);
924
+ if (arg !== undefined && arg !== null && !isObj(arg))
925
+ throw invalid([{ field: `${f.name}.${op}`, message: "must be a filter on its records' fields" }]);
926
+ const filter = (arg ?? undefined);
927
+ under(`${f.name}.${op}`, () => this.matches(target, probe, filter, inner));
928
+ const hit = (r) => this.matches(target, r, filter, inner);
929
+ ok &&= op === "some" ? rows.some(hit) : op === "none" ? !rows.some(hit) : rows.every(hit);
930
+ }
931
+ return ok;
932
+ }
933
+ sorted(m, rows, sort, readable) {
934
+ const ctx = { ...CTX, readable };
935
+ const keys = (Array.isArray(sort) ? sort : sort ? [sort] : []).flatMap((s) => this.sortKeys(m, s, ctx));
869
936
  if (!keys.length)
870
- keys.push({ t: { column: "createdAt" }, desc: true });
871
- keys.push({ t: { column: "id" }, desc: true });
937
+ keys.push({ at: (r) => r.createdAt, desc: true });
938
+ keys.push({ at: (r) => r.id, desc: true });
872
939
  return [...rows].sort((a, b) => {
873
940
  for (const k of keys) {
874
- const x = this.comparable(a, k.t), y = this.comparable(b, k.t);
941
+ const x = k.at(a), y = k.at(b);
875
942
  if (x === y)
876
943
  continue;
877
944
  // Nulls last, either way.
@@ -885,6 +952,26 @@ class Records {
885
952
  return 0;
886
953
  });
887
954
  }
955
+ /** A sort's values to order by, in turn (records.ts: sortTerms); a belongsTo's are read from its record, null without one the caller can read. */
956
+ sortKeys(m, sort, ctx) {
957
+ if (!isObj(sort))
958
+ throw invalid([{ field: "sort", message: "must be an object, like { createdAt: \"Descending\" }" }]);
959
+ return Object.entries(sort).flatMap(([name, dir]) => {
960
+ if (isObj(dir)) {
961
+ const f = m.byName.get(name);
962
+ if (f?.type !== "belongsTo")
963
+ throw invalid([{ field: name, message: f ? "sorts Ascending or Descending; only a belongsTo sorts by its record's fields" : `${m.name} has no field named ${name}` }]);
964
+ const probe = { id: "", createdAt: "", updatedAt: "", data: {}, vectors: new Map() };
965
+ const { target, inner } = this.reached(m, probe, f, ctx);
966
+ const parent = (row) => this.reached(m, row, f, ctx).rows[0];
967
+ return under(name, () => this.sortKeys(target, dir, inner)).map((k) => ({ at: (row) => { const p = parent(row); return p ? k.at(p) : null; }, desc: k.desc }));
968
+ }
969
+ if (dir !== "Ascending" && dir !== "Descending")
970
+ throw invalid([{ field: name, message: "sorts Ascending or Descending" }]);
971
+ const t = this.target(m, name, ctx);
972
+ return [{ at: (row) => this.comparable(row, t), desc: dir === "Descending" }];
973
+ });
974
+ }
888
975
  /** As the API's text search: every word in one of the text fields, and the rows holding the whole phrase. */
889
976
  textSearch(m, rows, text) {
890
977
  const words = searchWords(text);
@@ -903,11 +990,12 @@ class Records {
903
990
  const plan = this.plan(m, o.select);
904
991
  const first = Math.min(Math.max(1, Math.floor(o.first ?? 50)), MAX_PAGE);
905
992
  const offset = offsetOf(o.after);
906
- let rows = [...this.table(m).values()].filter((r) => this.matches(m, r, o.filter));
993
+ const ctx = { ...CTX, readable: o.readable };
994
+ let rows = [...this.table(m).values()].filter((r) => this.matches(m, r, o.filter, ctx));
907
995
  let distances = null;
908
996
  const text = typeof o.search === "string" ? this.textSearch(m, rows, o.search) : null;
909
997
  if (text) {
910
- rows = this.sorted(m, text.rows, o.sort);
998
+ rows = this.sorted(m, text.rows, o.sort, o.readable);
911
999
  // Unsorted, the rows holding the whole phrase come first (a stable sort keeps the default order within each).
912
1000
  if (!o.sort)
913
1001
  rows.sort((a, b) => Number(text.phrase.has(b.id)) - Number(text.phrase.has(a.id)));
@@ -935,7 +1023,7 @@ class Records {
935
1023
  rows = rows.filter((r) => distances.has(r.id)).sort((a, b) => distances.get(a.id) - distances.get(b.id) || (a.id < b.id ? -1 : 1));
936
1024
  }
937
1025
  else
938
- rows = this.sorted(m, rows, o.sort);
1026
+ rows = this.sorted(m, rows, o.sort, o.readable);
939
1027
  const page = rows.slice(offset, offset + first);
940
1028
  const budget = { left: 5000 };
941
1029
  const read = (r) => (plan ? this.selected(m, r, plan, o.readable, budget, false) : this.present(m, r, false));
@@ -945,9 +1033,9 @@ class Records {
945
1033
  endCursor: page.length ? cursorOf(offset + page.length) : null,
946
1034
  };
947
1035
  }
948
- count(model, filter) {
1036
+ count(model, filter, readable) {
949
1037
  const m = this.model(model);
950
- return [...this.table(m).values()].filter((r) => this.matches(m, r, filter)).length;
1038
+ return [...this.table(m).values()].filter((r) => this.matches(m, r, filter, { ...CTX, readable })).length;
951
1039
  }
952
1040
  // ---- select (records.ts: planOf, attach) ----
953
1041
  /** A select checked against the model, as records.ts's planOf checks it; null when unset. */
@@ -1047,20 +1135,21 @@ class Records {
1047
1135
  for (const rel of plan.relations) {
1048
1136
  const filter = both(readable?.(rel.target), rel.filter);
1049
1137
  const t = rel.target;
1138
+ const ctx = { ...CTX, readable };
1050
1139
  let rows;
1051
1140
  if (rel.link)
1052
- rows = this.sorted(t, [...this.table(t).values()].filter((r) => r.data[rel.link.key] === row.id && this.matches(t, r, filter)), rel.sort);
1141
+ rows = this.sorted(t, [...this.table(t).values()].filter((r) => r.data[rel.link.key] === row.id && this.matches(t, r, filter, ctx)), rel.sort, readable);
1053
1142
  else if (rel.join) {
1054
1143
  const { model: jm, self, sibling } = rel.join;
1055
1144
  const jf = readable?.(jm);
1056
- const reached = [...this.table(jm).values()].filter((j) => j.data[self.key] === row.id && this.matches(jm, j, jf))
1057
- .map((j) => this.table(t).get(j.data[sibling.key])).filter((r) => !!r && this.matches(t, r, filter));
1058
- rows = this.sorted(t, reached, rel.sort);
1145
+ const reached = [...this.table(jm).values()].filter((j) => j.data[self.key] === row.id && this.matches(jm, j, jf, ctx))
1146
+ .map((j) => this.table(t).get(j.data[sibling.key])).filter((r) => !!r && this.matches(t, r, filter, ctx));
1147
+ rows = this.sorted(t, reached, rel.sort, readable);
1059
1148
  }
1060
1149
  else {
1061
1150
  const id = out[rel.field.name];
1062
1151
  const r = typeof id === "string" ? this.table(t).get(id) : undefined;
1063
- rows = r && this.matches(t, r, filter) ? [r] : [];
1152
+ rows = r && this.matches(t, r, filter, ctx) ? [r] : [];
1064
1153
  }
1065
1154
  const kept = rows.slice(0, rel.first + 1);
1066
1155
  budget.left -= kept.length;
@@ -2044,7 +2133,63 @@ export function createTestApp(o = {}) {
2044
2133
  actionFilter(perms, scope, store.model(name), "update");
2045
2134
  }
2046
2135
  };
2047
- return {
2136
+ /** The fields an upsert finds its record by, checked as the API checks them, as the filter that finds it. */
2137
+ const upsertBy = (m, on, values) => {
2138
+ const problems = [];
2139
+ const parts = [];
2140
+ if (!on.length)
2141
+ problems.push({ field: "on", message: "names the field (or fields) to upsert by" });
2142
+ for (const field of on) {
2143
+ const f = field === "id" ? null : m.byName.get(field);
2144
+ if (field !== "id" && !f) {
2145
+ problems.push({ field, message: `${m.name} has no field named ${field}` });
2146
+ continue;
2147
+ }
2148
+ if (f && (!STORED.has(f.type) || f.type === "password" || f.type === "encryptedString" || f.type === "file")) {
2149
+ problems.push({ field, message: `a ${f.type} field can't be upserted by` });
2150
+ continue;
2151
+ }
2152
+ const v = values[field];
2153
+ if (v === undefined || v === null || v === "") {
2154
+ problems.push({ field, message: "is needed to upsert by it" });
2155
+ continue;
2156
+ }
2157
+ const link = f?.type === "belongsTo" && v && typeof v === "object" && typeof v._link === "string" ? v._link : v;
2158
+ parts.push({ [field]: { equals: link } });
2159
+ }
2160
+ if (problems.length)
2161
+ throw invalid(problems);
2162
+ return parts.length === 1 ? parts[0] : { AND: parts };
2163
+ };
2164
+ /** A batch as the API answers it: each record the way a single write goes, its refusal as its failure. */
2165
+ const batch = async (items, upsert = false) => {
2166
+ if (items.length > MAX_BULK)
2167
+ throw new ApiError(`A bulk call takes at most ${MAX_BULK} records; this one has ${items.length}.`, 400, "invalid_request");
2168
+ const records = [], failed = [];
2169
+ const counts = { succeeded: 0, failed: 0, ...(upsert ? { created: 0, updated: 0 } : {}) };
2170
+ for (const [index, it] of items.entries()) {
2171
+ try {
2172
+ const r = await it.work();
2173
+ records.push(r.record);
2174
+ counts.succeeded++;
2175
+ if (upsert) {
2176
+ if (r.created)
2177
+ counts.created++;
2178
+ else
2179
+ counts.updated++;
2180
+ }
2181
+ }
2182
+ catch (e) {
2183
+ if (!(e instanceof ApiError))
2184
+ throw e;
2185
+ records.push(null);
2186
+ counts.failed++;
2187
+ failed.push({ index, ...(it.id ? { id: it.id } : {}), error: { code: e.code ?? "invalid_request", message: e.message, ...(e.problems.length ? { problems: e.problems } : {}), ...(e instanceof ActionFailedError ? { logs: e.logs } : {}) } });
2188
+ }
2189
+ }
2190
+ return { records, failed, counts };
2191
+ };
2192
+ const client = {
2048
2193
  build: () => { throw new Error("build() makes a record for an action's run to save(); outside an action, use create()."); },
2049
2194
  findOne: async (id, o = {}) => findVisible(name, id, readOf(), wire(o.select), readable),
2050
2195
  findMany: async (q = {}) => store.findMany(name, narrow(wire(q))),
@@ -2073,6 +2218,27 @@ export function createTestApp(o = {}) {
2073
2218
  await canRun(scope, name, "delete", id);
2074
2219
  store.delete(name, id);
2075
2220
  },
2221
+ // As through the API: the record the on fields find (one the call's update grant reaches) is updated, else one is created.
2222
+ upsert: async ({ on, values }) => {
2223
+ const m = store.model(name);
2224
+ const v = scoped ? scopedValues(scope, m, wire(values)) : wire(values);
2225
+ const by = upsertBy(m, Array.isArray(on) ? on : [on], v);
2226
+ if (scoped)
2227
+ actionFilter(perms, scope, m, "create");
2228
+ const reach = scoped ? actionFilter(perms, scope, m, "update") : undefined;
2229
+ const found = (await store.findMany(name, { filter: reach ? { AND: [by, reach] } : by, first: 1 })).records[0];
2230
+ if (found)
2231
+ return { record: registry[`${name}/update`] ? (await runFor(scope, name, "update", { id: found.id, params: v })).record : await store.update(name, found.id, v), created: false };
2232
+ return { record: registry[`${name}/create`] ? (await runFor(scope, name, "create", { params: v })).record : await store.create(name, v), created: true };
2233
+ },
2234
+ bulkCreate: (values) => batch(values.map((v) => ({ work: async () => ({ record: await client.create(v) }) }))),
2235
+ bulkUpdate: (records) => batch(records.map((r) => ({ id: r.id, work: async () => ({ record: await client.update(r.id, r.values) }) }))),
2236
+ bulkDelete: async (ids) => {
2237
+ const r = await batch(ids.map((id) => ({ id, work: async () => { await client.delete(id); return { record: null }; } })));
2238
+ const lost = new Set(r.failed.map((f) => f.index));
2239
+ return { deleted: ids.filter((_id, i) => !lost.has(i)), failed: r.failed, counts: r.counts };
2240
+ },
2241
+ bulkUpsert: (q) => batch(q.records.map((v) => ({ work: () => client.upsert({ on: q.on, values: v }) })), true),
2076
2242
  // A record the call can't read answers false, as a missing one does.
2077
2243
  checkPassword: async (id, password, field) => (scoped && !(await findVisible(name, id, readOf())) ? false : store.checkPassword(name, id, password, typeof field === "string" ? field : field?.field)),
2078
2244
  run: async (action, q = {}) => {
@@ -2100,6 +2266,7 @@ export function createTestApp(o = {}) {
2100
2266
  return { directUploadToken: token };
2101
2267
  },
2102
2268
  };
2269
+ return client;
2103
2270
  };
2104
2271
  const enqueue = async (action, params = {}, q = {}) => {
2105
2272
  const t = (o.now ?? Date.now)();
@@ -2162,6 +2329,18 @@ export function createTestApp(o = {}) {
2162
2329
  const shop = scopedShop(scope, q.shop ?? null);
2163
2330
  return enqueue(action, params, shop ? { ...q, shop } : q);
2164
2331
  };
2332
+ // Every job is checked before any is queued, as the API does.
2333
+ const queueMany = async (action, entries, q = {}) => {
2334
+ if (entries.length > MAX_BULK)
2335
+ throw new ApiError(`A batch queues at most ${MAX_BULK} jobs; this one has ${entries.length}.`, 400, "invalid_request");
2336
+ const n = parseName(action);
2337
+ for (const e of entries)
2338
+ await canRun(scope, n.model, n.action, e.id ?? null);
2339
+ const out = [];
2340
+ for (const e of entries)
2341
+ out.push(await queue(action, e.params, { ...q, ...(e.id ? { id: e.id } : {}) }));
2342
+ return out;
2343
+ };
2165
2344
  const made = new Proxy({}, {
2166
2345
  get(_t, prop) {
2167
2346
  if (prop === "$global")
@@ -2170,6 +2349,8 @@ export function createTestApp(o = {}) {
2170
2349
  return (name) => made[name];
2171
2350
  if (prop === "enqueue")
2172
2351
  return queue;
2352
+ if (prop === "enqueueMany")
2353
+ return queueMany;
2173
2354
  if (prop === "forShop")
2174
2355
  return (s) => apiFor({ ...scope, shop: s });
2175
2356
  if (prop === "asRole")
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@inferencebureau/apps-sdk",
3
- "version": "0.11.0",
3
+ "version": "0.12.0",
4
4
  "description": "The SDK an Inference Bureau app's code imports: action helpers, metadata types, the records API client and a test harness for its actions.",
5
5
  "license": "UNLICENSED",
6
6
  "keywords": [