xmemory 3.21.2 → 3.22.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 +66 -0
- package/dist/cjs/types.d.ts +17 -12
- package/dist/cjs/version.d.ts +1 -1
- package/dist/cjs/version.js +1 -1
- package/dist/esm/types.d.ts +17 -12
- package/dist/esm/version.d.ts +1 -1
- package/dist/esm/version.js +1 -1
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -219,6 +219,27 @@ const result = await inst.write([
|
|
|
219
219
|
]);
|
|
220
220
|
```
|
|
221
221
|
|
|
222
|
+
Continuing the example above, where Bob was created: a relation mutation sets the
|
|
223
|
+
relation's own fields (see [Fields on a relation](#fields-on-a-relation)) in
|
|
224
|
+
`values`. An `update` names one
|
|
225
|
+
link by every endpoint, in a later write than the one that created it: a request
|
|
226
|
+
that creates a link cannot also change it. Here `person` and `company` declare
|
|
227
|
+
`primary_key: [name]`, which addressing them by `key` needs:
|
|
228
|
+
|
|
229
|
+
```typescript
|
|
230
|
+
const bobAtAcme = [
|
|
231
|
+
{ object_name: "person", key: { name: "Bob" } },
|
|
232
|
+
{ object_name: "company", key: { name: "Acme" } },
|
|
233
|
+
];
|
|
234
|
+
await inst.write([
|
|
235
|
+
{ object_mutation: { object_type: "company", create: { key: { name: "Acme" } } } },
|
|
236
|
+
{ relation_mutation: { relation_type: "employment", create: { endpoints: bobAtAcme, values: { title: "designer" } } } },
|
|
237
|
+
]);
|
|
238
|
+
await inst.write([
|
|
239
|
+
{ relation_mutation: { relation_type: "employment", update: { endpoints: bobAtAcme, values: { title: "lead designer" } } } },
|
|
240
|
+
]);
|
|
241
|
+
```
|
|
242
|
+
|
|
222
243
|
Options for the mutations form: `{ timeoutMs? }` (extraction options don't apply).
|
|
223
244
|
|
|
224
245
|
### `inst.writeAsync(text | mutations, options?)` → `AsyncWriteResult`
|
|
@@ -284,6 +305,51 @@ await inst.write([
|
|
|
284
305
|
]);
|
|
285
306
|
```
|
|
286
307
|
|
|
308
|
+
### Fields on a relation
|
|
309
|
+
|
|
310
|
+
A relation can declare fields of its own in the schema: values that belong to
|
|
311
|
+
one link rather than to either record, such as a person's title at a company.
|
|
312
|
+
Only structured writes set them; a text write does not, so a value that will
|
|
313
|
+
arrive in text is best kept on an object. They are shaped like an object's
|
|
314
|
+
fields:
|
|
315
|
+
|
|
316
|
+
```yaml
|
|
317
|
+
relations:
|
|
318
|
+
employment:
|
|
319
|
+
objects:
|
|
320
|
+
person:
|
|
321
|
+
type: person
|
|
322
|
+
on_delete: cascade
|
|
323
|
+
company:
|
|
324
|
+
type: company
|
|
325
|
+
on_delete: cascade
|
|
326
|
+
keys:
|
|
327
|
+
one_link_per_pair: [person, company]
|
|
328
|
+
fields:
|
|
329
|
+
title:
|
|
330
|
+
type: str
|
|
331
|
+
description: the person's job title at this company
|
|
332
|
+
started_on:
|
|
333
|
+
type: str
|
|
334
|
+
description: the day the person started at this company, as YYYY-MM-DD
|
|
335
|
+
description: person works at company
|
|
336
|
+
```
|
|
337
|
+
|
|
338
|
+
- A relation's field is never `required`, since a link is made before its values
|
|
339
|
+
are known. It takes no `merge` or `format`, and it cannot share a name with one
|
|
340
|
+
of the relation's roles or with a name the server reserves. A schema that breaks
|
|
341
|
+
this is refused: an `XmemoryAPIError` with status 422, code `INVALID_INPUT` and
|
|
342
|
+
`details.error_code` set to `"xmd_relation_field_invalid"` (a field that is not
|
|
343
|
+
well formed gets its own validation error instead).
|
|
344
|
+
- A relation's fields are declared when the relation is added, in the schema; a
|
|
345
|
+
migration plan's `add_relation` op carries the same fields. On a relation that
|
|
346
|
+
already exists, a schema update that adds or removes a field, or changes its
|
|
347
|
+
type, enum or default, is refused; its description can change.
|
|
348
|
+
- A relation `create` takes their values in `values`, and an `update` names one
|
|
349
|
+
link by every endpoint and sets them (see the example under `inst.write`). A
|
|
350
|
+
key over the relation's roles, as above, keeps the same two records to one
|
|
351
|
+
link, so an `update` by their endpoints never finds more than one.
|
|
352
|
+
|
|
287
353
|
### Mergeable text fields
|
|
288
354
|
|
|
289
355
|
By default a write replaces a field's stored value. A `str` field that is not
|
package/dist/cjs/types.d.ts
CHANGED
|
@@ -628,22 +628,22 @@ export interface GenerateSchemaResult {
|
|
|
628
628
|
export interface RelationEndpoint {
|
|
629
629
|
/** Relation role name from the instance schema. */
|
|
630
630
|
object_name: string;
|
|
631
|
-
/** Endpoint identity: user primary-key fields (field -> value)
|
|
631
|
+
/** Endpoint identity: user primary-key fields (field -> value). */
|
|
632
632
|
key?: Record<string, unknown>;
|
|
633
633
|
}
|
|
634
|
-
/** Create an object: `key` holds the user primary-key fields
|
|
635
|
-
*
|
|
634
|
+
/** Create an object: `key` holds the user primary-key fields, `values` the
|
|
635
|
+
* remaining field values. */
|
|
636
636
|
export interface ObjectCreatePayload {
|
|
637
637
|
key?: Record<string, unknown>;
|
|
638
638
|
values?: Record<string, unknown>;
|
|
639
639
|
}
|
|
640
|
-
/** Update an object identified by `key` (primary-key fields
|
|
641
|
-
*
|
|
640
|
+
/** Update an object identified by `key` (its primary-key fields). A `null` value
|
|
641
|
+
* in `values` clears that field. */
|
|
642
642
|
export interface ObjectUpdatePayload {
|
|
643
643
|
key: Record<string, unknown>;
|
|
644
644
|
values: Record<string, unknown>;
|
|
645
645
|
}
|
|
646
|
-
/** Delete the object identified by `key` (primary-key fields
|
|
646
|
+
/** Delete the object identified by `key` (its primary-key fields). */
|
|
647
647
|
export interface ObjectDeletePayload {
|
|
648
648
|
key: Record<string, unknown>;
|
|
649
649
|
}
|
|
@@ -652,17 +652,16 @@ export interface RelationCreatePayload {
|
|
|
652
652
|
endpoints: RelationEndpoint[];
|
|
653
653
|
values?: Record<string, unknown>;
|
|
654
654
|
}
|
|
655
|
-
/** Update a relation's own fields
|
|
656
|
-
*
|
|
657
|
-
* clears that field. */
|
|
655
|
+
/** Update a relation's own fields on one link, named by its `endpoints` (one per
|
|
656
|
+
* relation role); endpoints that match several links are refused. A `null` value
|
|
657
|
+
* in `values` clears that field. */
|
|
658
658
|
export interface RelationUpdatePayload {
|
|
659
659
|
key?: Record<string, unknown>;
|
|
660
660
|
endpoints?: RelationEndpoint[];
|
|
661
661
|
values: Record<string, unknown>;
|
|
662
662
|
}
|
|
663
|
-
/** Delete
|
|
664
|
-
*
|
|
665
|
-
* `allow_bulk_delete: true`. */
|
|
663
|
+
/** Delete the links matched by `endpoints` (a subset is allowed). Deleting more
|
|
664
|
+
* than one matched link requires `allow_bulk_delete: true`. */
|
|
666
665
|
export interface RelationDeletePayload {
|
|
667
666
|
key?: Record<string, unknown>;
|
|
668
667
|
endpoints?: RelationEndpoint[];
|
|
@@ -712,6 +711,7 @@ export type DecisionKind = "accept" | "reject" | "defer";
|
|
|
712
711
|
export type MigrationSource = "direct" | "suggestion_engine";
|
|
713
712
|
export type DefaultValue = string | number | boolean | null;
|
|
714
713
|
export type EnumValues = Array<string | number | boolean> | null;
|
|
714
|
+
/** An object's or a relation's field, as a migration op adds it. */
|
|
715
715
|
export interface FieldSpec {
|
|
716
716
|
name: string;
|
|
717
717
|
type: FieldType;
|
|
@@ -787,6 +787,11 @@ export interface AddRelation {
|
|
|
787
787
|
objects: Record<string, string>;
|
|
788
788
|
keys?: Record<string, string[]> | null;
|
|
789
789
|
on_delete?: Record<string, OnDelete> | null;
|
|
790
|
+
/** The relation's own fields: values that belong to one link, such as a
|
|
791
|
+
* person's title at a company. They are set when the relation is added; no
|
|
792
|
+
* migration op changes them later. None of them may be `required` or declare a
|
|
793
|
+
* format. Leave the key out for a relation without fields of its own. */
|
|
794
|
+
fields?: FieldSpec[];
|
|
790
795
|
should_backfill?: boolean;
|
|
791
796
|
}
|
|
792
797
|
export interface RemoveRelation {
|
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.22.0";
|
package/dist/cjs/version.js
CHANGED
package/dist/esm/types.d.ts
CHANGED
|
@@ -628,22 +628,22 @@ export interface GenerateSchemaResult {
|
|
|
628
628
|
export interface RelationEndpoint {
|
|
629
629
|
/** Relation role name from the instance schema. */
|
|
630
630
|
object_name: string;
|
|
631
|
-
/** Endpoint identity: user primary-key fields (field -> value)
|
|
631
|
+
/** Endpoint identity: user primary-key fields (field -> value). */
|
|
632
632
|
key?: Record<string, unknown>;
|
|
633
633
|
}
|
|
634
|
-
/** Create an object: `key` holds the user primary-key fields
|
|
635
|
-
*
|
|
634
|
+
/** Create an object: `key` holds the user primary-key fields, `values` the
|
|
635
|
+
* remaining field values. */
|
|
636
636
|
export interface ObjectCreatePayload {
|
|
637
637
|
key?: Record<string, unknown>;
|
|
638
638
|
values?: Record<string, unknown>;
|
|
639
639
|
}
|
|
640
|
-
/** Update an object identified by `key` (primary-key fields
|
|
641
|
-
*
|
|
640
|
+
/** Update an object identified by `key` (its primary-key fields). A `null` value
|
|
641
|
+
* in `values` clears that field. */
|
|
642
642
|
export interface ObjectUpdatePayload {
|
|
643
643
|
key: Record<string, unknown>;
|
|
644
644
|
values: Record<string, unknown>;
|
|
645
645
|
}
|
|
646
|
-
/** Delete the object identified by `key` (primary-key fields
|
|
646
|
+
/** Delete the object identified by `key` (its primary-key fields). */
|
|
647
647
|
export interface ObjectDeletePayload {
|
|
648
648
|
key: Record<string, unknown>;
|
|
649
649
|
}
|
|
@@ -652,17 +652,16 @@ export interface RelationCreatePayload {
|
|
|
652
652
|
endpoints: RelationEndpoint[];
|
|
653
653
|
values?: Record<string, unknown>;
|
|
654
654
|
}
|
|
655
|
-
/** Update a relation's own fields
|
|
656
|
-
*
|
|
657
|
-
* clears that field. */
|
|
655
|
+
/** Update a relation's own fields on one link, named by its `endpoints` (one per
|
|
656
|
+
* relation role); endpoints that match several links are refused. A `null` value
|
|
657
|
+
* in `values` clears that field. */
|
|
658
658
|
export interface RelationUpdatePayload {
|
|
659
659
|
key?: Record<string, unknown>;
|
|
660
660
|
endpoints?: RelationEndpoint[];
|
|
661
661
|
values: Record<string, unknown>;
|
|
662
662
|
}
|
|
663
|
-
/** Delete
|
|
664
|
-
*
|
|
665
|
-
* `allow_bulk_delete: true`. */
|
|
663
|
+
/** Delete the links matched by `endpoints` (a subset is allowed). Deleting more
|
|
664
|
+
* than one matched link requires `allow_bulk_delete: true`. */
|
|
666
665
|
export interface RelationDeletePayload {
|
|
667
666
|
key?: Record<string, unknown>;
|
|
668
667
|
endpoints?: RelationEndpoint[];
|
|
@@ -712,6 +711,7 @@ export type DecisionKind = "accept" | "reject" | "defer";
|
|
|
712
711
|
export type MigrationSource = "direct" | "suggestion_engine";
|
|
713
712
|
export type DefaultValue = string | number | boolean | null;
|
|
714
713
|
export type EnumValues = Array<string | number | boolean> | null;
|
|
714
|
+
/** An object's or a relation's field, as a migration op adds it. */
|
|
715
715
|
export interface FieldSpec {
|
|
716
716
|
name: string;
|
|
717
717
|
type: FieldType;
|
|
@@ -787,6 +787,11 @@ export interface AddRelation {
|
|
|
787
787
|
objects: Record<string, string>;
|
|
788
788
|
keys?: Record<string, string[]> | null;
|
|
789
789
|
on_delete?: Record<string, OnDelete> | null;
|
|
790
|
+
/** The relation's own fields: values that belong to one link, such as a
|
|
791
|
+
* person's title at a company. They are set when the relation is added; no
|
|
792
|
+
* migration op changes them later. None of them may be `required` or declare a
|
|
793
|
+
* format. Leave the key out for a relation without fields of its own. */
|
|
794
|
+
fields?: FieldSpec[];
|
|
790
795
|
should_backfill?: boolean;
|
|
791
796
|
}
|
|
792
797
|
export interface RemoveRelation {
|
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.22.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.22.0";
|