xmemory 3.22.0 → 3.24.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
@@ -240,6 +240,22 @@ await inst.write([
240
240
  ]);
241
241
  ```
242
242
 
243
+ A type declared with `primary_key: []` has no key. A `create` takes an empty
244
+ `key` and at least one non-null value. An `update` or `delete` names the record
245
+ by `match` with an empty `key`: field values the record holds, compared as keys
246
+ are. `match` must single out one record unless `allow_bulk: true` acts on every
247
+ record it matches, up to 100 records per request. A relation endpoint of such a
248
+ type takes `match` in place of `key` too. When it builds the request, the client
249
+ refuses a record named by both a `key` and a `match` that hold values (an update,
250
+ a delete or a relation endpoint), and `allow_bulk` without `match`:
251
+
252
+ ```typescript
253
+ await inst.write([
254
+ { object_mutation: { object_type: "item", update: { key: {}, match: { label: "A" }, values: { status: "done" } } } },
255
+ { object_mutation: { object_type: "item", delete: { key: {}, match: { status: "void" }, allow_bulk: true } } },
256
+ ]);
257
+ ```
258
+
243
259
  Options for the mutations form: `{ timeoutMs? }` (extraction options don't apply).
244
260
 
245
261
  ### `inst.writeAsync(text | mutations, options?)` → `AsyncWriteResult`
@@ -305,6 +321,16 @@ await inst.write([
305
321
  ]);
306
322
  ```
307
323
 
324
+ ### Labels
325
+
326
+ Fields and objects may also carry labels that xmemory sets: `field_kind` on a
327
+ field (`free_text`, `state` or `value`) and `interval` on an object (`true` or
328
+ `false`). They are hints about the data that help xmemory handle writes, not
329
+ identifiers or constraints. A label you state is kept, as long as it fits the
330
+ field's other settings; one you leave out keeps its current value. See the XMD
331
+ guide's [Labels](https://xmemory.ai/xmd/#labels) section for what each value
332
+ means.
333
+
308
334
  ### Fields on a relation
309
335
 
310
336
  A relation can declare fields of its own in the schema: values that belong to
@@ -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";
@@ -13,6 +13,46 @@ const types_js_1 = require("./types.js");
13
13
  function serializeScopeObjects(objects) {
14
14
  return objects.map((o) => ({ type: o.type, key: { key: o.key } }));
15
15
  }
16
+ /** Whether a mapping holds a value the request will carry: JSON leaves out a
17
+ * property whose value is `undefined`, so such a property does not count. */
18
+ function holdsAValue(mapping) {
19
+ return Object.values(mapping ?? {}).some((value) => value !== undefined);
20
+ }
21
+ /** Throw when a record is named by `key` and by `match` at once (an object update
22
+ * or delete, or a relation endpoint), or an object update or delete sets
23
+ * `allow_bulk` without `match`: the server refuses both, and the types leave
24
+ * `key` required so that code built before `match` compiles as before. Each
25
+ * mutation must be an object. */
26
+ function checkTargets(mutations) {
27
+ mutations.forEach((mutation, index) => {
28
+ if (mutation == null || typeof mutation !== "object") {
29
+ throw new Error(`mutation ${index}: each mutation must be an object`);
30
+ }
31
+ if ("relation_mutation" in mutation && mutation.relation_mutation != null) {
32
+ const body = mutation.relation_mutation;
33
+ const endpoints = (body.create ?? body.update ?? body.delete)?.endpoints ?? [];
34
+ endpoints.forEach((endpoint, at) => {
35
+ if (holdsAValue(endpoint.key) && holdsAValue(endpoint.match)) {
36
+ throw new Error(`mutation ${index}, endpoint ${at}: name the record by 'key' or by 'match', not both`);
37
+ }
38
+ });
39
+ return;
40
+ }
41
+ if (!("object_mutation" in mutation) || mutation.object_mutation == null)
42
+ return;
43
+ const body = mutation.object_mutation;
44
+ const target = body.update ?? body.delete;
45
+ if (target == null)
46
+ return;
47
+ const hasMatch = holdsAValue(target.match);
48
+ if (holdsAValue(target.key) && hasMatch) {
49
+ throw new Error(`mutation ${index}: name the record by 'key' or by 'match', not both`);
50
+ }
51
+ if (target.allow_bulk === true && !hasMatch) {
52
+ throw new Error(`mutation ${index}: 'allow_bulk' applies only with 'match'`);
53
+ }
54
+ });
55
+ }
16
56
  /** Build the shared `/write` + `/write_async` request body for either input mode. */
