xmemory 3.10.0 → 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 CHANGED
@@ -249,7 +249,7 @@ 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?, includeRelatedTypes?, traceId?, timeoutMs? }` — `readMode` defaults to `"single-answer"`.
252
+ Options: `{ readMode?, scope?, includeRelatedTypes?, relatedTypesDepth?, traceId?, timeoutMs? }` — `readMode` defaults to `"single-answer"`.
253
253
 
254
254
  #### What comes back
255
255
 
@@ -348,7 +348,7 @@ const result = await inst.read("Which courses require an English test?", {
348
348
  for (const touched of result.related_types?.touched ?? []) {
349
349
  console.log(touched.object_type, "did not return", touched.fields_not_returned);
350
350
  for (const link of touched.related) {
351
- const neighbour = result.related_types!.types[link.object_type];
351
+ const neighbour = result.related_types!.objects[link.object_type];
352
352
  console.log(" linked to", link.object_type, "via", link.relation, neighbour.fields);
353
353
  }
354
354
  }
@@ -357,7 +357,34 @@ for (const touched of result.related_types?.touched ?? []) {
357
357
  `related_types` is `null` unless the read asked for it. A requested read that
358
358
  executed nothing arrives with `touched: []`. The server caps the payload;
359
359
  `truncated` says when it did, and `omitted_touched` and each entry's
360
- `omitted_related` count what was dropped. Asking for it needs the
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
361
388
  `instance.get_own` permission on the API key, the same one the schema
362
389
  endpoints need, on top of `data.read`: a key without it gets a 403 whose
363
390
  message names the permission, and the plain read is unaffected.
@@ -236,6 +236,8 @@ class InstanceHandle {
236
236
  }
237
237
  if (options?.includeRelatedTypes != null)
238
238
  body.include_related_types = options.includeRelatedTypes;
239
+ if (options?.relatedTypesDepth != null)
240
+ body.related_types_depth = options.relatedTypesDepth;
239
241
  if (options?.traceId != null)
240
242
  body.trace_id = options.traceId;
241
243
  // The wire shape omits `reader_results` on a server without question
@@ -190,13 +190,19 @@ export interface TaggedReaderResult {
190
190
  */
191
191
  readonly error: string | null;
192
192
  }
193
- /** One relation edge from a touched type to a neighbouring type; {@link RelatedTypes.types} describes both ends. */
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
+ */
194
200
  export interface RelatedTypesLink {
195
- /** The neighbouring object type, described once under `types`. */
201
+ /** The neighbouring object type, described once under `objects`. */
196
202
  readonly object_type: string;
197
203
  /** The relation that links the two, described once under `relations`. */
198
204
  readonly relation: string;
199
- /** The relation role the touched type plays in this edge. */
205
+ /** The relation role the entry's own type plays in this edge. */
200
206
  readonly touched_role: string;
201
207
  /** The relation role the neighbouring type plays in this edge. */
202
208
  readonly related_role: string;
@@ -204,7 +210,7 @@ export interface RelatedTypesLink {
204
210
  }
205
211
  /** One object type the read touched, with what it withheld and what it is linked to. */
206
212
  export interface RelatedTypesTouched {
207
- /** Object type name as declared in the schema, described under `types`. */
213
+ /** Object type name as declared in the schema, described under `objects`. */
208
214
  readonly object_type: string;
209
215
  /**
210
216
  * Fields of this type the read did not project. Ask for one by name to see it;
@@ -217,13 +223,36 @@ export interface RelatedTypesTouched {
217
223
  /** Edges dropped from `related` to stay within the server's payload budget. */
218
224
  readonly omitted_related: number;
219
225
  }
220
- /** Catalog entry for an object type named anywhere in {@link RelatedTypes.touched}. */
226
+ /** Catalog entry for an object type named in {@link RelatedTypes.touched} or reached through `relatedTypesDepth`. */
221
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;
222
237
  readonly description: string | null;
223
238
  /** Declared primary-key fields, in declared order. */
224
239
  readonly primary_key: readonly string[];
225
240
  /** Every field of the object type, by name. */
226
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;
227
256
  }
228
257
  /** Catalog entry for a relation named by any edge. */
229
258
  export interface RelatedTypesRelation {
@@ -236,20 +265,38 @@ export interface RelatedTypesRelation {
236
265
  * describes every named type and relation exactly once. It is derived from the
237
266
  * instance schema and the statements the read executed — no extra rows are
238
267
  * read and no model is called — so an agent can phrase a deliberate follow-up
239
- * read instead of guessing. The server caps the payload; whatever it dropped is
240
- * counted on the entry it was dropped from, and `truncated` says that something
241
- * was.
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.
242
276
  */
243
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;
244
284
  /** Object types the read touched, sorted by name. Empty when the read executed nothing. */
245
285
  readonly touched: readonly RelatedTypesTouched[];
246
- /** Every object type named in `touched`, touched or neighbouring, once. */
247
- readonly types: Readonly<Record<string, RelatedTypesObjectType>>;
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>>;
248
288
  /** Every relation named by an edge, once. */
249
289
  readonly relations: Readonly<Record<string, RelatedTypesRelation>>;
250
290
  /** Touched types dropped to stay within the budget. */
251
291
  readonly omitted_touched: number;
252
- /** `true` when any type or edge was dropped for the budget. */
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. */
253
300
  readonly truncated: boolean;
254
301
  }
255
302
  export interface ReadResult {
@@ -679,6 +726,14 @@ export interface ReadOptions {
679
726
  * {@link RelatedTypesMode}.
680
727
  */
681
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;
682
737
  traceId?: string;
683
738
  timeoutMs?: number;
684
739
  }
@@ -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.10.0";
2
+ export declare const VERSION = "3.12.0";
@@ -2,4 +2,4 @@
2
2
  Object.defineProperty(exports, "__esModule", { value: true });
3
3
  exports.VERSION = void 0;
4
4
  /** Package version. Kept in sync with `package.json` — a test asserts they match. */
5
- exports.VERSION = "3.10.0";
5
+ exports.VERSION = "3.12.0";
@@ -232,6 +232,8 @@ export class InstanceHandle {
232
232
  }
233
233
  if (options?.includeRelatedTypes != null)
234
234
  body.include_related_types = options.includeRelatedTypes;
235
+ if (options?.relatedTypesDepth != null)
236
+ body.related_types_depth = options.relatedTypesDepth;
235
237
  if (options?.traceId != null)
236
238
  body.trace_id = options.traceId;
237
239
  // The wire shape omits `reader_results` on a server without question
@@ -190,13 +190,19 @@ export interface TaggedReaderResult {
190
190
  */
191
191
  readonly error: string | null;
192
192
  }
193
- /** One relation edge from a touched type to a neighbouring type; {@link RelatedTypes.types} describes both ends. */
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
+ */
194
200
  export interface RelatedTypesLink {
195
- /** The neighbouring object type, described once under `types`. */
201
+ /** The neighbouring object type, described once under `objects`. */
196
202
  readonly object_type: string;
197
203
  /** The relation that links the two, described once under `relations`. */
198
204
  readonly relation: string;
199
- /** The relation role the touched type plays in this edge. */
205
+ /** The relation role the entry's own type plays in this edge. */
200
206
  readonly touched_role: string;
201
207
  /** The relation role the neighbouring type plays in this edge. */
202
208
  readonly related_role: string;
@@ -204,7 +210,7 @@ export interface RelatedTypesLink {
204
210
  }
205
211
  /** One object type the read touched, with what it withheld and what it is linked to. */
206
212
  export interface RelatedTypesTouched {
207
- /** Object type name as declared in the schema, described under `types`. */
213
+ /** Object type name as declared in the schema, described under `objects`. */
208
214
  readonly object_type: string;
209
215
  /**
210
216
  * Fields of this type the read did not project. Ask for one by name to see it;
@@ -217,13 +223,36 @@ export interface RelatedTypesTouched {
217
223
  /** Edges dropped from `related` to stay within the server's payload budget. */
218
224
  readonly omitted_related: number;
219
225
  }
220
- /** Catalog entry for an object type named anywhere in {@link RelatedTypes.touched}. */
226
+ /** Catalog entry for an object type named in {@link RelatedTypes.touched} or reached through `relatedTypesDepth`. */
221
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;
222
237
  readonly description: string | null;
223
238
  /** Declared primary-key fields, in declared order. */
224
239
  readonly primary_key: readonly string[];
225
240
  /** Every field of the object type, by name. */
226
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;
227
256
  }
228
257
  /** Catalog entry for a relation named by any edge. */
229
258
  export interface RelatedTypesRelation {
@@ -236,20 +265,38 @@ export interface RelatedTypesRelation {
236
265
  * describes every named type and relation exactly once. It is derived from the
237
266
  * instance schema and the statements the read executed — no extra rows are
238
267
  * read and no model is called — so an agent can phrase a deliberate follow-up
239
- * read instead of guessing. The server caps the payload; whatever it dropped is
240
- * counted on the entry it was dropped from, and `truncated` says that something
241
- * was.
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.
242
276
  */
243
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;
244
284
  /** Object types the read touched, sorted by name. Empty when the read executed nothing. */
245
285
  readonly touched: readonly RelatedTypesTouched[];
246
- /** Every object type named in `touched`, touched or neighbouring, once. */
247
- readonly types: Readonly<Record<string, RelatedTypesObjectType>>;
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>>;
248
288
  /** Every relation named by an edge, once. */
249
289
  readonly relations: Readonly<Record<string, RelatedTypesRelation>>;
250
290
  /** Touched types dropped to stay within the budget. */
251
291
  readonly omitted_touched: number;
252
- /** `true` when any type or edge was dropped for the budget. */
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. */
253
300
  readonly truncated: boolean;
254
301
  }
255
302
  export interface ReadResult {
@@ -679,6 +726,14 @@ export interface ReadOptions {
679
726
  * {@link RelatedTypesMode}.
680
727
  */
681
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;
682
737
  traceId?: string;
683
738
  timeoutMs?: number;
684
739
  }
@@ -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.10.0";
2
+ export declare const VERSION = "3.12.0";
@@ -1,2 +1,2 @@
1
1
  /** Package version. Kept in sync with `package.json` — a test asserts they match. */
2
- export const VERSION = "3.10.0";
2
+ export const VERSION = "3.12.0";
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "xmemory",
3
- "version": "3.10.0",
3
+ "version": "3.12.0",
4
4
  "description": "xmemory",
5
5
  "keywords": [
6
6
  "xmemory"