xmemory 3.1.1 → 3.2.1
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 +19 -7
- package/dist/index.d.ts +1 -1
- package/dist/instance.js +5 -1
- package/dist/types.d.ts +29 -10
- package/dist/types.js +3 -5
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -155,6 +155,24 @@ console.log(result.reader_result);
|
|
|
155
155
|
|
|
156
156
|
Options: `{ readMode?, scope?, traceId?, timeoutMs? }` — `readMode` defaults to `"single-answer"`.
|
|
157
157
|
|
|
158
|
+
#### Composite queries
|
|
159
|
+
|
|
160
|
+
When a query bundles several independent questions, the server may decompose it
|
|
161
|
+
into sub-queries and answer each one. `reader_result` is still the combined
|
|
162
|
+
answer (for `"single-answer"` mode, a labelled multi-part string); `reader_results`
|
|
163
|
+
holds one `TaggedReaderResult` (`{ sub_query, reader_result, error }`) per
|
|
164
|
+
sub-query so you can read each answer unambiguously — a single-intent query
|
|
165
|
+
decomposes to one entry. `reader_results` is always an array: a server without
|
|
166
|
+
question decomposition omits the field on the wire and the client normalizes it
|
|
167
|
+
to `[]`, so it is empty regardless of how many questions the query held.
|
|
168
|
+
|
|
169
|
+
```typescript
|
|
170
|
+
const result = await inst.read("Who leads sales, and where is HQ?");
|
|
171
|
+
for (const part of result.reader_results) {
|
|
172
|
+
console.log(part.sub_query, "→", part.error ?? part.reader_result);
|
|
173
|
+
}
|
|
174
|
+
```
|
|
175
|
+
|
|
158
176
|
#### Scoped reads
|
|
159
177
|
|
|
160
178
|
By default a read may draw on the whole instance. Pass a `scope` to restrict it
|
|
@@ -343,19 +361,17 @@ when the server returned one), `details` (an optional structured payload), and
|
|
|
343
361
|
`retryAfter` (the `Retry-After` header in seconds, when the server sent one).
|
|
344
362
|
|
|
345
363
|
**Branch on `code`, not on the bare HTTP status** — the same status can mean
|
|
346
|
-
different things
|
|
364
|
+
different things:
|
|
347
365
|
|
|
348
366
|
| HTTP | `code` | Meaning | Retryable? |
|
|
349
367
|
| ---- | ----------------- | ---------------------------------------------------- | ---------------------------------- |
|
|
350
368
|
| 402 | `QUOTA_EXCEEDED` | Tenant exhausted its plan/usage allowance (a daily or monthly token quota). | **No.** Wait for the window to reset. |
|
|
351
|
-
| 402 | `TRIAL_ENDED` | Trial over / subscription lapsed. | **No.** Needs a plan change. |
|
|
352
369
|
| 429 | `RATE_LIMITED` | Genuine velocity / rate limit. | **Yes**, with backoff. |
|
|
353
370
|
|
|
354
371
|
For `QUOTA_EXCEEDED`, `details` carries `kind`
|
|
355
372
|
(`"daily_quota_exceeded"` | `"monthly_quota_exceeded"`) and
|
|
356
373
|
`retry_after_seconds` (`number | null`); when the window is resettable the
|
|
357
374
|
server also sends a `Retry-After` header, surfaced as `retryAfter` (seconds).
|
|
358
|
-
`TRIAL_ENDED` may carry `details.kind === "trial_exceeded"` or no details.
|
|
359
375
|
`RATE_LIMITED` is retryable — honour `retryAfter` (or `Retry-After`) for backoff.
|
|
360
376
|
The client never retries on its own; it only surfaces the value.
|
|
361
377
|
|
|
@@ -371,10 +387,6 @@ try {
|
|
|
371
387
|
console.error(`Quota exhausted (${kind}); resets in ${e.retryAfter ?? "?"}s`);
|
|
372
388
|
break;
|
|
373
389
|
}
|
|
374
|
-
case "TRIAL_ENDED":
|
|
375
|
-
// Non-retryable: trial over / subscription lapsed — upgrade required.
|
|
376
|
-
console.error("Trial ended — upgrade the plan.");
|
|
377
|
-
break;
|
|
378
390
|
case "RATE_LIMITED":
|
|
379
391
|
// Retryable: back off and retry, honouring Retry-After.
|
|
380
392
|
console.error(`Rate limited; retry after ${e.retryAfter ?? "a short delay"}s`);
|
package/dist/index.d.ts
CHANGED
|
@@ -9,6 +9,6 @@ export { SchemaType } from "./types.js";
|
|
|
9
9
|
export type { SchemaTypeValue, ExtractionLogic, ReadMode, WriteQueueStatus, FieldType, OnDelete, CastStrategy, DecisionKind, MigrationSource, } from "./types.js";
|
|
10
10
|
export type { ScopeObject, ReadScope, RelationsScope } from "./types.js";
|
|
11
11
|
export type { XmemoryClientOptions, RequestOptions, ReadOptions, WriteOptions, ExtractOptions, CreateInstanceOptions, GenerateSchemaOptions, UpdateInstanceSchemaOptions, DryRunMigrationOptions, ListMigrationsOptions, GetMigrationOptions, SuggestionRequestOptions, } from "./types.js";
|
|
12
|
-
export type { ClusterInfo, InstanceInfo, InstanceSchemaInfo, ReadResult, WriteResult, AsyncWriteResult, WriteStatusResult, ExtractResult, GenerateSchemaResult, ToolDescription, ToolParameterDescription, RawDescribeResult, } from "./types.js";
|
|
12
|
+
export type { ClusterInfo, InstanceInfo, InstanceSchemaInfo, ReadResult, TaggedReaderResult, WriteResult, AsyncWriteResult, WriteStatusResult, ExtractResult, GenerateSchemaResult, ToolDescription, ToolParameterDescription, RawDescribeResult, } from "./types.js";
|
|
13
13
|
export type { MigrationPlan, MigrationOp, FieldSpec, AddObject, RemoveObject, RenameObject, ChangeObject, AddField, RemoveField, RenameField, ChangeField, AddRelation, RemoveRelation, RenameRelation, ChangeRelation, DefaultValue, EnumValues, } from "./types.js";
|
|
14
14
|
export type { EnhanceSchemaResult, PlanSummary, DryRunResult, MigrationRecord, ListMigrationsResult, GetMigrationResult, ConsolidatedProposal, ProposalItem, ReviewSuggestionsResult, DecisionInput, RecordedDecision, DependencyWarning, DecideSuggestionsResult, ApplyPendingDecisionsResult, } from "./types.js";
|
package/dist/instance.js
CHANGED
|
@@ -127,10 +127,14 @@ export class InstanceHandle {
|
|
|
127
127
|
}
|
|
128
128
|
if (options?.traceId != null)
|
|
129
129
|
body.trace_id = options.traceId;
|
|
130
|
-
|
|
130
|
+
// The wire shape omits `reader_results` on a server without question
|
|
131
|
+
// decomposition, so type it as optional here and normalize to an always-array
|
|
132
|
+
// for the public `ReadResult` below.
|
|
133
|
+
const result = await this._requestOne("POST", `/instances/${this.id}/read`, {
|
|
131
134
|
body,
|
|
132
135
|
timeoutMs: options?.timeoutMs,
|
|
133
136
|
});
|
|
137
|
+
return { ...result, reader_results: result.reader_results ?? [] };
|
|
134
138
|
}
|
|
135
139
|
async write(text, options) {
|
|
136
140
|
const body = {
|
package/dist/types.d.ts
CHANGED
|
@@ -34,9 +34,8 @@ export declare class XmemoryAPIError extends Error {
|
|
|
34
34
|
/**
|
|
35
35
|
* Structured error code when the server returned one. **Branch on this,
|
|
36
36
|
* not on the bare HTTP `status`** — the same status can mean different
|
|
37
|
-
* things. HTTP 402 carries
|
|
38
|
-
* exhausted — non-retryable)
|
|
39
|
-
* lapsed — non-retryable); HTTP 429 carries `"RATE_LIMITED"` (genuine
|
|
37
|
+
* things. HTTP 402 carries `"QUOTA_EXCEEDED"` (plan/usage allowance
|
|
38
|
+
* exhausted — non-retryable); HTTP 429 carries `"RATE_LIMITED"` (genuine
|
|
40
39
|
* velocity limit — retryable with backoff, honour `retryAfter`). For the
|
|
41
40
|
* schema-evolution endpoints this is the `error_type` discriminator
|
|
42
41
|
* (e.g. `"stale_proposal_version"`, `"destructive_confirmation_required"`).
|
|
@@ -47,8 +46,7 @@ export declare class XmemoryAPIError extends Error {
|
|
|
47
46
|
* Optional structured `details` payload attached to some errors. For
|
|
48
47
|
* `"QUOTA_EXCEEDED"` this carries `kind`
|
|
49
48
|
* (`"daily_quota_exceeded"` | `"monthly_quota_exceeded"`) and
|
|
50
|
-
* `retry_after_seconds` (`number | null`)
|
|
51
|
-
* `kind: "trial_exceeded"` or no details at all.
|
|
49
|
+
* `retry_after_seconds` (`number | null`).
|
|
52
50
|
*/
|
|
53
51
|
readonly details?: (Record<string, unknown> | null) | undefined;
|
|
54
52
|
/**
|
|
@@ -63,9 +61,8 @@ export declare class XmemoryAPIError extends Error {
|
|
|
63
61
|
/**
|
|
64
62
|
* Structured error code when the server returned one. **Branch on this,
|
|
65
63
|
* not on the bare HTTP `status`** — the same status can mean different
|
|
66
|
-
* things. HTTP 402 carries
|
|
67
|
-
* exhausted — non-retryable)
|
|
68
|
-
* lapsed — non-retryable); HTTP 429 carries `"RATE_LIMITED"` (genuine
|
|
64
|
+
* things. HTTP 402 carries `"QUOTA_EXCEEDED"` (plan/usage allowance
|
|
65
|
+
* exhausted — non-retryable); HTTP 429 carries `"RATE_LIMITED"` (genuine
|
|
69
66
|
* velocity limit — retryable with backoff, honour `retryAfter`). For the
|
|
70
67
|
* schema-evolution endpoints this is the `error_type` discriminator
|
|
71
68
|
* (e.g. `"stale_proposal_version"`, `"destructive_confirmation_required"`).
|
|
@@ -76,8 +73,7 @@ export declare class XmemoryAPIError extends Error {
|
|
|
76
73
|
* Optional structured `details` payload attached to some errors. For
|
|
77
74
|
* `"QUOTA_EXCEEDED"` this carries `kind`
|
|
78
75
|
* (`"daily_quota_exceeded"` | `"monthly_quota_exceeded"`) and
|
|
79
|
-
* `retry_after_seconds` (`number | null`)
|
|
80
|
-
* `kind: "trial_exceeded"` or no details at all.
|
|
76
|
+
* `retry_after_seconds` (`number | null`).
|
|
81
77
|
*/
|
|
82
78
|
details?: (Record<string, unknown> | null) | undefined,
|
|
83
79
|
/**
|
|
@@ -112,9 +108,32 @@ export interface InstanceInfo {
|
|
|
112
108
|
export interface InstanceSchemaInfo {
|
|
113
109
|
readonly data_schema: Record<string, unknown>;
|
|
114
110
|
}
|
|
111
|
+
/**
|
|
112
|
+
* One sub-query and its own answer, in the requested read mode. Appears in
|
|
113
|
+
* {@link ReadResult.reader_results} when the server decomposed a composite query
|
|
114
|
+
* into independent sub-queries.
|
|
115
|
+
*/
|
|
116
|
+
export interface TaggedReaderResult {
|
|
117
|
+
readonly sub_query: string;
|
|
118
|
+
readonly reader_result: unknown;
|
|
119
|
+
/**
|
|
120
|
+
* A user-safe message set when this sub-query could not be answered while the
|
|
121
|
+
* others still were (partial tolerance); `null` otherwise.
|
|
122
|
+
*/
|
|
123
|
+
readonly error: string | null;
|
|
124
|
+
}
|
|
115
125
|
export interface ReadResult {
|
|
116
126
|
readonly trace_id: string | null;
|
|
117
127
|
readonly reader_result: unknown;
|
|
128
|
+
/**
|
|
129
|
+
* Per-sub-query answers when the server decomposed the query into independent
|
|
130
|
+
* sub-queries — one entry per sub-query, so a single-intent query decomposes
|
|
131
|
+
* to exactly one. `reader_result` above stays the combined back-compat value.
|
|
132
|
+
* Always an array: a server without question decomposition (or with it
|
|
133
|
+
* disabled) omits the field on the wire and the client normalizes it to `[]`,
|
|
134
|
+
* so the array is empty regardless of how many questions the query held.
|
|
135
|
+
*/
|
|
136
|
+
readonly reader_results: readonly TaggedReaderResult[];
|
|
118
137
|
}
|
|
119
138
|
export interface WriteResult {
|
|
120
139
|
readonly write_id: string;
|
package/dist/types.js
CHANGED
|
@@ -17,9 +17,8 @@ export class XmemoryAPIError extends Error {
|
|
|
17
17
|
/**
|
|
18
18
|
* Structured error code when the server returned one. **Branch on this,
|
|
19
19
|
* not on the bare HTTP `status`** — the same status can mean different
|
|
20
|
-
* things. HTTP 402 carries
|
|
21
|
-
* exhausted — non-retryable)
|
|
22
|
-
* lapsed — non-retryable); HTTP 429 carries `"RATE_LIMITED"` (genuine
|
|
20
|
+
* things. HTTP 402 carries `"QUOTA_EXCEEDED"` (plan/usage allowance
|
|
21
|
+
* exhausted — non-retryable); HTTP 429 carries `"RATE_LIMITED"` (genuine
|
|
23
22
|
* velocity limit — retryable with backoff, honour `retryAfter`). For the
|
|
24
23
|
* schema-evolution endpoints this is the `error_type` discriminator
|
|
25
24
|
* (e.g. `"stale_proposal_version"`, `"destructive_confirmation_required"`).
|
|
@@ -30,8 +29,7 @@ export class XmemoryAPIError extends Error {
|
|
|
30
29
|
* Optional structured `details` payload attached to some errors. For
|
|
31
30
|
* `"QUOTA_EXCEEDED"` this carries `kind`
|
|
32
31
|
* (`"daily_quota_exceeded"` | `"monthly_quota_exceeded"`) and
|
|
33
|
-
* `retry_after_seconds` (`number | null`)
|
|
34
|
-
* `kind: "trial_exceeded"` or no details at all.
|
|
32
|
+
* `retry_after_seconds` (`number | null`).
|
|
35
33
|
*/
|
|
36
34
|
details,
|
|
37
35
|
/**
|