17
57
  function buildWriteBody(input, options) {
18
58
  if (typeof input !== "string") {
@@ -25,6 +65,7 @@ function buildWriteBody(input, options) {
25
65
  if (options?.scope != null) {
26
66
  throw new Error("'scope' and structured mutations are mutually exclusive");
27
67
  }
68
+ checkTargets(input);
28
69
  // Structured path: no text, no extraction options — mutations go straight
29
70
  // to the wire.
30
71
  return { structured_mutations: input };
@@ -630,22 +630,37 @@ export interface RelationEndpoint {
630
630
  object_name: string;
631
631
  /** Endpoint identity: user primary-key fields (field -> value). */
632
632
  key?: Record<string, unknown>;
633
+ /** For an endpoint of a type without a primary key, in place of `key`: field
634
+ * values the record holds, which must single out one record. The client refuses
635
+ * an endpoint whose `key` and `match` both hold values. */
636
+ match?: Record<string, unknown>;
633
637
  }
634
638
  /** Create an object: `key` holds the user primary-key fields, `values` the
635
- * remaining field values. */
639
+ * remaining field values. For a type without a primary key, `key` is empty,
640
+ * `values` holds at least one non-null value, and each create adds a new record. */
636
641
  export interface ObjectCreatePayload {
637
642
  key?: Record<string, unknown>;
638
643
  values?: Record<string, unknown>;
639
644
  }
640
- /** Update an object identified by `key` (its primary-key fields). A `null` value
641
- * in `values` clears that field. */
645
+ /** Update an object identified by `key` (its primary-key fields), or, for a type
646
+ * without a primary key, by `match` with an empty `key`: field values the record
647
+ * holds, compared as keys are. `match` must single out one record unless
648
+ * `allow_bulk: true` acts on every record it matches, up to 100 records per
649
+ * request. A `null` value in `values` clears that field. The client refuses a
650
+ * non-empty `key` with `match`, and `allow_bulk` without `match`, when it builds
651
+ * the request. */
642
652
  export interface ObjectUpdatePayload {
643
653
  key: Record<string, unknown>;
654
+ match?: Record<string, unknown>;
655
+ allow_bulk?: boolean;
644
656
  values: Record<string, unknown>;
645
657
  }
646
- /** Delete the object identified by `key` (its primary-key fields). */
658
+ /** Delete the object identified by `key` (its primary-key fields), or, for a type
659
+ * without a primary key, by `match` with an empty `key`, as for an update. */
647
660
  export interface ObjectDeletePayload {
648
661
  key: Record<string, unknown>;
662
+ match?: Record<string, unknown>;
663
+ allow_bulk?: boolean;
649
664
  }
650
665
  /** Create a relation between the `endpoints`, with optional own-field `values`. */
651
666
  export interface RelationCreatePayload {
@@ -711,6 +726,12 @@ export type DecisionKind = "accept" | "reject" | "defer";
711
726
  export type MigrationSource = "direct" | "suggestion_engine";
712
727
  export type DefaultValue = string | number | boolean | null;
713
728
  export type EnumValues = Array<string | number | boolean> | null;
729
+ /** A field's declared format, as the server holds it. Kept open so a value a newer
730
+ * server adds, or a caller's own interface for one, still type-checks (`unknown`
731
+ * values would refuse an interface without an index signature). */
732
+ export type FieldFormat = Record<string, any>;
733
+ /** A field's label, as the server holds it. */
734
+ export type FieldKind = string;
714
735
  /** An object's or a relation's field, as a migration op adds it. */
715
736
  export interface FieldSpec {
716
737
  name: string;
@@ -719,6 +740,8 @@ export interface FieldSpec {
719
740
  description?: string | null;
720
741
  default?: DefaultValue;
721
742
  enum?: EnumValues;
743
+ format?: FieldFormat;
744
+ field_kind?: FieldKind;
722
745
  }
723
746
  export interface AddObject {
724
747
  op_type: "add_object";
@@ -727,6 +750,8 @@ export interface AddObject {
727
750
  primary_key: string[];
728
751
  fields: FieldSpec[];
729
752
  should_backfill?: boolean;
753
+ /** The object's label. */
754
+ interval?: boolean;
730
755
  }
731
756
  export interface RemoveObject {
732
757
  op_type: "remove_object";
@@ -742,6 +767,8 @@ export interface ChangeObject {
742
767
  name: string;
743
768
  new_primary_key?: string[] | null;
744
769
  new_description?: string | null;
770
+ /** Sets the object's label. */
771
+ new_interval?: boolean;
745
772
  }
746
773
  export interface AddField {
747
774
  op_type: "add_field";
@@ -753,6 +780,8 @@ export interface AddField {
753
780
  default?: DefaultValue;
754
781
  enum?: EnumValues;
755
782
  should_backfill?: boolean;
783
+ format?: FieldFormat;
784
+ field_kind?: FieldKind;
756
785
  }
757
786
  export interface RemoveField {
758
787
  op_type: "remove_field";
@@ -779,6 +808,12 @@ export interface ChangeField {
779
808
  cast_strategy?: CastStrategy | null;
780
809
  using_expression?: string | null;
781
810
  confirm_data_loss?: boolean;
811
+ /** Sets or replaces the field's declared format; `clear_format: true` removes it.
812
+ * Never both in one op. */
813
+ new_format?: FieldFormat;
814
+ clear_format?: boolean;
815
+ /** Sets the field's label. */
816
+ new_field_kind?: FieldKind;
782
817
  }
783
818
  export interface AddRelation {
784
819
  op_type: "add_relation";
@@ -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.22.0";
2
+ export declare const VERSION = "3.24.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.22.0";
5
+ exports.VERSION = "3.24.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";
@@ -10,6 +10,46 @@ import { SetupFormat } from "./types.js";
10
10
  function serializeScopeObjects(objects) {
11
11
  return objects.map((o) => ({ type: o.type, key: { key: o.key } }));
12
12
  }
13
+ /** Whether a mapping holds a value the request will carry: JSON leaves out a
14
+ * property whose value is `undefined`, so such a property does not count. */
15
+ function holdsAValue(mapping) {
16
+ return Object.values(mapping ?? {}).some((value) => value !== undefined);
17
+ }
18
+ /** Throw when a record is named by `key` and by `match` at once (an object update
19
+ * or delete, or a relation endpoint), or an object update or delete sets
20
+ * `allow_bulk` without `match`: the server refuses both, and the types leave
21
+ * `key` required so that code built before `match` compiles as before. Each
22
+ * mutation must be an object. */
23
+ function checkTargets(mutations) {
24
+ mutations.forEach((mutation, index) => {
25
+ if (mutation == null || typeof mutation !== "object") {
26
+ throw new Error(`mutation ${index}: each mutation must be an object`);
27
+ }
28
+ if ("relation_mutation" in mutation && mutation.relation_mutation != null) {
29
+ const body = mutation.relation_mutation;
30
+ const endpoints = (body.create ?? body.update ?? body.delete)?.endpoints ?? [];
31
+ endpoints.forEach((endpoint, at) => {
32
+ if (holdsAValue(endpoint.key) && holdsAValue(endpoint.match)) {
33
+ throw new Error(`mutation ${index}, endpoint ${at}: name the record by 'key' or by 'match', not both`);
34
+ }
35
+ });
36
+ return;
37
+ }
38
+ if (!("object_mutation" in mutation) || mutation.object_mutation == null)
39
+ return;
40
+ const body = mutation.object_mutation;
41
+ const target = body.update ?? body.delete;
42
+ if (target == null)
43
+ return;
44
+ const hasMatch = holdsAValue(target.match);
45
+ if (holdsAValue(target.key) && hasMatch) {
46
+ throw new Error(`mutation ${index}: name the record by 'key' or by 'match', not both`);
47
+ }
48
+ if (target.allow_bulk === true && !hasMatch) {
49
+ throw new Error(`mutation ${index}: 'allow_bulk' applies only with 'match'`);
50
+ }
51
+ });
52
+ }
13
53
  /** Build the shared `/write` + `/write_async` request body for either input mode. */
14
54
  function buildWriteBody(input, options) {
15
55
  if (typeof input !== "string") {
@@ -22,6 +62,7 @@ function buildWriteBody(input, options) {
22
62
  if (options?.scope != null) {
23
63
  throw new Error("'scope' and structured mutations are mutually exclusive");
24
64
  }
65
+ checkTargets(input);
25
66
  // Structured path: no text, no extraction options — mutations go straight
26
67
  // to the wire.
27
68
  return { structured_mutations: input };
@@ -630,22 +630,37 @@ export interface RelationEndpoint {
630
630
  object_name: string;
631
631
  /** Endpoint identity: user primary-key fields (field -> value). */
632
632
  key?: Record<string, unknown>;
633
+ /** For an endpoint of a type without a primary key, in place of `key`: field
634
+ * values the record holds, which must single out one record. The client refuses
635
+ * an endpoint whose `key` and `match` both hold values. */
636
+ match?: Record<string, unknown>;
633
637
  }
634
638
  /** Create an object: `key` holds the user primary-key fields, `values` the
635
- * remaining field values. */
639
+ * remaining field values. For a type without a primary key, `key` is empty,
640
+ * `values` holds at least one non-null value, and each create adds a new record. */
636
641
  export interface ObjectCreatePayload {
637
642
  key?: Record<string, unknown>;
638
643
  values?: Record<string, unknown>;
639
644
  }
640
- /** Update an object identified by `key` (its primary-key fields). A `null` value
641
- * in `values` clears that field. */
645
+ /** Update an object identified by `key` (its primary-key fields), or, for a type
646
+ * without a primary key, by `match` with an empty `key`: field values the record
647
+ * holds, compared as keys are. `match` must single out one record unless
648
+ * `allow_bulk: true` acts on every record it matches, up to 100 records per
649
+ * request. A `null` value in `values` clears that field. The client refuses a
650
+ * non-empty `key` with `match`, and `allow_bulk` without `match`, when it builds
651
+ * the request. */
642
652
  export interface ObjectUpdatePayload {
643
653
  key: Record<string, unknown>;
654
+ match?: Record<string, unknown>;
655
+ allow_bulk?: boolean;
644
656
  values: Record<string, unknown>;
645
657
  }
646
- /** Delete the object identified by `key` (its primary-key fields). */
658
+ /** Delete the object identified by `key` (its primary-key fields), or, for a type
659
+ * without a primary key, by `match` with an empty `key`, as for an update. */
647
660
  export interface ObjectDeletePayload {
648
661
  key: Record<string, unknown>;
662
+ match?: Record<string, unknown>;
663
+ allow_bulk?: boolean;
649
664
  }
650
665
  /** Create a relation between the `endpoints`, with optional own-field `values`. */
651
666
  export interface RelationCreatePayload {
@@ -711,6 +726,12 @@ export type DecisionKind = "accept" | "reject" | "defer";
711
726
  export type MigrationSource = "direct" | "suggestion_engine";
712
727
  export type DefaultValue = string | number | boolean | null;
713
728
  export type EnumValues = Array<string | number | boolean> | null;
729
+ /** A field's declared format, as the server holds it. Kept open so a value a newer
730
+ * server adds, or a caller's own interface for one, still type-checks (`unknown`
731
+ * values would refuse an interface without an index signature). */
732
+ export type FieldFormat = Record<string, any>;
733
+ /** A field's label, as the server holds it. */
734
+ export type FieldKind = string;
714
735
  /** An object's or a relation's field, as a migration op adds it. */
715
736
  export interface FieldSpec {
716
737
  name: string;
@@ -719,6 +740,8 @@ export interface FieldSpec {
719
740
  description?: string | null;
720
741
  default?: DefaultValue;
721
742
  enum?: EnumValues;
743
+ format?: FieldFormat;
744
+ field_kind?: FieldKind;
722
745
  }
723
746
  export interface AddObject {
724
747
  op_type: "add_object";
@@ -727,6 +750,8 @@ export interface AddObject {
727
750
  primary_key: string[];
728
751
  fields: FieldSpec[];
729
752
  should_backfill?: boolean;
753
+ /** The object's label. */
754
+ interval?: boolean;
730
755
  }
731
756
  export interface RemoveObject {
732
757
  op_type: "remove_object";
@@ -742,6 +767,8 @@ export interface ChangeObject {
742
767
  name: string;
743
768
  new_primary_key?: string[] | null;
744
769
  new_description?: string | null;
770
+ /** Sets the object's label. */
771
+ new_interval?: boolean;
745
772
  }
746
773
  export interface AddField {
747
774
  op_type: "add_field";
@@ -753,6 +780,8 @@ export interface AddField {
753
780
  default?: DefaultValue;
754
781
  enum?: EnumValues;
755
782
  should_backfill?: boolean;
783
+ format?: FieldFormat;
784
+ field_kind?: FieldKind;
756
785
  }
757
786
  export interface RemoveField {
758
787
  op_type: "remove_field";
@@ -779,6 +808,12 @@ export interface ChangeField {
779
808
  cast_strategy?: CastStrategy | null;
780
809
  using_expression?: string | null;
781
810
  confirm_data_loss?: boolean;
811
+ /** Sets or replaces the field's declared format; `clear_format: true` removes it.
812
+ * Never both in one op. */
813
+ new_format?: FieldFormat;
814
+ clear_format?: boolean;
815
+ /** Sets the field's label. */
816
+ new_field_kind?: FieldKind;
782
817
  }
783
818
  export interface AddRelation {
784
819
  op_type: "add_relation";
@@ -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.22.0";
2
+ export declare const VERSION = "3.24.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.22.0";
2
+ export const VERSION = "3.24.0";
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "xmemory",
3
- "version": "3.22.0",
3
+ "version": "3.24.0",
4
4
  "description": "xmemory",
5
5
  "keywords": [
6
6
  "xmemory"