xmemory 3.17.0 → 3.21.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 +88 -4
- 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 +8 -2
- package/dist/cjs/instance.js +3 -2
- package/dist/cjs/types.d.ts +107 -6
- 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 +8 -2
- package/dist/esm/instance.js +3 -2
- package/dist/esm/types.d.ts +107 -6
- package/dist/esm/version.d.ts +1 -1
- package/dist/esm/version.js +1 -1
- package/package.json +3 -3
package/README.md
CHANGED
|
@@ -247,8 +247,9 @@ 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
|
-
|
|
250
|
+
left out, a [field merge](#mergeable-text-fields) what it chose between, and a
|
|
251
|
+
[delete](#records-a-delete-left-without-a-link) the records it left without a link.
|
|
252
|
+
A status for a write that has not finished carries none, so the field is optional.
|
|
252
253
|
|
|
253
254
|
### Write ordering
|
|
254
255
|
|
|
@@ -283,6 +284,84 @@ await inst.write([
|
|
|
283
284
|
]);
|
|
284
285
|
```
|
|
285
286
|
|
|
287
|
+
### Mergeable text fields
|
|
288
|
+
|
|
289
|
+
By default a write replaces a field's stored value. A `str` field that is not
|
|
290
|
+
part of the primary key can instead declare a `merge` in the schema, so a later
|
|
291
|
+
text write merges its value into the text already stored. A server from before
|
|
292
|
+
field merges keeps the block but ignores it, and replaces the value as before:
|
|
293
|
+
|
|
294
|
+
```yaml
|
|
295
|
+
next_steps:
|
|
296
|
+
type: str
|
|
297
|
+
description: what is still to be done on the project, one step per line
|
|
298
|
+
merge:
|
|
299
|
+
rules:
|
|
300
|
+
- Keep every step that is still open.
|
|
301
|
+
- Drop a step the text says is done.
|
|
302
|
+
max_length: 400
|
|
303
|
+
```
|
|
304
|
+
|
|
305
|
+
- `max_length` is required, a whole number from 1 to 20,000: the length the
|
|
306
|
+
merge keeps the text within. `rules` is optional: up to 50 non-empty lines of
|
|
307
|
+
at most 1,000 characters each. `merge` takes no other key, and a schema that
|
|
308
|
+
breaks any of this is refused.
|
|
309
|
+
- With `rules`, the server merges the new value into the stored one by those
|
|
310
|
+
rules, within the cap.
|
|
311
|
+
- Without `rules`, the new value is appended on its own line, leaving out lines
|
|
312
|
+
whose facts are already stated; past the cap, the text is shortened, keeping
|
|
313
|
+
every fact.
|
|
314
|
+
- If a merge cannot be made, the new value is appended, even past the cap, and
|
|
315
|
+
nothing stored is cut.
|
|
316
|
+
- Only text writes merge, through the server's diff engine. A text write that
|
|
317
|
+
runs without it on such a schema — `diffEngine: false`, or a connection whose
|
|
318
|
+
default is off — is refused with a 400 `VALIDATION_ERROR`; through
|
|
319
|
+
`writeAsync` it is queued and fails, which `writeStatus` reports.
|
|
320
|
+
`WriteMutation[]` writes replace the value as given.
|
|
321
|
+
- Adding, changing or removing a `merge` is a metadata-only schema change.
|
|
322
|
+
|
|
323
|
+
Where a merge that changed the field found the new value contradicting the
|
|
324
|
+
stored one, `changes.merge_contradictions` says what each said and which one it
|
|
325
|
+
kept (`FieldMergeContradiction`):
|
|
326
|
+
|
|
327
|
+
```typescript
|
|
328
|
+
const result = await inst.write("The Harbour Wall survey moved to 10 March.");
|
|
329
|
+
for (const c of result.changes.merge_contradictions ?? []) {
|
|
330
|
+
console.log(c.object_type_name, c.identity, c.field, c.stored, "->", c.new, "kept:", c.kept);
|
|
331
|
+
}
|
|
332
|
+
```
|
|
333
|
+
|
|
334
|
+
The key is omitted when there is no such entry. An absent key does not prove the
|
|
335
|
+
texts agreed: a merge that failed, fell back to appending, or left the stored
|
|
336
|
+
text unchanged reports none.
|
|
337
|
+
|
|
338
|
+
### Records a delete left without a link
|
|
339
|
+
|
|
340
|
+
Deleting a record never deletes the records linked to it. The relation's
|
|
341
|
+
`on_delete` removes or clears each link, and the write lists those links under
|
|
342
|
+
`changes.deleted.relations`; a link the same write also states may be reported
|
|
343
|
+
under `relationship_outcomes` as well, or instead. A record whose last link of a
|
|
344
|
+
relation was the deleted one is listed in `changes.orphaned_records`
|
|
345
|
+
(`OrphanedRecord`), so you can decide whether it still belongs. `relation` is
|
|
346
|
+
the relation's class name: an XMD relation `works_at` comes back as `WorksAt`:
|
|
347
|
+
|
|
348
|
+
```typescript
|
|
349
|
+
const result = await inst.write("Remove the Harbour Wall project.");
|
|
350
|
+
for (const r of result.changes.orphaned_records ?? []) {
|
|
351
|
+
console.log(r.object_type_name, r.folded ? `${r.count} more` : r.identity, "has no", r.relation, "link left");
|
|
352
|
+
}
|
|
353
|
+
```
|
|
354
|
+
|
|
355
|
+
The key is omitted when there is no such record and by a server from before this
|
|
356
|
+
report, so a missing key means none reported. It means nothing at all when
|
|
357
|
+
`relationship_outcomes` reports the write's summary unavailable (an entry with
|
|
358
|
+
`status: "unavailable"`). A record the write deleted, or that still has a link
|
|
359
|
+
of that relation when the write completes, is not listed. Past 100 entries of
|
|
360
|
+
one type and relation, the rest arrive as one entry marked `folded: true`, with
|
|
361
|
+
an empty `identity` and their `count`. `deleted.relations` folds a delete's
|
|
362
|
+
links past 100 of one relation into one entry with that relation's `name`, empty
|
|
363
|
+
`endpoints` and `fields`, `folded: true` and their `count`.
|
|
364
|
+
|
|
286
365
|
### `inst.read(query, options?)` → `ReadResult`
|
|
287
366
|
|
|
288
367
|
Query the instance.
|
|
@@ -667,8 +746,8 @@ const xm = new XmemoryClient({ apiKey: "..." });
|
|
|
667
746
|
const current = (await xm.admin.getInstanceSchema("<instance-id>")).data_schema;
|
|
668
747
|
|
|
669
748
|
// 1. Enhance — new schema + an executor-ready migration plan.
|
|
670
|
-
const enhanced = await xm.admin.
|
|
671
|
-
"<
|
|
749
|
+
const enhanced = await xm.admin.enhanceInstanceSchema(
|
|
750
|
+
"<instance-id>",
|
|
672
751
|
"Rename Person.mail to Person.email.",
|
|
673
752
|
yaml.dump(current),
|
|
674
753
|
);
|
|
@@ -690,6 +769,11 @@ const info = await xm.admin.updateInstanceSchema("<instance-id>", newYaml, Schem
|
|
|
690
769
|
console.log(info.migration_id, info.prior_version, "->", info.new_version);
|
|
691
770
|
```
|
|
692
771
|
|
|
772
|
+
`enhanceInstanceSchema` runs on the model the instance is configured to use. To
|
|
773
|
+
enhance a schema not tied to an instance, call
|
|
774
|
+
`xm.admin.enhanceSchema("<cluster-id>", description, currentYaml)`, which runs
|
|
775
|
+
on the cluster's model.
|
|
776
|
+
|
|
693
777
|
### Migration history
|
|
694
778
|
|
|
695
779
|
```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, OrphanedRecord, AsyncWriteResult, WriteStatusResult, ExtractResult, GenerateSchemaResult, ToolDescription, ToolParameterDescription, RawDescribeResult, } from "./types.js";
|
|
14
14
|
export type { WriteMutation, ObjectMutationBody, ObjectCreatePayload, ObjectUpdatePayload, ObjectDeletePayload, RelationMutationBody, RelationCreatePayload, RelationUpdatePayload, RelationDeletePayload, RelationEndpoint, } from "./types.js";
|
|
15
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,6 +85,11 @@ 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
|
|
@@ -114,8 +119,9 @@ export declare class InstanceHandle {
|
|
|
114
119
|
writeAsync(mutations: readonly WriteMutation[], options?: RequestOptions): Promise<AsyncWriteResult>;
|
|
115
120
|
/**
|
|
116
121
|
* Poll a queued write. A finished one carries `changes` — the same report
|
|
117
|
-
* {@link write} returns inline, including what a `"drop"`-mode scope skipped
|
|
118
|
-
* 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.
|
|
119
125
|
*/
|
|
120
126
|
writeStatus(writeId: string, options?: RequestOptions): Promise<WriteStatusResult>;
|
|
121
127
|
extract(text: string, options?: ExtractOptions): Promise<ExtractResult>;
|
package/dist/cjs/instance.js
CHANGED
|
@@ -298,8 +298,9 @@ class InstanceHandle {
|
|
|
298
298
|
}
|
|
299
299
|
/**
|
|
300
300
|
* Poll a queued write. A finished one carries `changes` — the same report
|
|
301
|
-
* {@link write} returns inline, including what a `"drop"`-mode scope skipped
|
|
302
|
-
* 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.
|
|
303
304
|
*/
|
|
304
305
|
async writeStatus(writeId, options) {
|
|
305
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
|
@@ -455,19 +455,97 @@ export interface SkippedOutOfScope {
|
|
|
455
455
|
*/
|
|
456
456
|
readonly folded?: boolean;
|
|
457
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 & {});
|
|
490
|
+
}
|
|
491
|
+
/**
|
|
492
|
+
* A stored record a delete in the write left with no link of a relation it had
|
|
493
|
+
* one of: the deleted record was its last link of that relation.
|
|
494
|
+
*
|
|
495
|
+
* Deleting a record never deletes the records linked to it. Its links are
|
|
496
|
+
* removed or cleared, as the relation's `on_delete` says, and listed under
|
|
497
|
+
* `deleted.relations`; a link the same write also states may be reported under
|
|
498
|
+
* `relationship_outcomes` as well, or instead. A record left without any link
|
|
499
|
+
* of a relation is listed here, so the caller can decide whether it still
|
|
500
|
+
* belongs.
|
|
501
|
+
*/
|
|
502
|
+
export interface OrphanedRecord {
|
|
503
|
+
/** The object type of the record left without a link. */
|
|
504
|
+
readonly object_type_name: string;
|
|
505
|
+
/**
|
|
506
|
+
* The record as the write's other entries name it: by the write's own
|
|
507
|
+
* identifier when the write names it, otherwise by its primary key, rendered
|
|
508
|
+
* `field='value'` (a composite key's parts comma-separated). Empty for a type
|
|
509
|
+
* without a key, for a key missing a part, and on a folded entry.
|
|
510
|
+
*/
|
|
511
|
+
readonly identity: string;
|
|
512
|
+
/**
|
|
513
|
+
* The relation the record no longer has a link of, by its class name: an XMD
|
|
514
|
+
* relation `works_at` comes back as `WorksAt`.
|
|
515
|
+
*/
|
|
516
|
+
readonly relation: string;
|
|
517
|
+
/** On a folded entry, how many records it stands for. */
|
|
518
|
+
readonly count?: number;
|
|
519
|
+
/**
|
|
520
|
+
* `true` on an entry that stands for the records past the first 100 of one
|
|
521
|
+
* type and relation, with an empty `identity` and their `count`.
|
|
522
|
+
*/
|
|
523
|
+
readonly folded?: boolean;
|
|
524
|
+
}
|
|
458
525
|
/**
|
|
459
526
|
* What a write did, grouped into `created` / `updated` / `deleted`, plus what a
|
|
460
|
-
* `"drop"`-mode scope left out
|
|
527
|
+
* `"drop"`-mode scope left out, the contradictions a field merge resolved and
|
|
528
|
+
* the records a delete left without a link.
|
|
461
529
|
*
|
|
462
530
|
* The three groups stay `unknown`: their shape is the server's to evolve and
|
|
463
531
|
* this client has never modelled it. `skipped_out_of_scope` is typed because it
|
|
464
532
|
* is the one part a caller has to branch on — a `"drop"`-mode write succeeds
|
|
465
533
|
* whether or not it skipped anything, so this list is the only report that some
|
|
466
|
-
* of what the text said was not applied.
|
|
534
|
+
* of what the text said was not applied. `merge_contradictions` is typed because
|
|
535
|
+
* it is the only report of what a merge chose between, and `orphaned_records`
|
|
536
|
+
* because it is the only report of a record a delete left without a link.
|
|
467
537
|
*/
|
|
468
538
|
export interface WriteChanges {
|
|
469
539
|
readonly created: unknown;
|
|
470
540
|
readonly updated: unknown;
|
|
541
|
+
/**
|
|
542
|
+
* What the write deleted, as `{ objects, relations }`. A record delete's
|
|
543
|
+
* links, removed or cleared as the relation's `on_delete` says, are listed
|
|
544
|
+
* under `relations`; a link the same write also states may be reported
|
|
545
|
+
* under `relationship_outcomes` as well, or instead. Past 100 links of one
|
|
546
|
+
* relation, the rest arrive as one entry with that relation's `name`, empty
|
|
547
|
+
* `endpoints` and `fields`, `folded: true` and their `count`.
|
|
548
|
+
*/
|
|
471
549
|
readonly deleted: unknown;
|
|
472
550
|
/**
|
|
473
551
|
* Omitted by the server when nothing was skipped — which is every write that
|
|
@@ -478,6 +556,26 @@ export interface WriteChanges {
|
|
|
478
556
|
* {@link SkippedOutOfScope.folded}).
|
|
479
557
|
*/
|
|
480
558
|
readonly skipped_out_of_scope?: readonly SkippedOutOfScope[];
|
|
559
|
+
/**
|
|
560
|
+
* The contradictions a merge reported for a field the write changed.
|
|
561
|
+
* Advisory: the write landed either way. Omitted by the server when there is
|
|
562
|
+
* none, and by a server that predates field merges, so `undefined` and `[]`
|
|
563
|
+
* both mean "none reported" — not that the texts agreed: a merge that failed,
|
|
564
|
+
* appended, or left the stored text unchanged reports none.
|
|
565
|
+
*/
|
|
566
|
+
readonly merge_contradictions?: readonly FieldMergeContradiction[];
|
|
567
|
+
/**
|
|
568
|
+
* The stored records a delete in this write left with no link of a relation
|
|
569
|
+
* they had one of. Advisory: delete or relink such a record if it no longer
|
|
570
|
+
* belongs. A record the write deleted, or that still has a link of that
|
|
571
|
+
* relation when the write completes, is not listed. Omitted by the server
|
|
572
|
+
* when there is none, and by a server that predates the report, so
|
|
573
|
+
* `undefined` and `[]` both mean "none reported" — and nothing at all when
|
|
574
|
+
* `relationship_outcomes` reports the write's summary unavailable (an entry
|
|
575
|
+
* with `status: "unavailable"`). Past 100 entries of one type and relation,
|
|
576
|
+
* the rest arrive folded into one entry (see {@link OrphanedRecord.folded}).
|
|
577
|
+
*/
|
|
578
|
+
readonly orphaned_records?: readonly OrphanedRecord[];
|
|
481
579
|
}
|
|
482
580
|
export interface WriteResult {
|
|
483
581
|
readonly write_id: string;
|
|
@@ -485,8 +583,10 @@ export interface WriteResult {
|
|
|
485
583
|
/** Deep link to this write's trace in the console; `null` if no console is configured. */
|
|
486
584
|
readonly console_url: string | null;
|
|
487
585
|
/**
|
|
488
|
-
* What the write did, grouped into `created` / `updated` / `deleted
|
|
489
|
-
*
|
|
586
|
+
* What the write did, grouped into `created` / `updated` / `deleted`; for a
|
|
587
|
+
* scoped write in `"drop"` mode, what it skipped instead of applying; what a
|
|
588
|
+
* field merge chose between (`merge_contradictions`); and the records a delete
|
|
589
|
+
* left without a link (`orphaned_records`).
|
|
490
590
|
*/
|
|
491
591
|
readonly changes: WriteChanges;
|
|
492
592
|
}
|
|
@@ -508,7 +608,8 @@ export interface WriteStatusResult {
|
|
|
508
608
|
* What the finished write did, in the same shape {@link WriteResult.changes}
|
|
509
609
|
* carries — and the async caller's only view of it, since `writeAsync`
|
|
510
610
|
* returns before the write has done anything. It is therefore where a
|
|
511
|
-
* `"drop"`-mode scope reports what it skipped
|
|
611
|
+
* `"drop"`-mode scope reports what it skipped, a field merge what it chose
|
|
612
|
+
* between, and a delete the records it left without a link.
|
|
512
613
|
*
|
|
513
614
|
* Optional because a status is not always about a finished write: a queued,
|
|
514
615
|
* in-progress, failed or unknown `write_id` carries none. Read it once
|
|
@@ -980,7 +1081,7 @@ export interface PatchInstanceMetadataOptions {
|
|
|
980
1081
|
timeoutMs?: number;
|
|
981
1082
|
}
|
|
982
1083
|
export interface UpdateInstanceSchemaOptions {
|
|
983
|
-
/** Serialized migration plan from `enhanceSchema`; required for non-additive changes. */
|
|
1084
|
+
/** Serialized migration plan from `enhanceInstanceSchema` or `enhanceSchema`; required for non-additive changes. */
|
|
984
1085
|
migrationPlan?: MigrationPlan | Record<string, unknown>;
|
|
985
1086
|
/** Authorise ops that drop data (remove object/field, lossy type cast). */
|
|
986
1087
|
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.21.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, OrphanedRecord, AsyncWriteResult, WriteStatusResult, ExtractResult, GenerateSchemaResult, ToolDescription, ToolParameterDescription, RawDescribeResult, } from "./types.js";
|
|
14
14
|
export type { WriteMutation, ObjectMutationBody, ObjectCreatePayload, ObjectUpdatePayload, ObjectDeletePayload, RelationMutationBody, RelationCreatePayload, RelationUpdatePayload, RelationDeletePayload, RelationEndpoint, } from "./types.js";
|
|
15
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,6 +85,11 @@ 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
|
|
@@ -114,8 +119,9 @@ export declare class InstanceHandle {
|
|
|
114
119
|
writeAsync(mutations: readonly WriteMutation[], options?: RequestOptions): Promise<AsyncWriteResult>;
|
|
115
120
|
/**
|
|
116
121
|
* Poll a queued write. A finished one carries `changes` — the same report
|
|
117
|
-
* {@link write} returns inline, including what a `"drop"`-mode scope skipped
|
|
118
|
-
* 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.
|
|
119
125
|
*/
|
|
120
126
|
writeStatus(writeId: string, options?: RequestOptions): Promise<WriteStatusResult>;
|
|
121
127
|
extract(text: string, options?: ExtractOptions): Promise<ExtractResult>;
|
package/dist/esm/instance.js
CHANGED
|
@@ -294,8 +294,9 @@ export class InstanceHandle {
|
|
|
294
294
|
}
|
|
295
295
|
/**
|
|
296
296
|
* Poll a queued write. A finished one carries `changes` — the same report
|
|
297
|
-
* {@link write} returns inline, including what a `"drop"`-mode scope skipped
|
|
298
|
-
* 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.
|
|
299
300
|
*/
|
|
300
301
|
async writeStatus(writeId, options) {
|
|
301
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
|
@@ -455,19 +455,97 @@ export interface SkippedOutOfScope {
|
|
|
455
455
|
*/
|
|
456
456
|
readonly folded?: boolean;
|
|
457
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 & {});
|
|
490
|
+
}
|
|
491
|
+
/**
|
|
492
|
+
* A stored record a delete in the write left with no link of a relation it had
|
|
493
|
+
* one of: the deleted record was its last link of that relation.
|
|
494
|
+
*
|
|
495
|
+
* Deleting a record never deletes the records linked to it. Its links are
|
|
496
|
+
* removed or cleared, as the relation's `on_delete` says, and listed under
|
|
497
|
+
* `deleted.relations`; a link the same write also states may be reported under
|
|
498
|
+
* `relationship_outcomes` as well, or instead. A record left without any link
|
|
499
|
+
* of a relation is listed here, so the caller can decide whether it still
|
|
500
|
+
* belongs.
|
|
501
|
+
*/
|
|
502
|
+
export interface OrphanedRecord {
|
|
503
|
+
/** The object type of the record left without a link. */
|
|
504
|
+
readonly object_type_name: string;
|
|
505
|
+
/**
|
|
506
|
+
* The record as the write's other entries name it: by the write's own
|
|
507
|
+
* identifier when the write names it, otherwise by its primary key, rendered
|
|
508
|
+
* `field='value'` (a composite key's parts comma-separated). Empty for a type
|
|
509
|
+
* without a key, for a key missing a part, and on a folded entry.
|
|
510
|
+
*/
|
|
511
|
+
readonly identity: string;
|
|
512
|
+
/**
|
|
513
|
+
* The relation the record no longer has a link of, by its class name: an XMD
|
|
514
|
+
* relation `works_at` comes back as `WorksAt`.
|
|
515
|
+
*/
|
|
516
|
+
readonly relation: string;
|
|
517
|
+
/** On a folded entry, how many records it stands for. */
|
|
518
|
+
readonly count?: number;
|
|
519
|
+
/**
|
|
520
|
+
* `true` on an entry that stands for the records past the first 100 of one
|
|
521
|
+
* type and relation, with an empty `identity` and their `count`.
|
|
522
|
+
*/
|
|
523
|
+
readonly folded?: boolean;
|
|
524
|
+
}
|
|
458
525
|
/**
|
|
459
526
|
* What a write did, grouped into `created` / `updated` / `deleted`, plus what a
|
|
460
|
-
* `"drop"`-mode scope left out
|
|
527
|
+
* `"drop"`-mode scope left out, the contradictions a field merge resolved and
|
|
528
|
+
* the records a delete left without a link.
|
|
461
529
|
*
|
|
462
530
|
* The three groups stay `unknown`: their shape is the server's to evolve and
|
|
463
531
|
* this client has never modelled it. `skipped_out_of_scope` is typed because it
|
|
464
532
|
* is the one part a caller has to branch on — a `"drop"`-mode write succeeds
|
|
465
533
|
* whether or not it skipped anything, so this list is the only report that some
|
|
466
|
-
* of what the text said was not applied.
|
|
534
|
+
* of what the text said was not applied. `merge_contradictions` is typed because
|
|
535
|
+
* it is the only report of what a merge chose between, and `orphaned_records`
|
|
536
|
+
* because it is the only report of a record a delete left without a link.
|
|
467
537
|
*/
|
|
468
538
|
export interface WriteChanges {
|
|
469
539
|
readonly created: unknown;
|
|
470
540
|
readonly updated: unknown;
|
|
541
|
+
/**
|
|
542
|
+
* What the write deleted, as `{ objects, relations }`. A record delete's
|
|
543
|
+
* links, removed or cleared as the relation's `on_delete` says, are listed
|
|
544
|
+
* under `relations`; a link the same write also states may be reported
|
|
545
|
+
* under `relationship_outcomes` as well, or instead. Past 100 links of one
|
|
546
|
+
* relation, the rest arrive as one entry with that relation's `name`, empty
|
|
547
|
+
* `endpoints` and `fields`, `folded: true` and their `count`.
|
|
548
|
+
*/
|
|
471
549
|
readonly deleted: unknown;
|
|
472
550
|
/**
|
|
473
551
|
* Omitted by the server when nothing was skipped — which is every write that
|
|
@@ -478,6 +556,26 @@ export interface WriteChanges {
|
|
|
478
556
|
* {@link SkippedOutOfScope.folded}).
|
|
479
557
|
*/
|
|
480
558
|
readonly skipped_out_of_scope?: readonly SkippedOutOfScope[];
|
|
559
|
+
/**
|
|
560
|
+
* The contradictions a merge reported for a field the write changed.
|
|
561
|
+
* Advisory: the write landed either way. Omitted by the server when there is
|
|
562
|
+
* none, and by a server that predates field merges, so `undefined` and `[]`
|
|
563
|
+
* both mean "none reported" — not that the texts agreed: a merge that failed,
|
|
564
|
+
* appended, or left the stored text unchanged reports none.
|
|
565
|
+
*/
|
|
566
|
+
readonly merge_contradictions?: readonly FieldMergeContradiction[];
|
|
567
|
+
/**
|
|
568
|
+
* The stored records a delete in this write left with no link of a relation
|
|
569
|
+
* they had one of. Advisory: delete or relink such a record if it no longer
|
|
570
|
+
* belongs. A record the write deleted, or that still has a link of that
|
|
571
|
+
* relation when the write completes, is not listed. Omitted by the server
|
|
572
|
+
* when there is none, and by a server that predates the report, so
|
|
573
|
+
* `undefined` and `[]` both mean "none reported" — and nothing at all when
|
|
574
|
+
* `relationship_outcomes` reports the write's summary unavailable (an entry
|
|
575
|
+
* with `status: "unavailable"`). Past 100 entries of one type and relation,
|
|
576
|
+
* the rest arrive folded into one entry (see {@link OrphanedRecord.folded}).
|
|
577
|
+
*/
|
|
578
|
+
readonly orphaned_records?: readonly OrphanedRecord[];
|
|
481
579
|
}
|
|
482
580
|
export interface WriteResult {
|
|
483
581
|
readonly write_id: string;
|
|
@@ -485,8 +583,10 @@ export interface WriteResult {
|
|
|
485
583
|
/** Deep link to this write's trace in the console; `null` if no console is configured. */
|
|
486
584
|
readonly console_url: string | null;
|
|
487
585
|
/**
|
|
488
|
-
* What the write did, grouped into `created` / `updated` / `deleted
|
|
489
|
-
*
|
|
586
|
+
* What the write did, grouped into `created` / `updated` / `deleted`; for a
|
|
587
|
+
* scoped write in `"drop"` mode, what it skipped instead of applying; what a
|
|
588
|
+
* field merge chose between (`merge_contradictions`); and the records a delete
|
|
589
|
+
* left without a link (`orphaned_records`).
|
|
490
590
|
*/
|
|
491
591
|
readonly changes: WriteChanges;
|
|
492
592
|
}
|
|
@@ -508,7 +608,8 @@ export interface WriteStatusResult {
|
|
|
508
608
|
* What the finished write did, in the same shape {@link WriteResult.changes}
|
|
509
609
|
* carries — and the async caller's only view of it, since `writeAsync`
|
|
510
610
|
* returns before the write has done anything. It is therefore where a
|
|
511
|
-
* `"drop"`-mode scope reports what it skipped
|
|
611
|
+
* `"drop"`-mode scope reports what it skipped, a field merge what it chose
|
|
612
|
+
* between, and a delete the records it left without a link.
|
|
512
613
|
*
|
|
513
614
|
* Optional because a status is not always about a finished write: a queued,
|
|
514
615
|
* in-progress, failed or unknown `write_id` carries none. Read it once
|
|
@@ -980,7 +1081,7 @@ export interface PatchInstanceMetadataOptions {
|
|
|
980
1081
|
timeoutMs?: number;
|
|
981
1082
|
}
|
|
982
1083
|
export interface UpdateInstanceSchemaOptions {
|
|
983
|
-
/** Serialized migration plan from `enhanceSchema`; required for non-additive changes. */
|
|
1084
|
+
/** Serialized migration plan from `enhanceInstanceSchema` or `enhanceSchema`; required for non-additive changes. */
|
|
984
1085
|
migrationPlan?: MigrationPlan | Record<string, unknown>;
|
|
985
1086
|
/** Authorise ops that drop data (remove object/field, lossy type cast). */
|
|
986
1087
|
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.21.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.21.0";
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "xmemory",
|
|
3
|
-
"version": "3.
|
|
3
|
+
"version": "3.21.0",
|
|
4
4
|
"description": "xmemory",
|
|
5
5
|
"keywords": [
|
|
6
6
|
"xmemory"
|
|
@@ -40,8 +40,8 @@
|
|
|
40
40
|
"build:clean": "node -e \"require('fs').rmSync('dist',{recursive:true,force:true})\"",
|
|
41
41
|
"build:esm": "tsc -p tsconfig.esm.json && node -e \"require('fs').writeFileSync('dist/esm/package.json','{\\\"type\\\":\\\"module\\\"}')\"",
|
|
42
42
|
"build:cjs": "tsc -p tsconfig.cjs.json && node -e \"require('fs').writeFileSync('dist/cjs/package.json','{\\\"type\\\":\\\"commonjs\\\"}')\"",
|
|
43
|
-
"test": "tsc --noEmit && node --import tsx test.ts",
|
|
44
|
-
"test:types": "tsc --noEmit",
|
|
43
|
+
"test": "tsc --noEmit && tsc -p tsconfig.test.json && node --import tsx test.ts",
|
|
44
|
+
"test:types": "tsc --noEmit && tsc -p tsconfig.test.json",
|
|
45
45
|
"prepublishOnly": "npm run build"
|
|
46
46
|
},
|
|
47
47
|
"devDependencies": {
|