xmemory 3.15.0 → 3.17.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
@@ -250,6 +250,39 @@ did — and where a [scoped write](#scoped-writes) in `"drop"` mode reports what
250
250
  left out. A status for a write that has not finished carries none, so the field
251
251
  is optional.
252
252
 
253
+ ### Write ordering
254
+
255
+ Every write to an instance goes into one queue for that instance: `write` and
256
+ `writeAsync`, text and `WriteMutation[]` alike. Queued writes are processed in
257
+ parallel, but applied to the instance one at a time, in the order they were
258
+ queued (FIFO). A write is never applied ahead of an older one, even when its own
259
+ processing finished first.
260
+
261
+ - `writeAsync` resolves once the write is queued. `writeStatus` reports
262
+ `"queued"` until processing starts, and `"extracted"` while a processed write
263
+ waits for older writes to be applied.
264
+ - `write` waits in the same queue and resolves once its own write is applied.
265
+ It does not jump ahead of async writes queued before it.
266
+ - The order is the order the server receives the writes. Two writes sent at
267
+ the same time have no defined order between them, so when one must apply
268
+ after another, await the first call (`writeAsync` resolving with its
269
+ `write_id` is enough) before sending the second.
270
+ - Reads are not queued: a read sees only writes that have completed.
271
+
272
+ ```typescript
273
+ await inst.writeAsync("Bob joined the team as a designer.");
274
+ await inst.writeAsync("Bob moved to the London office.");
275
+ // Applied after both writes above, in order.
276
+ await inst.write([
277
+ {
278
+ object_mutation: {
279
+ object_type: "person",
280
+ update: { key: { name: "Bob" }, values: { role: "lead designer" } },
281
+ },
282
+ },
283
+ ]);
284
+ ```
285
+
253
286
  ### `inst.read(query, options?)` → `ReadResult`
254
287
 
255
288
  Query the instance.
@@ -264,13 +297,14 @@ Options: `{ readMode?, scope?, includeRelatedTypes?, relatedTypesDepth?, skipSug
264
297
  #### What comes back
265
298
 
266
299
  In `"single-answer"` mode `reader_result` is always the prose answer. In
267
- `"raw-tables"` and `"xresponse"` mode its value says which of four answers the
300
+ `"raw-tables"` and `"xresponse"` mode its value says which of five answers the
268
301
  read gave:
269
302
 
270
303
  | `reader_result` | Meaning | What to do |
271
304
  | --- | --- | --- |
272
305
  | rows | Answered. | Use them. |
273
- | exactly `{ columns: [], rows: [] }` / `{ objects: [], relations: [] }` | The query executed and matched nothing — every table and column it used exists, so the data is absent. | Trust the empty result. |
306
+ | exactly `{ columns: [], rows: [] }` / `{ objects: [], relations: [] }`, `notice` is `null` | The query executed and matched nothing — every table and column it used exists, so the data is absent. | Trust the empty result. |
307
+ | the same empty value, `notice` set | The server could not run a query that answers the question as asked, so the empty value says nothing about what is stored. | Rephrase the question, for example by naming the exact value to look up. Do not treat the data as absent. |
274
308
  | `null` | The schema provably cannot represent the concept. An answer, not a variant of the empty one. | Try a better-matching instance; this memory cannot hold it. |
275
309
  | *(throws)* | Every sub-query's SQL failed, so nothing was answered. | Catch `XmemoryAPIError` with `status` 422 and `code` `"INVALID_INPUT"`. It is the same answer for the same input, so do not retry it. |
276
310
 
@@ -278,6 +312,8 @@ read gave:
278
312
  const result = await inst.read("Which invoices are overdue?", { readMode: "raw-tables" });
279
313
  if (result.reader_result === null) {
280
314
  // Not a concept this memory holds — try another instance.
315
+ } else if (result.notice !== null) {
316
+ // Not answered as asked — rephrase; the data may well be stored.
281
317
  } else {
282
318
  const { rows } = result.reader_result as { columns: string[]; rows: unknown[][] };
283
319
  // rows.length === 0 means the data is absent, not that the read failed.
@@ -289,7 +325,7 @@ if (result.reader_result === null) {
289
325
  When a query bundles several independent questions, the server may decompose it
290
326
  into sub-queries and answer each one. `reader_result` is still the combined
291
327
  answer (for `"single-answer"` mode, a labelled multi-part string); `reader_results`
292
- holds one `TaggedReaderResult` (`{ sub_query, reader_result, error }`) per
328
+ holds one `TaggedReaderResult` (`{ sub_query, reader_result, error, notice }`) per
293
329
  sub-query so you can read each answer unambiguously — a single-intent query
294
330
  decomposes to one entry. `reader_results` is always an array: a server without
295
331
  question decomposition omits the field on the wire and the client normalizes it
@@ -302,14 +338,16 @@ for (const part of result.reader_results) {
302
338
  }
303
339
  ```
304
340
 
305
- Each part's `reader_result` uses the same four answers as above, with one more
341
+ Each part's `reader_result` uses the same five answers as above, with one more
306
342
  case: a sub-query whose SQL failed carries the empty result *and* a user-safe
307
343
  `error`, while the others are answered regardless. Its bytes then equal those
308
344
  of a sub-query that matched nothing, so read `error` before `reader_result`, as
309
345
  the loop above does. The combined `reader_result` folds the parts: rows if any
310
- sub-query answered; else the empty result if any executed and matched nothing;
311
- else `null`. In the tabular modes a read where *every* sub-query failed throws
312
- the 422 above instead.
346
+ sub-query answered; else the empty result if any executed and matched nothing,
347
+ or could not be answered as asked; else `null`. The top-level `notice` is set
348
+ when any part could not be answered as asked, even if another part answered,
349
+ so check it before trusting an empty part. In the tabular modes a read where
350
+ *every* sub-query failed throws the 422 above instead.
313
351
 
314
352
  #### Scoped reads
315
353
 
@@ -472,6 +510,16 @@ record's primary key as `field='value'` **only when the scope itself named that
472
510
  record**; otherwise it is empty, meaning "some other record of this type". The
473
511
  list is omitted when nothing was skipped, so treat `undefined` and `[]` alike.
474
512
 
513
+ The list holds at most 100 entries. Past that, entries are kept as they are
514
+ while there is room, those that name a record first, and the rest arrive folded:
515
+ one entry per `operation` and type, marked `folded: true`, with an empty
516
+ `identity`, no `fields` and the summed `count`. When even those would be more
517
+ than 100, none is kept as it was, and the last folded entries are folded once
518
+ more, into one entry per `operation` whose `object_type_name` is empty too.
519
+ Unnamed entries are folded before named ones, but a record the scope named can
520
+ still end up inside a folded entry. Summing `count` per `operation` still gives
521
+ the true totals, and an entry without `folded` means what it always did.
522
+
475
523
  Because a dropped write succeeds, this is also the mode that makes "create or
476
524
  update exactly this record" expressible: under `"drop"` a scoped record need not
477
525
  be stored yet, and the write creates it if it is missing. Under `"reject"` every
@@ -89,6 +89,11 @@ export declare class InstanceHandle {
89
89
  * response carries the previous value of every field the write changed,
90
90
  * resolving a scope answers whether each named object is stored, and a
91
91
  * drop-mode report says what the skipped changes would have written.
92
+ *
93
+ * Every write joins the instance's write queue, text and mutations alike, and
94
+ * {@link writeAsync} writes too. Queued writes are processed in parallel but
95
+ * applied one at a time, in the order they were queued; this call resolves
96
+ * once its own write is applied, after every write queued before it.
92
97
  */
93
98
  write(text: string, options?: WriteOptions): Promise<WriteResult>;
94
99
  write(mutations: readonly WriteMutation[], options?: RequestOptions): Promise<WriteResult>;
@@ -98,6 +103,12 @@ export declare class InstanceHandle {
98
103
  * the same `scope`. Under the default `"reject"` mode a scope violation is
99
104
  * reported by {@link writeStatus} as a failed write; under `"drop"` the write
100
105
  * completes, and what it skipped rides the completed status as `changes`.
106
+ *
107
+ * Resolves once the write is queued. Writes to an instance — sync and async,
108
+ * text and mutations — share one queue: they are processed in parallel but
109
+ * applied one at a time, in the order they were queued. The order is the
110
+ * order the server receives them, so await this call before sending a write
111
+ * that must apply after it.
101
112
  */
102
113
  writeAsync(text: string, options?: WriteOptions): Promise<AsyncWriteResult>;
103
114
  writeAsync(mutations: readonly WriteMutation[], options?: RequestOptions): Promise<AsyncWriteResult>;
@@ -264,15 +264,23 @@ class InstanceHandle {
264
264
  const readerResults = own(result, "reader_results");
265
265
  const traceId = own(result, "trace_id");
266
266
  const relatedTypes = own(result, "related_types");
267
+ const notice = own(result, "notice");
267
268
  // `reader_result` is required on the wire and `null` is one of its answers (a
268
269
  // refusal, in the tabular modes), so the coalescing only stands in for a field
269
270
  // the server omitted; a `null` the server sent arrives as the same `null`.
270
271
  return withConsoleUrl({
271
272
  ...result,
272
273
  reader_result: own(result, "reader_result") ?? null,
273
- reader_results: Array.isArray(readerResults) ? readerResults : [],
274
+ // A part's `notice` is normalized the same way: the server sends it only on the part it applies to.
275
+ reader_results: Array.isArray(readerResults)
276
+ ? readerResults.map((part) => {
277
+ const partNotice = own(part, "notice");
278
+ return { ...part, notice: typeof partNotice === "string" ? partNotice : null };
279
+ })
280
+ : [],
274
281
  related_types: relatedTypes != null && typeof relatedTypes === "object" ? relatedTypes : null,
275
282
  trace_id: typeof traceId === "string" ? traceId : null,
283
+ notice: typeof notice === "string" ? notice : null,
276
284
  });
277
285
  }
278
286
  async write(input, options) {
@@ -206,7 +206,7 @@ export interface InstanceSchemaInfo {
206
206
  * {@link ReadResult.reader_results} when the server decomposed a composite query
207
207
  * into independent sub-queries.
208
208
  *
209
- * `reader_result` gives one of the four answers described on
209
+ * `reader_result` gives one of the five answers described on
210
210
  * {@link ReadResult.reader_result}, with one more case: a sub-query whose SQL
211
211
  * failed carries the empty result *and* `error`, while the other sub-queries
212
212
  * are answered regardless. Its bytes then equal those of a sub-query that
@@ -222,6 +222,12 @@ export interface TaggedReaderResult {
222
222
  * with `status` 422 and `code` `"INVALID_INPUT"`.
223
223
  */
224
224
  readonly error: string | null;
225
+ /**
226
+ * Set when this sub-query could not be answered as asked (see
227
+ * {@link ReadResult.notice}); its empty `reader_result` is then not a
228
+ * no-match. `null` otherwise.
229
+ */
230
+ readonly notice: string | null;
225
231
  }
226
232
  /**
227
233
  * One relation edge from the entry's own type to a neighbouring type;
@@ -339,13 +345,18 @@ export interface ReadResult {
339
345
  /**
340
346
  * The answer, shaped by `readMode`. In `"single-answer"` mode it is always the
341
347
  * prose answer, never `null`. In `"raw-tables"` / `"xresponse"` mode its value
342
- * says which of four answers the read gave:
348
+ * says which of five answers the read gave:
343
349
  *
344
350
  * - rows — answered;
345
351
  * - exactly `{ columns: [], rows: [] }` (`"raw-tables"`) or
346
- * `{ objects: [], relations: [] }` (`"xresponse"`) — the query executed and
347
- * matched nothing: every table and column it used exists, so the data is
348
- * absent;
352
+ * `{ objects: [], relations: [] }` (`"xresponse"`) with `notice` null —
353
+ * the query executed and matched nothing: every table and column it used
354
+ * exists, so the data is absent;
355
+ * - the same empty value with `notice` set — the server could not run a query
356
+ * that answers the question as asked, so the empty value says nothing about
357
+ * what is stored. Rephrase the question (for example, name the exact value
358
+ * to look up) rather than treating the data as absent. In
359
+ * `"single-answer"` mode the answer is then the notice text itself;
349
360
  * - `null` — the schema provably cannot represent the concept. An answer in
350
361
  * its own right, not a variant of the empty one: this memory cannot hold
351
362
  * it, so a better-matching instance is worth trying;
@@ -355,8 +366,8 @@ export interface ReadResult {
355
366
  *
356
367
  * For a composite query this is the combined answer, folded from the parts:
357
368
  * rows if any sub-query answered; else the empty result if any executed and
358
- * matched nothing; else `null`. `reader_results` carries each part's own
359
- * answer.
369
+ * matched nothing, or could not be answered as asked; else `null`.
370
+ * `reader_results` carries each part's own answer.
360
371
  */
361
372
  readonly reader_result: unknown;
362
373
  /**
@@ -376,10 +387,26 @@ export interface ReadResult {
376
387
  * a requested read that executed nothing arrives with `touched: []` instead.
377
388
  */
378
389
  readonly related_types: RelatedTypes | null;
390
+ /**
391
+ * Set when the read, or one of its sub-queries, could not be answered as
392
+ * asked: the empty result beside it does not mean nothing is stored, so
393
+ * rephrase the question rather than treating the data as absent. On a
394
+ * composite read it is set when any part was affected, even if another part
395
+ * answered, and that part's entry in `reader_results` carries it too. `null`
396
+ * otherwise: the server omits the field on every other read, and a server
397
+ * that predates it never sends it; the client normalizes both to `null`.
398
+ */
399
+ readonly notice: string | null;
379
400
  }
380
401
  /**
381
402
  * One bundle of changes a `"drop"`-mode scoped write left out instead of
382
- * applying: one operation on one type, standing for `count` records.
403
+ * applying: one operation on one type (any type, for an entry folded per
404
+ * operation), standing for `count` records.
405
+ *
406
+ * The server lists at most 100 entries. Past that, it folds entries into ones
407
+ * marked {@link SkippedOutOfScope.folded}, so the counts per operation still add
408
+ * up (and per type too, unless the entries were folded a second time, per
409
+ * operation).
383
410
  */
384
411
  export interface SkippedOutOfScope {
385
412
  /**
@@ -392,19 +419,41 @@ export interface SkippedOutOfScope {
392
419
  * thing — something was skipped — so report it rather than dropping the entry.
393
420
  */
394
421
  readonly operation: "create" | "update" | "delete" | "merge" | "link" | "unlink" | (string & {});
395
- /** The object type, or the relation type for `"link"` / `"unlink"`. */
422
+ /**
423
+ * The object type, or the relation type for `"link"` / `"unlink"`. Empty on
424
+ * an entry folded per operation (see {@link SkippedOutOfScope.folded}).
425
+ */
396
426
  readonly object_type_name: string;
397
427
  /**
398
428
  * The skipped record's primary key, rendered `field='value'` — and **empty
399
429
  * unless the scope itself named that record**. The server identifies a record
400
430
  * here only when the caller already knew of it, so an empty string reads as
401
- * "some other record of this type", not as "a record with no key".
431
+ * "some other record of this type", not as "a record with no key". Always
432
+ * empty on a folded entry.
402
433
  */
403
434
  readonly identity: string;
404
- /** The field names the skipped changes would have written. */
435
+ /** The field names the skipped changes would have written; empty on a folded entry. */
405
436
  readonly fields: readonly string[];
406
- /** How many records this entry stands for. */
437
+ /** How many records this entry stands for; on a folded entry, the summed `count` of the entries folded into it. */
407
438
  readonly count: number;
439
+ /**
440
+ * `true` on an entry that stands for one or more left-out entries folded
441
+ * together; absent on every other entry, so an entry without it keeps the
442
+ * meaning above.
443
+ *
444
+ * The server lists at most 100 entries. Past that, it keeps entries as they
445
+ * are while there is room, those that name a record first, and folds the rest
446
+ * into one entry per `operation` and `object_type_name`, with an empty
447
+ * `identity`, no `fields` and the summed `count`. Unnamed entries are folded
448
+ * before named ones, but a record the scope named can still end up inside a
449
+ * folded entry. When even the folded entries would be more than 100, none is
450
+ * kept as it was, and the last folded entries are folded once more, into one
451
+ * entry per `operation` whose `object_type_name` is empty too. Either way,
452
+ * summing `count` per operation gives the true totals.
453
+ *
454
+ * Optional: a server that predates the cap never sends it, and never folds.
455
+ */
456
+ readonly folded?: boolean;
408
457
  }
409
458
  /**
410
459
  * What a write did, grouped into `created` / `updated` / `deleted`, plus what a
@@ -424,6 +473,9 @@ export interface WriteChanges {
424
473
  * Omitted by the server when nothing was skipped — which is every write that
425
474
  * did not ask for `"drop"` — so `undefined` and `[]` both mean "nothing left
426
475
  * out". Branch on whether there are entries, not on whether the key is there.
476
+ *
477
+ * At most 100 entries; past that, the rest arrive folded (see
478
+ * {@link SkippedOutOfScope.folded}).
427
479
  */
428
480
  readonly skipped_out_of_scope?: readonly SkippedOutOfScope[];
429
481
  }
@@ -1,2 +1,2 @@
1
1
  /** Package version. Kept in sync with `package.json` — a test asserts they match. */
2
- export declare const VERSION = "3.15.0";
2
+ export declare const VERSION = "3.17.0";
@@ -2,4 +2,4 @@
2
2
  Object.defineProperty(exports, "__esModule", { value: true });
3
3
  exports.VERSION = void 0;
4
4
  /** Package version. Kept in sync with `package.json` — a test asserts they match. */
5
- exports.VERSION = "3.15.0";
5
+ exports.VERSION = "3.17.0";
@@ -89,6 +89,11 @@ export declare class InstanceHandle {
89
89
  * response carries the previous value of every field the write changed,
90
90
  * resolving a scope answers whether each named object is stored, and a
91
91
  * drop-mode report says what the skipped changes would have written.
92
+ *
93
+ * Every write joins the instance's write queue, text and mutations alike, and
94
+ * {@link writeAsync} writes too. Queued writes are processed in parallel but
95
+ * applied one at a time, in the order they were queued; this call resolves
96
+ * once its own write is applied, after every write queued before it.
92
97
  */
93
98
  write(text: string, options?: WriteOptions): Promise<WriteResult>;
94
99
  write(mutations: readonly WriteMutation[], options?: RequestOptions): Promise<WriteResult>;
@@ -98,6 +103,12 @@ export declare class InstanceHandle {
98
103
  * the same `scope`. Under the default `"reject"` mode a scope violation is
99
104
  * reported by {@link writeStatus} as a failed write; under `"drop"` the write
100
105
  * completes, and what it skipped rides the completed status as `changes`.
106
+ *
107
+ * Resolves once the write is queued. Writes to an instance — sync and async,
108
+ * text and mutations — share one queue: they are processed in parallel but
109
+ * applied one at a time, in the order they were queued. The order is the
110
+ * order the server receives them, so await this call before sending a write
111
+ * that must apply after it.
101
112
  */
102
113
  writeAsync(text: string, options?: WriteOptions): Promise<AsyncWriteResult>;
103
114
  writeAsync(mutations: readonly WriteMutation[], options?: RequestOptions): Promise<AsyncWriteResult>;
@@ -260,15 +260,23 @@ export class InstanceHandle {
260
260
  const readerResults = own(result, "reader_results");
261
261
  const traceId = own(result, "trace_id");
262
262
  const relatedTypes = own(result, "related_types");
263
+ const notice = own(result, "notice");
263
264
  // `reader_result` is required on the wire and `null` is one of its answers (a
264
265
  // refusal, in the tabular modes), so the coalescing only stands in for a field
265
266
  // the server omitted; a `null` the server sent arrives as the same `null`.
266
267
  return withConsoleUrl({
267
268
  ...result,
268
269
  reader_result: own(result, "reader_result") ?? null,
269
- reader_results: Array.isArray(readerResults) ? readerResults : [],
270
+ // A part's `notice` is normalized the same way: the server sends it only on the part it applies to.
271
+ reader_results: Array.isArray(readerResults)
272
+ ? readerResults.map((part) => {
273
+ const partNotice = own(part, "notice");
274
+ return { ...part, notice: typeof partNotice === "string" ? partNotice : null };
275
+ })
276
+ : [],
270
277
  related_types: relatedTypes != null && typeof relatedTypes === "object" ? relatedTypes : null,
271
278
  trace_id: typeof traceId === "string" ? traceId : null,
279
+ notice: typeof notice === "string" ? notice : null,
272
280
  });
273
281
  }
274
282
  async write(input, options) {
@@ -206,7 +206,7 @@ export interface InstanceSchemaInfo {
206
206
  * {@link ReadResult.reader_results} when the server decomposed a composite query
207
207
  * into independent sub-queries.
208
208
  *
209
- * `reader_result` gives one of the four answers described on
209
+ * `reader_result` gives one of the five answers described on
210
210
  * {@link ReadResult.reader_result}, with one more case: a sub-query whose SQL
211
211
  * failed carries the empty result *and* `error`, while the other sub-queries
212
212
  * are answered regardless. Its bytes then equal those of a sub-query that
@@ -222,6 +222,12 @@ export interface TaggedReaderResult {
222
222
  * with `status` 422 and `code` `"INVALID_INPUT"`.
223
223
  */
224
224
  readonly error: string | null;
225
+ /**
226
+ * Set when this sub-query could not be answered as asked (see
227
+ * {@link ReadResult.notice}); its empty `reader_result` is then not a
228
+ * no-match. `null` otherwise.
229
+ */
230
+ readonly notice: string | null;
225
231
  }
226
232
  /**
227
233
  * One relation edge from the entry's own type to a neighbouring type;
@@ -339,13 +345,18 @@ export interface ReadResult {
339
345
  /**
340
346
  * The answer, shaped by `readMode`. In `"single-answer"` mode it is always the
341
347
  * prose answer, never `null`. In `"raw-tables"` / `"xresponse"` mode its value
342
- * says which of four answers the read gave:
348
+ * says which of five answers the read gave:
343
349
  *
344
350
  * - rows — answered;
345
351
  * - exactly `{ columns: [], rows: [] }` (`"raw-tables"`) or
346
- * `{ objects: [], relations: [] }` (`"xresponse"`) — the query executed and
347
- * matched nothing: every table and column it used exists, so the data is
348
- * absent;
352
+ * `{ objects: [], relations: [] }` (`"xresponse"`) with `notice` null —
353
+ * the query executed and matched nothing: every table and column it used
354
+ * exists, so the data is absent;
355
+ * - the same empty value with `notice` set — the server could not run a query
356
+ * that answers the question as asked, so the empty value says nothing about
357
+ * what is stored. Rephrase the question (for example, name the exact value
358
+ * to look up) rather than treating the data as absent. In
359
+ * `"single-answer"` mode the answer is then the notice text itself;
349
360
  * - `null` — the schema provably cannot represent the concept. An answer in
350
361
  * its own right, not a variant of the empty one: this memory cannot hold
351
362
  * it, so a better-matching instance is worth trying;
@@ -355,8 +366,8 @@ export interface ReadResult {
355
366
  *
356
367
  * For a composite query this is the combined answer, folded from the parts:
357
368
  * rows if any sub-query answered; else the empty result if any executed and
358
- * matched nothing; else `null`. `reader_results` carries each part's own
359
- * answer.
369
+ * matched nothing, or could not be answered as asked; else `null`.
370
+ * `reader_results` carries each part's own answer.
360
371
  */
361
372
  readonly reader_result: unknown;
362
373
  /**
@@ -376,10 +387,26 @@ export interface ReadResult {
376
387
  * a requested read that executed nothing arrives with `touched: []` instead.
377
388
  */
378
389
  readonly related_types: RelatedTypes | null;
390
+ /**
391
+ * Set when the read, or one of its sub-queries, could not be answered as
392
+ * asked: the empty result beside it does not mean nothing is stored, so
393
+ * rephrase the question rather than treating the data as absent. On a
394
+ * composite read it is set when any part was affected, even if another part
395
+ * answered, and that part's entry in `reader_results` carries it too. `null`
396
+ * otherwise: the server omits the field on every other read, and a server
397
+ * that predates it never sends it; the client normalizes both to `null`.
398
+ */
399
+ readonly notice: string | null;
379
400
  }
380
401
  /**
381
402
  * One bundle of changes a `"drop"`-mode scoped write left out instead of
382
- * applying: one operation on one type, standing for `count` records.
403
+ * applying: one operation on one type (any type, for an entry folded per
404
+ * operation), standing for `count` records.
405
+ *
406
+ * The server lists at most 100 entries. Past that, it folds entries into ones
407
+ * marked {@link SkippedOutOfScope.folded}, so the counts per operation still add
408
+ * up (and per type too, unless the entries were folded a second time, per
409
+ * operation).
383
410
  */
384
411
  export interface SkippedOutOfScope {
385
412
  /**
@@ -392,19 +419,41 @@ export interface SkippedOutOfScope {
392
419
  * thing — something was skipped — so report it rather than dropping the entry.
393
420
  */
394
421
  readonly operation: "create" | "update" | "delete" | "merge" | "link" | "unlink" | (string & {});
395
- /** The object type, or the relation type for `"link"` / `"unlink"`. */
422
+ /**
423
+ * The object type, or the relation type for `"link"` / `"unlink"`. Empty on
424
+ * an entry folded per operation (see {@link SkippedOutOfScope.folded}).
425
+ */
396
426
  readonly object_type_name: string;
397
427
  /**
398
428
  * The skipped record's primary key, rendered `field='value'` — and **empty
399
429
  * unless the scope itself named that record**. The server identifies a record
400
430
  * here only when the caller already knew of it, so an empty string reads as
401
- * "some other record of this type", not as "a record with no key".
431
+ * "some other record of this type", not as "a record with no key". Always
432
+ * empty on a folded entry.
402
433
  */
403
434
  readonly identity: string;
404
- /** The field names the skipped changes would have written. */
435
+ /** The field names the skipped changes would have written; empty on a folded entry. */
405
436
  readonly fields: readonly string[];
406
- /** How many records this entry stands for. */
437
+ /** How many records this entry stands for; on a folded entry, the summed `count` of the entries folded into it. */
407
438
  readonly count: number;
439
+ /**
440
+ * `true` on an entry that stands for one or more left-out entries folded
441
+ * together; absent on every other entry, so an entry without it keeps the
442
+ * meaning above.
443
+ *
444
+ * The server lists at most 100 entries. Past that, it keeps entries as they
445
+ * are while there is room, those that name a record first, and folds the rest
446
+ * into one entry per `operation` and `object_type_name`, with an empty
447
+ * `identity`, no `fields` and the summed `count`. Unnamed entries are folded
448
+ * before named ones, but a record the scope named can still end up inside a
449
+ * folded entry. When even the folded entries would be more than 100, none is
450
+ * kept as it was, and the last folded entries are folded once more, into one
451
+ * entry per `operation` whose `object_type_name` is empty too. Either way,
452
+ * summing `count` per operation gives the true totals.
453
+ *
454
+ * Optional: a server that predates the cap never sends it, and never folds.
455
+ */
456
+ readonly folded?: boolean;
408
457
  }
409
458
  /**
410
459
  * What a write did, grouped into `created` / `updated` / `deleted`, plus what a
@@ -424,6 +473,9 @@ export interface WriteChanges {
424
473
  * Omitted by the server when nothing was skipped — which is every write that
425
474
  * did not ask for `"drop"` — so `undefined` and `[]` both mean "nothing left
426
475
  * out". Branch on whether there are entries, not on whether the key is there.
476
+ *
477
+ * At most 100 entries; past that, the rest arrive folded (see
478
+ * {@link SkippedOutOfScope.folded}).
427
479
  */
428
480
  readonly skipped_out_of_scope?: readonly SkippedOutOfScope[];
429
481
  }
@@ -1,2 +1,2 @@
1
1
  /** Package version. Kept in sync with `package.json` — a test asserts they match. */
2
- export declare const VERSION = "3.15.0";
2
+ export declare const VERSION = "3.17.0";
@@ -1,2 +1,2 @@
1
1
  /** Package version. Kept in sync with `package.json` — a test asserts they match. */
2
- export const VERSION = "3.15.0";
2
+ export const VERSION = "3.17.0";
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "xmemory",
3
- "version": "3.15.0",
3
+ "version": "3.17.0",
4
4
  "description": "xmemory",
5
5
  "keywords": [
6
6
  "xmemory"