xmemory 3.8.3 → 3.12.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 +107 -1
- package/dist/cjs/client.d.ts +35 -0
- package/dist/cjs/client.js +62 -2
- package/dist/cjs/index.d.ts +2 -2
- package/dist/cjs/instance.js +12 -2
- package/dist/cjs/types.d.ts +182 -2
- package/dist/cjs/version.d.ts +2 -0
- package/dist/cjs/version.js +5 -0
- package/dist/esm/client.d.ts +35 -0
- package/dist/esm/client.js +59 -1
- package/dist/esm/index.d.ts +2 -2
- package/dist/esm/instance.js +12 -2
- package/dist/esm/types.d.ts +182 -2
- package/dist/esm/version.d.ts +2 -0
- package/dist/esm/version.js +2 -0
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -249,7 +249,30 @@ const result = await inst.read("Who is on the team?");
|
|
|
249
249
|
console.log(result.reader_result);
|
|
250
250
|
```
|
|
251
251
|
|
|
252
|
-
Options: `{ readMode?, scope?, traceId?, timeoutMs? }` — `readMode` defaults to `"single-answer"`.
|
|
252
|
+
Options: `{ readMode?, scope?, includeRelatedTypes?, relatedTypesDepth?, traceId?, timeoutMs? }` — `readMode` defaults to `"single-answer"`.
|
|
253
|
+
|
|
254
|
+
#### What comes back
|
|
255
|
+
|
|
256
|
+
In `"single-answer"` mode `reader_result` is always the prose answer. In
|
|
257
|
+
`"raw-tables"` and `"xresponse"` mode its value says which of four answers the
|
|
258
|
+
read gave:
|
|
259
|
+
|
|
260
|
+
| `reader_result` | Meaning | What to do |
|
|
261
|
+
| --- | --- | --- |
|
|
262
|
+
| rows | Answered. | Use them. |
|
|
263
|
+
| 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. |
|
|
264
|
+
| `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. |
|
|
265
|
+
| *(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. |
|
|
266
|
+
|
|
267
|
+
```typescript
|
|
268
|
+
const result = await inst.read("Which invoices are overdue?", { readMode: "raw-tables" });
|
|
269
|
+
if (result.reader_result === null) {
|
|
270
|
+
// Not a concept this memory holds — try another instance.
|
|
271
|
+
} else {
|
|
272
|
+
const { rows } = result.reader_result as { columns: string[]; rows: unknown[][] };
|
|
273
|
+
// rows.length === 0 means the data is absent, not that the read failed.
|
|
274
|
+
}
|
|
275
|
+
```
|
|
253
276
|
|
|
254
277
|
#### Composite queries
|
|
255
278
|
|
|
@@ -269,6 +292,15 @@ for (const part of result.reader_results) {
|
|
|
269
292
|
}
|
|
270
293
|
```
|
|
271
294
|
|
|
295
|
+
Each part's `reader_result` uses the same four answers as above, with one more
|
|
296
|
+
case: a sub-query whose SQL failed carries the empty result *and* a user-safe
|
|
297
|
+
`error`, while the others are answered regardless. Its bytes then equal those
|
|
298
|
+
of a sub-query that matched nothing, so read `error` before `reader_result`, as
|
|
299
|
+
the loop above does. The combined `reader_result` folds the parts: rows if any
|
|
300
|
+
sub-query answered; else the empty result if any executed and matched nothing;
|
|
301
|
+
else `null`. In the tabular modes a read where *every* sub-query failed throws
|
|
302
|
+
the 422 above instead.
|
|
303
|
+
|
|
272
304
|
#### Scoped reads
|
|
273
305
|
|
|
274
306
|
By default a read may draw on the whole instance. Pass a `scope` to restrict it
|
|
@@ -297,6 +329,66 @@ const result = await inst.read("What do we know about these people?", {
|
|
|
297
329
|
restricts the read to the listed objects only, while `"all_relations"` also
|
|
298
330
|
exposes the relations among the in-scope objects.
|
|
299
331
|
|
|
332
|
+
#### Related types
|
|
333
|
+
|
|
334
|
+
A read can also say what else the memory could answer about. Pass
|
|
335
|
+
`includeRelatedTypes: "types"` and `related_types` on the result names the
|
|
336
|
+
object types the read touched, each with the fields it did not return and the
|
|
337
|
+
object types a declared relation links it to (the relation, both roles, and its
|
|
338
|
+
cardinality seen from the touched type), plus a catalog that describes every
|
|
339
|
+
named type (description, primary key, field names) and relation once. It is
|
|
340
|
+
derived from the instance schema and the statements the read executed — no
|
|
341
|
+
extra rows, no model call — so an agent can ask a deliberate follow-up instead
|
|
342
|
+
of guessing what the store holds.
|
|
343
|
+
|
|
344
|
+
```typescript
|
|
345
|
+
const result = await inst.read("Which courses require an English test?", {
|
|
346
|
+
includeRelatedTypes: "types",
|
|
347
|
+
});
|
|
348
|
+
for (const touched of result.related_types?.touched ?? []) {
|
|
349
|
+
console.log(touched.object_type, "did not return", touched.fields_not_returned);
|
|
350
|
+
for (const link of touched.related) {
|
|
351
|
+
const neighbour = result.related_types!.objects[link.object_type];
|
|
352
|
+
console.log(" linked to", link.object_type, "via", link.relation, neighbour.fields);
|
|
353
|
+
}
|
|
354
|
+
}
|
|
355
|
+
```
|
|
356
|
+
|
|
357
|
+
`related_types` is `null` unless the read asked for it. A requested read that
|
|
358
|
+
executed nothing arrives with `touched: []`. The server caps the payload;
|
|
359
|
+
`truncated` says when it did, and `omitted_touched` and each entry's
|
|
360
|
+
`omitted_related` count what was dropped.
|
|
361
|
+
|
|
362
|
+
To follow the relations further, add `relatedTypesDepth: 2` (up to 3). Every
|
|
363
|
+
entry under `related_types.objects` then carries its `distance` from the touched
|
|
364
|
+
types (0 for a touched type) and, between the touched types and the last level,
|
|
365
|
+
its own `related` edges, so the walk can be continued from the catalog:
|
|
366
|
+
|
|
367
|
+
```typescript
|
|
368
|
+
const result = await inst.read("Which courses require an English test?", {
|
|
369
|
+
includeRelatedTypes: "types",
|
|
370
|
+
relatedTypesDepth: 2,
|
|
371
|
+
});
|
|
372
|
+
for (const [name, entry] of Object.entries(result.related_types?.objects ?? {})) {
|
|
373
|
+
console.log(name, "at distance", entry.distance);
|
|
374
|
+
for (const link of entry.related) {
|
|
375
|
+
console.log(" linked to", link.object_type, "via", link.relation);
|
|
376
|
+
}
|
|
377
|
+
}
|
|
378
|
+
```
|
|
379
|
+
|
|
380
|
+
`related_types.depth` echoes the depth asked for. `distance` counts listed edges
|
|
381
|
+
from the nearest touched type, and `omitted_objects` counts the types within that
|
|
382
|
+
many relation levels that the server's budgets kept out of the catalog; `truncated`
|
|
383
|
+
says something was cut. Left unset, nothing is sent and the server serves one
|
|
384
|
+
level in the shape it always had: `depth`, `omitted_objects` and the catalog
|
|
385
|
+
entries' `distance`, `related` and `omitted_related` are then absent. A value
|
|
386
|
+
outside 1 to 3 is a 422 whose `code` is `VALIDATION_ERROR`. Asking for related
|
|
387
|
+
types needs the
|
|
388
|
+
`instance.get_own` permission on the API key, the same one the schema
|
|
389
|
+
endpoints need, on top of `data.read`: a key without it gets a 403 whose
|
|
390
|
+
message names the permission, and the plain read is unaffected.
|
|
391
|
+
|
|
300
392
|
#### Scoped writes
|
|
301
393
|
|
|
302
394
|
A write is normally free to touch anything in the instance: the extractor sees
|
|
@@ -527,6 +619,18 @@ Advisory values — `step.kind`, `fragment.merge`, `format` — are widened to a
|
|
|
527
619
|
added to the server after this release, so an additive change does not become a breaking
|
|
528
620
|
one. A `step.kind` you do not recognise is not something to execute.
|
|
529
621
|
|
|
622
|
+
## Request identification
|
|
623
|
+
|
|
624
|
+
Every request this client issues carries an `X-Xmemory-Client` header naming the package and its
|
|
625
|
+
release, followed by the host — for example `xmemory-node/3.9.0 (node v24.5.0; darwin)`. The
|
|
626
|
+
parenthetical reports `process.version` and `process.platform`, says `unknown` for either one a host
|
|
627
|
+
does not supply, and never carries a hostname. The API uses it to tell its own clients apart.
|
|
628
|
+
|
|
629
|
+
The identity travels in a dedicated header rather than in `User-Agent`, which belongs to the runtime:
|
|
630
|
+
your `User-Agent` is neither read nor written, and every other header on the request is left alone. A
|
|
631
|
+
proxy that strips unknown `X-` headers costs the attribution but not the request — the call still goes
|
|
632
|
+
through, counted as a generic caller.
|
|
633
|
+
|
|
530
634
|
## Error handling
|
|
531
635
|
|
|
532
636
|
All errors throw `XmemoryAPIError`. Health check failures throw `XmemoryHealthCheckError` (a subclass).
|
|
@@ -562,6 +666,8 @@ different things:
|
|
|
562
666
|
| ---- | ----------------- | ---------------------------------------------------- | ---------------------------------- |
|
|
563
667
|
| 402 | `QUOTA_EXCEEDED` | Tenant exhausted its plan/usage allowance (a daily or monthly token quota). | **No.** Wait for the window to reset. |
|
|
564
668
|
| 429 | `RATE_LIMITED` | Genuine velocity / rate limit. | **Yes**, with backoff. |
|
|
669
|
+
| 422 | `INVALID_INPUT` | A read that answered nothing: in `"raw-tables"` / `"xresponse"` mode every sub-query's SQL failed, or the model provider declined the input. See [What comes back](#what-comes-back). | **No.** Same input, same answer. |
|
|
670
|
+
| 403 | `FORBIDDEN` | The API key lacks a permission the call needs — for a read with `includeRelatedTypes: "types"`, `instance.get_own`; the message names it. See [Related types](#related-types). | **No.** Repeat without the option, or use a key that holds it. |
|
|
565
671
|
|
|
566
672
|
For `QUOTA_EXCEEDED`, `details` carries `kind`
|
|
567
673
|
(`"daily_quota_exceeded"` | `"monthly_quota_exceeded"`) and
|
package/dist/cjs/client.d.ts
CHANGED
|
@@ -3,6 +3,41 @@
|
|
|
3
3
|
*/
|
|
4
4
|
import { InstanceHandle } from "./instance.js";
|
|
5
5
|
import { type AgentSetupResult, type ClusterInfo, type CreateInstanceOptions, type DryRunMigrationOptions, type DryRunResult, type EnhanceSchemaResult, type GenerateSchemaOptions, type GenerateSchemaResult, type GetMigrationOptions, type InstanceInfo, type InstanceSchemaInfo, type ListMigrationsOptions, type ListMigrationsResult, type MigrationRecord, type PatchInstanceMetadataOptions, type RequestOptions, type SchemaTypeValue, type SetupFormatValue, type UpdateInstanceMetadataOptions, type UpdateInstanceSchemaOptions, type XmemoryClientOptions } from "./types.js";
|
|
6
|
+
/**
|
|
7
|
+
* The identity this client sends in `X-Xmemory-Client`. A host detail is admitted only as a short,
|
|
8
|
+
* non-empty run of printable ASCII carrying no space, semicolon or parenthesis, and becomes
|
|
9
|
+
* `unknown` otherwise.
|
|
10
|
+
* The reasons differ by character. A bundler shim routinely supplies a partial `process`, whose
|
|
11
|
+
* missing fields would write the word "undefined" into the header. A control character such as NUL
|
|
12
|
+
* or a newline makes `fetch` reject the request outright, and a character above `\xff` cannot be
|
|
13
|
+
* converted to a header value at all. The rest — a byte outside ASCII, a tab, a space, a semicolon,
|
|
14
|
+
* a parenthesis — is carried fine, but would blur the boundaries of the parenthetical this builds.
|
|
15
|
+
* The length cap is there because nothing else bounds what a host may report into a header this
|
|
16
|
+
* sends on every request. Not re-exported from `index.ts` — exported here so the tests can cover
|
|
17
|
+
* those substitutions directly.
|
|
18
|
+
*/
|
|
19
|
+
export declare function buildClientIdentity(version: string, host: {
|
|
20
|
+
version?: unknown;
|
|
21
|
+
platform?: unknown;
|
|
22
|
+
} | undefined): string;
|
|
23
|
+
/**
|
|
24
|
+
* The header this client identifies itself in. A dedicated field rather than `User-Agent`: that one
|
|
25
|
+
* belongs to whoever built the request — the runtime, or the caller — and in a browser `fetch`
|
|
26
|
+
* treats it as forbidden and drops it silently. Nothing else on the wire claims this name.
|
|
27
|
+
*/
|
|
28
|
+
export declare const CLIENT_HEADER = "X-Xmemory-Client";
|
|
29
|
+
/**
|
|
30
|
+
* The headers a request goes out with: everything the caller built, in a new object so the
|
|
31
|
+
* caller's own is left untouched, plus this client's identity. Any existing spelling of the identity
|
|
32
|
+
* header is dropped first — header names are case-insensitive on the wire, so leaving one behind
|
|
33
|
+
* would put two values under one name, and `fetch` joins those into a single comma-separated value
|
|
34
|
+
* whose first token is the one the API reads. `User-Agent` and everything else pass through
|
|
35
|
+
* untouched. No public entry point lets a caller supply request headers today — `_fetch` only ever
|
|
36
|
+
* sees what `_headers()` built — so the drop is defensive against a future call site that does, not
|
|
37
|
+
* a live collision. Not re-exported from `index.ts`; exported here so the tests can cover the merge
|
|
38
|
+
* directly.
|
|
39
|
+
*/
|
|
40
|
+
export declare function withClientHeader(existing: Record<string, string> | undefined): Record<string, string>;
|
|
6
41
|
export interface AdminNamespace {
|
|
7
42
|
listClusters(options?: RequestOptions & {
|
|
8
43
|
ids?: string[];
|
package/dist/cjs/client.js
CHANGED
|
@@ -3,10 +3,13 @@
|
|
|
3
3
|
* XmemoryClient — main entry point for the xmemory API.
|
|
4
4
|
*/
|
|
5
5
|
Object.defineProperty(exports, "__esModule", { value: true });
|
|
6
|
-
exports.XmemoryClient = void 0;
|
|
6
|
+
exports.XmemoryClient = exports.CLIENT_HEADER = void 0;
|
|
7
|
+
exports.buildClientIdentity = buildClientIdentity;
|
|
8
|
+
exports.withClientHeader = withClientHeader;
|
|
7
9
|
exports.xmemoryInstance = xmemoryInstance;
|
|
8
10
|
const instance_js_1 = require("./instance.js");
|
|
9
11
|
const types_js_1 = require("./types.js");
|
|
12
|
+
const version_js_1 = require("./version.js");
|
|
10
13
|
const DEFAULT_BASE_URL = "https://api.xmemory.ai";
|
|
11
14
|
/**
|
|
12
15
|
* An *own* property of a decoded response, or `undefined`.
|
|
@@ -27,6 +30,59 @@ function ownArray(source, key) {
|
|
|
27
30
|
return Array.isArray(value) ? value : [];
|
|
28
31
|
}
|
|
29
32
|
const DEFAULT_TIMEOUT_MS = 60_000;
|
|
33
|
+
const HOST_FIELD_MAX = 64;
|
|
34
|
+
/** One host detail, reduced to something a header value may safely carry. */
|
|
35
|
+
const hostField = (value) => typeof value === "string" &&
|
|
36
|
+
value.length <= HOST_FIELD_MAX &&
|
|
37
|
+
/^[\x21-\x7e]+$/.test(value) &&
|
|
38
|
+
!/[;()]/.test(value)
|
|
39
|
+
? value
|
|
40
|
+
: "unknown";
|
|
41
|
+
/**
|
|
42
|
+
* The identity this client sends in `X-Xmemory-Client`. A host detail is admitted only as a short,
|
|
43
|
+
* non-empty run of printable ASCII carrying no space, semicolon or parenthesis, and becomes
|
|
44
|
+
* `unknown` otherwise.
|
|
45
|
+
* The reasons differ by character. A bundler shim routinely supplies a partial `process`, whose
|
|
46
|
+
* missing fields would write the word "undefined" into the header. A control character such as NUL
|
|
47
|
+
* or a newline makes `fetch` reject the request outright, and a character above `\xff` cannot be
|
|
48
|
+
* converted to a header value at all. The rest — a byte outside ASCII, a tab, a space, a semicolon,
|
|
49
|
+
* a parenthesis — is carried fine, but would blur the boundaries of the parenthetical this builds.
|
|
50
|
+
* The length cap is there because nothing else bounds what a host may report into a header this
|
|
51
|
+
* sends on every request. Not re-exported from `index.ts` — exported here so the tests can cover
|
|
52
|
+
* those substitutions directly.
|
|
53
|
+
*/
|
|
54
|
+
function buildClientIdentity(version, host) {
|
|
55
|
+
return `xmemory-node/${version} (node ${hostField(host?.version)}; ${hostField(host?.platform)})`;
|
|
56
|
+
}
|
|
57
|
+
/**
|
|
58
|
+
* The header this client identifies itself in. A dedicated field rather than `User-Agent`: that one
|
|
59
|
+
* belongs to whoever built the request — the runtime, or the caller — and in a browser `fetch`
|
|
60
|
+
* treats it as forbidden and drops it silently. Nothing else on the wire claims this name.
|
|
61
|
+
*/
|
|
62
|
+
exports.CLIENT_HEADER = "X-Xmemory-Client";
|
|
63
|
+
// `process` is absent in a browser and partial under some bundler shims, so the fields are read
|
|
64
|
+
// defensively and each one falls back to `unknown`.
|
|
65
|
+
const CLIENT_IDENTITY = buildClientIdentity(version_js_1.VERSION, typeof process !== "undefined" ? process : undefined);
|
|
66
|
+
/**
|
|
67
|
+
* The headers a request goes out with: everything the caller built, in a new object so the
|
|
68
|
+
* caller's own is left untouched, plus this client's identity. Any existing spelling of the identity
|
|
69
|
+
* header is dropped first — header names are case-insensitive on the wire, so leaving one behind
|
|
70
|
+
* would put two values under one name, and `fetch` joins those into a single comma-separated value
|
|
71
|
+
* whose first token is the one the API reads. `User-Agent` and everything else pass through
|
|
72
|
+
* untouched. No public entry point lets a caller supply request headers today — `_fetch` only ever
|
|
73
|
+
* sees what `_headers()` built — so the drop is defensive against a future call site that does, not
|
|
74
|
+
* a live collision. Not re-exported from `index.ts`; exported here so the tests can cover the merge
|
|
75
|
+
* directly.
|
|
76
|
+
*/
|
|
77
|
+
function withClientHeader(existing) {
|
|
78
|
+
const headers = {};
|
|
79
|
+
for (const [name, value] of Object.entries(existing ?? {})) {
|
|
80
|
+
if (name.toLowerCase() !== exports.CLIENT_HEADER.toLowerCase())
|
|
81
|
+
headers[name] = value;
|
|
82
|
+
}
|
|
83
|
+
headers[exports.CLIENT_HEADER] = CLIENT_IDENTITY;
|
|
84
|
+
return headers;
|
|
85
|
+
}
|
|
30
86
|
const ORANGE = "\x1b[38;5;208m";
|
|
31
87
|
const RESET = "\x1b[0m";
|
|
32
88
|
function deprecationWarning(message) {
|
|
@@ -142,7 +198,11 @@ class XmemoryClient {
|
|
|
142
198
|
const controller = new AbortController();
|
|
143
199
|
const timer = setTimeout(() => controller.abort(), timeoutMs);
|
|
144
200
|
try {
|
|
145
|
-
return await fetch(url, {
|
|
201
|
+
return await fetch(url, {
|
|
202
|
+
...init,
|
|
203
|
+
headers: withClientHeader(init.headers),
|
|
204
|
+
signal: controller.signal,
|
|
205
|
+
});
|
|
146
206
|
}
|
|
147
207
|
finally {
|
|
148
208
|
clearTimeout(timer);
|
package/dist/cjs/index.d.ts
CHANGED
|
@@ -7,10 +7,10 @@ export { DescribeResult, InstanceHandle } from "./instance.js";
|
|
|
7
7
|
export { XmemoryAPIError, XmemoryHealthCheckError } from "./types.js";
|
|
8
8
|
export { SchemaType } from "./types.js";
|
|
9
9
|
export { AgentSurface, BindingTier, FragmentMerge, SetupFormat, StepKind } from "./types.js";
|
|
10
|
-
export type { AgentSetupResult, AgentSetupStep, AgentSetupSurface, AgentSurfaceValue, FragmentMergeValue, ProjectFragment, ProjectSetup, SetupFormatValue, StepKindValue, BindingTierValue, SchemaTypeValue, ExtractionLogic, ReadMode, WriteQueueStatus, FieldType, OnDelete, CastStrategy, DecisionKind, MigrationSource, } from "./types.js";
|
|
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 } 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, WriteResult, AsyncWriteResult, WriteStatusResult, ExtractResult, GenerateSchemaResult, ToolDescription, ToolParameterDescription, RawDescribeResult, } from "./types.js";
|
|
13
|
+
export type { ClusterInfo, InstanceInfo, InstanceSchemaInfo, ReadResult, TaggedReaderResult, RelatedTypes, RelatedTypesTouched, RelatedTypesLink, RelatedTypesObjectType, RelatedTypesRelation, WriteResult, 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.js
CHANGED
|
@@ -234,11 +234,16 @@ class InstanceHandle {
|
|
|
234
234
|
relations_scope: options.scope.relationsScope ?? "no_relations",
|
|
235
235
|
};
|
|
236
236
|
}
|
|
237
|
+
if (options?.includeRelatedTypes != null)
|
|
238
|
+
body.include_related_types = options.includeRelatedTypes;
|
|
239
|
+
if (options?.relatedTypesDepth != null)
|
|
240
|
+
body.related_types_depth = options.relatedTypesDepth;
|
|
237
241
|
if (options?.traceId != null)
|
|
238
242
|
body.trace_id = options.traceId;
|
|
239
243
|
// The wire shape omits `reader_results` on a server without question
|
|
240
|
-
// decomposition,
|
|
241
|
-
//
|
|
244
|
+
// decomposition, and `related_types` unless the read asked for it, so type
|
|
245
|
+
// them as optional here and normalize (always-array, `null`) for the public
|
|
246
|
+
// `ReadResult` below.
|
|
242
247
|
const result = await this._requestOne("POST", `/instances/${this.id}/read`, {
|
|
243
248
|
body,
|
|
244
249
|
timeoutMs: options?.timeoutMs,
|
|
@@ -248,10 +253,15 @@ class InstanceHandle {
|
|
|
248
253
|
// by `Object.prototype` when the caller reads it.
|
|
249
254
|
const readerResults = own(result, "reader_results");
|
|
250
255
|
const traceId = own(result, "trace_id");
|
|
256
|
+
const relatedTypes = own(result, "related_types");
|
|
257
|
+
// `reader_result` is required on the wire and `null` is one of its answers (a
|
|
258
|
+
// refusal, in the tabular modes), so the coalescing only stands in for a field
|
|
259
|
+
// the server omitted; a `null` the server sent arrives as the same `null`.
|
|
251
260
|
return withConsoleUrl({
|
|
252
261
|
...result,
|
|
253
262
|
reader_result: own(result, "reader_result") ?? null,
|
|
254
263
|
reader_results: Array.isArray(readerResults) ? readerResults : [],
|
|
264
|
+
related_types: relatedTypes != null && typeof relatedTypes === "object" ? relatedTypes : null,
|
|
255
265
|
trace_id: typeof traceId === "string" ? traceId : null,
|
|
256
266
|
});
|
|
257
267
|
}
|
package/dist/cjs/types.d.ts
CHANGED
|
@@ -8,6 +8,23 @@ export declare const SchemaType: {
|
|
|
8
8
|
export type SchemaTypeValue = (typeof SchemaType)[keyof typeof SchemaType];
|
|
9
9
|
export type ExtractionLogic = "fast" | "deep";
|
|
10
10
|
export type ReadMode = "single-answer" | "raw-tables" | "xresponse";
|
|
11
|
+
/**
|
|
12
|
+
* What a read says about the schema around its answer. `"types"` adds
|
|
13
|
+
* {@link ReadResult.related_types} to the result; `"none"` (the server default)
|
|
14
|
+
* leaves it out. Asking for it needs the `instance.get_own` permission on the
|
|
15
|
+
* API key, the same one the schema endpoints need, on top of `data.read`: a key
|
|
16
|
+
* without it gets a 403 whose message names the permission, and the plain read
|
|
17
|
+
* is unaffected.
|
|
18
|
+
*/
|
|
19
|
+
export type RelatedTypesMode = "none" | "types";
|
|
20
|
+
/**
|
|
21
|
+
* Cardinality of a relation seen from the touched type's role, derived from the
|
|
22
|
+
* relation's unique keys: `"one_to_many"` means one touched record links to many
|
|
23
|
+
* neighbours and each neighbour to at most one touched record; `"many_to_one"`
|
|
24
|
+
* is the reverse; `"unconstrained"` means the schema declares no uniqueness rule
|
|
25
|
+
* for the relation.
|
|
26
|
+
*/
|
|
27
|
+
export type RelationCardinality = "one_to_one" | "one_to_many" | "many_to_one" | "many_to_many" | "unconstrained";
|
|
11
28
|
/**
|
|
12
29
|
* One concrete object a scoped read or a scoped write may touch. Identify it by
|
|
13
30
|
* `type` (PascalCase class name or snake_case table name) plus its user-defined
|
|
@@ -155,20 +172,159 @@ export interface InstanceSchemaInfo {
|
|
|
155
172
|
* One sub-query and its own answer, in the requested read mode. Appears in
|
|
156
173
|
* {@link ReadResult.reader_results} when the server decomposed a composite query
|
|
157
174
|
* into independent sub-queries.
|
|
175
|
+
*
|
|
176
|
+
* `reader_result` gives one of the four answers described on
|
|
177
|
+
* {@link ReadResult.reader_result}, with one more case: a sub-query whose SQL
|
|
178
|
+
* failed carries the empty result *and* `error`, while the other sub-queries
|
|
179
|
+
* are answered regardless. Its bytes then equal those of a sub-query that
|
|
180
|
+
* matched nothing, so read `error` before `reader_result`.
|
|
158
181
|
*/
|
|
159
182
|
export interface TaggedReaderResult {
|
|
160
183
|
readonly sub_query: string;
|
|
161
184
|
readonly reader_result: unknown;
|
|
162
185
|
/**
|
|
163
|
-
* A user-safe message set when this sub-query could not be
|
|
164
|
-
*
|
|
186
|
+
* A user-safe message set when this sub-query's SQL could not be executed;
|
|
187
|
+
* `null` otherwise. In `"raw-tables"` / `"xresponse"` mode a read where every
|
|
188
|
+
* sub-query failed does not return at all: it throws {@link XmemoryAPIError}
|
|
189
|
+
* with `status` 422 and `code` `"INVALID_INPUT"`.
|
|
165
190
|
*/
|
|
166
191
|
readonly error: string | null;
|
|
167
192
|
}
|
|
193
|
+
/**
|
|
194
|
+
* One relation edge from the entry's own type to a neighbouring type;
|
|
195
|
+
* {@link RelatedTypes.objects} describes both ends. The entry is a touched type
|
|
196
|
+
* (under `touched`) or, at a `relatedTypesDepth` above 1, a catalog entry
|
|
197
|
+
* (under `objects`); `touched_role` is the role the entry's own type plays
|
|
198
|
+
* either way.
|
|
199
|
+
*/
|
|
200
|
+
export interface RelatedTypesLink {
|
|
201
|
+
/** The neighbouring object type, described once under `objects`. */
|
|
202
|
+
readonly object_type: string;
|
|
203
|
+
/** The relation that links the two, described once under `relations`. */
|
|
204
|
+
readonly relation: string;
|
|
205
|
+
/** The relation role the entry's own type plays in this edge. */
|
|
206
|
+
readonly touched_role: string;
|
|
207
|
+
/** The relation role the neighbouring type plays in this edge. */
|
|
208
|
+
readonly related_role: string;
|
|
209
|
+
readonly cardinality: RelationCardinality;
|
|
210
|
+
}
|
|
211
|
+
/** One object type the read touched, with what it withheld and what it is linked to. */
|
|
212
|
+
export interface RelatedTypesTouched {
|
|
213
|
+
/** Object type name as declared in the schema, described under `objects`. */
|
|
214
|
+
readonly object_type: string;
|
|
215
|
+
/**
|
|
216
|
+
* Fields of this type the read did not project. Ask for one by name to see it;
|
|
217
|
+
* an expression the reader could not attribute to a field counts here rather
|
|
218
|
+
* than as returned.
|
|
219
|
+
*/
|
|
220
|
+
readonly fields_not_returned: readonly string[];
|
|
221
|
+
/** Relation edges to neighbouring types, sorted by relation then type. A self-relation lists one edge per role. */
|
|
222
|
+
readonly related: readonly RelatedTypesLink[];
|
|
223
|
+
/** Edges dropped from `related` to stay within the server's payload budget. */
|
|
224
|
+
readonly omitted_related: number;
|
|
225
|
+
}
|
|
226
|
+
/** Catalog entry for an object type named in {@link RelatedTypes.touched} or reached through `relatedTypesDepth`. */
|
|
227
|
+
export interface RelatedTypesObjectType {
|
|
228
|
+
/**
|
|
229
|
+
* Listed edges from the nearest touched type: 0 for a touched type, 1 for a
|
|
230
|
+
* type a touched type's listed edge names, and so on up to
|
|
231
|
+
* {@link RelatedTypes.depth}. A route through an edge the server's budget cut
|
|
232
|
+
* is not followed, so this can exceed the schema's own hop count; the cutting
|
|
233
|
+
* entry's `omitted_related` says when. Absent on a one-level read: the server
|
|
234
|
+
* then serves the payload it always did, without the depth keys.
|
|
235
|
+
*/
|
|
236
|
+
readonly distance?: number;
|
|
237
|
+
readonly description: string | null;
|
|
238
|
+
/** Declared primary-key fields, in declared order. */
|
|
239
|
+
readonly primary_key: readonly string[];
|
|
240
|
+
/** Every field of the object type, by name. */
|
|
241
|
+
readonly fields: readonly string[];
|
|
242
|
+
/**
|
|
243
|
+
* This type's own relation edges, for an entry whose `distance` is at least 1
|
|
244
|
+
* and below `depth`. Empty for a touched type (its edges are on its `touched`
|
|
245
|
+
* entry), at the last level, and once the server's shared edge budget is spent
|
|
246
|
+
* (then `omitted_related` counts every edge the type has). Absent on a
|
|
247
|
+
* one-level read.
|
|
248
|
+
*/
|
|
249
|
+
readonly related?: readonly RelatedTypesLink[];
|
|
250
|
+
/**
|
|
251
|
+
* Edges of this type the server did not list: cut by its per-type cap, by the
|
|
252
|
+
* edge budget shared with the touched entries, or dropped with a level for its
|
|
253
|
+
* byte budget. Absent on a one-level read.
|
|
254
|
+
*/
|
|
255
|
+
readonly omitted_related?: number;
|
|
256
|
+
}
|
|
257
|
+
/** Catalog entry for a relation named by any edge. */
|
|
258
|
+
export interface RelatedTypesRelation {
|
|
259
|
+
readonly description: string | null;
|
|
260
|
+
}
|
|
261
|
+
/**
|
|
262
|
+
* What else the memory could answer about, for a read that asked with
|
|
263
|
+
* `includeRelatedTypes: "types"`: the object types the read touched, each with
|
|
264
|
+
* the fields it did not return and its relation edges, plus a catalog that
|
|
265
|
+
* describes every named type and relation exactly once. It is derived from the
|
|
266
|
+
* instance schema and the statements the read executed — no extra rows are
|
|
267
|
+
* read and no model is called — so an agent can phrase a deliberate follow-up
|
|
268
|
+
* read instead of guessing. With a `relatedTypesDepth` above 1 the catalog
|
|
269
|
+
* follows the listed edges further: each entry carries its `distance` from the
|
|
270
|
+
* touched types and, below the last level, its own edges. The server caps the
|
|
271
|
+
* payload; whatever it dropped is counted — an edge on the entry it was dropped
|
|
272
|
+
* from, a type the catalog could not list on `omitted_objects` — and `truncated`
|
|
273
|
+
* says that something was. A one-level read is served in the shape that
|
|
274
|
+
* predates the depth, so `depth`, `omitted_objects` and the catalog entries'
|
|
275
|
+
* depth fields are then absent.
|
|
276
|
+
*/
|
|
277
|
+
export interface RelatedTypes {
|
|
278
|
+
/**
|
|
279
|
+
* Relation levels asked for (`relatedTypesDepth`). Never lowered by the server:
|
|
280
|
+
* what its budgets kept the walk from listing is counted on `omitted_objects`
|
|
281
|
+
* and on each entry's `omitted_related`. Absent on a one-level read.
|
|
282
|
+
*/
|
|
283
|
+
readonly depth?: number;
|
|
284
|
+
/** Object types the read touched, sorted by name. Empty when the read executed nothing. */
|
|
285
|
+
readonly touched: readonly RelatedTypesTouched[];
|
|
286
|
+
/** Every object type a listed edge names — touched, or reached through the listed edges within `depth` levels — once. */
|
|
287
|
+
readonly objects: Readonly<Record<string, RelatedTypesObjectType>>;
|
|
288
|
+
/** Every relation named by an edge, once. */
|
|
289
|
+
readonly relations: Readonly<Record<string, RelatedTypesRelation>>;
|
|
290
|
+
/** Touched types dropped to stay within the budget. */
|
|
291
|
+
readonly omitted_touched: number;
|
|
292
|
+
/**
|
|
293
|
+
* Object types within `depth` relation levels of the touched types in the
|
|
294
|
+
* schema that the catalog does not list: the route to them ran through an edge
|
|
295
|
+
* the server's budget cut, or their level was dropped for its byte budget.
|
|
296
|
+
* Absent on a one-level read.
|
|
297
|
+
*/
|
|
298
|
+
readonly omitted_objects?: number;
|
|
299
|
+
/** `true` when any type, edge or level was dropped for the budget. */
|
|
300
|
+
readonly truncated: boolean;
|
|
301
|
+
}
|
|
168
302
|
export interface ReadResult {
|
|
169
303
|
readonly trace_id: string | null;
|
|
170
304
|
/** Deep link to this read's trace in the console; `null` if no console is configured. */
|
|
171
305
|
readonly console_url: string | null;
|
|
306
|
+
/**
|
|
307
|
+
* The answer, shaped by `readMode`. In `"single-answer"` mode it is always the
|
|
308
|
+
* prose answer, never `null`. In `"raw-tables"` / `"xresponse"` mode its value
|
|
309
|
+
* says which of four answers the read gave:
|
|
310
|
+
*
|
|
311
|
+
* - rows — answered;
|
|
312
|
+
* - exactly `{ columns: [], rows: [] }` (`"raw-tables"`) or
|
|
313
|
+
* `{ objects: [], relations: [] }` (`"xresponse"`) — the query executed and
|
|
314
|
+
* matched nothing: every table and column it used exists, so the data is
|
|
315
|
+
* absent;
|
|
316
|
+
* - `null` — the schema provably cannot represent the concept. An answer in
|
|
317
|
+
* its own right, not a variant of the empty one: this memory cannot hold
|
|
318
|
+
* it, so a better-matching instance is worth trying;
|
|
319
|
+
* - no result at all — every sub-query's SQL failed, so nothing was
|
|
320
|
+
* answered. The read throws {@link XmemoryAPIError} with `status` 422 and
|
|
321
|
+
* `code` `"INVALID_INPUT"` rather than reporting an empty result.
|
|
322
|
+
*
|
|
323
|
+
* For a composite query this is the combined answer, folded from the parts:
|
|
324
|
+
* rows if any sub-query answered; else the empty result if any executed and
|
|
325
|
+
* matched nothing; else `null`. `reader_results` carries each part's own
|
|
326
|
+
* answer.
|
|
327
|
+
*/
|
|
172
328
|
readonly reader_result: unknown;
|
|
173
329
|
/**
|
|
174
330
|
* Per-sub-query answers when the server decomposed the query into independent
|
|
@@ -179,6 +335,14 @@ export interface ReadResult {
|
|
|
179
335
|
* so the array is empty regardless of how many questions the query held.
|
|
180
336
|
*/
|
|
181
337
|
readonly reader_results: readonly TaggedReaderResult[];
|
|
338
|
+
/**
|
|
339
|
+
* The schema around the answer, when the read asked for it with
|
|
340
|
+
* `includeRelatedTypes: "types"`; `null` otherwise. The wire omits the field
|
|
341
|
+
* unless it was requested, and a server that predates the option never sends
|
|
342
|
+
* it; the client normalizes both to `null`, so `null` means "not asked for" and
|
|
343
|
+
* a requested read that executed nothing arrives with `touched: []` instead.
|
|
344
|
+
*/
|
|
345
|
+
readonly related_types: RelatedTypes | null;
|
|
182
346
|
}
|
|
183
347
|
export interface WriteResult {
|
|
184
348
|
readonly write_id: string;
|
|
@@ -554,6 +718,22 @@ export interface ReadOptions {
|
|
|
554
718
|
readMode?: ReadMode;
|
|
555
719
|
/** Restrict the read to a set of concrete objects (plus optional relation traversal). */
|
|
556
720
|
scope?: ReadScope;
|
|
721
|
+
/**
|
|
722
|
+
* `"types"` asks for {@link ReadResult.related_types}: the object types the read
|
|
723
|
+
* touched, the fields it did not return, and the object types a declared
|
|
724
|
+
* relation links them to. Left unset, nothing is sent and the server default
|
|
725
|
+
* (`"none"`) applies. Needs `instance.get_own` on the API key; see
|
|
726
|
+
* {@link RelatedTypesMode}.
|
|
727
|
+
*/
|
|
728
|
+
includeRelatedTypes?: RelatedTypesMode;
|
|
729
|
+
/**
|
|
730
|
+
* With `includeRelatedTypes: "types"`, how many relation levels the catalog
|
|
731
|
+
* follows out from the touched types, 1 to 3. Every entry under
|
|
732
|
+
* {@link RelatedTypes.objects} then carries its `distance` and, below the last
|
|
733
|
+
* level, its own `related` edges. Left unset, nothing is sent and the server
|
|
734
|
+
* serves one level; a value out of range is a 422.
|
|
735
|
+
*/
|
|
736
|
+
relatedTypesDepth?: number;
|
|
557
737
|
traceId?: string;
|
|
558
738
|
timeoutMs?: number;
|
|
559
739
|
}
|
package/dist/esm/client.d.ts
CHANGED
|
@@ -3,6 +3,41 @@
|
|
|
3
3
|
*/
|
|
4
4
|
import { InstanceHandle } from "./instance.js";
|
|
5
5
|
import { type AgentSetupResult, type ClusterInfo, type CreateInstanceOptions, type DryRunMigrationOptions, type DryRunResult, type EnhanceSchemaResult, type GenerateSchemaOptions, type GenerateSchemaResult, type GetMigrationOptions, type InstanceInfo, type InstanceSchemaInfo, type ListMigrationsOptions, type ListMigrationsResult, type MigrationRecord, type PatchInstanceMetadataOptions, type RequestOptions, type SchemaTypeValue, type SetupFormatValue, type UpdateInstanceMetadataOptions, type UpdateInstanceSchemaOptions, type XmemoryClientOptions } from "./types.js";
|
|
6
|
+
/**
|
|
7
|
+
* The identity this client sends in `X-Xmemory-Client`. A host detail is admitted only as a short,
|
|
8
|
+
* non-empty run of printable ASCII carrying no space, semicolon or parenthesis, and becomes
|
|
9
|
+
* `unknown` otherwise.
|
|
10
|
+
* The reasons differ by character. A bundler shim routinely supplies a partial `process`, whose
|
|
11
|
+
* missing fields would write the word "undefined" into the header. A control character such as NUL
|
|
12
|
+
* or a newline makes `fetch` reject the request outright, and a character above `\xff` cannot be
|
|
13
|
+
* converted to a header value at all. The rest — a byte outside ASCII, a tab, a space, a semicolon,
|
|
14
|
+
* a parenthesis — is carried fine, but would blur the boundaries of the parenthetical this builds.
|
|
15
|
+
* The length cap is there because nothing else bounds what a host may report into a header this
|
|
16
|
+
* sends on every request. Not re-exported from `index.ts` — exported here so the tests can cover
|
|
17
|
+
* those substitutions directly.
|
|
18
|
+
*/
|
|
19
|
+
export declare function buildClientIdentity(version: string, host: {
|
|
20
|
+
version?: unknown;
|
|
21
|
+
platform?: unknown;
|
|
22
|
+
} | undefined): string;
|
|
23
|
+
/**
|
|
24
|
+
* The header this client identifies itself in. A dedicated field rather than `User-Agent`: that one
|
|
25
|
+
* belongs to whoever built the request — the runtime, or the caller — and in a browser `fetch`
|
|
26
|
+
* treats it as forbidden and drops it silently. Nothing else on the wire claims this name.
|
|
27
|
+
*/
|
|
28
|
+
export declare const CLIENT_HEADER = "X-Xmemory-Client";
|
|
29
|
+
/**
|
|
30
|
+
* The headers a request goes out with: everything the caller built, in a new object so the
|
|
31
|
+
* caller's own is left untouched, plus this client's identity. Any existing spelling of the identity
|
|
32
|
+
* header is dropped first — header names are case-insensitive on the wire, so leaving one behind
|
|
33
|
+
* would put two values under one name, and `fetch` joins those into a single comma-separated value
|
|
34
|
+
* whose first token is the one the API reads. `User-Agent` and everything else pass through
|
|
35
|
+
* untouched. No public entry point lets a caller supply request headers today — `_fetch` only ever
|
|
36
|
+
* sees what `_headers()` built — so the drop is defensive against a future call site that does, not
|
|
37
|
+
* a live collision. Not re-exported from `index.ts`; exported here so the tests can cover the merge
|
|
38
|
+
* directly.
|
|
39
|
+
*/
|
|
40
|
+
export declare function withClientHeader(existing: Record<string, string> | undefined): Record<string, string>;
|
|
6
41
|
export interface AdminNamespace {
|
|
7
42
|
listClusters(options?: RequestOptions & {
|
|
8
43
|
ids?: string[];
|
package/dist/esm/client.js
CHANGED
|
@@ -3,6 +3,7 @@
|
|
|
3
3
|
*/
|
|
4
4
|
import { InstanceHandle } from "./instance.js";
|
|
5
5
|
import { SetupFormat, XmemoryAPIError, XmemoryHealthCheckError, buildInstanceSchema, } from "./types.js";
|
|
6
|
+
import { VERSION } from "./version.js";
|
|
6
7
|
const DEFAULT_BASE_URL = "https://api.xmemory.ai";
|
|
7
8
|
/**
|
|
8
9
|
* An *own* property of a decoded response, or `undefined`.
|
|
@@ -23,6 +24,59 @@ function ownArray(source, key) {
|
|
|
23
24
|
return Array.isArray(value) ? value : [];
|
|
24
25
|
}
|
|
25
26
|
const DEFAULT_TIMEOUT_MS = 60_000;
|
|
27
|
+
const HOST_FIELD_MAX = 64;
|
|
28
|
+
/** One host detail, reduced to something a header value may safely carry. */
|
|
29
|
+
const hostField = (value) => typeof value === "string" &&
|
|
30
|
+
value.length <= HOST_FIELD_MAX &&
|
|
31
|
+
/^[\x21-\x7e]+$/.test(value) &&
|
|
32
|
+
!/[;()]/.test(value)
|
|
33
|
+
? value
|
|
34
|
+
: "unknown";
|
|
35
|
+
/**
|
|
36
|
+
* The identity this client sends in `X-Xmemory-Client`. A host detail is admitted only as a short,
|
|
37
|
+
* non-empty run of printable ASCII carrying no space, semicolon or parenthesis, and becomes
|
|
38
|
+
* `unknown` otherwise.
|
|
39
|
+
* The reasons differ by character. A bundler shim routinely supplies a partial `process`, whose
|
|
40
|
+
* missing fields would write the word "undefined" into the header. A control character such as NUL
|
|
41
|
+
* or a newline makes `fetch` reject the request outright, and a character above `\xff` cannot be
|
|
42
|
+
* converted to a header value at all. The rest — a byte outside ASCII, a tab, a space, a semicolon,
|
|
43
|
+
* a parenthesis — is carried fine, but would blur the boundaries of the parenthetical this builds.
|
|
44
|
+
* The length cap is there because nothing else bounds what a host may report into a header this
|
|
45
|
+
* sends on every request. Not re-exported from `index.ts` — exported here so the tests can cover
|
|
46
|
+
* those substitutions directly.
|
|
47
|
+
*/
|
|
48
|
+
export function buildClientIdentity(version, host) {
|
|
49
|
+
return `xmemory-node/${version} (node ${hostField(host?.version)}; ${hostField(host?.platform)})`;
|
|
50
|
+
}
|
|
51
|
+
/**
|
|
52
|
+
* The header this client identifies itself in. A dedicated field rather than `User-Agent`: that one
|
|
53
|
+
* belongs to whoever built the request — the runtime, or the caller — and in a browser `fetch`
|
|
54
|
+
* treats it as forbidden and drops it silently. Nothing else on the wire claims this name.
|
|
55
|
+
*/
|
|
56
|
+
export const CLIENT_HEADER = "X-Xmemory-Client";
|
|
57
|
+
// `process` is absent in a browser and partial under some bundler shims, so the fields are read
|
|
58
|
+
// defensively and each one falls back to `unknown`.
|
|
59
|
+
const CLIENT_IDENTITY = buildClientIdentity(VERSION, typeof process !== "undefined" ? process : undefined);
|
|
60
|
+
/**
|
|
61
|
+
* The headers a request goes out with: everything the caller built, in a new object so the
|
|
62
|
+
* caller's own is left untouched, plus this client's identity. Any existing spelling of the identity
|
|
63
|
+
* header is dropped first — header names are case-insensitive on the wire, so leaving one behind
|
|
64
|
+
* would put two values under one name, and `fetch` joins those into a single comma-separated value
|
|
65
|
+
* whose first token is the one the API reads. `User-Agent` and everything else pass through
|
|
66
|
+
* untouched. No public entry point lets a caller supply request headers today — `_fetch` only ever
|
|
67
|
+
* sees what `_headers()` built — so the drop is defensive against a future call site that does, not
|
|
68
|
+
* a live collision. Not re-exported from `index.ts`; exported here so the tests can cover the merge
|
|
69
|
+
* directly.
|
|
70
|
+
*/
|
|
71
|
+
export function withClientHeader(existing) {
|
|
72
|
+
const headers = {};
|
|
73
|
+
for (const [name, value] of Object.entries(existing ?? {})) {
|
|
74
|
+
if (name.toLowerCase() !== CLIENT_HEADER.toLowerCase())
|
|
75
|
+
headers[name] = value;
|
|
76
|
+
}
|
|
77
|
+
headers[CLIENT_HEADER] = CLIENT_IDENTITY;
|
|
78
|
+
return headers;
|
|
79
|
+
}
|
|
26
80
|
const ORANGE = "\x1b[38;5;208m";
|
|
27
81
|
const RESET = "\x1b[0m";
|
|
28
82
|
function deprecationWarning(message) {
|
|
@@ -138,7 +192,11 @@ export class XmemoryClient {
|
|
|
138
192
|
const controller = new AbortController();
|
|
139
193
|
const timer = setTimeout(() => controller.abort(), timeoutMs);
|
|
140
194
|
try {
|
|
141
|
-
return await fetch(url, {
|
|
195
|
+
return await fetch(url, {
|
|
196
|
+
...init,
|
|
197
|
+
headers: withClientHeader(init.headers),
|
|
198
|
+
signal: controller.signal,
|
|
199
|
+
});
|
|
142
200
|
}
|
|
143
201
|
finally {
|
|
144
202
|
clearTimeout(timer);
|
package/dist/esm/index.d.ts
CHANGED
|
@@ -7,10 +7,10 @@ export { DescribeResult, InstanceHandle } from "./instance.js";
|
|
|
7
7
|
export { XmemoryAPIError, XmemoryHealthCheckError } from "./types.js";
|
|
8
8
|
export { SchemaType } from "./types.js";
|
|
9
9
|
export { AgentSurface, BindingTier, FragmentMerge, SetupFormat, StepKind } from "./types.js";
|
|
10
|
-
export type { AgentSetupResult, AgentSetupStep, AgentSetupSurface, AgentSurfaceValue, FragmentMergeValue, ProjectFragment, ProjectSetup, SetupFormatValue, StepKindValue, BindingTierValue, SchemaTypeValue, ExtractionLogic, ReadMode, WriteQueueStatus, FieldType, OnDelete, CastStrategy, DecisionKind, MigrationSource, } from "./types.js";
|
|
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 } 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, WriteResult, AsyncWriteResult, WriteStatusResult, ExtractResult, GenerateSchemaResult, ToolDescription, ToolParameterDescription, RawDescribeResult, } from "./types.js";
|
|
13
|
+
export type { ClusterInfo, InstanceInfo, InstanceSchemaInfo, ReadResult, TaggedReaderResult, RelatedTypes, RelatedTypesTouched, RelatedTypesLink, RelatedTypesObjectType, RelatedTypesRelation, WriteResult, 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.js
CHANGED
|
@@ -230,11 +230,16 @@ export class InstanceHandle {
|
|
|
230
230
|
relations_scope: options.scope.relationsScope ?? "no_relations",
|
|
231
231
|
};
|
|
232
232
|
}
|
|
233
|
+
if (options?.includeRelatedTypes != null)
|
|
234
|
+
body.include_related_types = options.includeRelatedTypes;
|
|
235
|
+
if (options?.relatedTypesDepth != null)
|
|
236
|
+
body.related_types_depth = options.relatedTypesDepth;
|
|
233
237
|
if (options?.traceId != null)
|
|
234
238
|
body.trace_id = options.traceId;
|
|
235
239
|
// The wire shape omits `reader_results` on a server without question
|
|
236
|
-
// decomposition,
|
|
237
|
-
//
|
|
240
|
+
// decomposition, and `related_types` unless the read asked for it, so type
|
|
241
|
+
// them as optional here and normalize (always-array, `null`) for the public
|
|
242
|
+
// `ReadResult` below.
|
|
238
243
|
const result = await this._requestOne("POST", `/instances/${this.id}/read`, {
|
|
239
244
|
body,
|
|
240
245
|
timeoutMs: options?.timeoutMs,
|
|
@@ -244,10 +249,15 @@ export class InstanceHandle {
|
|
|
244
249
|
// by `Object.prototype` when the caller reads it.
|
|
245
250
|
const readerResults = own(result, "reader_results");
|
|
246
251
|
const traceId = own(result, "trace_id");
|
|
252
|
+
const relatedTypes = own(result, "related_types");
|
|
253
|
+
// `reader_result` is required on the wire and `null` is one of its answers (a
|
|
254
|
+
// refusal, in the tabular modes), so the coalescing only stands in for a field
|
|
255
|
+
// the server omitted; a `null` the server sent arrives as the same `null`.
|
|
247
256
|
return withConsoleUrl({
|
|
248
257
|
...result,
|
|
249
258
|
reader_result: own(result, "reader_result") ?? null,
|
|
250
259
|
reader_results: Array.isArray(readerResults) ? readerResults : [],
|
|
260
|
+
related_types: relatedTypes != null && typeof relatedTypes === "object" ? relatedTypes : null,
|
|
251
261
|
trace_id: typeof traceId === "string" ? traceId : null,
|
|
252
262
|
});
|
|
253
263
|
}
|
package/dist/esm/types.d.ts
CHANGED
|
@@ -8,6 +8,23 @@ export declare const SchemaType: {
|
|
|
8
8
|
export type SchemaTypeValue = (typeof SchemaType)[keyof typeof SchemaType];
|
|
9
9
|
export type ExtractionLogic = "fast" | "deep";
|
|
10
10
|
export type ReadMode = "single-answer" | "raw-tables" | "xresponse";
|
|
11
|
+
/**
|
|
12
|
+
* What a read says about the schema around its answer. `"types"` adds
|
|
13
|
+
* {@link ReadResult.related_types} to the result; `"none"` (the server default)
|
|
14
|
+
* leaves it out. Asking for it needs the `instance.get_own` permission on the
|
|
15
|
+
* API key, the same one the schema endpoints need, on top of `data.read`: a key
|
|
16
|
+
* without it gets a 403 whose message names the permission, and the plain read
|
|
17
|
+
* is unaffected.
|
|
18
|
+
*/
|
|
19
|
+
export type RelatedTypesMode = "none" | "types";
|
|
20
|
+
/**
|
|
21
|
+
* Cardinality of a relation seen from the touched type's role, derived from the
|
|
22
|
+
* relation's unique keys: `"one_to_many"` means one touched record links to many
|
|
23
|
+
* neighbours and each neighbour to at most one touched record; `"many_to_one"`
|
|
24
|
+
* is the reverse; `"unconstrained"` means the schema declares no uniqueness rule
|
|
25
|
+
* for the relation.
|
|
26
|
+
*/
|
|
27
|
+
export type RelationCardinality = "one_to_one" | "one_to_many" | "many_to_one" | "many_to_many" | "unconstrained";
|
|
11
28
|
/**
|
|
12
29
|
* One concrete object a scoped read or a scoped write may touch. Identify it by
|
|
13
30
|
* `type` (PascalCase class name or snake_case table name) plus its user-defined
|
|
@@ -155,20 +172,159 @@ export interface InstanceSchemaInfo {
|
|
|
155
172
|
* One sub-query and its own answer, in the requested read mode. Appears in
|
|
156
173
|
* {@link ReadResult.reader_results} when the server decomposed a composite query
|
|
157
174
|
* into independent sub-queries.
|
|
175
|
+
*
|
|
176
|
+
* `reader_result` gives one of the four answers described on
|
|
177
|
+
* {@link ReadResult.reader_result}, with one more case: a sub-query whose SQL
|
|
178
|
+
* failed carries the empty result *and* `error`, while the other sub-queries
|
|
179
|
+
* are answered regardless. Its bytes then equal those of a sub-query that
|
|
180
|
+
* matched nothing, so read `error` before `reader_result`.
|
|
158
181
|
*/
|
|
159
182
|
export interface TaggedReaderResult {
|
|
160
183
|
readonly sub_query: string;
|
|
161
184
|
readonly reader_result: unknown;
|
|
162
185
|
/**
|
|
163
|
-
* A user-safe message set when this sub-query could not be
|
|
164
|
-
*
|
|
186
|
+
* A user-safe message set when this sub-query's SQL could not be executed;
|
|
187
|
+
* `null` otherwise. In `"raw-tables"` / `"xresponse"` mode a read where every
|
|
188
|
+
* sub-query failed does not return at all: it throws {@link XmemoryAPIError}
|
|
189
|
+
* with `status` 422 and `code` `"INVALID_INPUT"`.
|
|
165
190
|
*/
|
|
166
191
|
readonly error: string | null;
|
|
167
192
|
}
|
|
193
|
+
/**
|
|
194
|
+
* One relation edge from the entry's own type to a neighbouring type;
|
|
195
|
+
* {@link RelatedTypes.objects} describes both ends. The entry is a touched type
|
|
196
|
+
* (under `touched`) or, at a `relatedTypesDepth` above 1, a catalog entry
|
|
197
|
+
* (under `objects`); `touched_role` is the role the entry's own type plays
|
|
198
|
+
* either way.
|
|
199
|
+
*/
|
|
200
|
+
export interface RelatedTypesLink {
|
|
201
|
+
/** The neighbouring object type, described once under `objects`. */
|
|
202
|
+
readonly object_type: string;
|
|
203
|
+
/** The relation that links the two, described once under `relations`. */
|
|
204
|
+
readonly relation: string;
|
|
205
|
+
/** The relation role the entry's own type plays in this edge. */
|
|
206
|
+
readonly touched_role: string;
|
|
207
|
+
/** The relation role the neighbouring type plays in this edge. */
|
|
208
|
+
readonly related_role: string;
|
|
209
|
+
readonly cardinality: RelationCardinality;
|
|
210
|
+
}
|
|
211
|
+
/** One object type the read touched, with what it withheld and what it is linked to. */
|
|
212
|
+
export interface RelatedTypesTouched {
|
|
213
|
+
/** Object type name as declared in the schema, described under `objects`. */
|
|
214
|
+
readonly object_type: string;
|
|
215
|
+
/**
|
|
216
|
+
* Fields of this type the read did not project. Ask for one by name to see it;
|
|
217
|
+
* an expression the reader could not attribute to a field counts here rather
|
|
218
|
+
* than as returned.
|
|
219
|
+
*/
|
|
220
|
+
readonly fields_not_returned: readonly string[];
|
|
221
|
+
/** Relation edges to neighbouring types, sorted by relation then type. A self-relation lists one edge per role. */
|
|
222
|
+
readonly related: readonly RelatedTypesLink[];
|
|
223
|
+
/** Edges dropped from `related` to stay within the server's payload budget. */
|
|
224
|
+
readonly omitted_related: number;
|
|
225
|
+
}
|
|
226
|
+
/** Catalog entry for an object type named in {@link RelatedTypes.touched} or reached through `relatedTypesDepth`. */
|
|
227
|
+
export interface RelatedTypesObjectType {
|
|
228
|
+
/**
|
|
229
|
+
* Listed edges from the nearest touched type: 0 for a touched type, 1 for a
|
|
230
|
+
* type a touched type's listed edge names, and so on up to
|
|
231
|
+
* {@link RelatedTypes.depth}. A route through an edge the server's budget cut
|
|
232
|
+
* is not followed, so this can exceed the schema's own hop count; the cutting
|
|
233
|
+
* entry's `omitted_related` says when. Absent on a one-level read: the server
|
|
234
|
+
* then serves the payload it always did, without the depth keys.
|
|
235
|
+
*/
|
|
236
|
+
readonly distance?: number;
|
|
237
|
+
readonly description: string | null;
|
|
238
|
+
/** Declared primary-key fields, in declared order. */
|
|
239
|
+
readonly primary_key: readonly string[];
|
|
240
|
+
/** Every field of the object type, by name. */
|
|
241
|
+
readonly fields: readonly string[];
|
|
242
|
+
/**
|
|
243
|
+
* This type's own relation edges, for an entry whose `distance` is at least 1
|
|
244
|
+
* and below `depth`. Empty for a touched type (its edges are on its `touched`
|
|
245
|
+
* entry), at the last level, and once the server's shared edge budget is spent
|
|
246
|
+
* (then `omitted_related` counts every edge the type has). Absent on a
|
|
247
|
+
* one-level read.
|
|
248
|
+
*/
|
|
249
|
+
readonly related?: readonly RelatedTypesLink[];
|
|
250
|
+
/**
|
|
251
|
+
* Edges of this type the server did not list: cut by its per-type cap, by the
|
|
252
|
+
* edge budget shared with the touched entries, or dropped with a level for its
|
|
253
|
+
* byte budget. Absent on a one-level read.
|
|
254
|
+
*/
|
|
255
|
+
readonly omitted_related?: number;
|
|
256
|
+
}
|
|
257
|
+
/** Catalog entry for a relation named by any edge. */
|
|
258
|
+
export interface RelatedTypesRelation {
|
|
259
|
+
readonly description: string | null;
|
|
260
|
+
}
|
|
261
|
+
/**
|
|
262
|
+
* What else the memory could answer about, for a read that asked with
|
|
263
|
+
* `includeRelatedTypes: "types"`: the object types the read touched, each with
|
|
264
|
+
* the fields it did not return and its relation edges, plus a catalog that
|
|
265
|
+
* describes every named type and relation exactly once. It is derived from the
|
|
266
|
+
* instance schema and the statements the read executed — no extra rows are
|
|
267
|
+
* read and no model is called — so an agent can phrase a deliberate follow-up
|
|
268
|
+
* read instead of guessing. With a `relatedTypesDepth` above 1 the catalog
|
|
269
|
+
* follows the listed edges further: each entry carries its `distance` from the
|
|
270
|
+
* touched types and, below the last level, its own edges. The server caps the
|
|
271
|
+
* payload; whatever it dropped is counted — an edge on the entry it was dropped
|
|
272
|
+
* from, a type the catalog could not list on `omitted_objects` — and `truncated`
|
|
273
|
+
* says that something was. A one-level read is served in the shape that
|
|
274
|
+
* predates the depth, so `depth`, `omitted_objects` and the catalog entries'
|
|
275
|
+
* depth fields are then absent.
|
|
276
|
+
*/
|
|
277
|
+
export interface RelatedTypes {
|
|
278
|
+
/**
|
|
279
|
+
* Relation levels asked for (`relatedTypesDepth`). Never lowered by the server:
|
|
280
|
+
* what its budgets kept the walk from listing is counted on `omitted_objects`
|
|
281
|
+
* and on each entry's `omitted_related`. Absent on a one-level read.
|
|
282
|
+
*/
|
|
283
|
+
readonly depth?: number;
|
|
284
|
+
/** Object types the read touched, sorted by name. Empty when the read executed nothing. */
|
|
285
|
+
readonly touched: readonly RelatedTypesTouched[];
|
|
286
|
+
/** Every object type a listed edge names — touched, or reached through the listed edges within `depth` levels — once. */
|
|
287
|
+
readonly objects: Readonly<Record<string, RelatedTypesObjectType>>;
|
|
288
|
+
/** Every relation named by an edge, once. */
|
|
289
|
+
readonly relations: Readonly<Record<string, RelatedTypesRelation>>;
|
|
290
|
+
/** Touched types dropped to stay within the budget. */
|
|
291
|
+
readonly omitted_touched: number;
|
|
292
|
+
/**
|
|
293
|
+
* Object types within `depth` relation levels of the touched types in the
|
|
294
|
+
* schema that the catalog does not list: the route to them ran through an edge
|
|
295
|
+
* the server's budget cut, or their level was dropped for its byte budget.
|
|
296
|
+
* Absent on a one-level read.
|
|
297
|
+
*/
|
|
298
|
+
readonly omitted_objects?: number;
|
|
299
|
+
/** `true` when any type, edge or level was dropped for the budget. */
|
|
300
|
+
readonly truncated: boolean;
|
|
301
|
+
}
|
|
168
302
|
export interface ReadResult {
|
|
169
303
|
readonly trace_id: string | null;
|
|
170
304
|
/** Deep link to this read's trace in the console; `null` if no console is configured. */
|
|
171
305
|
readonly console_url: string | null;
|
|
306
|
+
/**
|
|
307
|
+
* The answer, shaped by `readMode`. In `"single-answer"` mode it is always the
|
|
308
|
+
* prose answer, never `null`. In `"raw-tables"` / `"xresponse"` mode its value
|
|
309
|
+
* says which of four answers the read gave:
|
|
310
|
+
*
|
|
311
|
+
* - rows — answered;
|
|
312
|
+
* - exactly `{ columns: [], rows: [] }` (`"raw-tables"`) or
|
|
313
|
+
* `{ objects: [], relations: [] }` (`"xresponse"`) — the query executed and
|
|
314
|
+
* matched nothing: every table and column it used exists, so the data is
|
|
315
|
+
* absent;
|
|
316
|
+
* - `null` — the schema provably cannot represent the concept. An answer in
|
|
317
|
+
* its own right, not a variant of the empty one: this memory cannot hold
|
|
318
|
+
* it, so a better-matching instance is worth trying;
|
|
319
|
+
* - no result at all — every sub-query's SQL failed, so nothing was
|
|
320
|
+
* answered. The read throws {@link XmemoryAPIError} with `status` 422 and
|
|
321
|
+
* `code` `"INVALID_INPUT"` rather than reporting an empty result.
|
|
322
|
+
*
|
|
323
|
+
* For a composite query this is the combined answer, folded from the parts:
|
|
324
|
+
* rows if any sub-query answered; else the empty result if any executed and
|
|
325
|
+
* matched nothing; else `null`. `reader_results` carries each part's own
|
|
326
|
+
* answer.
|
|
327
|
+
*/
|
|
172
328
|
readonly reader_result: unknown;
|
|
173
329
|
/**
|
|
174
330
|
* Per-sub-query answers when the server decomposed the query into independent
|
|
@@ -179,6 +335,14 @@ export interface ReadResult {
|
|
|
179
335
|
* so the array is empty regardless of how many questions the query held.
|
|
180
336
|
*/
|
|
181
337
|
readonly reader_results: readonly TaggedReaderResult[];
|
|
338
|
+
/**
|
|
339
|
+
* The schema around the answer, when the read asked for it with
|
|
340
|
+
* `includeRelatedTypes: "types"`; `null` otherwise. The wire omits the field
|
|
341
|
+
* unless it was requested, and a server that predates the option never sends
|
|
342
|
+
* it; the client normalizes both to `null`, so `null` means "not asked for" and
|
|
343
|
+
* a requested read that executed nothing arrives with `touched: []` instead.
|
|
344
|
+
*/
|
|
345
|
+
readonly related_types: RelatedTypes | null;
|
|
182
346
|
}
|
|
183
347
|
export interface WriteResult {
|
|
184
348
|
readonly write_id: string;
|
|
@@ -554,6 +718,22 @@ export interface ReadOptions {
|
|
|
554
718
|
readMode?: ReadMode;
|
|
555
719
|
/** Restrict the read to a set of concrete objects (plus optional relation traversal). */
|
|
556
720
|
scope?: ReadScope;
|
|
721
|
+
/**
|
|
722
|
+
* `"types"` asks for {@link ReadResult.related_types}: the object types the read
|
|
723
|
+
* touched, the fields it did not return, and the object types a declared
|
|
724
|
+
* relation links them to. Left unset, nothing is sent and the server default
|
|
725
|
+
* (`"none"`) applies. Needs `instance.get_own` on the API key; see
|
|
726
|
+
* {@link RelatedTypesMode}.
|
|
727
|
+
*/
|
|
728
|
+
includeRelatedTypes?: RelatedTypesMode;
|
|
729
|
+
/**
|
|
730
|
+
* With `includeRelatedTypes: "types"`, how many relation levels the catalog
|
|
731
|
+
* follows out from the touched types, 1 to 3. Every entry under
|
|
732
|
+
* {@link RelatedTypes.objects} then carries its `distance` and, below the last
|
|
733
|
+
* level, its own `related` edges. Left unset, nothing is sent and the server
|
|
734
|
+
* serves one level; a value out of range is a 422.
|
|
735
|
+
*/
|
|
736
|
+
relatedTypesDepth?: number;
|
|
557
737
|
traceId?: string;
|
|
558
738
|
timeoutMs?: number;
|
|
559
739
|
}
|