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 +68 -8
- package/dist/cjs/instance.d.ts +3 -9
- package/dist/cjs/types.d.ts +18 -14
- package/dist/cjs/version.d.ts +1 -1
- package/dist/cjs/version.js +1 -1
- package/dist/esm/instance.d.ts +3 -9
- package/dist/esm/types.d.ts +18 -14
- package/dist/esm/version.d.ts +1 -1
- package/dist/esm/version.js +1 -1
- package/package.json +1 -1
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?,
|
|
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
|
|
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`.
|
package/dist/cjs/instance.d.ts
CHANGED
|
@@ -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`
|
|
71
|
-
*
|
|
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
|
|
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,
|
package/dist/cjs/types.d.ts
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.
|
|
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)
|
|
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
|
|
636
|
-
*
|
|
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
|
|
642
|
-
*
|
|
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
|
|
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
|
|
657
|
-
*
|
|
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
|
|
665
|
-
*
|
|
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 {
|
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/instance.d.ts
CHANGED
|
@@ -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`
|
|
71
|
-
*
|
|
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
|
|
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,
|
package/dist/esm/types.d.ts
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.
|
|
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)
|
|
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
|
|
636
|
-
*
|
|
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
|
|
642
|
-
*
|
|
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
|
|
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
|
|
657
|
-
*
|
|
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
|
|
665
|
-
*
|
|
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 {
|
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";
|