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 +16 -0
- package/dist/cjs/instance.js +41 -0
- package/dist/cjs/types.d.ts +19 -4
- package/dist/cjs/version.d.ts +1 -1
- package/dist/cjs/version.js +1 -1
- package/dist/esm/instance.js +41 -0
- package/dist/esm/types.d.ts +19 -4
- package/dist/esm/version.d.ts +1 -1
- package/dist/esm/version.js +1 -1
- package/package.json +1 -1
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`
|
package/dist/cjs/instance.js
CHANGED
|
@@ -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 };
|
package/dist/cjs/types.d.ts
CHANGED
|
@@ -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)
|
|
641
|
-
*
|
|
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 {
|
package/dist/cjs/version.d.ts
CHANGED
|
@@ -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.
|
|
2
|
+
export declare const VERSION = "3.24.0";
|
package/dist/cjs/version.js
CHANGED
package/dist/esm/instance.js
CHANGED
|
@@ -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 };
|
package/dist/esm/types.d.ts
CHANGED
|
@@ -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)
|
|
641
|
-
*
|
|
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 {
|
package/dist/esm/version.d.ts
CHANGED
|
@@ -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.
|
|
2
|
+
export declare const VERSION = "3.24.0";
|
package/dist/esm/version.js
CHANGED
|
@@ -1,2 +1,2 @@
|
|
|
1
1
|
/** Package version. Kept in sync with `package.json` — a test asserts they match. */
|
|
2
|
-
export const VERSION = "3.
|
|
2
|
+
export const VERSION = "3.24.0";
|