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 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
@@ -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), or `{ xuid: ... }`. */
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 (no `xuid` — it is
635
- * generated server-side), `values` the remaining field values. */
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 or `{ xuid: ... }`).
641
- * A `null` value in `values` clears that field. */
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 or `{ xuid: ... }`). */
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. Address it by `endpoints`, or by
656
- * `key: { xuid: ... }` when endpoints are ambiguous. A `null` value in `values`
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 relation(s) matched by `endpoints` (a subset is allowed) or by
664
- * `key: { xuid: ... }`. Deleting more than one matched row requires
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 {
@@ -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.21.2";
2
+ export declare const VERSION = "3.22.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.21.2";
5
+ exports.VERSION = "3.22.0";
@@ -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), or `{ xuid: ... }`. */
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 (no `xuid` — it is
635
- * generated server-side), `values` the remaining field values. */
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 or `{ xuid: ... }`).
641
- * A `null` value in `values` clears that field. */
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 or `{ xuid: ... }`). */
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. Address it by `endpoints`, or by
656
- * `key: { xuid: ... }` when endpoints are ambiguous. A `null` value in `values`
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 relation(s) matched by `endpoints` (a subset is allowed) or by
664
- * `key: { xuid: ... }`. Deleting more than one matched row requires
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 {
@@ -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.21.2";
2
+ export declare const VERSION = "3.22.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.21.2";
2
+ export const VERSION = "3.22.0";
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "xmemory",
3
- "version": "3.21.2",
3
+ "version": "3.22.0",
4
4
  "description": "xmemory",
5
5
  "keywords": [
6
6
  "xmemory"