xmemory 3.2.1 → 3.3.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
@@ -115,9 +115,9 @@ Get a handle to an instance and use it for reads, writes, and extractions.
115
115
  const inst = xm.instance("<instance-id>");
116
116
  ```
117
117
 
118
- ### `inst.write(text, options?)` → `WriteResult`
118
+ ### `inst.write(text | mutations, options?)` → `WriteResult`
119
119
 
120
- Extract and store structured objects from text.
120
+ Extract and store structured objects from text:
121
121
 
122
122
  ```typescript
123
123
  const result = await inst.write("Bob is a designer based in Berlin.");
@@ -127,9 +127,34 @@ console.log(result.changes); // what the write created / updated / deleted
127
127
 
128
128
  Options: `{ extractionLogic?, diffEngine?, timeoutMs? }` — `extractionLogic` defaults to `"fast"`.
129
129
 
130
- ### `inst.writeAsync(text, options?)` → `AsyncWriteResult`
130
+ Or pass a `WriteMutation[]` for **structured writes** — deterministic, LLM-free
131
+ create/update/delete mutations applied in array order (later mutations may
132
+ reference objects created earlier in the batch; a `null` value in `values`
133
+ clears that field):
131
134
 
132
- Start an asynchronous write. Returns a `write_id` for tracking.
135
+ ```typescript
136
+ const result = await inst.write([
137
+ {
138
+ object_mutation: {
139
+ object_type: "person",
140
+ create: { key: { name: "Bob" }, values: { role: "designer" } },
141
+ },
142
+ },
143
+ {
144
+ object_mutation: {
145
+ object_type: "person",
146
+ update: { key: { name: "Bob" }, values: { role: null } }, // null clears
147
+ },
148
+ },
149
+ ]);
150
+ ```
151
+
152
+ Options for the mutations form: `{ timeoutMs? }` (extraction options don't apply).
153
+
154
+ ### `inst.writeAsync(text | mutations, options?)` → `AsyncWriteResult`
155
+
156
+ Start an asynchronous write (same text / `WriteMutation[]` dual input as
157
+ `inst.write`). Returns a `write_id` for tracking.
133
158
 
134
159
  ```typescript
135
160
  const { write_id } = await inst.writeAsync("Carol manages the London office.");
package/dist/index.d.ts CHANGED
@@ -10,5 +10,6 @@ export type { SchemaTypeValue, ExtractionLogic, ReadMode, WriteQueueStatus, Fiel
10
10
  export type { ScopeObject, ReadScope, RelationsScope } from "./types.js";
11
11
  export type { XmemoryClientOptions, RequestOptions, ReadOptions, WriteOptions, ExtractOptions, CreateInstanceOptions, GenerateSchemaOptions, UpdateInstanceSchemaOptions, DryRunMigrationOptions, ListMigrationsOptions, GetMigrationOptions, SuggestionRequestOptions, } from "./types.js";
12
12
  export type { ClusterInfo, InstanceInfo, InstanceSchemaInfo, ReadResult, TaggedReaderResult, WriteResult, AsyncWriteResult, WriteStatusResult, ExtractResult, GenerateSchemaResult, ToolDescription, ToolParameterDescription, RawDescribeResult, } from "./types.js";
13
+ export type { WriteMutation, ObjectMutationBody, ObjectCreatePayload, ObjectUpdatePayload, ObjectDeletePayload, RelationMutationBody, RelationCreatePayload, RelationUpdatePayload, RelationDeletePayload, RelationEndpoint, } from "./types.js";
13
14
  export type { MigrationPlan, MigrationOp, FieldSpec, AddObject, RemoveObject, RenameObject, ChangeObject, AddField, RemoveField, RenameField, ChangeField, AddRelation, RemoveRelation, RenameRelation, ChangeRelation, DefaultValue, EnumValues, } from "./types.js";
14
15
  export type { EnhanceSchemaResult, PlanSummary, DryRunResult, MigrationRecord, ListMigrationsResult, GetMigrationResult, ConsolidatedProposal, ProposalItem, ReviewSuggestionsResult, DecisionInput, RecordedDecision, DependencyWarning, DecideSuggestionsResult, ApplyPendingDecisionsResult, } from "./types.js";
@@ -1,7 +1,7 @@
1
1
  /**
2
2
  * InstanceHandle — scoped data operations on a single xmemory instance.
3
3
  */
4
- import type { ApplyPendingDecisionsResult, AsyncWriteResult, DecideSuggestionsResult, DecisionInput, ExtractOptions, ExtractResult, InstanceSchemaInfo, RawDescribeResult, ReadOptions, ReadResult, RequestOneFn, RequestOptions, ReviewSuggestionsResult, SuggestionRequestOptions, ToolDescription, WriteOptions, WriteResult, WriteStatusResult } from "./types.js";
4
+ import type { ApplyPendingDecisionsResult, AsyncWriteResult, DecideSuggestionsResult, DecisionInput, ExtractOptions, ExtractResult, InstanceSchemaInfo, RawDescribeResult, ReadOptions, ReadResult, RequestOneFn, RequestOptions, ReviewSuggestionsResult, SuggestionRequestOptions, ToolDescription, WriteMutation, WriteOptions, WriteResult, WriteStatusResult } from "./types.js";
5
5
  export declare class DescribeResult {
6
6
  readonly instanceId: string;
7
7
  readonly instanceName: string;
@@ -32,8 +32,23 @@ export declare class InstanceHandle {
32
32
  private _describeTtlMs;
33
33
  constructor(id: string, requestOne: RequestOneFn);
34
34
  read(query: string, options?: ReadOptions): Promise<ReadResult>;
35
+ /**
36
+ * Write to this instance: extract from free text, or apply structured
37
+ * mutations. Pass a string to extract structured data from free-form text,
38
+ * or a `WriteMutation[]` to apply deterministic, LLM-free create / update /
39
+ * delete edits (applied in array order; later mutations may reference
40
+ * objects created earlier in the batch, and a `null` value in a mutation's
41
+ * `values` clears that field). `extractionLogic` / `diffEngine` only apply
42
+ * to the text form.
43
+ */
35
44
  write(text: string, options?: WriteOptions): Promise<WriteResult>;
45
+ write(mutations: readonly WriteMutation[], options?: RequestOptions): Promise<WriteResult>;
46
+ /**
47
+ * Submit a write job and return immediately with a `write_id` for polling.
48
+ * Accepts the same text / `WriteMutation[]` dual input as {@link write}.
49
+ */
36
50
  writeAsync(text: string, options?: WriteOptions): Promise<AsyncWriteResult>;
51
+ writeAsync(mutations: readonly WriteMutation[], options?: RequestOptions): Promise<AsyncWriteResult>;
37
52
  writeStatus(writeId: string, options?: RequestOptions): Promise<WriteStatusResult>;
38
53
  extract(text: string, options?: ExtractOptions): Promise<ExtractResult>;
39
54
  getSchema(options?: RequestOptions): Promise<InstanceSchemaInfo>;
package/dist/instance.js CHANGED
@@ -1,6 +1,24 @@
1
1
  /**
2
2
  * InstanceHandle — scoped data operations on a single xmemory instance.
3
3
  */
4
+ /** Build the shared `/write` + `/write_async` request body for either input mode. */
5
+ function buildWriteBody(input, options) {
6
+ if (typeof input !== "string") {
7
+ if (input.length === 0) {
8
+ throw new Error("structured write requires at least one mutation");
9
+ }
10
+ // Structured path: no text, no extraction options — mutations go straight
11
+ // to the wire.
12
+ return { structured_mutations: input };
13
+ }
14
+ const body = {
15
+ text: input,
16
+ extraction_logic: options?.extractionLogic ?? "fast",
17
+ };
18
+ if (options?.diffEngine != null)
19
+ body.use_diff_engine = options.diffEngine;
20
+ return body;
21
+ }
4
22
  const DEFAULT_DESCRIBE_TTL_MS = 300_000; // 5 minutes
5
23
  export class DescribeResult {
6
24
  instanceId;
@@ -136,27 +154,15 @@ export class InstanceHandle {
136
154
  });
137
155
  return { ...result, reader_results: result.reader_results ?? [] };
138
156
  }
139
- async write(text, options) {
140
- const body = {
141
- text,
142
- extraction_logic: options?.extractionLogic ?? "fast",
143
- };
144
- if (options?.diffEngine != null)
145
- body.diff_engine = options.diffEngine;
157
+ async write(input, options) {
146
158
  return this._requestOne("POST", `/instances/${this.id}/write`, {
147
- body,
159
+ body: buildWriteBody(input, options),
148
160
  timeoutMs: options?.timeoutMs,
149
161
  });
150
162
  }
151
- async writeAsync(text, options) {
152
- const body = {
153
- text,
154
- extraction_logic: options?.extractionLogic ?? "fast",
155
- };
156
- if (options?.diffEngine != null)
157
- body.diff_engine = options.diffEngine;
163
+ async writeAsync(input, options) {
158
164
  return this._requestOne("POST", `/instances/${this.id}/write_async`, {
159
- body,
165
+ body: buildWriteBody(input, options),
160
166
  timeoutMs: options?.timeoutMs,
161
167
  });
162
168
  }
package/dist/types.d.ts CHANGED
@@ -157,6 +157,86 @@ export interface ExtractResult {
157
157
  export interface GenerateSchemaResult {
158
158
  readonly data_schema: Record<string, unknown>;
159
159
  }
160
+ export interface RelationEndpoint {
161
+ /** Relation role name from the instance schema. */
162
+ object_name: string;
163
+ /** Endpoint identity: user primary-key fields (field -> value), or `{ xuid: ... }`. */
164
+ key?: Record<string, unknown>;
165
+ }
166
+ /** Create an object: `key` holds the user primary-key fields (no `xuid` — it is
167
+ * generated server-side), `values` the remaining field values. */
168
+ export interface ObjectCreatePayload {
169
+ key?: Record<string, unknown>;
170
+ values?: Record<string, unknown>;
171
+ }
172
+ /** Update an object identified by `key` (primary-key fields or `{ xuid: ... }`).
173
+ * A `null` value in `values` clears that field. */
174
+ export interface ObjectUpdatePayload {
175
+ key: Record<string, unknown>;
176
+ values: Record<string, unknown>;
177
+ }
178
+ /** Delete the object identified by `key` (primary-key fields or `{ xuid: ... }`). */
179
+ export interface ObjectDeletePayload {
180
+ key: Record<string, unknown>;
181
+ }
182
+ /** Create a relation between the `endpoints`, with optional own-field `values`. */
183
+ export interface RelationCreatePayload {
184
+ endpoints: RelationEndpoint[];
185
+ values?: Record<string, unknown>;
186
+ }
187
+ /** Update a relation's own fields. Address it by `endpoints`, or by
188
+ * `key: { xuid: ... }` when endpoints are ambiguous. A `null` value in `values`
189
+ * clears that field. */
190
+ export interface RelationUpdatePayload {
191
+ key?: Record<string, unknown>;
192
+ endpoints?: RelationEndpoint[];
193
+ values: Record<string, unknown>;
194
+ }
195
+ /** Delete relation(s) matched by `endpoints` (a subset is allowed) or by
196
+ * `key: { xuid: ... }`. Deleting more than one matched row requires
197
+ * `allow_bulk_delete: true`. */
198
+ export interface RelationDeletePayload {
199
+ key?: Record<string, unknown>;
200
+ endpoints?: RelationEndpoint[];
201
+ allow_bulk_delete?: boolean;
202
+ }
203
+ export type ObjectMutationBody = {
204
+ object_type: string;
205
+ } & ({
206
+ create: ObjectCreatePayload;
207
+ update?: never;
208
+ delete?: never;
209
+ } | {
210
+ update: ObjectUpdatePayload;
211
+ create?: never;
212
+ delete?: never;
213
+ } | {
214
+ delete: ObjectDeletePayload;
215
+ create?: never;
216
+ update?: never;
217
+ });
218
+ export type RelationMutationBody = {
219
+ relation_type: string;
220
+ } & ({
221
+ create: RelationCreatePayload;
222
+ update?: never;
223
+ delete?: never;
224
+ } | {
225
+ update: RelationUpdatePayload;
226
+ create?: never;
227
+ delete?: never;
228
+ } | {
229
+ delete: RelationDeletePayload;
230
+ create?: never;
231
+ update?: never;
232
+ });
233
+ export type WriteMutation = {
234
+ object_mutation: ObjectMutationBody;
235
+ relation_mutation?: never;
236
+ } | {
237
+ relation_mutation: RelationMutationBody;
238
+ object_mutation?: never;
239
+ };
160
240
  export type FieldType = "str" | "string" | "int" | "integer" | "float" | "bool" | "boolean";
161
241
  export type OnDelete = "nullify" | "cascade";
162
242
  export type CastStrategy = "safe_implicit" | "explicit_using" | "lossy";
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "xmemory",
3
- "version": "3.2.1",
3
+ "version": "3.3.0",
4
4
  "description": "xmemory",
5
5
  "keywords": [
6
6
  "xmemory"