xmemory 3.15.0 → 3.20.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 +115 -11
- package/dist/cjs/client.d.ts +14 -0
- package/dist/cjs/client.js +6 -0
- package/dist/cjs/index.d.ts +1 -1
- package/dist/cjs/instance.d.ts +19 -2
- package/dist/cjs/instance.js +12 -3
- package/dist/cjs/types.d.ts +114 -18
- package/dist/cjs/version.d.ts +1 -1
- package/dist/cjs/version.js +1 -1
- package/dist/esm/client.d.ts +14 -0
- package/dist/esm/client.js +6 -0
- package/dist/esm/index.d.ts +1 -1
- package/dist/esm/instance.d.ts +19 -2
- package/dist/esm/instance.js +12 -3
- package/dist/esm/types.d.ts +114 -18
- package/dist/esm/version.d.ts +1 -1
- package/dist/esm/version.js +1 -1
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -247,8 +247,92 @@ if (status.write_status === "completed") {
|
|
|
247
247
|
|
|
248
248
|
A finished write carries `changes`, the async path's only view of what the write
|
|
249
249
|
did — and where a [scoped write](#scoped-writes) in `"drop"` mode reports what it
|
|
250
|
-
left out
|
|
251
|
-
is optional.
|
|
250
|
+
left out, and a [field merge](#mergeable-text-fields) what it chose between. A
|
|
251
|
+
status for a write that has not finished carries none, so the field is optional.
|
|
252
|
+
|
|
253
|
+
### Write ordering
|
|
254
|
+
|
|
255
|
+
Every write to an instance goes into one queue for that instance: `write` and
|
|
256
|
+
`writeAsync`, text and `WriteMutation[]` alike. Queued writes are processed in
|
|
257
|
+
parallel, but applied to the instance one at a time, in the order they were
|
|
258
|
+
queued (FIFO). A write is never applied ahead of an older one, even when its own
|
|
259
|
+
processing finished first.
|
|
260
|
+
|
|
261
|
+
- `writeAsync` resolves once the write is queued. `writeStatus` reports
|
|
262
|
+
`"queued"` until processing starts, and `"extracted"` while a processed write
|
|
263
|
+
waits for older writes to be applied.
|
|
264
|
+
- `write` waits in the same queue and resolves once its own write is applied.
|
|
265
|
+
It does not jump ahead of async writes queued before it.
|
|
266
|
+
- The order is the order the server receives the writes. Two writes sent at
|
|
267
|
+
the same time have no defined order between them, so when one must apply
|
|
268
|
+
after another, await the first call (`writeAsync` resolving with its
|
|
269
|
+
`write_id` is enough) before sending the second.
|
|
270
|
+
- Reads are not queued: a read sees only writes that have completed.
|
|
271
|
+
|
|
272
|
+
```typescript
|
|
273
|
+
await inst.writeAsync("Bob joined the team as a designer.");
|
|
274
|
+
await inst.writeAsync("Bob moved to the London office.");
|
|
275
|
+
// Applied after both writes above, in order.
|
|
276
|
+
await inst.write([
|
|
277
|
+
{
|
|
278
|
+
object_mutation: {
|
|
279
|
+
object_type: "person",
|
|
280
|
+
update: { key: { name: "Bob" }, values: { role: "lead designer" } },
|
|
281
|
+
},
|
|
282
|
+
},
|
|
283
|
+
]);
|
|
284
|
+
```
|
|
285
|
+
|
|
286
|
+
### Mergeable text fields
|
|
287
|
+
|
|
288
|
+
By default a write replaces a field's stored value. A `str` field that is not
|
|
289
|
+
part of the primary key can instead declare a `merge` in the schema, so a later
|
|
290
|
+
text write merges its value into the text already stored. A server from before
|
|
291
|
+
field merges keeps the block but ignores it, and replaces the value as before:
|
|
292
|
+
|
|
293
|
+
```yaml
|
|
294
|
+
next_steps:
|
|
295
|
+
type: str
|
|
296
|
+
description: what is still to be done on the project, one step per line
|
|
297
|
+
merge:
|
|
298
|
+
rules:
|
|
299
|
+
- Keep every step that is still open.
|
|
300
|
+
- Drop a step the text says is done.
|
|
301
|
+
max_length: 400
|
|
302
|
+
```
|
|
303
|
+
|
|
304
|
+
- `max_length` is required, a whole number from 1 to 20,000: the length the
|
|
305
|
+
merge keeps the text within. `rules` is optional: up to 50 non-empty lines of
|
|
306
|
+
at most 1,000 characters each. `merge` takes no other key, and a schema that
|
|
307
|
+
breaks any of this is refused.
|
|
308
|
+
- With `rules`, the server merges the new value into the stored one by those
|
|
309
|
+
rules, within the cap.
|
|
310
|
+
- Without `rules`, the new value is appended on its own line, leaving out lines
|
|
311
|
+
whose facts are already stated; past the cap, the text is shortened, keeping
|
|
312
|
+
every fact.
|
|
313
|
+
- If a merge cannot be made, the new value is appended, even past the cap, and
|
|
314
|
+
nothing stored is cut.
|
|
315
|
+
- Only text writes merge, through the server's diff engine. A text write that
|
|
316
|
+
runs without it on such a schema — `diffEngine: false`, or a connection whose
|
|
317
|
+
default is off — is refused with a 400 `VALIDATION_ERROR`; through
|
|
318
|
+
`writeAsync` it is queued and fails, which `writeStatus` reports.
|
|
319
|
+
`WriteMutation[]` writes replace the value as given.
|
|
320
|
+
- Adding, changing or removing a `merge` is a metadata-only schema change.
|
|
321
|
+
|
|
322
|
+
Where a merge that changed the field found the new value contradicting the
|
|
323
|
+
stored one, `changes.merge_contradictions` says what each said and which one it
|
|
324
|
+
kept (`FieldMergeContradiction`):
|
|
325
|
+
|
|
326
|
+
```typescript
|
|
327
|
+
const result = await inst.write("The Harbour Wall survey moved to 10 March.");
|
|
328
|
+
for (const c of result.changes.merge_contradictions ?? []) {
|
|
329
|
+
console.log(c.object_type_name, c.identity, c.field, c.stored, "->", c.new, "kept:", c.kept);
|
|
330
|
+
}
|
|
331
|
+
```
|
|
332
|
+
|
|
333
|
+
The key is omitted when there is no such entry. An absent key does not prove the
|
|
334
|
+
texts agreed: a merge that failed, fell back to appending, or left the stored
|
|
335
|
+
text unchanged reports none.
|
|
252
336
|
|
|
253
337
|
### `inst.read(query, options?)` → `ReadResult`
|
|
254
338
|
|
|
@@ -264,13 +348,14 @@ Options: `{ readMode?, scope?, includeRelatedTypes?, relatedTypesDepth?, skipSug
|
|
|
264
348
|
#### What comes back
|
|
265
349
|
|
|
266
350
|
In `"single-answer"` mode `reader_result` is always the prose answer. In
|
|
267
|
-
`"raw-tables"` and `"xresponse"` mode its value says which of
|
|
351
|
+
`"raw-tables"` and `"xresponse"` mode its value says which of five answers the
|
|
268
352
|
read gave:
|
|
269
353
|
|
|
270
354
|
| `reader_result` | Meaning | What to do |
|
|
271
355
|
| --- | --- | --- |
|
|
272
356
|
| rows | Answered. | Use them. |
|
|
273
|
-
| exactly `{ columns: [], rows: [] }` / `{ objects: [], relations: [] }` | The query executed and matched nothing — every table and column it used exists, so the data is absent. | Trust the empty result. |
|
|
357
|
+
| exactly `{ columns: [], rows: [] }` / `{ objects: [], relations: [] }`, `notice` is `null` | The query executed and matched nothing — every table and column it used exists, so the data is absent. | Trust the empty result. |
|
|
358
|
+
| the same empty value, `notice` set | The server could not run a query that answers the question as asked, so the empty value says nothing about what is stored. | Rephrase the question, for example by naming the exact value to look up. Do not treat the data as absent. |
|
|
274
359
|
| `null` | The schema provably cannot represent the concept. An answer, not a variant of the empty one. | Try a better-matching instance; this memory cannot hold it. |
|
|
275
360
|
| *(throws)* | Every sub-query's SQL failed, so nothing was answered. | Catch `XmemoryAPIError` with `status` 422 and `code` `"INVALID_INPUT"`. It is the same answer for the same input, so do not retry it. |
|
|
276
361
|
|
|
@@ -278,6 +363,8 @@ read gave:
|
|
|
278
363
|
const result = await inst.read("Which invoices are overdue?", { readMode: "raw-tables" });
|
|
279
364
|
if (result.reader_result === null) {
|
|
280
365
|
// Not a concept this memory holds — try another instance.
|
|
366
|
+
} else if (result.notice !== null) {
|
|
367
|
+
// Not answered as asked — rephrase; the data may well be stored.
|
|
281
368
|
} else {
|
|
282
369
|
const { rows } = result.reader_result as { columns: string[]; rows: unknown[][] };
|
|
283
370
|
// rows.length === 0 means the data is absent, not that the read failed.
|
|
@@ -289,7 +376,7 @@ if (result.reader_result === null) {
|
|
|
289
376
|
When a query bundles several independent questions, the server may decompose it
|
|
290
377
|
into sub-queries and answer each one. `reader_result` is still the combined
|
|
291
378
|
answer (for `"single-answer"` mode, a labelled multi-part string); `reader_results`
|
|
292
|
-
holds one `TaggedReaderResult` (`{ sub_query, reader_result, error }`) per
|
|
379
|
+
holds one `TaggedReaderResult` (`{ sub_query, reader_result, error, notice }`) per
|
|
293
380
|
sub-query so you can read each answer unambiguously — a single-intent query
|
|
294
381
|
decomposes to one entry. `reader_results` is always an array: a server without
|
|
295
382
|
question decomposition omits the field on the wire and the client normalizes it
|
|
@@ -302,14 +389,16 @@ for (const part of result.reader_results) {
|
|
|
302
389
|
}
|
|
303
390
|
```
|
|
304
391
|
|
|
305
|
-
Each part's `reader_result` uses the same
|
|
392
|
+
Each part's `reader_result` uses the same five answers as above, with one more
|
|
306
393
|
case: a sub-query whose SQL failed carries the empty result *and* a user-safe
|
|
307
394
|
`error`, while the others are answered regardless. Its bytes then equal those
|
|
308
395
|
of a sub-query that matched nothing, so read `error` before `reader_result`, as
|
|
309
396
|
the loop above does. The combined `reader_result` folds the parts: rows if any
|
|
310
|
-
sub-query answered; else the empty result if any executed and matched nothing
|
|
311
|
-
|
|
312
|
-
|
|
397
|
+
sub-query answered; else the empty result if any executed and matched nothing,
|
|
398
|
+
or could not be answered as asked; else `null`. The top-level `notice` is set
|
|
399
|
+
when any part could not be answered as asked, even if another part answered,
|
|
400
|
+
so check it before trusting an empty part. In the tabular modes a read where
|
|
401
|
+
*every* sub-query failed throws the 422 above instead.
|
|
313
402
|
|
|
314
403
|
#### Scoped reads
|
|
315
404
|
|
|
@@ -472,6 +561,16 @@ record's primary key as `field='value'` **only when the scope itself named that
|
|
|
472
561
|
record**; otherwise it is empty, meaning "some other record of this type". The
|
|
473
562
|
list is omitted when nothing was skipped, so treat `undefined` and `[]` alike.
|
|
474
563
|
|
|
564
|
+
The list holds at most 100 entries. Past that, entries are kept as they are
|
|
565
|
+
while there is room, those that name a record first, and the rest arrive folded:
|
|
566
|
+
one entry per `operation` and type, marked `folded: true`, with an empty
|
|
567
|
+
`identity`, no `fields` and the summed `count`. When even those would be more
|
|
568
|
+
than 100, none is kept as it was, and the last folded entries are folded once
|
|
569
|
+
more, into one entry per `operation` whose `object_type_name` is empty too.
|
|
570
|
+
Unnamed entries are folded before named ones, but a record the scope named can
|
|
571
|
+
still end up inside a folded entry. Summing `count` per `operation` still gives
|
|
572
|
+
the true totals, and an entry without `folded` means what it always did.
|
|
573
|
+
|
|
475
574
|
Because a dropped write succeeds, this is also the mode that makes "create or
|
|
476
575
|
update exactly this record" expressible: under `"drop"` a scoped record need not
|
|
477
576
|
be stored yet, and the write creates it if it is missing. Under `"reject"` every
|
|
@@ -619,8 +718,8 @@ const xm = new XmemoryClient({ apiKey: "..." });
|
|
|
619
718
|
const current = (await xm.admin.getInstanceSchema("<instance-id>")).data_schema;
|
|
620
719
|
|
|
621
720
|
// 1. Enhance — new schema + an executor-ready migration plan.
|
|
622
|
-
const enhanced = await xm.admin.
|
|
623
|
-
"<
|
|
721
|
+
const enhanced = await xm.admin.enhanceInstanceSchema(
|
|
722
|
+
"<instance-id>",
|
|
624
723
|
"Rename Person.mail to Person.email.",
|
|
625
724
|
yaml.dump(current),
|
|
626
725
|
);
|
|
@@ -642,6 +741,11 @@ const info = await xm.admin.updateInstanceSchema("<instance-id>", newYaml, Schem
|
|
|
642
741
|
console.log(info.migration_id, info.prior_version, "->", info.new_version);
|
|
643
742
|
```
|
|
644
743
|
|
|
744
|
+
`enhanceInstanceSchema` runs on the model the instance is configured to use. To
|
|
745
|
+
enhance a schema not tied to an instance, call
|
|
746
|
+
`xm.admin.enhanceSchema("<cluster-id>", description, currentYaml)`, which runs
|
|
747
|
+
on the cluster's model.
|
|
748
|
+
|
|
645
749
|
### Migration history
|
|
646
750
|
|
|
647
751
|
```typescript
|
package/dist/cjs/client.d.ts
CHANGED
|
@@ -77,7 +77,21 @@ export interface AdminNamespace {
|
|
|
77
77
|
*/
|
|
78
78
|
patchInstanceMetadata(instanceId: string, options?: PatchInstanceMetadataOptions): Promise<InstanceInfo>;
|
|
79
79
|
generateSchema(clusterId: string, schemaDescription: string, options?: GenerateSchemaOptions): Promise<GenerateSchemaResult>;
|
|
80
|
+
/**
|
|
81
|
+
* Evolve a schema not tied to an instance, on the cluster's model. To evolve
|
|
82
|
+
* an instance's schema, use `enhanceInstanceSchema`.
|
|
83
|
+
*/
|
|
80
84
|
enhanceSchema(clusterId: string, schemaDescription: string, currentYmlSchema: string, options?: RequestOptions): Promise<EnhanceSchemaResult>;
|
|
85
|
+
/**
|
|
86
|
+
* Evolve an instance's schema, returning the new schema and a migration plan.
|
|
87
|
+
*
|
|
88
|
+
* Pass the instance's current YAML schema plus a description of the change
|
|
89
|
+
* you want; nothing is applied. It runs on the model the instance is
|
|
90
|
+
* configured to use. The result's `migration_plan` is executor-ready: hand it
|
|
91
|
+
* to `dryRunMigration` to preview the DDL, then to `updateInstanceSchema` to
|
|
92
|
+
* apply it.
|
|
93
|
+
*/
|
|
94
|
+
enhanceInstanceSchema(instanceId: string, schemaDescription: string, currentYmlSchema: string, options?: RequestOptions): Promise<EnhanceSchemaResult>;
|
|
81
95
|
dryRunMigration(instanceId: string, schemaText: string, schemaType: SchemaTypeValue, options?: DryRunMigrationOptions): Promise<DryRunResult>;
|
|
82
96
|
listMigrations(instanceId: string, options?: ListMigrationsOptions): Promise<ListMigrationsResult>;
|
|
83
97
|
getMigration(instanceId: string, migrationId: string, options?: GetMigrationOptions): Promise<MigrationRecord>;
|
package/dist/cjs/client.js
CHANGED
|
@@ -425,6 +425,12 @@ class XmemoryClient {
|
|
|
425
425
|
timeoutMs: options?.timeoutMs,
|
|
426
426
|
});
|
|
427
427
|
},
|
|
428
|
+
enhanceInstanceSchema: async (instanceId, schemaDescription, currentYmlSchema, options) => {
|
|
429
|
+
return this._requestOne("POST", `/instances/${instanceId}/schema/enhance`, {
|
|
430
|
+
body: { schema_description: schemaDescription, current_yml_schema: currentYmlSchema },
|
|
431
|
+
timeoutMs: options?.timeoutMs,
|
|
432
|
+
});
|
|
433
|
+
},
|
|
428
434
|
dryRunMigration: async (instanceId, schemaText, schemaType, options) => {
|
|
429
435
|
const body = {
|
|
430
436
|
instance_schema: (0, types_js_1.buildInstanceSchema)(schemaText, schemaType),
|
package/dist/cjs/index.d.ts
CHANGED
|
@@ -10,7 +10,7 @@ export { AgentSurface, BindingTier, FragmentMerge, SetupFormat, StepKind } from
|
|
|
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
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, WriteChanges, SkippedOutOfScope, 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, FieldMergeContradiction, 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
|
@@ -85,10 +85,20 @@ export declare class InstanceHandle {
|
|
|
85
85
|
* write create a scoped record that is not stored yet, and is computed by the
|
|
86
86
|
* diff engine, so passing `diffEngine: false` with it is a 400.
|
|
87
87
|
*
|
|
88
|
+
* A text write on a schema with a `merge` field also needs the diff engine:
|
|
89
|
+
* with the engine off, by `diffEngine: false` or by the connection's default,
|
|
90
|
+
* it is refused with a 400 `VALIDATION_ERROR`; a {@link writeAsync} one is
|
|
91
|
+
* queued and fails, which {@link writeStatus} reports.
|
|
92
|
+
*
|
|
88
93
|
* A scoped write additionally requires read permission on the instance: the
|
|
89
94
|
* response carries the previous value of every field the write changed,
|
|
90
95
|
* resolving a scope answers whether each named object is stored, and a
|
|
91
96
|
* drop-mode report says what the skipped changes would have written.
|
|
97
|
+
*
|
|
98
|
+
* Every write joins the instance's write queue, text and mutations alike, and
|
|
99
|
+
* {@link writeAsync} writes too. Queued writes are processed in parallel but
|
|
100
|
+
* applied one at a time, in the order they were queued; this call resolves
|
|
101
|
+
* once its own write is applied, after every write queued before it.
|
|
92
102
|
*/
|
|
93
103
|
write(text: string, options?: WriteOptions): Promise<WriteResult>;
|
|
94
104
|
write(mutations: readonly WriteMutation[], options?: RequestOptions): Promise<WriteResult>;
|
|
@@ -98,13 +108,20 @@ export declare class InstanceHandle {
|
|
|
98
108
|
* the same `scope`. Under the default `"reject"` mode a scope violation is
|
|
99
109
|
* reported by {@link writeStatus} as a failed write; under `"drop"` the write
|
|
100
110
|
* completes, and what it skipped rides the completed status as `changes`.
|
|
111
|
+
*
|
|
112
|
+
* Resolves once the write is queued. Writes to an instance — sync and async,
|
|
113
|
+
* text and mutations — share one queue: they are processed in parallel but
|
|
114
|
+
* applied one at a time, in the order they were queued. The order is the
|
|
115
|
+
* order the server receives them, so await this call before sending a write
|
|
116
|
+
* that must apply after it.
|
|
101
117
|
*/
|
|
102
118
|
writeAsync(text: string, options?: WriteOptions): Promise<AsyncWriteResult>;
|
|
103
119
|
writeAsync(mutations: readonly WriteMutation[], options?: RequestOptions): Promise<AsyncWriteResult>;
|
|
104
120
|
/**
|
|
105
121
|
* 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
|
|
122
|
+
* {@link write} returns inline, including what a `"drop"`-mode scope skipped
|
|
123
|
+
* and what a field merge chose between; a status for a write that has not
|
|
124
|
+
* finished carries none.
|
|
108
125
|
*/
|
|
109
126
|
writeStatus(writeId: string, options?: RequestOptions): Promise<WriteStatusResult>;
|
|
110
127
|
extract(text: string, options?: ExtractOptions): Promise<ExtractResult>;
|
package/dist/cjs/instance.js
CHANGED
|
@@ -264,15 +264,23 @@ class InstanceHandle {
|
|
|
264
264
|
const readerResults = own(result, "reader_results");
|
|
265
265
|
const traceId = own(result, "trace_id");
|
|
266
266
|
const relatedTypes = own(result, "related_types");
|
|
267
|
+
const notice = own(result, "notice");
|
|
267
268
|
// `reader_result` is required on the wire and `null` is one of its answers (a
|
|
268
269
|
// refusal, in the tabular modes), so the coalescing only stands in for a field
|
|
269
270
|
// the server omitted; a `null` the server sent arrives as the same `null`.
|
|
270
271
|
return withConsoleUrl({
|
|
271
272
|
...result,
|
|
272
273
|
reader_result: own(result, "reader_result") ?? null,
|
|
273
|
-
|
|
274
|
+
// A part's `notice` is normalized the same way: the server sends it only on the part it applies to.
|
|
275
|
+
reader_results: Array.isArray(readerResults)
|
|
276
|
+
? readerResults.map((part) => {
|
|
277
|
+
const partNotice = own(part, "notice");
|
|
278
|
+
return { ...part, notice: typeof partNotice === "string" ? partNotice : null };
|
|
279
|
+
})
|
|
280
|
+
: [],
|
|
274
281
|
related_types: relatedTypes != null && typeof relatedTypes === "object" ? relatedTypes : null,
|
|
275
282
|
trace_id: typeof traceId === "string" ? traceId : null,
|
|
283
|
+
notice: typeof notice === "string" ? notice : null,
|
|
276
284
|
});
|
|
277
285
|
}
|
|
278
286
|
async write(input, options) {
|
|
@@ -290,8 +298,9 @@ class InstanceHandle {
|
|
|
290
298
|
}
|
|
291
299
|
/**
|
|
292
300
|
* 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
|
|
301
|
+
* {@link write} returns inline, including what a `"drop"`-mode scope skipped
|
|
302
|
+
* and what a field merge chose between; a status for a write that has not
|
|
303
|
+
* finished carries none.
|
|
295
304
|
*/
|
|
296
305
|
async writeStatus(writeId, options) {
|
|
297
306
|
return withConsoleUrl(await this._requestOne("POST", `/instances/${this.id}/write_status`, { body: { write_id: writeId }, timeoutMs: options?.timeoutMs }));
|
package/dist/cjs/types.d.ts
CHANGED
|
@@ -206,7 +206,7 @@ export interface InstanceSchemaInfo {
|
|
|
206
206
|
* {@link ReadResult.reader_results} when the server decomposed a composite query
|
|
207
207
|
* into independent sub-queries.
|
|
208
208
|
*
|
|
209
|
-
* `reader_result` gives one of the
|
|
209
|
+
* `reader_result` gives one of the five answers described on
|
|
210
210
|
* {@link ReadResult.reader_result}, with one more case: a sub-query whose SQL
|
|
211
211
|
* failed carries the empty result *and* `error`, while the other sub-queries
|
|
212
212
|
* are answered regardless. Its bytes then equal those of a sub-query that
|
|
@@ -222,6 +222,12 @@ export interface TaggedReaderResult {
|
|
|
222
222
|
* with `status` 422 and `code` `"INVALID_INPUT"`.
|
|
223
223
|
*/
|
|
224
224
|
readonly error: string | null;
|
|
225
|
+
/**
|
|
226
|
+
* Set when this sub-query could not be answered as asked (see
|
|
227
|
+
* {@link ReadResult.notice}); its empty `reader_result` is then not a
|
|
228
|
+
* no-match. `null` otherwise.
|
|
229
|
+
*/
|
|
230
|
+
readonly notice: string | null;
|
|
225
231
|
}
|
|
226
232
|
/**
|
|
227
233
|
* One relation edge from the entry's own type to a neighbouring type;
|
|
@@ -339,13 +345,18 @@ export interface ReadResult {
|
|
|
339
345
|
/**
|
|
340
346
|
* The answer, shaped by `readMode`. In `"single-answer"` mode it is always the
|
|
341
347
|
* prose answer, never `null`. In `"raw-tables"` / `"xresponse"` mode its value
|
|
342
|
-
* says which of
|
|
348
|
+
* says which of five answers the read gave:
|
|
343
349
|
*
|
|
344
350
|
* - rows — answered;
|
|
345
351
|
* - exactly `{ columns: [], rows: [] }` (`"raw-tables"`) or
|
|
346
|
-
* `{ objects: [], relations: [] }` (`"xresponse"`)
|
|
347
|
-
* matched nothing: every table and column it used
|
|
348
|
-
* absent;
|
|
352
|
+
* `{ objects: [], relations: [] }` (`"xresponse"`) with `notice` null —
|
|
353
|
+
* the query executed and matched nothing: every table and column it used
|
|
354
|
+
* exists, so the data is absent;
|
|
355
|
+
* - the same empty value with `notice` set — the server could not run a query
|
|
356
|
+
* that answers the question as asked, so the empty value says nothing about
|
|
357
|
+
* what is stored. Rephrase the question (for example, name the exact value
|
|
358
|
+
* to look up) rather than treating the data as absent. In
|
|
359
|
+
* `"single-answer"` mode the answer is then the notice text itself;
|
|
349
360
|
* - `null` — the schema provably cannot represent the concept. An answer in
|
|
350
361
|
* its own right, not a variant of the empty one: this memory cannot hold
|
|
351
362
|
* it, so a better-matching instance is worth trying;
|
|
@@ -355,8 +366,8 @@ export interface ReadResult {
|
|
|
355
366
|
*
|
|
356
367
|
* For a composite query this is the combined answer, folded from the parts:
|
|
357
368
|
* rows if any sub-query answered; else the empty result if any executed and
|
|
358
|
-
* matched nothing; else `null`.
|
|
359
|
-
* answer.
|
|
369
|
+
* matched nothing, or could not be answered as asked; else `null`.
|
|
370
|
+
* `reader_results` carries each part's own answer.
|
|
360
371
|
*/
|
|
361
372
|
readonly reader_result: unknown;
|
|
362
373
|
/**
|
|
@@ -376,10 +387,26 @@ export interface ReadResult {
|
|
|
376
387
|
* a requested read that executed nothing arrives with `touched: []` instead.
|
|
377
388
|
*/
|
|
378
389
|
readonly related_types: RelatedTypes | null;
|
|
390
|
+
/**
|
|
391
|
+
* Set when the read, or one of its sub-queries, could not be answered as
|
|
392
|
+
* asked: the empty result beside it does not mean nothing is stored, so
|
|
393
|
+
* rephrase the question rather than treating the data as absent. On a
|
|
394
|
+
* composite read it is set when any part was affected, even if another part
|
|
395
|
+
* answered, and that part's entry in `reader_results` carries it too. `null`
|
|
396
|
+
* otherwise: the server omits the field on every other read, and a server
|
|
397
|
+
* that predates it never sends it; the client normalizes both to `null`.
|
|
398
|
+
*/
|
|
399
|
+
readonly notice: string | null;
|
|
379
400
|
}
|
|
380
401
|
/**
|
|
381
402
|
* One bundle of changes a `"drop"`-mode scoped write left out instead of
|
|
382
|
-
* applying: one operation on one type,
|
|
403
|
+
* applying: one operation on one type (any type, for an entry folded per
|
|
404
|
+
* operation), standing for `count` records.
|
|
405
|
+
*
|
|
406
|
+
* The server lists at most 100 entries. Past that, it folds entries into ones
|
|
407
|
+
* marked {@link SkippedOutOfScope.folded}, so the counts per operation still add
|
|
408
|
+
* up (and per type too, unless the entries were folded a second time, per
|
|
409
|
+
* operation).
|
|
383
410
|
*/
|
|
384
411
|
export interface SkippedOutOfScope {
|
|
385
412
|
/**
|
|
@@ -392,29 +419,85 @@ export interface SkippedOutOfScope {
|
|
|
392
419
|
* thing — something was skipped — so report it rather than dropping the entry.
|
|
393
420
|
*/
|
|
394
421
|
readonly operation: "create" | "update" | "delete" | "merge" | "link" | "unlink" | (string & {});
|
|
395
|
-
/**
|
|
422
|
+
/**
|
|
423
|
+
* The object type, or the relation type for `"link"` / `"unlink"`. Empty on
|
|
424
|
+
* an entry folded per operation (see {@link SkippedOutOfScope.folded}).
|
|
425
|
+
*/
|
|
396
426
|
readonly object_type_name: string;
|
|
397
427
|
/**
|
|
398
428
|
* The skipped record's primary key, rendered `field='value'` — and **empty
|
|
399
429
|
* unless the scope itself named that record**. The server identifies a record
|
|
400
430
|
* 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".
|
|
431
|
+
* "some other record of this type", not as "a record with no key". Always
|
|
432
|
+
* empty on a folded entry.
|
|
402
433
|
*/
|
|
403
434
|
readonly identity: string;
|
|
404
|
-
/** The field names the skipped changes would have written. */
|
|
435
|
+
/** The field names the skipped changes would have written; empty on a folded entry. */
|
|
405
436
|
readonly fields: readonly string[];
|
|
406
|
-
/** How many records this entry stands for. */
|
|
437
|
+
/** How many records this entry stands for; on a folded entry, the summed `count` of the entries folded into it. */
|
|
407
438
|
readonly count: number;
|
|
439
|
+
/**
|
|
440
|
+
* `true` on an entry that stands for one or more left-out entries folded
|
|
441
|
+
* together; absent on every other entry, so an entry without it keeps the
|
|
442
|
+
* meaning above.
|
|
443
|
+
*
|
|
444
|
+
* The server lists at most 100 entries. Past that, it keeps entries as they
|
|
445
|
+
* are while there is room, those that name a record first, and folds the rest
|
|
446
|
+
* into one entry per `operation` and `object_type_name`, with an empty
|
|
447
|
+
* `identity`, no `fields` and the summed `count`. Unnamed entries are folded
|
|
448
|
+
* before named ones, but a record the scope named can still end up inside a
|
|
449
|
+
* folded entry. When even the folded entries would be more than 100, none is
|
|
450
|
+
* kept as it was, and the last folded entries are folded once more, into one
|
|
451
|
+
* entry per `operation` whose `object_type_name` is empty too. Either way,
|
|
452
|
+
* summing `count` per operation gives the true totals.
|
|
453
|
+
*
|
|
454
|
+
* Optional: a server that predates the cap never sends it, and never folds.
|
|
455
|
+
*/
|
|
456
|
+
readonly folded?: boolean;
|
|
457
|
+
}
|
|
458
|
+
/**
|
|
459
|
+
* One contradiction a text field's merge resolved: what the stored value said,
|
|
460
|
+
* what the write's value said, and which of the two the merged value keeps.
|
|
461
|
+
*
|
|
462
|
+
* Only a `str` field whose schema declares a `merge` produces these. A later
|
|
463
|
+
* text write merges its value into the stored text instead of replacing it,
|
|
464
|
+
* and where the two disagreed about the same thing, the merge kept one.
|
|
465
|
+
*/
|
|
466
|
+
export interface FieldMergeContradiction {
|
|
467
|
+
/** The object type of the record whose field merged. */
|
|
468
|
+
readonly object_type_name: string;
|
|
469
|
+
/**
|
|
470
|
+
* The record's primary key, rendered `field='value'` (a composite key's parts
|
|
471
|
+
* comma-separated); empty for a record that has no key or is missing part of
|
|
472
|
+
* it.
|
|
473
|
+
*/
|
|
474
|
+
readonly identity: string;
|
|
475
|
+
/** The field that merged. */
|
|
476
|
+
readonly field: string;
|
|
477
|
+
/** What the stored value said, as the merge quoted it, cut to 300 characters. */
|
|
478
|
+
readonly stored: string;
|
|
479
|
+
/**
|
|
480
|
+
* What the write's value said (or that of a record the write merged into
|
|
481
|
+
* this one), as the merge quoted it, cut to 300 characters.
|
|
482
|
+
*/
|
|
483
|
+
readonly new: string;
|
|
484
|
+
/**
|
|
485
|
+
* Which of the two the merged value keeps. Widened with `(string & {})` like
|
|
486
|
+
* {@link SkippedOutOfScope.operation}, so a value named by a server newer
|
|
487
|
+
* than this release is still typed rather than rejected.
|
|
488
|
+
*/
|
|
489
|
+
readonly kept: "stored" | "new" | (string & {});
|
|
408
490
|
}
|
|
409
491
|
/**
|
|
410
492
|
* What a write did, grouped into `created` / `updated` / `deleted`, plus what a
|
|
411
|
-
* `"drop"`-mode scope left out.
|
|
493
|
+
* `"drop"`-mode scope left out and the contradictions a field merge resolved.
|
|
412
494
|
*
|
|
413
495
|
* The three groups stay `unknown`: their shape is the server's to evolve and
|
|
414
496
|
* this client has never modelled it. `skipped_out_of_scope` is typed because it
|
|
415
497
|
* is the one part a caller has to branch on — a `"drop"`-mode write succeeds
|
|
416
498
|
* whether or not it skipped anything, so this list is the only report that some
|
|
417
|
-
* of what the text said was not applied.
|
|
499
|
+
* of what the text said was not applied. `merge_contradictions` is typed because
|
|
500
|
+
* it is the only report of what a merge chose between.
|
|
418
501
|
*/
|
|
419
502
|
export interface WriteChanges {
|
|
420
503
|
readonly created: unknown;
|
|
@@ -424,8 +507,19 @@ export interface WriteChanges {
|
|
|
424
507
|
* Omitted by the server when nothing was skipped — which is every write that
|
|
425
508
|
* did not ask for `"drop"` — so `undefined` and `[]` both mean "nothing left
|
|
426
509
|
* out". Branch on whether there are entries, not on whether the key is there.
|
|
510
|
+
*
|
|
511
|
+
* At most 100 entries; past that, the rest arrive folded (see
|
|
512
|
+
* {@link SkippedOutOfScope.folded}).
|
|
427
513
|
*/
|
|
428
514
|
readonly skipped_out_of_scope?: readonly SkippedOutOfScope[];
|
|
515
|
+
/**
|
|
516
|
+
* The contradictions a merge reported for a field the write changed.
|
|
517
|
+
* Advisory: the write landed either way. Omitted by the server when there is
|
|
518
|
+
* none, and by a server that predates field merges, so `undefined` and `[]`
|
|
519
|
+
* both mean "none reported" — not that the texts agreed: a merge that failed,
|
|
520
|
+
* appended, or left the stored text unchanged reports none.
|
|
521
|
+
*/
|
|
522
|
+
readonly merge_contradictions?: readonly FieldMergeContradiction[];
|
|
429
523
|
}
|
|
430
524
|
export interface WriteResult {
|
|
431
525
|
readonly write_id: string;
|
|
@@ -433,8 +527,9 @@ export interface WriteResult {
|
|
|
433
527
|
/** Deep link to this write's trace in the console; `null` if no console is configured. */
|
|
434
528
|
readonly console_url: string | null;
|
|
435
529
|
/**
|
|
436
|
-
* What the write did, grouped into `created` / `updated` / `deleted
|
|
437
|
-
*
|
|
530
|
+
* What the write did, grouped into `created` / `updated` / `deleted`; for a
|
|
531
|
+
* scoped write in `"drop"` mode, what it skipped instead of applying; and
|
|
532
|
+
* what a field merge chose between (`merge_contradictions`).
|
|
438
533
|
*/
|
|
439
534
|
readonly changes: WriteChanges;
|
|
440
535
|
}
|
|
@@ -456,7 +551,8 @@ export interface WriteStatusResult {
|
|
|
456
551
|
* What the finished write did, in the same shape {@link WriteResult.changes}
|
|
457
552
|
* carries — and the async caller's only view of it, since `writeAsync`
|
|
458
553
|
* returns before the write has done anything. It is therefore where a
|
|
459
|
-
* `"drop"`-mode scope reports what it skipped
|
|
554
|
+
* `"drop"`-mode scope reports what it skipped, and a field merge what it chose
|
|
555
|
+
* between.
|
|
460
556
|
*
|
|
461
557
|
* Optional because a status is not always about a finished write: a queued,
|
|
462
558
|
* in-progress, failed or unknown `write_id` carries none. Read it once
|
|
@@ -928,7 +1024,7 @@ export interface PatchInstanceMetadataOptions {
|
|
|
928
1024
|
timeoutMs?: number;
|
|
929
1025
|
}
|
|
930
1026
|
export interface UpdateInstanceSchemaOptions {
|
|
931
|
-
/** Serialized migration plan from `enhanceSchema`; required for non-additive changes. */
|
|
1027
|
+
/** Serialized migration plan from `enhanceInstanceSchema` or `enhanceSchema`; required for non-additive changes. */
|
|
932
1028
|
migrationPlan?: MigrationPlan | Record<string, unknown>;
|
|
933
1029
|
/** Authorise ops that drop data (remove object/field, lossy type cast). */
|
|
934
1030
|
confirmDestructive?: boolean;
|
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.20.0";
|
package/dist/cjs/version.js
CHANGED
package/dist/esm/client.d.ts
CHANGED
|
@@ -77,7 +77,21 @@ export interface AdminNamespace {
|
|
|
77
77
|
*/
|
|
78
78
|
patchInstanceMetadata(instanceId: string, options?: PatchInstanceMetadataOptions): Promise<InstanceInfo>;
|
|
79
79
|
generateSchema(clusterId: string, schemaDescription: string, options?: GenerateSchemaOptions): Promise<GenerateSchemaResult>;
|
|
80
|
+
/**
|
|
81
|
+
* Evolve a schema not tied to an instance, on the cluster's model. To evolve
|
|
82
|
+
* an instance's schema, use `enhanceInstanceSchema`.
|
|
83
|
+
*/
|
|
80
84
|
enhanceSchema(clusterId: string, schemaDescription: string, currentYmlSchema: string, options?: RequestOptions): Promise<EnhanceSchemaResult>;
|
|
85
|
+
/**
|
|
86
|
+
* Evolve an instance's schema, returning the new schema and a migration plan.
|
|
87
|
+
*
|
|
88
|
+
* Pass the instance's current YAML schema plus a description of the change
|
|
89
|
+
* you want; nothing is applied. It runs on the model the instance is
|
|
90
|
+
* configured to use. The result's `migration_plan` is executor-ready: hand it
|
|
91
|
+
* to `dryRunMigration` to preview the DDL, then to `updateInstanceSchema` to
|
|
92
|
+
* apply it.
|
|
93
|
+
*/
|
|
94
|
+
enhanceInstanceSchema(instanceId: string, schemaDescription: string, currentYmlSchema: string, options?: RequestOptions): Promise<EnhanceSchemaResult>;
|
|
81
95
|
dryRunMigration(instanceId: string, schemaText: string, schemaType: SchemaTypeValue, options?: DryRunMigrationOptions): Promise<DryRunResult>;
|
|
82
96
|
listMigrations(instanceId: string, options?: ListMigrationsOptions): Promise<ListMigrationsResult>;
|
|
83
97
|
getMigration(instanceId: string, migrationId: string, options?: GetMigrationOptions): Promise<MigrationRecord>;
|
package/dist/esm/client.js
CHANGED
|
@@ -419,6 +419,12 @@ export class XmemoryClient {
|
|
|
419
419
|
timeoutMs: options?.timeoutMs,
|
|
420
420
|
});
|
|
421
421
|
},
|
|
422
|
+
enhanceInstanceSchema: async (instanceId, schemaDescription, currentYmlSchema, options) => {
|
|
423
|
+
return this._requestOne("POST", `/instances/${instanceId}/schema/enhance`, {
|
|
424
|
+
body: { schema_description: schemaDescription, current_yml_schema: currentYmlSchema },
|
|
425
|
+
timeoutMs: options?.timeoutMs,
|
|
426
|
+
});
|
|
427
|
+
},
|
|
422
428
|
dryRunMigration: async (instanceId, schemaText, schemaType, options) => {
|
|
423
429
|
const body = {
|
|
424
430
|
instance_schema: buildInstanceSchema(schemaText, schemaType),
|
package/dist/esm/index.d.ts
CHANGED
|
@@ -10,7 +10,7 @@ export { AgentSurface, BindingTier, FragmentMerge, SetupFormat, StepKind } from
|
|
|
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
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, WriteChanges, SkippedOutOfScope, 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, FieldMergeContradiction, 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
|
@@ -85,10 +85,20 @@ export declare class InstanceHandle {
|
|
|
85
85
|
* write create a scoped record that is not stored yet, and is computed by the
|
|
86
86
|
* diff engine, so passing `diffEngine: false` with it is a 400.
|
|
87
87
|
*
|
|
88
|
+
* A text write on a schema with a `merge` field also needs the diff engine:
|
|
89
|
+
* with the engine off, by `diffEngine: false` or by the connection's default,
|
|
90
|
+
* it is refused with a 400 `VALIDATION_ERROR`; a {@link writeAsync} one is
|
|
91
|
+
* queued and fails, which {@link writeStatus} reports.
|
|
92
|
+
*
|
|
88
93
|
* A scoped write additionally requires read permission on the instance: the
|
|
89
94
|
* response carries the previous value of every field the write changed,
|
|
90
95
|
* resolving a scope answers whether each named object is stored, and a
|
|
91
96
|
* drop-mode report says what the skipped changes would have written.
|
|
97
|
+
*
|
|
98
|
+
* Every write joins the instance's write queue, text and mutations alike, and
|
|
99
|
+
* {@link writeAsync} writes too. Queued writes are processed in parallel but
|
|
100
|
+
* applied one at a time, in the order they were queued; this call resolves
|
|
101
|
+
* once its own write is applied, after every write queued before it.
|
|
92
102
|
*/
|
|
93
103
|
write(text: string, options?: WriteOptions): Promise<WriteResult>;
|
|
94
104
|
write(mutations: readonly WriteMutation[], options?: RequestOptions): Promise<WriteResult>;
|
|
@@ -98,13 +108,20 @@ export declare class InstanceHandle {
|
|
|
98
108
|
* the same `scope`. Under the default `"reject"` mode a scope violation is
|
|
99
109
|
* reported by {@link writeStatus} as a failed write; under `"drop"` the write
|
|
100
110
|
* completes, and what it skipped rides the completed status as `changes`.
|
|
111
|
+
*
|
|
112
|
+
* Resolves once the write is queued. Writes to an instance — sync and async,
|
|
113
|
+
* text and mutations — share one queue: they are processed in parallel but
|
|
114
|
+
* applied one at a time, in the order they were queued. The order is the
|
|
115
|
+
* order the server receives them, so await this call before sending a write
|
|
116
|
+
* that must apply after it.
|
|
101
117
|
*/
|
|
102
118
|
writeAsync(text: string, options?: WriteOptions): Promise<AsyncWriteResult>;
|
|
103
119
|
writeAsync(mutations: readonly WriteMutation[], options?: RequestOptions): Promise<AsyncWriteResult>;
|
|
104
120
|
/**
|
|
105
121
|
* 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
|
|
122
|
+
* {@link write} returns inline, including what a `"drop"`-mode scope skipped
|
|
123
|
+
* and what a field merge chose between; a status for a write that has not
|
|
124
|
+
* finished carries none.
|
|
108
125
|
*/
|
|
109
126
|
writeStatus(writeId: string, options?: RequestOptions): Promise<WriteStatusResult>;
|
|
110
127
|
extract(text: string, options?: ExtractOptions): Promise<ExtractResult>;
|
package/dist/esm/instance.js
CHANGED
|
@@ -260,15 +260,23 @@ export class InstanceHandle {
|
|
|
260
260
|
const readerResults = own(result, "reader_results");
|
|
261
261
|
const traceId = own(result, "trace_id");
|
|
262
262
|
const relatedTypes = own(result, "related_types");
|
|
263
|
+
const notice = own(result, "notice");
|
|
263
264
|
// `reader_result` is required on the wire and `null` is one of its answers (a
|
|
264
265
|
// refusal, in the tabular modes), so the coalescing only stands in for a field
|
|
265
266
|
// the server omitted; a `null` the server sent arrives as the same `null`.
|
|
266
267
|
return withConsoleUrl({
|
|
267
268
|
...result,
|
|
268
269
|
reader_result: own(result, "reader_result") ?? null,
|
|
269
|
-
|
|
270
|
+
// A part's `notice` is normalized the same way: the server sends it only on the part it applies to.
|
|
271
|
+
reader_results: Array.isArray(readerResults)
|
|
272
|
+
? readerResults.map((part) => {
|
|
273
|
+
const partNotice = own(part, "notice");
|
|
274
|
+
return { ...part, notice: typeof partNotice === "string" ? partNotice : null };
|
|
275
|
+
})
|
|
276
|
+
: [],
|
|
270
277
|
related_types: relatedTypes != null && typeof relatedTypes === "object" ? relatedTypes : null,
|
|
271
278
|
trace_id: typeof traceId === "string" ? traceId : null,
|
|
279
|
+
notice: typeof notice === "string" ? notice : null,
|
|
272
280
|
});
|
|
273
281
|
}
|
|
274
282
|
async write(input, options) {
|
|
@@ -286,8 +294,9 @@ export class InstanceHandle {
|
|
|
286
294
|
}
|
|
287
295
|
/**
|
|
288
296
|
* 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
|
|
297
|
+
* {@link write} returns inline, including what a `"drop"`-mode scope skipped
|
|
298
|
+
* and what a field merge chose between; a status for a write that has not
|
|
299
|
+
* finished carries none.
|
|
291
300
|
*/
|
|
292
301
|
async writeStatus(writeId, options) {
|
|
293
302
|
return withConsoleUrl(await this._requestOne("POST", `/instances/${this.id}/write_status`, { body: { write_id: writeId }, timeoutMs: options?.timeoutMs }));
|
package/dist/esm/types.d.ts
CHANGED
|
@@ -206,7 +206,7 @@ export interface InstanceSchemaInfo {
|
|
|
206
206
|
* {@link ReadResult.reader_results} when the server decomposed a composite query
|
|
207
207
|
* into independent sub-queries.
|
|
208
208
|
*
|
|
209
|
-
* `reader_result` gives one of the
|
|
209
|
+
* `reader_result` gives one of the five answers described on
|
|
210
210
|
* {@link ReadResult.reader_result}, with one more case: a sub-query whose SQL
|
|
211
211
|
* failed carries the empty result *and* `error`, while the other sub-queries
|
|
212
212
|
* are answered regardless. Its bytes then equal those of a sub-query that
|
|
@@ -222,6 +222,12 @@ export interface TaggedReaderResult {
|
|
|
222
222
|
* with `status` 422 and `code` `"INVALID_INPUT"`.
|
|
223
223
|
*/
|
|
224
224
|
readonly error: string | null;
|
|
225
|
+
/**
|
|
226
|
+
* Set when this sub-query could not be answered as asked (see
|
|
227
|
+
* {@link ReadResult.notice}); its empty `reader_result` is then not a
|
|
228
|
+
* no-match. `null` otherwise.
|
|
229
|
+
*/
|
|
230
|
+
readonly notice: string | null;
|
|
225
231
|
}
|
|
226
232
|
/**
|
|
227
233
|
* One relation edge from the entry's own type to a neighbouring type;
|
|
@@ -339,13 +345,18 @@ export interface ReadResult {
|
|
|
339
345
|
/**
|
|
340
346
|
* The answer, shaped by `readMode`. In `"single-answer"` mode it is always the
|
|
341
347
|
* prose answer, never `null`. In `"raw-tables"` / `"xresponse"` mode its value
|
|
342
|
-
* says which of
|
|
348
|
+
* says which of five answers the read gave:
|
|
343
349
|
*
|
|
344
350
|
* - rows — answered;
|
|
345
351
|
* - exactly `{ columns: [], rows: [] }` (`"raw-tables"`) or
|
|
346
|
-
* `{ objects: [], relations: [] }` (`"xresponse"`)
|
|
347
|
-
* matched nothing: every table and column it used
|
|
348
|
-
* absent;
|
|
352
|
+
* `{ objects: [], relations: [] }` (`"xresponse"`) with `notice` null —
|
|
353
|
+
* the query executed and matched nothing: every table and column it used
|
|
354
|
+
* exists, so the data is absent;
|
|
355
|
+
* - the same empty value with `notice` set — the server could not run a query
|
|
356
|
+
* that answers the question as asked, so the empty value says nothing about
|
|
357
|
+
* what is stored. Rephrase the question (for example, name the exact value
|
|
358
|
+
* to look up) rather than treating the data as absent. In
|
|
359
|
+
* `"single-answer"` mode the answer is then the notice text itself;
|
|
349
360
|
* - `null` — the schema provably cannot represent the concept. An answer in
|
|
350
361
|
* its own right, not a variant of the empty one: this memory cannot hold
|
|
351
362
|
* it, so a better-matching instance is worth trying;
|
|
@@ -355,8 +366,8 @@ export interface ReadResult {
|
|
|
355
366
|
*
|
|
356
367
|
* For a composite query this is the combined answer, folded from the parts:
|
|
357
368
|
* rows if any sub-query answered; else the empty result if any executed and
|
|
358
|
-
* matched nothing; else `null`.
|
|
359
|
-
* answer.
|
|
369
|
+
* matched nothing, or could not be answered as asked; else `null`.
|
|
370
|
+
* `reader_results` carries each part's own answer.
|
|
360
371
|
*/
|
|
361
372
|
readonly reader_result: unknown;
|
|
362
373
|
/**
|
|
@@ -376,10 +387,26 @@ export interface ReadResult {
|
|
|
376
387
|
* a requested read that executed nothing arrives with `touched: []` instead.
|
|
377
388
|
*/
|
|
378
389
|
readonly related_types: RelatedTypes | null;
|
|
390
|
+
/**
|
|
391
|
+
* Set when the read, or one of its sub-queries, could not be answered as
|
|
392
|
+
* asked: the empty result beside it does not mean nothing is stored, so
|
|
393
|
+
* rephrase the question rather than treating the data as absent. On a
|
|
394
|
+
* composite read it is set when any part was affected, even if another part
|
|
395
|
+
* answered, and that part's entry in `reader_results` carries it too. `null`
|
|
396
|
+
* otherwise: the server omits the field on every other read, and a server
|
|
397
|
+
* that predates it never sends it; the client normalizes both to `null`.
|
|
398
|
+
*/
|
|
399
|
+
readonly notice: string | null;
|
|
379
400
|
}
|
|
380
401
|
/**
|
|
381
402
|
* One bundle of changes a `"drop"`-mode scoped write left out instead of
|
|
382
|
-
* applying: one operation on one type,
|
|
403
|
+
* applying: one operation on one type (any type, for an entry folded per
|
|
404
|
+
* operation), standing for `count` records.
|
|
405
|
+
*
|
|
406
|
+
* The server lists at most 100 entries. Past that, it folds entries into ones
|
|
407
|
+
* marked {@link SkippedOutOfScope.folded}, so the counts per operation still add
|
|
408
|
+
* up (and per type too, unless the entries were folded a second time, per
|
|
409
|
+
* operation).
|
|
383
410
|
*/
|
|
384
411
|
export interface SkippedOutOfScope {
|
|
385
412
|
/**
|
|
@@ -392,29 +419,85 @@ export interface SkippedOutOfScope {
|
|
|
392
419
|
* thing — something was skipped — so report it rather than dropping the entry.
|
|
393
420
|
*/
|
|
394
421
|
readonly operation: "create" | "update" | "delete" | "merge" | "link" | "unlink" | (string & {});
|
|
395
|
-
/**
|
|
422
|
+
/**
|
|
423
|
+
* The object type, or the relation type for `"link"` / `"unlink"`. Empty on
|
|
424
|
+
* an entry folded per operation (see {@link SkippedOutOfScope.folded}).
|
|
425
|
+
*/
|
|
396
426
|
readonly object_type_name: string;
|
|
397
427
|
/**
|
|
398
428
|
* The skipped record's primary key, rendered `field='value'` — and **empty
|
|
399
429
|
* unless the scope itself named that record**. The server identifies a record
|
|
400
430
|
* 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".
|
|
431
|
+
* "some other record of this type", not as "a record with no key". Always
|
|
432
|
+
* empty on a folded entry.
|
|
402
433
|
*/
|
|
403
434
|
readonly identity: string;
|
|
404
|
-
/** The field names the skipped changes would have written. */
|
|
435
|
+
/** The field names the skipped changes would have written; empty on a folded entry. */
|
|
405
436
|
readonly fields: readonly string[];
|
|
406
|
-
/** How many records this entry stands for. */
|
|
437
|
+
/** How many records this entry stands for; on a folded entry, the summed `count` of the entries folded into it. */
|
|
407
438
|
readonly count: number;
|
|
439
|
+
/**
|
|
440
|
+
* `true` on an entry that stands for one or more left-out entries folded
|
|
441
|
+
* together; absent on every other entry, so an entry without it keeps the
|
|
442
|
+
* meaning above.
|
|
443
|
+
*
|
|
444
|
+
* The server lists at most 100 entries. Past that, it keeps entries as they
|
|
445
|
+
* are while there is room, those that name a record first, and folds the rest
|
|
446
|
+
* into one entry per `operation` and `object_type_name`, with an empty
|
|
447
|
+
* `identity`, no `fields` and the summed `count`. Unnamed entries are folded
|
|
448
|
+
* before named ones, but a record the scope named can still end up inside a
|
|
449
|
+
* folded entry. When even the folded entries would be more than 100, none is
|
|
450
|
+
* kept as it was, and the last folded entries are folded once more, into one
|
|
451
|
+
* entry per `operation` whose `object_type_name` is empty too. Either way,
|
|
452
|
+
* summing `count` per operation gives the true totals.
|
|
453
|
+
*
|
|
454
|
+
* Optional: a server that predates the cap never sends it, and never folds.
|
|
455
|
+
*/
|
|
456
|
+
readonly folded?: boolean;
|
|
457
|
+
}
|
|
458
|
+
/**
|
|
459
|
+
* One contradiction a text field's merge resolved: what the stored value said,
|
|
460
|
+
* what the write's value said, and which of the two the merged value keeps.
|
|
461
|
+
*
|
|
462
|
+
* Only a `str` field whose schema declares a `merge` produces these. A later
|
|
463
|
+
* text write merges its value into the stored text instead of replacing it,
|
|
464
|
+
* and where the two disagreed about the same thing, the merge kept one.
|
|
465
|
+
*/
|
|
466
|
+
export interface FieldMergeContradiction {
|
|
467
|
+
/** The object type of the record whose field merged. */
|
|
468
|
+
readonly object_type_name: string;
|
|
469
|
+
/**
|
|
470
|
+
* The record's primary key, rendered `field='value'` (a composite key's parts
|
|
471
|
+
* comma-separated); empty for a record that has no key or is missing part of
|
|
472
|
+
* it.
|
|
473
|
+
*/
|
|
474
|
+
readonly identity: string;
|
|
475
|
+
/** The field that merged. */
|
|
476
|
+
readonly field: string;
|
|
477
|
+
/** What the stored value said, as the merge quoted it, cut to 300 characters. */
|
|
478
|
+
readonly stored: string;
|
|
479
|
+
/**
|
|
480
|
+
* What the write's value said (or that of a record the write merged into
|
|
481
|
+
* this one), as the merge quoted it, cut to 300 characters.
|
|
482
|
+
*/
|
|
483
|
+
readonly new: string;
|
|
484
|
+
/**
|
|
485
|
+
* Which of the two the merged value keeps. Widened with `(string & {})` like
|
|
486
|
+
* {@link SkippedOutOfScope.operation}, so a value named by a server newer
|
|
487
|
+
* than this release is still typed rather than rejected.
|
|
488
|
+
*/
|
|
489
|
+
readonly kept: "stored" | "new" | (string & {});
|
|
408
490
|
}
|
|
409
491
|
/**
|
|
410
492
|
* What a write did, grouped into `created` / `updated` / `deleted`, plus what a
|
|
411
|
-
* `"drop"`-mode scope left out.
|
|
493
|
+
* `"drop"`-mode scope left out and the contradictions a field merge resolved.
|
|
412
494
|
*
|
|
413
495
|
* The three groups stay `unknown`: their shape is the server's to evolve and
|
|
414
496
|
* this client has never modelled it. `skipped_out_of_scope` is typed because it
|
|
415
497
|
* is the one part a caller has to branch on — a `"drop"`-mode write succeeds
|
|
416
498
|
* whether or not it skipped anything, so this list is the only report that some
|
|
417
|
-
* of what the text said was not applied.
|
|
499
|
+
* of what the text said was not applied. `merge_contradictions` is typed because
|
|
500
|
+
* it is the only report of what a merge chose between.
|
|
418
501
|
*/
|
|
419
502
|
export interface WriteChanges {
|
|
420
503
|
readonly created: unknown;
|
|
@@ -424,8 +507,19 @@ export interface WriteChanges {
|
|
|
424
507
|
* Omitted by the server when nothing was skipped — which is every write that
|
|
425
508
|
* did not ask for `"drop"` — so `undefined` and `[]` both mean "nothing left
|
|
426
509
|
* out". Branch on whether there are entries, not on whether the key is there.
|
|
510
|
+
*
|
|
511
|
+
* At most 100 entries; past that, the rest arrive folded (see
|
|
512
|
+
* {@link SkippedOutOfScope.folded}).
|
|
427
513
|
*/
|
|
428
514
|
readonly skipped_out_of_scope?: readonly SkippedOutOfScope[];
|
|
515
|
+
/**
|
|
516
|
+
* The contradictions a merge reported for a field the write changed.
|
|
517
|
+
* Advisory: the write landed either way. Omitted by the server when there is
|
|
518
|
+
* none, and by a server that predates field merges, so `undefined` and `[]`
|
|
519
|
+
* both mean "none reported" — not that the texts agreed: a merge that failed,
|
|
520
|
+
* appended, or left the stored text unchanged reports none.
|
|
521
|
+
*/
|
|
522
|
+
readonly merge_contradictions?: readonly FieldMergeContradiction[];
|
|
429
523
|
}
|
|
430
524
|
export interface WriteResult {
|
|
431
525
|
readonly write_id: string;
|
|
@@ -433,8 +527,9 @@ export interface WriteResult {
|
|
|
433
527
|
/** Deep link to this write's trace in the console; `null` if no console is configured. */
|
|
434
528
|
readonly console_url: string | null;
|
|
435
529
|
/**
|
|
436
|
-
* What the write did, grouped into `created` / `updated` / `deleted
|
|
437
|
-
*
|
|
530
|
+
* What the write did, grouped into `created` / `updated` / `deleted`; for a
|
|
531
|
+
* scoped write in `"drop"` mode, what it skipped instead of applying; and
|
|
532
|
+
* what a field merge chose between (`merge_contradictions`).
|
|
438
533
|
*/
|
|
439
534
|
readonly changes: WriteChanges;
|
|
440
535
|
}
|
|
@@ -456,7 +551,8 @@ export interface WriteStatusResult {
|
|
|
456
551
|
* What the finished write did, in the same shape {@link WriteResult.changes}
|
|
457
552
|
* carries — and the async caller's only view of it, since `writeAsync`
|
|
458
553
|
* returns before the write has done anything. It is therefore where a
|
|
459
|
-
* `"drop"`-mode scope reports what it skipped
|
|
554
|
+
* `"drop"`-mode scope reports what it skipped, and a field merge what it chose
|
|
555
|
+
* between.
|
|
460
556
|
*
|
|
461
557
|
* Optional because a status is not always about a finished write: a queued,
|
|
462
558
|
* in-progress, failed or unknown `write_id` carries none. Read it once
|
|
@@ -928,7 +1024,7 @@ export interface PatchInstanceMetadataOptions {
|
|
|
928
1024
|
timeoutMs?: number;
|
|
929
1025
|
}
|
|
930
1026
|
export interface UpdateInstanceSchemaOptions {
|
|
931
|
-
/** Serialized migration plan from `enhanceSchema`; required for non-additive changes. */
|
|
1027
|
+
/** Serialized migration plan from `enhanceInstanceSchema` or `enhanceSchema`; required for non-additive changes. */
|
|
932
1028
|
migrationPlan?: MigrationPlan | Record<string, unknown>;
|
|
933
1029
|
/** Authorise ops that drop data (remove object/field, lossy type cast). */
|
|
934
1030
|
confirmDestructive?: boolean;
|
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.20.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.20.0";
|