xmemory 3.13.0 → 3.14.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 +76 -18
- package/dist/cjs/index.d.ts +2 -2
- package/dist/cjs/instance.d.ts +27 -11
- package/dist/cjs/instance.js +14 -1
- package/dist/cjs/types.d.ts +104 -7
- package/dist/cjs/version.d.ts +1 -1
- package/dist/cjs/version.js +1 -1
- package/dist/esm/index.d.ts +2 -2
- package/dist/esm/instance.d.ts +27 -11
- package/dist/esm/instance.js +14 -1
- package/dist/esm/types.d.ts +104 -7
- package/dist/esm/version.d.ts +1 -1
- package/dist/esm/version.js +1 -1
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -195,7 +195,7 @@ Every data operation — `read`, `write`, `writeAsync`, `writeStatus`, `extract`
|
|
|
195
195
|
record, and `null` when the server has no console configured.
|
|
196
196
|
|
|
197
197
|
Options: `{ extractionLogic?, diffEngine?, scope?, timeoutMs? }` — `extractionLogic`
|
|
198
|
-
defaults to `"fast"`; see [Scoped writes](#scoped-writes) for `scope`.
|
|
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
|
|
201
201
|
create/update/delete mutations applied in array order (later mutations may
|
|
@@ -225,7 +225,9 @@ Options for the mutations form: `{ timeoutMs? }` (extraction options don't apply
|
|
|
225
225
|
|
|
226
226
|
Start an asynchronous write (same text / `WriteMutation[]` dual input and the
|
|
227
227
|
same options as `inst.write`, `scope` included). Returns a `write_id` for
|
|
228
|
-
tracking; a scope violation is reported by
|
|
228
|
+
tracking; under the default `"reject"` mode a scope violation is reported by
|
|
229
|
+
`inst.writeStatus` as a failed write, while under `"drop"` the write completes
|
|
230
|
+
and `inst.writeStatus` carries what it skipped.
|
|
229
231
|
|
|
230
232
|
```typescript
|
|
231
233
|
const { write_id } = await inst.writeAsync("Carol manages the London office.");
|
|
@@ -238,8 +240,16 @@ Poll the status of an async write.
|
|
|
238
240
|
```typescript
|
|
239
241
|
const status = await inst.writeStatus(write_id);
|
|
240
242
|
console.log(status.write_status); // "queued" | "processing" | "completed" | "failed" | "not_found"
|
|
243
|
+
if (status.write_status === "completed") {
|
|
244
|
+
console.log(status.changes); // the same report inst.write returns inline
|
|
245
|
+
}
|
|
241
246
|
```
|
|
242
247
|
|
|
248
|
+
A finished write carries `changes`, the async path's only view of what the write
|
|
249
|
+
did — and where a [scoped write](#scoped-writes) in `"drop"` mode reports what it
|
|
250
|
+
left out. A status for a write that has not finished carries none, so the field
|
|
251
|
+
is optional.
|
|
252
|
+
|
|
243
253
|
### `inst.read(query, options?)` → `ReadResult`
|
|
244
254
|
|
|
245
255
|
Query the instance.
|
|
@@ -406,8 +416,8 @@ const result = await inst.read("Does invoice INV-42 exist?", { skipSuggestionCap
|
|
|
406
416
|
|
|
407
417
|
A write is normally free to touch anything in the instance: the extractor sees
|
|
408
418
|
the text alone, and whatever it produces is reconciled against the whole
|
|
409
|
-
instance. Pass a `scope` to anchor a text write to a set of concrete
|
|
410
|
-
|
|
419
|
+
instance. Pass a `scope` to anchor a text write to a set of concrete objects
|
|
420
|
+
instead — the same `ScopeObject` shape as a scoped read:
|
|
411
421
|
|
|
412
422
|
```typescript
|
|
413
423
|
const result = await inst.write(
|
|
@@ -416,19 +426,57 @@ const result = await inst.write(
|
|
|
416
426
|
);
|
|
417
427
|
```
|
|
418
428
|
|
|
419
|
-
|
|
420
|
-
|
|
421
|
-
producing a near-duplicate record. And the write is then **confined** to the
|
|
422
|
-
scope: it may only modify or delete the scoped objects, and create new objects
|
|
423
|
-
and relations anchored to them. A write that would touch any other existing
|
|
424
|
-
object fails with a validation error rather than applying partially — that
|
|
429
|
+
The write is **confined** to the scope: it may only modify or delete the scoped
|
|
430
|
+
objects, and create new objects and relations anchored to them. That
|
|
425
431
|
confinement is checked against the resulting plan, so it holds regardless of
|
|
426
|
-
what the extractor produced.
|
|
432
|
+
what the extractor produced. Extraction itself is unchanged by a scope — it
|
|
433
|
+
runs on the text alone, so the text still names the objects it means.
|
|
427
434
|
|
|
428
435
|
A write scope takes the same `ScopeObject`s as a read scope, identified the same
|
|
429
436
|
way. Unlike a read scope there is no `relationsScope`: the relations among the
|
|
430
437
|
scoped objects always accompany the extraction hint.
|
|
431
438
|
|
|
439
|
+
**What becomes of a change that falls outside the scope is the scope's `mode`.**
|
|
440
|
+
By default (`mode: "reject"`) a write that would touch any other existing object
|
|
441
|
+
fails with a validation error rather than applying partially — the write is
|
|
442
|
+
all-or-nothing, and one stray sentence in the text costs you the whole thing.
|
|
443
|
+
|
|
444
|
+
Pass `mode: "drop"` and it applies anyway. The write runs the plan it would have
|
|
445
|
+
run unscoped, minus every out-of-scope change and every change that depended on
|
|
446
|
+
one, and reports what it left out on `changes.skipped_out_of_scope`:
|
|
447
|
+
|
|
448
|
+
```typescript
|
|
449
|
+
const result = await inst.write(
|
|
450
|
+
"Alice Smith is a surgeon now, and her colleague Bob Lee moved to Rotterdam.",
|
|
451
|
+
{
|
|
452
|
+
scope: {
|
|
453
|
+
objects: [{ type: "Person", key: { full_name: "Alice Smith" } }],
|
|
454
|
+
mode: "drop",
|
|
455
|
+
},
|
|
456
|
+
},
|
|
457
|
+
);
|
|
458
|
+
|
|
459
|
+
for (const skipped of result.changes.skipped_out_of_scope ?? []) {
|
|
460
|
+
console.log(skipped.operation, skipped.object_type_name, skipped.identity, skipped.fields, skipped.count);
|
|
461
|
+
// "update" "Person" "" ["city"] 1
|
|
462
|
+
// ^ empty: the scope never named Bob Lee
|
|
463
|
+
}
|
|
464
|
+
```
|
|
465
|
+
|
|
466
|
+
Dropping only ever *removes* changes. The write never gains a change it would
|
|
467
|
+
not otherwise have made, and never re-points one at a scoped record instead —
|
|
468
|
+
so `"drop"` narrows a write, it does not redirect it. Each entry stands for
|
|
469
|
+
`count` records of one `operation` (`"create"`, `"update"`, `"delete"`,
|
|
470
|
+
`"merge"`, `"link"` or `"unlink"`) on one type, and `identity` renders the
|
|
471
|
+
record's primary key as `field='value'` **only when the scope itself named that
|
|
472
|
+
record**; otherwise it is empty, meaning "some other record of this type". The
|
|
473
|
+
list is omitted when nothing was skipped, so treat `undefined` and `[]` alike.
|
|
474
|
+
|
|
475
|
+
Because a dropped write succeeds, this is also the mode that makes "create or
|
|
476
|
+
update exactly this record" expressible: under `"drop"` a scoped record need not
|
|
477
|
+
be stored yet, and the write creates it if it is missing. Under `"reject"` every
|
|
478
|
+
scoped record must already exist.
|
|
479
|
+
|
|
432
480
|
Things to know before reaching for it:
|
|
433
481
|
|
|
434
482
|
- Scope applies to **text writes only**. The `WriteMutation[]` overload takes
|
|
@@ -437,13 +485,23 @@ Things to know before reaching for it:
|
|
|
437
485
|
anchor to.
|
|
438
486
|
- Only objects of a type with a **user-defined primary key** can be scoped. A
|
|
439
487
|
scope names records by that key, so a type declared `primary_key: []` has
|
|
440
|
-
nothing to name its records by
|
|
441
|
-
|
|
442
|
-
|
|
443
|
-
|
|
444
|
-
-
|
|
445
|
-
|
|
446
|
-
|
|
488
|
+
nothing to name its records by — and `"drop"` never creates a record of such a
|
|
489
|
+
type, for the same reason.
|
|
490
|
+
- `"drop"` is computed by the server's **diff engine**, so asking for it with
|
|
491
|
+
`diffEngine: false` is refused with a 400. `"reject"` has no such requirement.
|
|
492
|
+
- The server caps the number of scoped objects per write, and can have scoped
|
|
493
|
+
writes disabled entirely. Both are server-side rules, so they surface as an
|
|
494
|
+
`XmemoryAPIError`.
|
|
495
|
+
- A scoped write additionally requires **read** permission on the instance: the
|
|
496
|
+
response carries the previous value of every field the write changed,
|
|
497
|
+
resolving a scope answers whether each named object is stored, and a
|
|
498
|
+
drop-mode report says what the skipped changes would have written. An API key
|
|
499
|
+
with write access alone is refused.
|
|
500
|
+
- `mode` is sent only when it changes something: leaving it unset and setting it
|
|
501
|
+
to `"reject"` both put no `mode` on the wire, so naming the default for the
|
|
502
|
+
next reader keeps working against a server that predates the field. A server
|
|
503
|
+
that predates it rejects an unknown body field, so only send `"drop"` to one
|
|
504
|
+
that carries it.
|
|
447
505
|
|
|
448
506
|
### `inst.extract(text, options?)` → `ExtractResult`
|
|
449
507
|
|
package/dist/cjs/index.d.ts
CHANGED
|
@@ -8,9 +8,9 @@ export { XmemoryAPIError, XmemoryHealthCheckError } from "./types.js";
|
|
|
8
8
|
export { SchemaType } from "./types.js";
|
|
9
9
|
export { AgentSurface, BindingTier, FragmentMerge, SetupFormat, StepKind } from "./types.js";
|
|
10
10
|
export type { AgentSetupResult, AgentSetupStep, AgentSetupSurface, AgentSurfaceValue, FragmentMergeValue, ProjectFragment, ProjectSetup, SetupFormatValue, StepKindValue, BindingTierValue, SchemaTypeValue, ExtractionLogic, ReadMode, RelatedTypesMode, RelationCardinality, WriteQueueStatus, FieldType, OnDelete, CastStrategy, DecisionKind, MigrationSource, } from "./types.js";
|
|
11
|
-
export type { ScopeObject, ReadScope, WriteScope, RelationsScope } from "./types.js";
|
|
11
|
+
export type { ScopeObject, ReadScope, WriteScope, RelationsScope, WriteScopeMode } from "./types.js";
|
|
12
12
|
export type { XmemoryClientOptions, RequestOptions, ReadOptions, WriteOptions, ExtractOptions, CreateInstanceOptions, GenerateSchemaOptions, UpdateInstanceMetadataOptions, PatchInstanceMetadataOptions, UpdateInstanceSchemaOptions, DryRunMigrationOptions, ListMigrationsOptions, GetMigrationOptions, SuggestionRequestOptions, } from "./types.js";
|
|
13
|
-
export type { ClusterInfo, InstanceInfo, InstanceSchemaInfo, ReadResult, TaggedReaderResult, RelatedTypes, RelatedTypesTouched, RelatedTypesLink, RelatedTypesObjectType, RelatedTypesRelation, WriteResult, AsyncWriteResult, WriteStatusResult, ExtractResult, GenerateSchemaResult, ToolDescription, ToolParameterDescription, RawDescribeResult, } from "./types.js";
|
|
13
|
+
export type { ClusterInfo, InstanceInfo, InstanceSchemaInfo, ReadResult, TaggedReaderResult, RelatedTypes, RelatedTypesTouched, RelatedTypesLink, RelatedTypesObjectType, RelatedTypesRelation, WriteResult, WriteChanges, SkippedOutOfScope, 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
15
|
export type { MigrationPlan, MigrationOp, FieldSpec, AddObject, RemoveObject, RenameObject, ChangeObject, AddField, RemoveField, RenameField, ChangeField, AddRelation, RemoveRelation, RenameRelation, ChangeRelation, DefaultValue, EnumValues, } from "./types.js";
|
|
16
16
|
export type { EnhanceSchemaResult, PlanSummary, DryRunResult, MigrationRecord, ListMigrationsResult, GetMigrationResult, ConsolidatedProposal, ProposalItem, ReviewSuggestionsResult, DecisionInput, RecordedDecision, DependencyWarning, DecideSuggestionsResult, ApplyPendingDecisionsResult, } from "./types.js";
|
package/dist/cjs/instance.d.ts
CHANGED
|
@@ -70,26 +70,42 @@ export declare class InstanceHandle {
|
|
|
70
70
|
* `values` clears that field). `extractionLogic` / `diffEngine` only apply
|
|
71
71
|
* to the text form.
|
|
72
72
|
*
|
|
73
|
-
* Pass `scope` — a `WriteScope` of concrete
|
|
74
|
-
*
|
|
75
|
-
*
|
|
76
|
-
*
|
|
77
|
-
*
|
|
78
|
-
*
|
|
79
|
-
*
|
|
80
|
-
*
|
|
81
|
-
* the
|
|
73
|
+
* Pass `scope` — a `WriteScope` of concrete objects, each named by its
|
|
74
|
+
* user-defined primary key — to anchor a text write to them. The write is
|
|
75
|
+
* then confined to the scope: it may only modify or delete the scoped objects
|
|
76
|
+
* and create new objects and relations anchored to them. Extraction is
|
|
77
|
+
* unchanged by a scope — it runs on the text alone, so the text still names
|
|
78
|
+
* the objects it means.
|
|
79
|
+
*
|
|
80
|
+
* What becomes of a change that falls outside is the scope's `mode`. Under
|
|
81
|
+
* `"reject"` (the default) a write that would touch any other existing object
|
|
82
|
+
* fails, and nothing applies. Under `"drop"` that change is skipped — along
|
|
83
|
+
* with anything that depended on it — the rest applies, and what was left out
|
|
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 scoped write additionally requires read permission on the instance: the
|
|
89
|
+
* response carries the previous value of every field the write changed,
|
|
90
|
+
* resolving a scope answers whether each named object is stored, and a
|
|
91
|
+
* drop-mode report says what the skipped changes would have written.
|
|
82
92
|
*/
|
|
83
93
|
write(text: string, options?: WriteOptions): Promise<WriteResult>;
|
|
84
94
|
write(mutations: readonly WriteMutation[], options?: RequestOptions): Promise<WriteResult>;
|
|
85
95
|
/**
|
|
86
96
|
* Submit a write job and return immediately with a `write_id` for polling.
|
|
87
97
|
* Accepts the same text / `WriteMutation[]` dual input as {@link write}, and
|
|
88
|
-
* the same `scope`.
|
|
89
|
-
* failed write
|
|
98
|
+
* the same `scope`. Under the default `"reject"` mode a scope violation is
|
|
99
|
+
* reported by {@link writeStatus} as a failed write; under `"drop"` the write
|
|
100
|
+
* completes, and what it skipped rides the completed status as `changes`.
|
|
90
101
|
*/
|
|
91
102
|
writeAsync(text: string, options?: WriteOptions): Promise<AsyncWriteResult>;
|
|
92
103
|
writeAsync(mutations: readonly WriteMutation[], options?: RequestOptions): Promise<AsyncWriteResult>;
|
|
104
|
+
/**
|
|
105
|
+
* Poll a queued write. A finished one carries `changes` — the same report
|
|
106
|
+
* {@link write} returns inline, including what a `"drop"`-mode scope skipped;
|
|
107
|
+
* a status for a write that has not finished carries none.
|
|
108
|
+
*/
|
|
93
109
|
writeStatus(writeId: string, options?: RequestOptions): Promise<WriteStatusResult>;
|
|
94
110
|
extract(text: string, options?: ExtractOptions): Promise<ExtractResult>;
|
|
95
111
|
getSchema(options?: RequestOptions): Promise<InstanceSchemaInfo>;
|
package/dist/cjs/instance.js
CHANGED
|
@@ -36,7 +36,15 @@ function buildWriteBody(input, options) {
|
|
|
36
36
|
if (options?.diffEngine != null)
|
|
37
37
|
body.use_diff_engine = options.diffEngine;
|
|
38
38
|
if (options?.scope != null) {
|
|
39
|
-
|
|
39
|
+
const scope = { objects: serializeScopeObjects(options.scope.objects) };
|
|
40
|
+
// Only a mode that changes something is sent. The server omits `mode` at its
|
|
41
|
+
// default, so a scope that does not ask for `"drop"` stays byte-identical for a
|
|
42
|
+
// server that predates the field — a caller who spells the default out for the
|
|
43
|
+
// next reader does not thereby require a newer deployment.
|
|
44
|
+
if (options.scope.mode != null && options.scope.mode !== "reject") {
|
|
45
|
+
scope.mode = options.scope.mode;
|
|
46
|
+
}
|
|
47
|
+
body.scope = scope;
|
|
40
48
|
}
|
|
41
49
|
return body;
|
|
42
50
|
}
|
|
@@ -280,6 +288,11 @@ class InstanceHandle {
|
|
|
280
288
|
const traceId = own(result, "trace_id");
|
|
281
289
|
return withConsoleUrl({ ...result, trace_id: typeof traceId === "string" ? traceId : null });
|
|
282
290
|
}
|
|
291
|
+
/**
|
|
292
|
+
* Poll a queued write. A finished one carries `changes` — the same report
|
|
293
|
+
* {@link write} returns inline, including what a `"drop"`-mode scope skipped;
|
|
294
|
+
* a status for a write that has not finished carries none.
|
|
295
|
+
*/
|
|
283
296
|
async writeStatus(writeId, options) {
|
|
284
297
|
return withConsoleUrl(await this._requestOne("POST", `/instances/${this.id}/write_status`, { body: { write_id: writeId }, timeoutMs: options?.timeoutMs }));
|
|
285
298
|
}
|
package/dist/cjs/types.d.ts
CHANGED
|
@@ -47,15 +47,48 @@ export interface ReadScope {
|
|
|
47
47
|
relationsScope?: RelationsScope;
|
|
48
48
|
}
|
|
49
49
|
/**
|
|
50
|
-
*
|
|
51
|
-
*
|
|
52
|
-
*
|
|
50
|
+
* What a scoped write does with a change that falls outside its scope.
|
|
51
|
+
*
|
|
52
|
+
* `"reject"` — the server's default — is all-or-nothing: a plan that would
|
|
53
|
+
* touch anything outside the scope fails the whole write, and nothing applies.
|
|
54
|
+
*
|
|
55
|
+
* `"drop"` applies the rest. The write runs the plan it would have run
|
|
56
|
+
* unscoped, minus every out-of-scope change and every change that depended on
|
|
57
|
+
* one, and reports what it left out as
|
|
58
|
+
* {@link WriteChanges.skipped_out_of_scope}. It only ever removes changes: it
|
|
59
|
+
* never adds one and never re-targets one at a scoped record, so `"drop"`
|
|
60
|
+
* narrows a write rather than redirecting it.
|
|
61
|
+
*
|
|
62
|
+
* Two further differences from `"reject"`. A scoped record need not be stored
|
|
63
|
+
* yet — `"drop"` may create a record whose primary key the scope names, which
|
|
64
|
+
* is what makes "create or update exactly this record" expressible, while
|
|
65
|
+
* `"reject"` requires every scoped record to exist already. And a type that
|
|
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.
|
|
69
|
+
*/
|
|
70
|
+
export type WriteScopeMode = "reject" | "drop";
|
|
71
|
+
/**
|
|
72
|
+
* A write's scope: the concrete `objects` the write is anchored to, and what to
|
|
73
|
+
* do with a change that falls outside them. The write is confined to them — it
|
|
53
74
|
* may only modify or delete the scoped objects and create new objects and
|
|
54
|
-
* relations anchored to them.
|
|
55
|
-
* the
|
|
75
|
+
* relations anchored to them. Extraction is unchanged by a scope: it runs on
|
|
76
|
+
* the text alone, so the text still names the objects it means.
|
|
77
|
+
*
|
|
78
|
+
* Unlike `ReadScope`, the second field is not a relation policy: relation
|
|
79
|
+
* changes follow the confinement rule, and there is nothing to choose. It is
|
|
80
|
+
* the out-of-scope `mode`, which decides whether the write fails or reports
|
|
81
|
+
* what it skipped.
|
|
56
82
|
*/
|
|
57
83
|
export interface WriteScope {
|
|
58
84
|
objects: ScopeObject[];
|
|
85
|
+
/**
|
|
86
|
+
* `"reject"` by default. Left unset — or set to `"reject"` — nothing is sent,
|
|
87
|
+
* so naming the default for the reader's sake still leaves the request
|
|
88
|
+
* byte-identical for a server that predates the field. See
|
|
89
|
+
* {@link WriteScopeMode}.
|
|
90
|
+
*/
|
|
91
|
+
mode?: WriteScopeMode;
|
|
59
92
|
}
|
|
60
93
|
export type WriteQueueStatus = "queued" | "processing" | "extracting" | "extracted" | "applying" | "completed" | "failed" | "not_found";
|
|
61
94
|
export declare class XmemoryAPIError extends Error {
|
|
@@ -344,13 +377,66 @@ export interface ReadResult {
|
|
|
344
377
|
*/
|
|
345
378
|
readonly related_types: RelatedTypes | null;
|
|
346
379
|
}
|
|
380
|
+
/**
|
|
381
|
+
* One bundle of changes a `"drop"`-mode scoped write left out instead of
|
|
382
|
+
* applying: one operation on one type, standing for `count` records.
|
|
383
|
+
*/
|
|
384
|
+
export interface SkippedOutOfScope {
|
|
385
|
+
/**
|
|
386
|
+
* What the skipped changes would have done. `"link"` / `"unlink"` are
|
|
387
|
+
* relation changes, the rest object ones.
|
|
388
|
+
*
|
|
389
|
+
* Widened with `(string & {})` like the advisory values further down this
|
|
390
|
+
* file, so an operation named by a server newer than this release is still
|
|
391
|
+
* typed rather than rejected. One you do not recognise still means the same
|
|
392
|
+
* thing — something was skipped — so report it rather than dropping the entry.
|
|
393
|
+
*/
|
|
394
|
+
readonly operation: "create" | "update" | "delete" | "merge" | "link" | "unlink" | (string & {});
|
|
395
|
+
/** The object type, or the relation type for `"link"` / `"unlink"`. */
|
|
396
|
+
readonly object_type_name: string;
|
|
397
|
+
/**
|
|
398
|
+
* The skipped record's primary key, rendered `field='value'` — and **empty
|
|
399
|
+
* unless the scope itself named that record**. The server identifies a record
|
|
400
|
+
* here only when the caller already knew of it, so an empty string reads as
|
|
401
|
+
* "some other record of this type", not as "a record with no key".
|
|
402
|
+
*/
|
|
403
|
+
readonly identity: string;
|
|
404
|
+
/** The field names the skipped changes would have written. */
|
|
405
|
+
readonly fields: readonly string[];
|
|
406
|
+
/** How many records this entry stands for. */
|
|
407
|
+
readonly count: number;
|
|
408
|
+
}
|
|
409
|
+
/**
|
|
410
|
+
* What a write did, grouped into `created` / `updated` / `deleted`, plus what a
|
|
411
|
+
* `"drop"`-mode scope left out.
|
|
412
|
+
*
|
|
413
|
+
* The three groups stay `unknown`: their shape is the server's to evolve and
|
|
414
|
+
* this client has never modelled it. `skipped_out_of_scope` is typed because it
|
|
415
|
+
* is the one part a caller has to branch on — a `"drop"`-mode write succeeds
|
|
416
|
+
* whether or not it skipped anything, so this list is the only report that some
|
|
417
|
+
* of what the text said was not applied.
|
|
418
|
+
*/
|
|
419
|
+
export interface WriteChanges {
|
|
420
|
+
readonly created: unknown;
|
|
421
|
+
readonly updated: unknown;
|
|
422
|
+
readonly deleted: unknown;
|
|
423
|
+
/**
|
|
424
|
+
* Omitted by the server when nothing was skipped — which is every write that
|
|
425
|
+
* did not ask for `"drop"` — so `undefined` and `[]` both mean "nothing left
|
|
426
|
+
* out". Branch on whether there are entries, not on whether the key is there.
|
|
427
|
+
*/
|
|
428
|
+
readonly skipped_out_of_scope?: readonly SkippedOutOfScope[];
|
|
429
|
+
}
|
|
347
430
|
export interface WriteResult {
|
|
348
431
|
readonly write_id: string;
|
|
349
432
|
readonly trace_id: string | null;
|
|
350
433
|
/** Deep link to this write's trace in the console; `null` if no console is configured. */
|
|
351
434
|
readonly console_url: string | null;
|
|
352
|
-
/**
|
|
353
|
-
|
|
435
|
+
/**
|
|
436
|
+
* What the write did, grouped into `created` / `updated` / `deleted`, and —
|
|
437
|
+
* for a scoped write in `"drop"` mode — what it skipped instead of applying.
|
|
438
|
+
*/
|
|
439
|
+
readonly changes: WriteChanges;
|
|
354
440
|
}
|
|
355
441
|
export interface AsyncWriteResult {
|
|
356
442
|
readonly write_id: string;
|
|
@@ -366,6 +452,17 @@ export interface WriteStatusResult {
|
|
|
366
452
|
readonly console_url: string | null;
|
|
367
453
|
readonly error_detail: string | null;
|
|
368
454
|
readonly completed_at: string | null;
|
|
455
|
+
/**
|
|
456
|
+
* What the finished write did, in the same shape {@link WriteResult.changes}
|
|
457
|
+
* carries — and the async caller's only view of it, since `writeAsync`
|
|
458
|
+
* returns before the write has done anything. It is therefore where a
|
|
459
|
+
* `"drop"`-mode scope reports what it skipped.
|
|
460
|
+
*
|
|
461
|
+
* Optional because a status is not always about a finished write: a queued,
|
|
462
|
+
* in-progress, failed or unknown `write_id` carries none. Read it once
|
|
463
|
+
* `write_status` is `"completed"`.
|
|
464
|
+
*/
|
|
465
|
+
readonly changes?: WriteChanges;
|
|
369
466
|
}
|
|
370
467
|
export interface ExtractResult {
|
|
371
468
|
readonly trace_id: string | null;
|
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.14.0";
|
package/dist/cjs/version.js
CHANGED
package/dist/esm/index.d.ts
CHANGED
|
@@ -8,9 +8,9 @@ export { XmemoryAPIError, XmemoryHealthCheckError } from "./types.js";
|
|
|
8
8
|
export { SchemaType } from "./types.js";
|
|
9
9
|
export { AgentSurface, BindingTier, FragmentMerge, SetupFormat, StepKind } from "./types.js";
|
|
10
10
|
export type { AgentSetupResult, AgentSetupStep, AgentSetupSurface, AgentSurfaceValue, FragmentMergeValue, ProjectFragment, ProjectSetup, SetupFormatValue, StepKindValue, BindingTierValue, SchemaTypeValue, ExtractionLogic, ReadMode, RelatedTypesMode, RelationCardinality, WriteQueueStatus, FieldType, OnDelete, CastStrategy, DecisionKind, MigrationSource, } from "./types.js";
|
|
11
|
-
export type { ScopeObject, ReadScope, WriteScope, RelationsScope } from "./types.js";
|
|
11
|
+
export type { ScopeObject, ReadScope, WriteScope, RelationsScope, WriteScopeMode } from "./types.js";
|
|
12
12
|
export type { XmemoryClientOptions, RequestOptions, ReadOptions, WriteOptions, ExtractOptions, CreateInstanceOptions, GenerateSchemaOptions, UpdateInstanceMetadataOptions, PatchInstanceMetadataOptions, UpdateInstanceSchemaOptions, DryRunMigrationOptions, ListMigrationsOptions, GetMigrationOptions, SuggestionRequestOptions, } from "./types.js";
|
|
13
|
-
export type { ClusterInfo, InstanceInfo, InstanceSchemaInfo, ReadResult, TaggedReaderResult, RelatedTypes, RelatedTypesTouched, RelatedTypesLink, RelatedTypesObjectType, RelatedTypesRelation, WriteResult, AsyncWriteResult, WriteStatusResult, ExtractResult, GenerateSchemaResult, ToolDescription, ToolParameterDescription, RawDescribeResult, } from "./types.js";
|
|
13
|
+
export type { ClusterInfo, InstanceInfo, InstanceSchemaInfo, ReadResult, TaggedReaderResult, RelatedTypes, RelatedTypesTouched, RelatedTypesLink, RelatedTypesObjectType, RelatedTypesRelation, WriteResult, WriteChanges, SkippedOutOfScope, 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
15
|
export type { MigrationPlan, MigrationOp, FieldSpec, AddObject, RemoveObject, RenameObject, ChangeObject, AddField, RemoveField, RenameField, ChangeField, AddRelation, RemoveRelation, RenameRelation, ChangeRelation, DefaultValue, EnumValues, } from "./types.js";
|
|
16
16
|
export type { EnhanceSchemaResult, PlanSummary, DryRunResult, MigrationRecord, ListMigrationsResult, GetMigrationResult, ConsolidatedProposal, ProposalItem, ReviewSuggestionsResult, DecisionInput, RecordedDecision, DependencyWarning, DecideSuggestionsResult, ApplyPendingDecisionsResult, } from "./types.js";
|
package/dist/esm/instance.d.ts
CHANGED
|
@@ -70,26 +70,42 @@ export declare class InstanceHandle {
|
|
|
70
70
|
* `values` clears that field). `extractionLogic` / `diffEngine` only apply
|
|
71
71
|
* to the text form.
|
|
72
72
|
*
|
|
73
|
-
* Pass `scope` — a `WriteScope` of concrete
|
|
74
|
-
*
|
|
75
|
-
*
|
|
76
|
-
*
|
|
77
|
-
*
|
|
78
|
-
*
|
|
79
|
-
*
|
|
80
|
-
*
|
|
81
|
-
* the
|
|
73
|
+
* Pass `scope` — a `WriteScope` of concrete objects, each named by its
|
|
74
|
+
* user-defined primary key — to anchor a text write to them. The write is
|
|
75
|
+
* then confined to the scope: it may only modify or delete the scoped objects
|
|
76
|
+
* and create new objects and relations anchored to them. Extraction is
|
|
77
|
+
* unchanged by a scope — it runs on the text alone, so the text still names
|
|
78
|
+
* the objects it means.
|
|
79
|
+
*
|
|
80
|
+
* What becomes of a change that falls outside is the scope's `mode`. Under
|
|
81
|
+
* `"reject"` (the default) a write that would touch any other existing object
|
|
82
|
+
* fails, and nothing applies. Under `"drop"` that change is skipped — along
|
|
83
|
+
* with anything that depended on it — the rest applies, and what was left out
|
|
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 scoped write additionally requires read permission on the instance: the
|
|
89
|
+
* response carries the previous value of every field the write changed,
|
|
90
|
+
* resolving a scope answers whether each named object is stored, and a
|
|
91
|
+
* drop-mode report says what the skipped changes would have written.
|
|
82
92
|
*/
|
|
83
93
|
write(text: string, options?: WriteOptions): Promise<WriteResult>;
|
|
84
94
|
write(mutations: readonly WriteMutation[], options?: RequestOptions): Promise<WriteResult>;
|
|
85
95
|
/**
|
|
86
96
|
* Submit a write job and return immediately with a `write_id` for polling.
|
|
87
97
|
* Accepts the same text / `WriteMutation[]` dual input as {@link write}, and
|
|
88
|
-
* the same `scope`.
|
|
89
|
-
* failed write
|
|
98
|
+
* the same `scope`. Under the default `"reject"` mode a scope violation is
|
|
99
|
+
* reported by {@link writeStatus} as a failed write; under `"drop"` the write
|
|
100
|
+
* completes, and what it skipped rides the completed status as `changes`.
|
|
90
101
|
*/
|
|
91
102
|
writeAsync(text: string, options?: WriteOptions): Promise<AsyncWriteResult>;
|
|
92
103
|
writeAsync(mutations: readonly WriteMutation[], options?: RequestOptions): Promise<AsyncWriteResult>;
|
|
104
|
+
/**
|
|
105
|
+
* Poll a queued write. A finished one carries `changes` — the same report
|
|
106
|
+
* {@link write} returns inline, including what a `"drop"`-mode scope skipped;
|
|
107
|
+
* a status for a write that has not finished carries none.
|
|
108
|
+
*/
|
|
93
109
|
writeStatus(writeId: string, options?: RequestOptions): Promise<WriteStatusResult>;
|
|
94
110
|
extract(text: string, options?: ExtractOptions): Promise<ExtractResult>;
|
|
95
111
|
getSchema(options?: RequestOptions): Promise<InstanceSchemaInfo>;
|
package/dist/esm/instance.js
CHANGED
|
@@ -33,7 +33,15 @@ function buildWriteBody(input, options) {
|
|
|
33
33
|
if (options?.diffEngine != null)
|
|
34
34
|
body.use_diff_engine = options.diffEngine;
|
|
35
35
|
if (options?.scope != null) {
|
|
36
|
-
|
|
36
|
+
const scope = { objects: serializeScopeObjects(options.scope.objects) };
|
|
37
|
+
// Only a mode that changes something is sent. The server omits `mode` at its
|
|
38
|
+
// default, so a scope that does not ask for `"drop"` stays byte-identical for a
|
|
39
|
+
// server that predates the field — a caller who spells the default out for the
|
|
40
|
+
// next reader does not thereby require a newer deployment.
|
|
41
|
+
if (options.scope.mode != null && options.scope.mode !== "reject") {
|
|
42
|
+
scope.mode = options.scope.mode;
|
|
43
|
+
}
|
|
44
|
+
body.scope = scope;
|
|
37
45
|
}
|
|
38
46
|
return body;
|
|
39
47
|
}
|
|
@@ -276,6 +284,11 @@ export class InstanceHandle {
|
|
|
276
284
|
const traceId = own(result, "trace_id");
|
|
277
285
|
return withConsoleUrl({ ...result, trace_id: typeof traceId === "string" ? traceId : null });
|
|
278
286
|
}
|
|
287
|
+
/**
|
|
288
|
+
* Poll a queued write. A finished one carries `changes` — the same report
|
|
289
|
+
* {@link write} returns inline, including what a `"drop"`-mode scope skipped;
|
|
290
|
+
* a status for a write that has not finished carries none.
|
|
291
|
+
*/
|
|
279
292
|
async writeStatus(writeId, options) {
|
|
280
293
|
return withConsoleUrl(await this._requestOne("POST", `/instances/${this.id}/write_status`, { body: { write_id: writeId }, timeoutMs: options?.timeoutMs }));
|
|
281
294
|
}
|
package/dist/esm/types.d.ts
CHANGED
|
@@ -47,15 +47,48 @@ export interface ReadScope {
|
|
|
47
47
|
relationsScope?: RelationsScope;
|
|
48
48
|
}
|
|
49
49
|
/**
|
|
50
|
-
*
|
|
51
|
-
*
|
|
52
|
-
*
|
|
50
|
+
* What a scoped write does with a change that falls outside its scope.
|
|
51
|
+
*
|
|
52
|
+
* `"reject"` — the server's default — is all-or-nothing: a plan that would
|
|
53
|
+
* touch anything outside the scope fails the whole write, and nothing applies.
|
|
54
|
+
*
|
|
55
|
+
* `"drop"` applies the rest. The write runs the plan it would have run
|
|
56
|
+
* unscoped, minus every out-of-scope change and every change that depended on
|
|
57
|
+
* one, and reports what it left out as
|
|
58
|
+
* {@link WriteChanges.skipped_out_of_scope}. It only ever removes changes: it
|
|
59
|
+
* never adds one and never re-targets one at a scoped record, so `"drop"`
|
|
60
|
+
* narrows a write rather than redirecting it.
|
|
61
|
+
*
|
|
62
|
+
* Two further differences from `"reject"`. A scoped record need not be stored
|
|
63
|
+
* yet — `"drop"` may create a record whose primary key the scope names, which
|
|
64
|
+
* is what makes "create or update exactly this record" expressible, while
|
|
65
|
+
* `"reject"` requires every scoped record to exist already. And a type that
|
|
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.
|
|
69
|
+
*/
|
|
70
|
+
export type WriteScopeMode = "reject" | "drop";
|
|
71
|
+
/**
|
|
72
|
+
* A write's scope: the concrete `objects` the write is anchored to, and what to
|
|
73
|
+
* do with a change that falls outside them. The write is confined to them — it
|
|
53
74
|
* may only modify or delete the scoped objects and create new objects and
|
|
54
|
-
* relations anchored to them.
|
|
55
|
-
* the
|
|
75
|
+
* relations anchored to them. Extraction is unchanged by a scope: it runs on
|
|
76
|
+
* the text alone, so the text still names the objects it means.
|
|
77
|
+
*
|
|
78
|
+
* Unlike `ReadScope`, the second field is not a relation policy: relation
|
|
79
|
+
* changes follow the confinement rule, and there is nothing to choose. It is
|
|
80
|
+
* the out-of-scope `mode`, which decides whether the write fails or reports
|
|
81
|
+
* what it skipped.
|
|
56
82
|
*/
|
|
57
83
|
export interface WriteScope {
|
|
58
84
|
objects: ScopeObject[];
|
|
85
|
+
/**
|
|
86
|
+
* `"reject"` by default. Left unset — or set to `"reject"` — nothing is sent,
|
|
87
|
+
* so naming the default for the reader's sake still leaves the request
|
|
88
|
+
* byte-identical for a server that predates the field. See
|
|
89
|
+
* {@link WriteScopeMode}.
|
|
90
|
+
*/
|
|
91
|
+
mode?: WriteScopeMode;
|
|
59
92
|
}
|
|
60
93
|
export type WriteQueueStatus = "queued" | "processing" | "extracting" | "extracted" | "applying" | "completed" | "failed" | "not_found";
|
|
61
94
|
export declare class XmemoryAPIError extends Error {
|
|
@@ -344,13 +377,66 @@ export interface ReadResult {
|
|
|
344
377
|
*/
|
|
345
378
|
readonly related_types: RelatedTypes | null;
|
|
346
379
|
}
|
|
380
|
+
/**
|
|
381
|
+
* One bundle of changes a `"drop"`-mode scoped write left out instead of
|
|
382
|
+
* applying: one operation on one type, standing for `count` records.
|
|
383
|
+
*/
|
|
384
|
+
export interface SkippedOutOfScope {
|
|
385
|
+
/**
|
|
386
|
+
* What the skipped changes would have done. `"link"` / `"unlink"` are
|
|
387
|
+
* relation changes, the rest object ones.
|
|
388
|
+
*
|
|
389
|
+
* Widened with `(string & {})` like the advisory values further down this
|
|
390
|
+
* file, so an operation named by a server newer than this release is still
|
|
391
|
+
* typed rather than rejected. One you do not recognise still means the same
|
|
392
|
+
* thing — something was skipped — so report it rather than dropping the entry.
|
|
393
|
+
*/
|
|
394
|
+
readonly operation: "create" | "update" | "delete" | "merge" | "link" | "unlink" | (string & {});
|
|
395
|
+
/** The object type, or the relation type for `"link"` / `"unlink"`. */
|
|
396
|
+
readonly object_type_name: string;
|
|
397
|
+
/**
|
|
398
|
+
* The skipped record's primary key, rendered `field='value'` — and **empty
|
|
399
|
+
* unless the scope itself named that record**. The server identifies a record
|
|
400
|
+
* here only when the caller already knew of it, so an empty string reads as
|
|
401
|
+
* "some other record of this type", not as "a record with no key".
|
|
402
|
+
*/
|
|
403
|
+
readonly identity: string;
|
|
404
|
+
/** The field names the skipped changes would have written. */
|
|
405
|
+
readonly fields: readonly string[];
|
|
406
|
+
/** How many records this entry stands for. */
|
|
407
|
+
readonly count: number;
|
|
408
|
+
}
|
|
409
|
+
/**
|
|
410
|
+
* What a write did, grouped into `created` / `updated` / `deleted`, plus what a
|
|
411
|
+
* `"drop"`-mode scope left out.
|
|
412
|
+
*
|
|
413
|
+
* The three groups stay `unknown`: their shape is the server's to evolve and
|
|
414
|
+
* this client has never modelled it. `skipped_out_of_scope` is typed because it
|
|
415
|
+
* is the one part a caller has to branch on — a `"drop"`-mode write succeeds
|
|
416
|
+
* whether or not it skipped anything, so this list is the only report that some
|
|
417
|
+
* of what the text said was not applied.
|
|
418
|
+
*/
|
|
419
|
+
export interface WriteChanges {
|
|
420
|
+
readonly created: unknown;
|
|
421
|
+
readonly updated: unknown;
|
|
422
|
+
readonly deleted: unknown;
|
|
423
|
+
/**
|
|
424
|
+
* Omitted by the server when nothing was skipped — which is every write that
|
|
425
|
+
* did not ask for `"drop"` — so `undefined` and `[]` both mean "nothing left
|
|
426
|
+
* out". Branch on whether there are entries, not on whether the key is there.
|
|
427
|
+
*/
|
|
428
|
+
readonly skipped_out_of_scope?: readonly SkippedOutOfScope[];
|
|
429
|
+
}
|
|
347
430
|
export interface WriteResult {
|
|
348
431
|
readonly write_id: string;
|
|
349
432
|
readonly trace_id: string | null;
|
|
350
433
|
/** Deep link to this write's trace in the console; `null` if no console is configured. */
|
|
351
434
|
readonly console_url: string | null;
|
|
352
|
-
/**
|
|
353
|
-
|
|
435
|
+
/**
|
|
436
|
+
* What the write did, grouped into `created` / `updated` / `deleted`, and —
|
|
437
|
+
* for a scoped write in `"drop"` mode — what it skipped instead of applying.
|
|
438
|
+
*/
|
|
439
|
+
readonly changes: WriteChanges;
|
|
354
440
|
}
|
|
355
441
|
export interface AsyncWriteResult {
|
|
356
442
|
readonly write_id: string;
|
|
@@ -366,6 +452,17 @@ export interface WriteStatusResult {
|
|
|
366
452
|
readonly console_url: string | null;
|
|
367
453
|
readonly error_detail: string | null;
|
|
368
454
|
readonly completed_at: string | null;
|
|
455
|
+
/**
|
|
456
|
+
* What the finished write did, in the same shape {@link WriteResult.changes}
|
|
457
|
+
* carries — and the async caller's only view of it, since `writeAsync`
|
|
458
|
+
* returns before the write has done anything. It is therefore where a
|
|
459
|
+
* `"drop"`-mode scope reports what it skipped.
|
|
460
|
+
*
|
|
461
|
+
* Optional because a status is not always about a finished write: a queued,
|
|
462
|
+
* in-progress, failed or unknown `write_id` carries none. Read it once
|
|
463
|
+
* `write_status` is `"completed"`.
|
|
464
|
+
*/
|
|
465
|
+
readonly changes?: WriteChanges;
|
|
369
466
|
}
|
|
370
467
|
export interface ExtractResult {
|
|
371
468
|
readonly trace_id: string | null;
|
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.14.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.14.0";
|