xmemory 3.23.0 → 3.24.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
@@ -240,6 +240,22 @@ await inst.write([
240
240
  ]);
241
241
  ```
242
242
 
243
+ A type declared with `primary_key: []` has no key. A `create` takes an empty
244
+ `key` and at least one non-null value. An `update` or `delete` names the record
245
+ by `match` with an empty `key`: field values the record holds, compared as keys
246
+ are. `match` must single out one record unless `allow_bulk: true` acts on every
247
+ record it matches, up to 100 records per request. A relation endpoint of such a
248
+ type takes `match` in place of `key` too. When it builds the request, the client
249
+ refuses a record named by both a `key` and a `match` that hold values (an update,
250
+ a delete or a relation endpoint), and `allow_bulk` without `match`:
251
+
252
+ ```typescript
253
+ await inst.write([
254
+ { object_mutation: { object_type: "item", update: { key: {}, match: { label: "A" }, values: { status: "done" } } } },
255
+ { object_mutation: { object_type: "item", delete: { key: {}, match: { status: "void" }, allow_bulk: true } } },
256
+ ]);
257
+ ```
258
+
243
259
  Options for the mutations form: `{ timeoutMs? }` (extraction options don't apply).
244
260
 
245
261
  ### `inst.writeAsync(text | mutations, options?)` → `AsyncWriteResult`
@@ -13,6 +13,46 @@ const types_js_1 = require("./types.js");
13
13
  function serializeScopeObjects(objects) {
14
14
  return objects.map((o) => ({ type: o.type, key: { key: o.key } }));
15
15
  }
16
+ /** Whether a mapping holds a value the request will carry: JSON leaves out a
17
+ * property whose value is `undefined`, so such a property does not count. */
18
+ function holdsAValue(mapping) {
19
+ return Object.values(mapping ?? {}).some((value) => value !== undefined);
20
+ }
21
+ /** Throw when a record is named by `key` and by `match` at once (an object update
22
+ * or delete, or a relation endpoint), or an object update or delete sets
23
+ * `allow_bulk` without `match`: the server refuses both, and the types leave
24
+ * `key` required so that code built before `match` compiles as before. Each
25
+ * mutation must be an object. */
26
+ function checkTargets(mutations) {
27
+ mutations.forEach((mutation, index) => {
28
+ if (mutation == null || typeof mutation !== "object") {
29
+ throw new Error(`mutation ${index}: each mutation must be an object`);
30
+ }
31
+ if ("relation_mutation" in mutation && mutation.relation_mutation != null) {
32
+ const body = mutation.relation_mutation;
33
+ const endpoints = (body.create ?? body.update ?? body.delete)?.endpoints ?? [];
34
+ endpoints.forEach((endpoint, at) => {
35
+ if (holdsAValue(endpoint.key) && holdsAValue(endpoint.match)) {
36
+ throw new Error(`mutation ${index}, endpoint ${at}: name the record by 'key' or by 'match', not both`);
37
+ }
38
+ });
39
+ return;
40
+ }
41
+ if (!("object_mutation" in mutation) || mutation.object_mutation == null)
42
+ return;
43
+ const body = mutation.object_mutation;
44
+ const target = body.update ?? body.delete;
45
+ if (target == null)
46
+ return;
47
+ const hasMatch = holdsAValue(target.match);
48
+ if (holdsAValue(target.key) && hasMatch) {
49
+ throw new Error(`mutation ${index}: name the record by 'key' or by 'match', not both`);
50
+ }
51
+ if (target.allow_bulk === true && !hasMatch) {
52
+ throw new Error(`mutation ${index}: 'allow_bulk' applies only with 'match'`);
53
+ }
54
+ });
55
+ }
16
56
  /** Build the shared `/write` + `/write_async` request body for either input mode. */
17
57
  function buildWriteBody(input, options) {
18
58
  if (typeof input !== "string") {
@@ -25,6 +65,7 @@ function buildWriteBody(input, options) {
25
65
  if (options?.scope != null) {
26
66
  throw new Error("'scope' and structured mutations are mutually exclusive");
27
67
  }
68
+ checkTargets(input);
28
69
  // Structured path: no text, no extraction options — mutations go straight
29
70
  // to the wire.
30
71
  return { structured_mutations: input };
@@ -630,22 +630,37 @@ export interface RelationEndpoint {
630
630
  object_name: string;
631
631
  /** Endpoint identity: user primary-key fields (field -> value). */
632
632
  key?: Record<string, unknown>;
633
+ /** For an endpoint of a type without a primary key, in place of `key`: field
634
+ * values the record holds, which must single out one record. The client refuses
635
+ * an endpoint whose `key` and `match` both hold values. */
636
+ match?: Record<string, unknown>;
633
637
  }
634
638
  /** Create an object: `key` holds the user primary-key fields, `values` the
635
- * remaining field values. */
639
+ * remaining field values. For a type without a primary key, `key` is empty,
640
+ * `values` holds at least one non-null value, and each create adds a new record. */
636
641
  export interface ObjectCreatePayload {
637
642
  key?: Record<string, unknown>;
638
643
  values?: Record<string, unknown>;
639
644
  }
640
- /** Update an object identified by `key` (its primary-key fields). A `null` value
641
- * in `values` clears that field. */
645
+ /** Update an object identified by `key` (its primary-key fields), or, for a type
646
+ * without a primary key, by `match` with an empty `key`: field values the record
647
+ * holds, compared as keys are. `match` must single out one record unless
648
+ * `allow_bulk: true` acts on every record it matches, up to 100 records per
649
+ * request. A `null` value in `values` clears that field. The client refuses a
650
+ * non-empty `key` with `match`, and `allow_bulk` without `match`, when it builds
651
+ * the request. */
642
652
  export interface ObjectUpdatePayload {
643
653
  key: Record<string, unknown>;
654
+ match?: Record<string, unknown>;
655
+ allow_bulk?: boolean;
644
656
  values: Record<string, unknown>;
645
657
  }
646
- /** Delete the object identified by `key` (its primary-key fields). */
658
+ /** Delete the object identified by `key` (its primary-key fields), or, for a type
659
+ * without a primary key, by `match` with an empty `key`, as for an update. */
647
660
  export interface ObjectDeletePayload {
648
661
  key: Record<string, unknown>;
662
+ match?: Record<string, unknown>;
663
+ allow_bulk?: boolean;
649
664
  }
650
665
  /** Create a relation between the `endpoints`, with optional own-field `values`. */
651
666
  export interface RelationCreatePayload {
@@ -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.23.0";
2
+ export declare const VERSION = "3.24.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.23.0";
5
+ exports.VERSION = "3.24.0";
@@ -10,6 +10,46 @@ import { SetupFormat } from "./types.js";
10
10
  function serializeScopeObjects(objects) {
11
11
  return objects.map((o) => ({ type: o.type, key: { key: o.key } }));
12
12
  }
13
+ /** Whether a mapping holds a value the request will carry: JSON leaves out a
14
+ * property whose value is `undefined`, so such a property does not count. */
15
+ function holdsAValue(mapping) {
16
+ return Object.values(mapping ?? {}).some((value) => value !== undefined);
17
+ }
18
+ /** Throw when a record is named by `key` and by `match` at once (an object update
19
+ * or delete, or a relation endpoint), or an object update or delete sets
20
+ * `allow_bulk` without `match`: the server refuses both, and the types leave
21
+ * `key` required so that code built before `match` compiles as before. Each
22
+ * mutation must be an object. */
23
+ function checkTargets(mutations) {
24
+ mutations.forEach((mutation, index) => {
25
+ if (mutation == null || typeof mutation !== "object") {
26
+ throw new Error(`mutation ${index}: each mutation must be an object`);
27
+ }
28
+ if ("relation_mutation" in mutation && mutation.relation_mutation != null) {
29
+ const body = mutation.relation_mutation;
30
+ const endpoints = (body.create ?? body.update ?? body.delete)?.endpoints ?? [];
31
+ endpoints.forEach((endpoint, at) => {
32
+ if (holdsAValue(endpoint.key) && holdsAValue(endpoint.match)) {
33
+ throw new Error(`mutation ${index}, endpoint ${at}: name the record by 'key' or by 'match', not both`);
34
+ }
35
+ });
36
+ return;
37
+ }
38
+ if (!("object_mutation" in mutation) || mutation.object_mutation == null)
39
+ return;
40
+ const body = mutation.object_mutation;
41
+ const target = body.update ?? body.delete;
42
+ if (target == null)
43
+ return;
44
+ const hasMatch = holdsAValue(target.match);
45
+ if (holdsAValue(target.key) && hasMatch) {
46
+ throw new Error(`mutation ${index}: name the record by 'key' or by 'match', not both`);
47
+ }
48
+ if (target.allow_bulk === true && !hasMatch) {
49
+ throw new Error(`mutation ${index}: 'allow_bulk' applies only with 'match'`);
50
+ }
51
+ });
52
+ }
13
53
  /** Build the shared `/write` + `/write_async` request body for either input mode. */
14
54
  function buildWriteBody(input, options) {
15
55
  if (typeof input !== "string") {
@@ -22,6 +62,7 @@ function buildWriteBody(input, options) {
22
62
  if (options?.scope != null) {
23
63
  throw new Error("'scope' and structured mutations are mutually exclusive");
24
64
  }
65
+ checkTargets(input);
25
66
  // Structured path: no text, no extraction options — mutations go straight
26
67
  // to the wire.
27
68
  return { structured_mutations: input };
@@ -630,22 +630,37 @@ export interface RelationEndpoint {
630
630
  object_name: string;
631
631
  /** Endpoint identity: user primary-key fields (field -> value). */
632
632
  key?: Record<string, unknown>;
633
+ /** For an endpoint of a type without a primary key, in place of `key`: field
634
+ * values the record holds, which must single out one record. The client refuses
635
+ * an endpoint whose `key` and `match` both hold values. */
636
+ match?: Record<string, unknown>;
633
637
  }
634
638
  /** Create an object: `key` holds the user primary-key fields, `values` the
635
- * remaining field values. */
639
+ * remaining field values. For a type without a primary key, `key` is empty,
640
+ * `values` holds at least one non-null value, and each create adds a new record. */
636
641
  export interface ObjectCreatePayload {
637
642
  key?: Record<string, unknown>;
638
643
  values?: Record<string, unknown>;
639
644
  }
640
- /** Update an object identified by `key` (its primary-key fields). A `null` value
641
- * in `values` clears that field. */
645
+ /** Update an object identified by `key` (its primary-key fields), or, for a type
646
+ * without a primary key, by `match` with an empty `key`: field values the record
647
+ * holds, compared as keys are. `match` must single out one record unless
648
+ * `allow_bulk: true` acts on every record it matches, up to 100 records per
649
+ * request. A `null` value in `values` clears that field. The client refuses a
650
+ * non-empty `key` with `match`, and `allow_bulk` without `match`, when it builds
651
+ * the request. */
642
652
  export interface ObjectUpdatePayload {
643
653
  key: Record<string, unknown>;
654
+ match?: Record<string, unknown>;
655
+ allow_bulk?: boolean;
644
656
  values: Record<string, unknown>;
645
657
  }
646
- /** Delete the object identified by `key` (its primary-key fields). */
658
+ /** Delete the object identified by `key` (its primary-key fields), or, for a type
659
+ * without a primary key, by `match` with an empty `key`, as for an update. */
647
660
  export interface ObjectDeletePayload {
648
661
  key: Record<string, unknown>;
662
+ match?: Record<string, unknown>;
663
+ allow_bulk?: boolean;
649
664
  }
650
665
  /** Create a relation between the `endpoints`, with optional own-field `values`. */
651
666
  export interface RelationCreatePayload {
@@ -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.23.0";
2
+ export declare const VERSION = "3.24.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.23.0";
2
+ export const VERSION = "3.24.0";
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "xmemory",
3
- "version": "3.23.0",
3
+ "version": "3.24.0",
4
4
  "description": "xmemory",
5
5
  "keywords": [
6
6
  "xmemory"