xmemory 3.21.2 → 3.23.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,61 @@ await inst.write([
284
305
  ]);
285
306
  ```
286
307
 
308
+ ### Labels
309
+
310
+ Fields and objects may also carry labels that xmemory sets: `field_kind` on a
311
+ field (`free_text`, `state` or `value`) and `interval` on an object (`true` or
312
+ `false`). They are hints about the data that help xmemory handle writes, not
313
+ identifiers or constraints. A label you state is kept, as long as it fits the
314
+ field's other settings; one you leave out keeps its current value. See the XMD
315
+ guide's [Labels](https://xmemory.ai/xmd/#labels) section for what each value
316
+ means.
317
+
318
+ ### Fields on a relation
319
+
320
+ A relation can declare fields of its own in the schema: values that belong to
321
+ one link rather than to either record, such as a person's title at a company.
322
+ Only structured writes set them; a text write does not, so a value that will
323
+ arrive in text is best kept on an object. They are shaped like an object's
324
+ fields:
325
+
326
+ ```yaml
327
+ relations:
328
+ employment:
329
+ objects:
330
+ person:
331
+ type: person
332
+ on_delete: cascade
333
+ company:
334
+ type: company
335
+ on_delete: cascade
336
+ keys:
337
+ one_link_per_pair: [person, company]
338
+ fields:
339
+ title:
340
+ type: str
341
+ description: the person's job title at this company
342
+ started_on:
343
+ type: str
344
+ description: the day the person started at this company, as YYYY-MM-DD
345
+ description: person works at company
346
+ ```
347
+
348
+ - A relation's field is never `required`, since a link is made before its values
349
+ are known. It takes no `merge` or `format`, and it cannot share a name with one
350
+ of the relation's roles or with a name the server reserves. A schema that breaks
351
+ this is refused: an `XmemoryAPIError` with status 422, code `INVALID_INPUT` and
352
+ `details.error_code` set to `"xmd_relation_field_invalid"` (a field that is not
353
+ well formed gets its own validation error instead).
354
+ - A relation's fields are declared when the relation is added, in the schema; a
355
+ migration plan's `add_relation` op carries the same fields. On a relation that
356
+ already exists, a schema update that adds or removes a field, or changes its
357
+ type, enum or default, is refused; its description can change.
358
+ - A relation `create` takes their values in `values`, and an `update` names one
359
+ link by every endpoint and sets them (see the example under `inst.write`). A
360
+ key over the relation's roles, as above, keeps the same two records to one
361
+ link, so an `update` by their endpoints never finds more than one.
362
+
287
363
  ### Mergeable text fields
288
364
 
289
365
  By default a write replaces a field's stored value. A `str` field that is not
@@ -12,5 +12,5 @@ export type { ScopeObject, ReadScope, WriteScope, RelationsScope, WriteScopeMode
12
12
  export type { XmemoryClientOptions, RequestOptions, ReadOptions, WriteOptions, ExtractOptions, CreateInstanceOptions, GenerateSchemaOptions, UpdateInstanceMetadataOptions, PatchInstanceMetadataOptions, UpdateInstanceSchemaOptions, DryRunMigrationOptions, ListMigrationsOptions, GetMigrationOptions, SuggestionRequestOptions, } from "./types.js";
13
13
  export type { ClusterInfo, InstanceInfo, InstanceSchemaInfo, ReadResult, TaggedReaderResult, RelatedTypes, RelatedTypesTouched, RelatedTypesLink, RelatedTypesObjectType, RelatedTypesRelation, WriteResult, WriteChanges, SkippedOutOfScope, FieldMergeContradiction, OrphanedRecord, AsyncWriteResult, WriteStatusResult, ExtractResult, GenerateSchemaResult, ToolDescription, ToolParameterDescription, RawDescribeResult, } from "./types.js";
14
14
  export type { WriteMutation, ObjectMutationBody, ObjectCreatePayload, ObjectUpdatePayload, ObjectDeletePayload, RelationMutationBody, RelationCreatePayload, RelationUpdatePayload, RelationDeletePayload, RelationEndpoint, } from "./types.js";
15
- export type { MigrationPlan, MigrationOp, FieldSpec, AddObject, RemoveObject, RenameObject, ChangeObject, AddField, RemoveField, RenameField, ChangeField, AddRelation, RemoveRelation, RenameRelation, ChangeRelation, DefaultValue, EnumValues, } from "./types.js";
15
+ export type { MigrationPlan, MigrationOp, FieldSpec, AddObject, RemoveObject, RenameObject, ChangeObject, AddField, RemoveField, RenameField, ChangeField, AddRelation, RemoveRelation, RenameRelation, ChangeRelation, DefaultValue, EnumValues, FieldFormat, FieldKind, } from "./types.js";
16
16
  export type { EnhanceSchemaResult, PlanSummary, DryRunResult, MigrationRecord, ListMigrationsResult, GetMigrationResult, ConsolidatedProposal, ProposalItem, ReviewSuggestionsResult, DecisionInput, RecordedDecision, DependencyWarning, DecideSuggestionsResult, ApplyPendingDecisionsResult, } from "./types.js";
@@ -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,13 @@ 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
+ /** A field's declared format, as the server holds it. Kept open so a value a newer
715
+ * server adds, or a caller's own interface for one, still type-checks (`unknown`
716
+ * values would refuse an interface without an index signature). */
717
+ export type FieldFormat = Record<string, any>;
718
+ /** A field's label, as the server holds it. */
719
+ export type FieldKind = string;
720
+ /** An object's or a relation's field, as a migration op adds it. */
715
721
  export interface FieldSpec {
716
722
  name: string;
717
723
  type: FieldType;
@@ -719,6 +725,8 @@ export interface FieldSpec {
719
725
  description?: string | null;
720
726
  default?: DefaultValue;
721
727
  enum?: EnumValues;
728
+ format?: FieldFormat;
729
+ field_kind?: FieldKind;
722
730
  }
723
731
  export interface AddObject {
724
732
  op_type: "add_object";
@@ -727,6 +735,8 @@ export interface AddObject {
727
735
  primary_key: string[];
728
736
  fields: FieldSpec[];
729
737
  should_backfill?: boolean;
738
+ /** The object's label. */
739
+ interval?: boolean;
730
740
  }
731
741
  export interface RemoveObject {
732
742
  op_type: "remove_object";
@@ -742,6 +752,8 @@ export interface ChangeObject {
742
752
  name: string;
743
753
  new_primary_key?: string[] | null;
744
754
  new_description?: string | null;
755
+ /** Sets the object's label. */
756
+ new_interval?: boolean;
745
757
  }
746
758
  export interface AddField {
747
759
  op_type: "add_field";
@@ -753,6 +765,8 @@ export interface AddField {
753
765
  default?: DefaultValue;
754
766
  enum?: EnumValues;
755
767
  should_backfill?: boolean;
768
+ format?: FieldFormat;
769
+ field_kind?: FieldKind;
756
770
  }
757
771
  export interface RemoveField {
758
772
  op_type: "remove_field";
@@ -779,6 +793,12 @@ export interface ChangeField {
779
793
  cast_strategy?: CastStrategy | null;
780
794
  using_expression?: string | null;
781
795
  confirm_data_loss?: boolean;
796
+ /** Sets or replaces the field's declared format; `clear_format: true` removes it.
797
+ * Never both in one op. */
798
+ new_format?: FieldFormat;
799
+ clear_format?: boolean;
800
+ /** Sets the field's label. */
801
+ new_field_kind?: FieldKind;
782
802
  }
783
803
  export interface AddRelation {
784
804
  op_type: "add_relation";
@@ -787,6 +807,11 @@ export interface AddRelation {
787
807
  objects: Record<string, string>;
788
808
  keys?: Record<string, string[]> | null;
789
809
  on_delete?: Record<string, OnDelete> | null;
810
+ /** The relation's own fields: values that belong to one link, such as a
811
+ * person's title at a company. They are set when the relation is added; no
812
+ * migration op changes them later. None of them may be `required` or declare a
813
+ * format. Leave the key out for a relation without fields of its own. */
814
+ fields?: FieldSpec[];
790
815
  should_backfill?: boolean;
791
816
  }
792
817
  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.23.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.23.0";
@@ -12,5 +12,5 @@ export type { ScopeObject, ReadScope, WriteScope, RelationsScope, WriteScopeMode
12
12
  export type { XmemoryClientOptions, RequestOptions, ReadOptions, WriteOptions, ExtractOptions, CreateInstanceOptions, GenerateSchemaOptions, UpdateInstanceMetadataOptions, PatchInstanceMetadataOptions, UpdateInstanceSchemaOptions, DryRunMigrationOptions, ListMigrationsOptions, GetMigrationOptions, SuggestionRequestOptions, } from "./types.js";
13
13
  export type { ClusterInfo, InstanceInfo, InstanceSchemaInfo, ReadResult, TaggedReaderResult, RelatedTypes, RelatedTypesTouched, RelatedTypesLink, RelatedTypesObjectType, RelatedTypesRelation, WriteResult, WriteChanges, SkippedOutOfScope, FieldMergeContradiction, OrphanedRecord, AsyncWriteResult, WriteStatusResult, ExtractResult, GenerateSchemaResult, ToolDescription, ToolParameterDescription, RawDescribeResult, } from "./types.js";
14
14
  export type { WriteMutation, ObjectMutationBody, ObjectCreatePayload, ObjectUpdatePayload, ObjectDeletePayload, RelationMutationBody, RelationCreatePayload, RelationUpdatePayload, RelationDeletePayload, RelationEndpoint, } from "./types.js";
15
- export type { MigrationPlan, MigrationOp, FieldSpec, AddObject, RemoveObject, RenameObject, ChangeObject, AddField, RemoveField, RenameField, ChangeField, AddRelation, RemoveRelation, RenameRelation, ChangeRelation, DefaultValue, EnumValues, } from "./types.js";
15
+ export type { MigrationPlan, MigrationOp, FieldSpec, AddObject, RemoveObject, RenameObject, ChangeObject, AddField, RemoveField, RenameField, ChangeField, AddRelation, RemoveRelation, RenameRelation, ChangeRelation, DefaultValue, EnumValues, FieldFormat, FieldKind, } from "./types.js";
16
16
  export type { EnhanceSchemaResult, PlanSummary, DryRunResult, MigrationRecord, ListMigrationsResult, GetMigrationResult, ConsolidatedProposal, ProposalItem, ReviewSuggestionsResult, DecisionInput, RecordedDecision, DependencyWarning, DecideSuggestionsResult, ApplyPendingDecisionsResult, } from "./types.js";
@@ -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,13 @@ 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
+ /** A field's declared format, as the server holds it. Kept open so a value a newer
715
+ * server adds, or a caller's own interface for one, still type-checks (`unknown`
716
+ * values would refuse an interface without an index signature). */
717
+ export type FieldFormat = Record<string, any>;
718
+ /** A field's label, as the server holds it. */
719
+ export type FieldKind = string;
720
+ /** An object's or a relation's field, as a migration op adds it. */
715
721
  export interface FieldSpec {
716
722
  name: string;
717
723
  type: FieldType;
@@ -719,6 +725,8 @@ export interface FieldSpec {
719
725
  description?: string | null;
720
726
  default?: DefaultValue;
721
727
  enum?: EnumValues;
728
+ format?: FieldFormat;
729
+ field_kind?: FieldKind;
722
730
  }
723
731
  export interface AddObject {
724
732
  op_type: "add_object";
@@ -727,6 +735,8 @@ export interface AddObject {
727
735
  primary_key: string[];
728
736
  fields: FieldSpec[];
729
737
  should_backfill?: boolean;
738
+ /** The object's label. */
739
+ interval?: boolean;
730
740
  }
731
741
  export interface RemoveObject {
732
742
  op_type: "remove_object";
@@ -742,6 +752,8 @@ export interface ChangeObject {
742
752
  name: string;
743
753
  new_primary_key?: string[] | null;
744
754
  new_description?: string | null;
755
+ /** Sets the object's label. */
756
+ new_interval?: boolean;
745
757
  }
746
758
  export interface AddField {
747
759
  op_type: "add_field";
@@ -753,6 +765,8 @@ export interface AddField {
753
765
  default?: DefaultValue;
754
766
  enum?: EnumValues;
755
767
  should_backfill?: boolean;
768
+ format?: FieldFormat;
769
+ field_kind?: FieldKind;
756
770
  }
757
771
  export interface RemoveField {
758
772
  op_type: "remove_field";
@@ -779,6 +793,12 @@ export interface ChangeField {
779
793
  cast_strategy?: CastStrategy | null;
780
794
  using_expression?: string | null;
781
795
  confirm_data_loss?: boolean;
796
+ /** Sets or replaces the field's declared format; `clear_format: true` removes it.
797
+ * Never both in one op. */
798
+ new_format?: FieldFormat;
799
+ clear_format?: boolean;
800
+ /** Sets the field's label. */
801
+ new_field_kind?: FieldKind;
782
802
  }
783
803
  export interface AddRelation {
784
804
  op_type: "add_relation";
@@ -787,6 +807,11 @@ export interface AddRelation {
787
807
  objects: Record<string, string>;
788
808
  keys?: Record<string, string[]> | null;
789
809
  on_delete?: Record<string, OnDelete> | null;
810
+ /** The relation's own fields: values that belong to one link, such as a
811
+ * person's title at a company. They are set when the relation is added; no
812
+ * migration op changes them later. None of them may be `required` or declare a
813
+ * format. Leave the key out for a relation without fields of its own. */
814
+ fields?: FieldSpec[];
790
815
  should_backfill?: boolean;
791
816
  }
792
817
  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.23.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.23.0";
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "xmemory",
3
- "version": "3.21.2",
3
+ "version": "3.23.0",
4
4
  "description": "xmemory",
5
5
  "keywords": [
6
6
  "xmemory"