xmemory 3.21.1 → 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
@@ -194,7 +194,7 @@ Every data operation — `read`, `write`, `writeAsync`, `writeStatus`, `extract`
194
194
  `console_url`, the deep link to that call's trace. It is per operation rather than per
195
195
  record, and `null` when the server has no console configured.
196
196
 
197
- Options: `{ extractionLogic?, diffEngine?, scope?, timeoutMs? }` — `extractionLogic`
197
+ Options: `{ extractionLogic?, scope?, timeoutMs? }` — `extractionLogic`
198
198
  defaults to `"fast"`; see [Scoped writes](#scoped-writes) for `scope` and its `mode`.
199
199
 
200
200
  Or pass a `WriteMutation[]` for **structured writes** — deterministic, LLM-free
@@ -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
@@ -313,11 +379,7 @@ next_steps:
313
379
  every fact.
314
380
  - If a merge cannot be made, the new value is appended, even past the cap, and
315
381
  nothing stored is cut.
316
- - Only text writes merge, through the server's diff engine. A text write that
317
- runs without it on such a schema — `diffEngine: false`, or a connection whose
318
- default is off — is refused with a 400 `VALIDATION_ERROR`; through
319
- `writeAsync` it is queued and fails, which `writeStatus` reports.
320
- `WriteMutation[]` writes replace the value as given.
382
+ - Only text writes merge. `WriteMutation[]` writes replace the value as given.
321
383
  - Adding, changing or removing a `merge` is a metadata-only schema change.
322
384
 
323
385
  Where a merge that changed the field found the new value contradicting the
@@ -614,8 +676,6 @@ Things to know before reaching for it:
614
676
  scope names records by that key, so a type declared `primary_key: []` has
615
677
  nothing to name its records by — and `"drop"` never creates a record of such a
616
678
  type, for the same reason.
617
- - `"drop"` is computed by the server's **diff engine**, so asking for it with
618
- `diffEngine: false` is refused with a 400. `"reject"` has no such requirement.
619
679
  - The server caps the number of scoped objects per write, and can have scoped
620
680
  writes disabled entirely. Both are server-side rules, so they surface as an
621
681
  `XmemoryAPIError`.
@@ -67,8 +67,8 @@ export declare class InstanceHandle {
67
67
  * or a `WriteMutation[]` to apply deterministic, LLM-free create / update /
68
68
  * delete edits (applied in array order; later mutations may reference
69
69
  * objects created earlier in the batch, and a `null` value in a mutation's
70
- * `values` clears that field). `extractionLogic` / `diffEngine` only apply
71
- * to the text form.
70
+ * `values` clears that field). `extractionLogic` only applies to the text
71
+ * form.
72
72
  *
73
73
  * Pass `scope` — a `WriteScope` of concrete objects, each named by its
74
74
  * user-defined primary key — to anchor a text write to them. The write is
@@ -82,13 +82,7 @@ export declare class InstanceHandle {
82
82
  * fails, and nothing applies. Under `"drop"` that change is skipped — along
83
83
  * with anything that depended on it — the rest applies, and what was left out
84
84
  * comes back on `result.changes.skipped_out_of_scope`. `"drop"` also lets the
85
- * write create a scoped record that is not stored yet, and is computed by the
86
- * diff engine, so passing `diffEngine: false` with it is a 400.
87
- *
88
- * A text write on a schema with a `merge` field also needs the diff engine:
89
- * with the engine off, by `diffEngine: false` or by the connection's default,
90
- * it is refused with a 400 `VALIDATION_ERROR`; a {@link writeAsync} one is
91
- * queued and fails, which {@link writeStatus} reports.
85
+ * write create a scoped record that is not stored yet.
92
86
  *
93
87
  * A scoped write additionally requires read permission on the instance: the
94
88
  * response carries the previous value of every field the write changed,
@@ -64,8 +64,7 @@ export interface ReadScope {
64
64
  * is what makes "create or update exactly this record" expressible, while
65
65
  * `"reject"` requires every scoped record to exist already. And a type that
66
66
  * declares no user-defined primary key is never created under `"drop"`, since
67
- * a scope has no way to name such a record. `"drop"` is computed by the
68
- * server's diff engine, so pairing it with `diffEngine: false` is a 400.
67
+ * a scope has no way to name such a record.
69
68
  */
70
69
  export type WriteScopeMode = "reject" | "drop";
71
70
  /**
@@ -629,22 +628,22 @@ export interface GenerateSchemaResult {
629
628
  export interface RelationEndpoint {
630
629
  /** Relation role name from the instance schema. */
631
630
  object_name: string;
632
- /** Endpoint identity: user primary-key fields (field -> value), or `{ xuid: ... }`. */
631
+ /** Endpoint identity: user primary-key fields (field -> value). */
633
632
  key?: Record<string, unknown>;
634
633
  }
635
- /** Create an object: `key` holds the user primary-key fields (no `xuid` — it is
636
- * 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. */
637
636
  export interface ObjectCreatePayload {
638
637
  key?: Record<string, unknown>;
639
638
  values?: Record<string, unknown>;
640
639
  }
641
- /** Update an object identified by `key` (primary-key fields or `{ xuid: ... }`).
642
- * 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. */
643
642
  export interface ObjectUpdatePayload {
644
643
  key: Record<string, unknown>;
645
644
  values: Record<string, unknown>;
646
645
  }
647
- /** Delete the object identified by `key` (primary-key fields or `{ xuid: ... }`). */
646
+ /** Delete the object identified by `key` (its primary-key fields). */
648
647
  export interface ObjectDeletePayload {
649
648
  key: Record<string, unknown>;
650
649
  }
@@ -653,17 +652,16 @@ export interface RelationCreatePayload {
653
652
  endpoints: RelationEndpoint[];
654
653
  values?: Record<string, unknown>;
655
654
  }
656
- /** Update a relation's own fields. Address it by `endpoints`, or by
657
- * `key: { xuid: ... }` when endpoints are ambiguous. A `null` value in `values`
658
- * 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. */
659
658
  export interface RelationUpdatePayload {
660
659
  key?: Record<string, unknown>;
661
660
  endpoints?: RelationEndpoint[];
662
661
  values: Record<string, unknown>;
663
662
  }
664
- /** Delete relation(s) matched by `endpoints` (a subset is allowed) or by
665
- * `key: { xuid: ... }`. Deleting more than one matched row requires
666
- * `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`. */
667
665
  export interface RelationDeletePayload {
668
666
  key?: Record<string, unknown>;
669
667
  endpoints?: RelationEndpoint[];
@@ -713,6 +711,7 @@ export type DecisionKind = "accept" | "reject" | "defer";
713
711
  export type MigrationSource = "direct" | "suggestion_engine";
714
712
  export type DefaultValue = string | number | boolean | null;
715
713
  export type EnumValues = Array<string | number | boolean> | null;
714
+ /** An object's or a relation's field, as a migration op adds it. */
716
715
  export interface FieldSpec {
717
716
  name: string;
718
717
  type: FieldType;
@@ -788,6 +787,11 @@ export interface AddRelation {
788
787
  objects: Record<string, string>;
789
788
  keys?: Record<string, string[]> | null;
790
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[];
791
795
  should_backfill?: boolean;
792
796
  }
793
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.1";
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.1";
5
+ exports.VERSION = "3.22.0";
@@ -67,8 +67,8 @@ export declare class InstanceHandle {
67
67
  * or a `WriteMutation[]` to apply deterministic, LLM-free create / update /
68
68
  * delete edits (applied in array order; later mutations may reference
69
69
  * objects created earlier in the batch, and a `null` value in a mutation's
70
- * `values` clears that field). `extractionLogic` / `diffEngine` only apply
71
- * to the text form.
70
+ * `values` clears that field). `extractionLogic` only applies to the text
71
+ * form.
72
72
  *
73
73
  * Pass `scope` — a `WriteScope` of concrete objects, each named by its
74
74
  * user-defined primary key — to anchor a text write to them. The write is
@@ -82,13 +82,7 @@ export declare class InstanceHandle {
82
82
  * fails, and nothing applies. Under `"drop"` that change is skipped — along
83
83
  * with anything that depended on it — the rest applies, and what was left out
84
84
  * comes back on `result.changes.skipped_out_of_scope`. `"drop"` also lets the
85
- * write create a scoped record that is not stored yet, and is computed by the
86
- * diff engine, so passing `diffEngine: false` with it is a 400.
87
- *
88
- * A text write on a schema with a `merge` field also needs the diff engine:
89
- * with the engine off, by `diffEngine: false` or by the connection's default,
90
- * it is refused with a 400 `VALIDATION_ERROR`; a {@link writeAsync} one is
91
- * queued and fails, which {@link writeStatus} reports.
85
+ * write create a scoped record that is not stored yet.
92
86
  *
93
87
  * A scoped write additionally requires read permission on the instance: the
94
88
  * response carries the previous value of every field the write changed,
@@ -64,8 +64,7 @@ export interface ReadScope {
64
64
  * is what makes "create or update exactly this record" expressible, while
65
65
  * `"reject"` requires every scoped record to exist already. And a type that
66
66
  * declares no user-defined primary key is never created under `"drop"`, since
67
- * a scope has no way to name such a record. `"drop"` is computed by the
68
- * server's diff engine, so pairing it with `diffEngine: false` is a 400.
67
+ * a scope has no way to name such a record.
69
68
  */
70
69
  export type WriteScopeMode = "reject" | "drop";
71
70
  /**
@@ -629,22 +628,22 @@ export interface GenerateSchemaResult {
629
628
  export interface RelationEndpoint {
630
629
  /** Relation role name from the instance schema. */
631
630
  object_name: string;
632
- /** Endpoint identity: user primary-key fields (field -> value), or `{ xuid: ... }`. */
631
+ /** Endpoint identity: user primary-key fields (field -> value). */
633
632
  key?: Record<string, unknown>;
634
633
  }
635
- /** Create an object: `key` holds the user primary-key fields (no `xuid` — it is
636
- * 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. */
637
636
  export interface ObjectCreatePayload {
638
637
  key?: Record<string, unknown>;
639
638
  values?: Record<string, unknown>;
640
639
  }
641
- /** Update an object identified by `key` (primary-key fields or `{ xuid: ... }`).
642
- * 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. */
643
642
  export interface ObjectUpdatePayload {
644
643
  key: Record<string, unknown>;
645
644
  values: Record<string, unknown>;
646
645
  }
647
- /** Delete the object identified by `key` (primary-key fields or `{ xuid: ... }`). */
646
+ /** Delete the object identified by `key` (its primary-key fields). */
648
647
  export interface ObjectDeletePayload {
649
648
  key: Record<string, unknown>;
650
649
  }
@@ -653,17 +652,16 @@ export interface RelationCreatePayload {
653
652
  endpoints: RelationEndpoint[];
654
653
  values?: Record<string, unknown>;
655
654
  }
656
- /** Update a relation's own fields. Address it by `endpoints`, or by
657
- * `key: { xuid: ... }` when endpoints are ambiguous. A `null` value in `values`
658
- * 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. */
659
658
  export interface RelationUpdatePayload {
660
659
  key?: Record<string, unknown>;
661
660
  endpoints?: RelationEndpoint[];
662
661
  values: Record<string, unknown>;
663
662
  }
664
- /** Delete relation(s) matched by `endpoints` (a subset is allowed) or by
665
- * `key: { xuid: ... }`. Deleting more than one matched row requires
666
- * `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`. */
667
665
  export interface RelationDeletePayload {
668
666
  key?: Record<string, unknown>;
669
667
  endpoints?: RelationEndpoint[];
@@ -713,6 +711,7 @@ export type DecisionKind = "accept" | "reject" | "defer";
713
711
  export type MigrationSource = "direct" | "suggestion_engine";
714
712
  export type DefaultValue = string | number | boolean | null;
715
713
  export type EnumValues = Array<string | number | boolean> | null;
714
+ /** An object's or a relation's field, as a migration op adds it. */
716
715
  export interface FieldSpec {
717
716
  name: string;
718
717
  type: FieldType;
@@ -788,6 +787,11 @@ export interface AddRelation {
788
787
  objects: Record<string, string>;
789
788
  keys?: Record<string, string[]> | null;
790
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[];
791
795
  should_backfill?: boolean;
792
796
  }
793
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.1";
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.1";
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.1",
3
+ "version": "3.22.0",
4
4
  "description": "xmemory",
5
5
  "keywords": [
6
6
  "xmemory"