@astrale-os/sdk 0.6.0-beta.65 → 0.6.0-beta.67

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.
@@ -66,8 +66,9 @@ export interface DomainQuery<DomainValue extends Domain = Domain, As extends Aut
66
66
  <Output>(query: QueryDefinition<DomainValue, void, Output>): Promise<Output>;
67
67
  <Input, Output>(query: QueryDefinition<DomainValue, Input, Output>, input: Input): Promise<Output>;
68
68
  /**
69
- * Every row of a page Query, page after page; past `max` rows, `TOO_MANY`, as `all({ max })`.
70
- * Each page is a read of its own, at its own snapshot.
69
+ * Every row of a page Query, page after page; past `max` rows answered, `TOO_MANY`. A row a page
70
+ * leaves out does not count, unlike `all({ max })`, which counts every row it reads. Each page is
71
+ * a read of its own, at its own snapshot.
71
72
  */
72
73
  readonly all: <R extends DefinedQuery>(query: R, input: InputOf<R>, options: '~page' extends keyof R ? {
73
74
  readonly as: As;
@@ -1,6 +1,5 @@
1
1
  import type { MutationPropsInput } from '@astrale-os/kernel-core/graph/mutate';
2
2
  import type { PropertyInputOf, ResolvedClass, ResolvedProperty } from '@astrale-os/kernel-dsl/v1';
3
- import { PropertyValues } from '@astrale-os/kernel-dsl/v1/language';
4
3
  import type { schema } from '../../../platform/schema/index.js';
5
4
  import type { StoredPropertyInputOf } from '../../../platform/schema/property-input.js';
6
5
  import type { ReceivedFile } from '../../file/index.js';
@@ -24,11 +23,11 @@ export interface RichPropertyDelta<Class> {
24
23
  }
25
24
  export declare function properties<Class extends ResolvedClass>(selected: Class, input: RichPropertyInput<Class>): MutationPropsInput;
26
25
  export declare function conditions<Class extends ResolvedClass>(selected: Class, input: RichPropertyConditions<Class>): Readonly<{
27
- equals?: PropertyValues | undefined;
26
+ equals?: import("@astrale-os/kernel-dsl/v1").PropertyValues | undefined;
28
27
  absent?: readonly `${string}:class.${string}.property.${string}`[] | undefined;
29
28
  }>;
30
29
  export declare function delta<Class extends ResolvedClass>(selected: Class, input: RichPropertyDelta<Class>): Readonly<{
31
- set: Readonly<Record<`${string}:class.${string}.property.${string}`, import("@astrale-os/kernel-dsl/v1/language").PropertyValue>>;
30
+ set: Readonly<Record<`${string}:class.${string}.property.${string}`, import("../../../platform/schema/index.js").Value>>;
32
31
  unset: readonly `${string}:class.${string}.property.${string}`[];
33
32
  }>;
34
33
  export declare function resolvedProperty<Class extends ResolvedClass>(selected: Class, name: RichPropertyName<Class>): ResolvedProperty;
@@ -1,38 +1,15 @@
1
1
  import { PropertyKey } from '@astrale-os/kernel-dsl/v1/addressing';
2
- import { PropertyValues } from '@astrale-os/kernel-dsl/v1/language';
3
2
  import { isReceivedFile } from '../../file/index.js';
4
3
  export function properties(selected, input) {
5
- const ordinary = Object.create(null);
6
- const receipts = [];
7
- const sources = new Map();
8
- for (const [name, value] of Object.entries(input)) {
9
- const property = resolvedProperty(selected, name);
10
- const previous = sources.get(property.key);
11
- if (previous !== undefined) {
12
- throw new TypeError(`Property ${property.key} is supplied through both ${JSON.stringify(previous)} and ${JSON.stringify(name)}.`);
13
- }
14
- sources.set(property.key, name);
15
- if (isBlobProperty(property)) {
16
- // A received file attaches as its upload receipt.
17
- const receipt = isReceivedFile(value) ? value.receipt : value;
18
- if (typeof receipt !== 'string') {
19
- throw new TypeError(`Blob Property ${property.key} requires an upload receipt or a received file.`);
20
- }
21
- receipts.push([property.key, receipt]);
22
- }
23
- else {
24
- ordinary[name] = value;
25
- }
26
- }
27
- // Blob receipts are admitted by the Kernel executor. A property's ordinary validator expects
28
- // the stored Ref, so run it only for ordinary write values before combining the two sets.
29
- const admitted = selected.properties.from(ordinary);
30
- return receipts.length === 0
31
- ? admitted
32
- : PropertyValues.create([
33
- ...Object.entries(admitted).map(([key, value]) => [PropertyKey(key), value]),
34
- ...receipts,
35
- ]);
4
+ // A received file attaches to a blob Property as its upload receipt, which `from` takes.
5
+ const values = Object.fromEntries(Object.entries(input).map(([name, value]) => [
6
+ name,
7
+ isReceivedFile(value) &&
8
+ isBlobProperty(resolvedProperty(selected, name))
9
+ ? value.receipt
10
+ : value,
11
+ ]));
12
+ return selected.properties.from(values);
36
13
  }
37
14
  export function conditions(selected, input) {
38
15
  return Object.freeze({
@@ -12,7 +12,10 @@
12
12
  import type { EdgeKey, EdgeSlug } from '../../../platform/graph/edge/index.js';
13
13
  import type { NodeId } from '../../../platform/graph/node/index.js';
14
14
  import type { QueryPropertyKey, QueryPropertyValues, QueryRendering } from '../language/query.js';
15
- /** On request (W8): the roots the caller's view cannot decide, up to the fold's bound. */
15
+ /**
16
+ * On request (W8): the roots the caller's view cannot decide, up to the read's bound: a page's
17
+ * size, a count's `upTo`.
18
+ */
16
19
  export interface QueryUndecided {
17
20
  readonly count: number;
18
21
  readonly more: boolean;
@@ -112,7 +115,7 @@ export interface QueryCountAnswer {
112
115
  readonly more: boolean;
113
116
  readonly undecided?: QueryUndecided;
114
117
  }
115
- /** What a Query answers, by its family (the name of its root fold). */
118
+ /** What a Query answers, by its family: `list`, `exists` or `count`. */
116
119
  export type QueryAnswerOf<Source, Q> = Q extends {
117
120
  readonly list: unknown;
118
121
  } ? QueryListAnswer<Source, Q> : Q extends {
@@ -135,10 +135,15 @@ export class Crossings {
135
135
  const edges = [...new Set(known.flatMap((c) => this.#concreteOf(c)))];
136
136
  const reached = this.model.reached(known, direction).flatMap((c) => this.#concreteOf(c));
137
137
  const nodes = this.#narrowed([...new Set(reached)], traversal.node);
138
- for (const c of [...edges, ...nodes])
138
+ // A walk also crosses the Nodes it passes through: those it reaches that meet `through`.
139
+ const reach = traversal.reachable;
140
+ const passed = reach === undefined ? [] : this.#narrowed([...new Set(reached)], reach.through);
141
+ for (const c of new Set([...edges, ...nodes, ...passed]))
139
142
  this.#require(query, relation, c);
140
143
  this.#where(query, traversal.edge, label, { relation, classes: edges });
141
144
  this.#where(query, traversal.node, label, { relation, classes: nodes });
145
+ if (reach !== undefined)
146
+ this.#where(query, reach.through, label, { relation, classes: passed });
142
147
  }
143
148
  /**
144
149
  * The concrete Classes a condition keeps: an `is` or `isExactly` conjunct, or an `or` of them,
@@ -11,7 +11,10 @@ export interface QueryErrorDetails {
11
11
  readonly class: string;
12
12
  readonly target?: string;
13
13
  };
14
- /** `get` or `find` met a fact the reader may not read: a Node, or an Edge read at the root. */
14
+ /**
15
+ * `get` or `find` met a fact the reader may not read: a Node, an Edge read at the root, or the
16
+ * Edge of a row read `.withEdge()`.
17
+ */
15
18
  NOT_READABLE: {
16
19
  readonly class: string;
17
20
  readonly id: NodeId | EdgeKey;
@@ -49,9 +52,12 @@ export interface QueryErrorDetails {
49
52
  OUTDATED: {
50
53
  readonly kernelCode: 'QUERY_EXPECTATION_MISMATCH';
51
54
  };
52
- /** The Host does not serve v7, or does not give each row's Class. */
55
+ /**
56
+ * The Host does not serve v7, does not give each row's Class, or does not follow a relation
57
+ * more than one Edge (`.reachable()`).
58
+ */
53
59
  UNSUPPORTED: {
54
- readonly feature: 'v7' | 'classes';
60
+ readonly feature: 'v7' | 'classes' | 'reachable';
55
61
  };
56
62
  }
57
63
  export type QueryErrorCode = keyof QueryErrorDetails;
@@ -25,7 +25,9 @@ function sentence(code, details) {
25
25
  case 'UNSUPPORTED':
26
26
  return details.feature === 'v7'
27
27
  ? 'the Host does not serve Query v7'
28
- : 'the Host does not give the Class of each row';
28
+ : details.feature === 'reachable'
29
+ ? 'the Host does not follow a relation more than one Edge (.reachable())'
30
+ : 'the Host does not give the Class of each row';
29
31
  }
30
32
  }
31
33
  export class QueryError extends Error {
@@ -7,14 +7,17 @@
7
7
  import type { NodeId } from '../../../platform/graph/node/index.js';
8
8
  import type { QueryListAnswer } from '../answer/answer.js';
9
9
  import type { Model } from '../handles/model.js';
10
- import type { EdgeRootPlan, NodeRootPlan, Pattern, ReadPlan } from '../handles/plan.js';
10
+ import type { EdgeRootPlan, Pattern, ReadPlan } from '../handles/plan.js';
11
11
  import type { EdgeKey } from '../handles/rows.js';
12
12
  type Json = Readonly<Record<string, unknown>>;
13
13
  type FactId = NodeId | EdgeKey;
14
- /** One delivered item; a Kernel with K-C gives each Node item its Class. */
15
- interface Item {
14
+ /** A fact a row shows; a Kernel with K-C gives a Node its Class, an Edge's key holds its own. */
15
+ interface Shown {
16
16
  readonly fact: FactId;
17
17
  readonly class?: string;
18
+ }
19
+ /** One delivered item. */
20
+ interface Item extends Shown {
18
21
  readonly edge?: EdgeKey;
19
22
  readonly source?: Item;
20
23
  readonly target?: Item;
@@ -26,14 +29,17 @@ export declare class Renderer {
26
29
  readonly query: string;
27
30
  readonly model: Model;
28
31
  constructor(query: string, model: Model, answer: QueryListAnswer<unknown, unknown>);
29
- /** A Node row, or `undefined` when the reader may not read it and the read does not keep it. */
32
+ /**
33
+ * A Node row, or `undefined` when the reader may not read a fact it reads as values and the read
34
+ * does not keep it.
35
+ */
30
36
  node(item: Item, pattern: Pattern): Json | undefined;
31
37
  /** An Edge root row: its identity, its slug and values when read as values, and both ends. */
32
38
  edge(item: Item, plan: EdgeRootPlan): Json | undefined;
33
- /** The rows of a root list, Node or Edge, leaving out what the reader may not read. */
34
- rootRows(items: readonly Item[], root: NodeRootPlan | EdgeRootPlan): readonly Json[];
35
- /** The one root row `get` or `find` gives. */
36
- rootOne(item: Item, root: NodeRootPlan | EdgeRootPlan): Json;
39
+ /** The one row `get` or `find` gives: one the reader may not read is an error, since it exists. */
40
+ one(item: Item, plan: Pattern | EdgeRootPlan): Json;
41
+ /** The rows of a list, Node or Edge, leaving out what the reader may not read. */
42
+ rows(items: readonly Item[], plan: Pattern | EdgeRootPlan): readonly Json[];
37
43
  }
38
44
  /** The answer of a root read with nothing to read: its verb's empty answer. */
39
45
  export declare function emptyResult(query: string, plan: ReadPlan): unknown;
@@ -77,35 +77,65 @@ export class Renderer {
77
77
  #names(c) {
78
78
  return freeze(c === undefined ? [] : [...this.model.propertyNames(c)]);
79
79
  }
80
- /** A Node row, or `undefined` when the reader may not read it and the read does not keep it. */
80
+ /**
81
+ * What a row may not show, the one rule of every render path and verb: the first fact it reads
82
+ * as values that the reader may not read. A row reads as values its own fact, the Edge
83
+ * `.withEdge()` reads and an Edge root's ends, each unless read as a reference. A reference shows
84
+ * no value, and the Kernel answers one for every fact the reader traverses: the table holds that
85
+ * fact only when another read of the answer renders it as values, which does not decide this row.
86
+ */
87
+ #unread(item, plan) {
88
+ const asValues = (select, shown) => select === 'value' ? shown : undefined;
89
+ const { edge } = plan;
90
+ const shown = 'source' in plan
91
+ ? [
92
+ asValues(plan.select, item),
93
+ asValues(plan.source.select, item.source),
94
+ asValues(plan.target.select, item.target),
95
+ ]
96
+ : [
97
+ asValues(plan.select, item),
98
+ asValues(edge, item.edge === undefined ? undefined : { fact: item.edge }),
99
+ ];
100
+ return shown.find((one) => one !== undefined && this.#withheld(one.fact));
101
+ }
102
+ /**
103
+ * A Node row, or `undefined` when the reader may not read a fact it reads as values and the read
104
+ * does not keep it.
105
+ */
81
106
  node(item, pattern) {
82
107
  const cls = this.#class(item);
83
108
  const id = item.fact;
84
109
  const layout = this.#layoutClass(cls, pattern.classes);
85
- if (this.#withheld(id)) {
86
- if (!pattern.withheld)
87
- return undefined;
110
+ const unread = this.#unread(item, pattern);
111
+ if (unread !== undefined && !pattern.withheld)
112
+ return undefined;
113
+ if (unread === item)
88
114
  return freeze({ id, $class: cls, $withheld: this.#names(layout) });
89
- }
90
115
  const row = { id, $class: cls };
91
116
  if (pattern.select === 'value')
92
117
  Object.assign(row, this.#values(id, layout, ROW_KEYS));
93
118
  for (const branch of pattern.branches)
94
119
  row[branch.key] = this.#relation(item, branch);
95
- const edge = pattern.edge;
120
+ const { edge, reachable } = pattern;
96
121
  if (edge !== undefined && item.edge !== undefined)
97
- row.$edge = this.#edgeValues(item.edge, edge);
122
+ row.$edge = this.#edgeValues(item.edge, edge, reachable === true);
98
123
  return freeze(row);
99
124
  }
100
125
  /**
101
- * What `.withEdge()` adds: the Edge's Class, and its slug with its values or the names it
102
- * withholds.
126
+ * What `.withEdge()` adds: the Edge's Class, and its slug with its values or, on a row
127
+ * `.includeWithheld()` keeps, the names it withholds. On a relation that follows one Edge or
128
+ * more (`ends`), the Edge leaves a Node its walk passed through: it names both its ends.
103
129
  */
104
- #edgeValues(edge, select) {
130
+ #edgeValues(edge, select, ends) {
131
+ const identity = {
132
+ $class: edge.class,
133
+ ...(ends ? { $source: edge.source, $target: edge.target } : {}),
134
+ };
105
135
  if (select === 'reference')
106
- return freeze({ $class: edge.class });
136
+ return freeze(identity);
107
137
  const c = this.#known(edge.class);
108
- const named = { $class: edge.class, ...this.#slug(edge) };
138
+ const named = { ...identity, ...this.#slug(edge) };
109
139
  if (this.#withheld(edge))
110
140
  return freeze({ ...named, $withheld: this.#names(c) });
111
141
  return freeze({ ...named, ...this.#values(edge, c, NO_TAKEN) });
@@ -133,15 +163,17 @@ export class Renderer {
133
163
  ...(plan.select === 'value' ? this.#slug(key) : {}),
134
164
  };
135
165
  const c = this.#known(key.class);
136
- if (this.#withheld(key)) {
137
- if (!plan.withheld)
138
- return undefined;
166
+ const unread = this.#unread(item, plan);
167
+ if (unread !== undefined && !plan.withheld)
168
+ return undefined;
169
+ if (unread === item)
139
170
  return freeze({ ...identity, $withheld: this.#names(c) });
140
- }
141
171
  const roles = new Set([plan.source.role, plan.target.role]);
142
172
  const row = { ...identity };
143
173
  if (plan.select === 'value')
144
174
  Object.assign(row, this.#values(key, c, roles));
175
+ // `#unread` has ruled on the row: an end it let through that the reader may not read, one
176
+ // `.includeWithheld()` keeps, renders withheld; an end read as a reference renders as one.
145
177
  const end = (rendered, { classes, select }) => {
146
178
  if (rendered === undefined)
147
179
  return undefined;
@@ -173,20 +205,20 @@ export class Renderer {
173
205
  throw this.#integrity(relation, 0);
174
206
  return undefined;
175
207
  }
176
- return this.#one(item, plan);
208
+ return this.one(item, plan);
177
209
  }
178
210
  case 'first':
179
211
  return items[0] === undefined ? undefined : this.node(items[0], plan);
180
212
  case 'firstMore': {
181
213
  const n = plan.bound;
182
- return freeze({ rows: this.#rows(items.slice(0, n), plan), more: items.length > n });
214
+ return freeze({ rows: this.rows(items.slice(0, n), plan), more: items.length > n });
183
215
  }
184
216
  case 'all':
185
217
  if (items.length > plan.bound)
186
218
  throw new QueryError('TOO_MANY', this.query, { limit: 'max', bound: plan.bound });
187
- return this.#rows(items, plan);
219
+ return this.rows(items, plan);
188
220
  default:
189
- return this.#rows(items, plan);
221
+ return this.rows(items, plan);
190
222
  }
191
223
  }
192
224
  #emptyRelation(parent, plan) {
@@ -209,29 +241,22 @@ export class Renderer {
209
241
  #integrity(at, found) {
210
242
  return new QueryError('INTEGRITY', this.query, { ...at, found });
211
243
  }
212
- /** The one row `get` or `find` gives: one the reader may not read is an error, since it exists. */
213
- #one(item, pattern) {
214
- if (this.#withheld(item.fact))
215
- throw new QueryError('NOT_READABLE', this.query, { class: this.#class(item), id: item.fact });
216
- return this.node(item, pattern);
217
- }
218
- #rows(items, pattern) {
219
- return freeze(items.flatMap((item) => this.node(item, pattern) ?? []));
244
+ #row(item, plan) {
245
+ return 'source' in plan ? this.edge(item, plan) : this.node(item, plan);
220
246
  }
221
- /** The rows of a root list, Node or Edge, leaving out what the reader may not read. */
222
- rootRows(items, root) {
223
- return freeze(items.flatMap((item) => (root.kind === 'nodes' ? this.node(item, root) : this.edge(item, root)) ?? []));
224
- }
225
- /** The one root row `get` or `find` gives. */
226
- rootOne(item, root) {
227
- if (this.#withheld(item.fact)) {
228
- const fact = item.fact;
247
+ /** The one row `get` or `find` gives: one the reader may not read is an error, since it exists. */
248
+ one(item, plan) {
249
+ const unread = this.#unread(item, plan);
250
+ if (unread !== undefined)
229
251
  throw new QueryError('NOT_READABLE', this.query, {
230
- class: typeof fact === 'string' ? this.#class(item) : fact.class,
231
- id: fact,
252
+ class: typeof unread.fact === 'string' ? this.#class(unread) : unread.fact.class,
253
+ id: unread.fact,
232
254
  });
233
- }
234
- return (root.kind === 'nodes' ? this.node(item, root) : this.edge(item, root));
255
+ return this.#row(item, plan);
256
+ }
257
+ /** The rows of a list, Node or Edge, leaving out what the reader may not read. */
258
+ rows(items, plan) {
259
+ return freeze(items.flatMap((item) => this.#row(item, plan) ?? []));
235
260
  }
236
261
  }
237
262
  /** The root Classes a root error names. */
@@ -280,25 +305,25 @@ export function rootResult(query, model, plan, answer) {
280
305
  const [item] = items;
281
306
  if (item === undefined)
282
307
  return emptyResult(query, plan);
283
- return renderer.rootOne(item, root);
308
+ return renderer.one(item, root);
284
309
  }
285
310
  case 'first':
286
- return items[0] === undefined ? undefined : renderer.rootRows(items.slice(0, 1), root)[0];
311
+ return items[0] === undefined ? undefined : renderer.rows(items.slice(0, 1), root)[0];
287
312
  case 'firstMore': {
288
313
  const n = plan.bound;
289
- return freeze({ rows: renderer.rootRows(items.slice(0, n), root), more: items.length > n });
314
+ return freeze({ rows: renderer.rows(items.slice(0, n), root), more: items.length > n });
290
315
  }
291
316
  case 'page':
292
317
  return freeze({
293
- rows: renderer.rootRows(items, root),
318
+ rows: renderer.rows(items, root),
294
319
  ...(complete || cursor === undefined ? {} : { next: cursor }),
295
320
  });
296
321
  case 'all':
297
322
  if (items.length > plan.bound)
298
323
  throw new QueryError('TOO_MANY', query, { limit: 'max', bound: plan.bound });
299
- return renderer.rootRows(items, root);
324
+ return renderer.rows(items, root);
300
325
  default:
301
- return renderer.rootRows(items, root);
326
+ return renderer.rows(items, root);
302
327
  }
303
328
  }
304
329
  /**
@@ -314,6 +339,7 @@ function documentRoot(plan) {
314
339
  verb: b.mode === 'count' ? 'count' : 'firstN',
315
340
  empty: false,
316
341
  edge: b.selectEdge,
342
+ ...(b.reachable === undefined ? {} : { reachable: true }),
317
343
  classes: [],
318
344
  select: b.select === 'value' ? 'value' : 'reference',
319
345
  withheld: false,
@@ -72,9 +72,10 @@ export declare function planStep(run: Run, built: unknown, single: boolean, earl
72
72
  */
73
73
  export declare function runQuery<R extends DefinedQuery>(client: QueryClient, domain: Domain, query: R, input: InputOf<R>, call?: QueryPageOptions, declared?: readonly DeclaredClass[]): Promise<OutputOf<R>>;
74
74
  /**
75
- * Every row of a page Query for `input`, page after page: past `max` rows, `TOO_MANY`, as
76
- * `all({ max })`. Each page is a call of its own, with its own bounds (S11) and its own snapshot,
77
- * and asks for at most the rows `max` leaves, plus one: the pages read at most `max + 1` rows.
75
+ * Every row of a page Query for `input`, page after page: past `max` rows answered, `TOO_MANY`. A
76
+ * row a page leaves out does not count, unlike `all({ max })`, which counts every row it reads.
77
+ * Each page is a call of its own, with its own bounds (S11) and its own snapshot, and asks for at
78
+ * most the rows `max` leaves, plus one: the pages read at most `max + 1` rows and those left out.
78
79
  */
79
80
  export declare function runEveryPage<R extends DefinedQuery>(client: QueryClient, domain: Domain, query: R, input: InputOf<R>, max: number, declared?: readonly DeclaredClass[]): Promise<readonly unknown[]>;
80
81
  /**
@@ -115,6 +115,9 @@ export class Run {
115
115
  if (isSnapshotStale(error))
116
116
  return new QueryError('REFUSED', this.query, { kernelCode, retryable: true }, cause);
117
117
  const refusals = refusalsOf(error);
118
+ // A Host that predates `.reachable()` refuses the member it does not know, at its pointer.
119
+ if (refusals?.some(unknownReach))
120
+ return new QueryError('UNSUPPORTED', this.query, { feature: 'reachable' }, cause);
118
121
  if (refusals !== undefined) {
119
122
  const path = refusals[0]?.path ?? (typeof details.path === 'string' ? details.path : undefined);
120
123
  return new QueryError('INPUT_INVALID', this.query, {
@@ -134,6 +137,12 @@ export class Run {
134
137
  return new QueryError('REFUSED', this.query, { kernelCode, retryable: false }, cause);
135
138
  }
136
139
  }
140
+ /** Whether a refusal says the Host does not know the `reachable` member of a Traversal. */
141
+ function unknownReach(refusal) {
142
+ return (refusal.phase === 'decode' &&
143
+ refusal.code === 'QUERY_SHAPE' &&
144
+ refusal.path.endsWith('/reachable'));
145
+ }
137
146
  /** A page document of `size` rows. */
138
147
  function withLimit(document, size) {
139
148
  const list = document.list;
@@ -327,9 +336,10 @@ export async function runQuery(client, domain, query, input, call = {}, declared
327
336
  return (await answer(new Run(client, domain, query.id, declared), built, call));
328
337
  }
329
338
  /**
330
- * Every row of a page Query for `input`, page after page: past `max` rows, `TOO_MANY`, as
331
- * `all({ max })`. Each page is a call of its own, with its own bounds (S11) and its own snapshot,
332
- * and asks for at most the rows `max` leaves, plus one: the pages read at most `max + 1` rows.
339
+ * Every row of a page Query for `input`, page after page: past `max` rows answered, `TOO_MANY`. A
340
+ * row a page leaves out does not count, unlike `all({ max })`, which counts every row it reads.
341
+ * Each page is a call of its own, with its own bounds (S11) and its own snapshot, and asks for at
342
+ * most the rows `max` leaves, plus one: the pages read at most `max + 1` rows and those left out.
333
343
  */
334
344
  export async function runEveryPage(client, domain, query, input, max, declared) {
335
345
  const built = build(domain, query, input);
@@ -9,8 +9,8 @@ import type { KernelDomain } from '../../../platform/schema/kernel.js';
9
9
  import type { SizedQuery } from '../language/query.js';
10
10
  import type { Cond, Conditions, HandleMembers, IsCond, Ordering, PropOf, PropsOf, Unordered } from './conditions.js';
11
11
  import type { Cls, Dom, KeyOf, LayoutOf, OriginOf, PropNamesOf, Satisfies, Single, Untyped, ValueOfEntry } from './domain.js';
12
- import type { Far, RelationsOf, SourceKeys, SourceRole, TargetKeys, TargetRole, ViaCheck, ViaOptions } from './relations.js';
13
- import type { Count, EdgeRootRef, EdgeRootRow, EdgeValues, Page, Ref, Row, RowKeys, WithheldEdgeRow, WithheldRow } from './rows.js';
12
+ import type { CanWalk, Far, Followed, RelationsOf, SourceKeys, SourceRole, TargetKeys, TargetRole, ViaCheck, ViaFollowed, ViaOptions } from './relations.js';
13
+ import type { Count, EdgeEnds, EdgeRootRef, EdgeRootRow, EdgeValues, Page, Ref, Row, RowKeys, WithheldEdgeRow, WithheldEdgeValues, WithheldRow } from './rows.js';
14
14
  /** A read: what a verb returns, an opaque description the Query runs, typed by its answer `T`. */
15
15
  export interface Read<out T> {
16
16
  readonly '~read': T;
@@ -82,7 +82,7 @@ export interface NodeMethods<S, K extends string> {
82
82
  is<X extends string>(cls: ClassHandle<X> & IsCheck<S, K, X>, conditions: (node: NodeHandle<S, X>) => Conditions): Cond;
83
83
  isExactly<X extends string>(cls: ClassHandle<X> & IsCheck<S, K, X>): IsCond<X>;
84
84
  /** The Edges of one Class (or several) from this Node; the far end's Classes come from the Edge. */
85
- via<const X extends AnyEdgeSet | readonly [AnyEdgeSet, ...AnyEdgeSet[]], const O extends ViaOptions = {}>(edge: X & ViaCheck<S, K, EdgeKeysOf<X>, O>, options?: O): RelSet<S, Far<S, K, EdgeKeysOf<X>, O>, EdgeKeysOf<X>, {}, 'value', false>;
85
+ via<const X extends AnyEdgeSet | readonly [AnyEdgeSet, ...AnyEdgeSet[]], const O extends ViaOptions = {}>(edge: X & ViaCheck<S, K, EdgeKeysOf<X>, O>, options?: O): RelSet<S, Far<S, K, EdgeKeysOf<X>, O>, EdgeKeysOf<X>, {}, 'value', false, ViaFollowed<S, K, EdgeKeysOf<X>, O>>;
86
86
  }
87
87
  type IsUnion<K, All = K> = K extends unknown ? ([All] extends [K] ? false : true) : never;
88
88
  type FlatOf<S, K> = LayoutOf<Cls<S, K>, HandleMembers>['flat'];
@@ -118,9 +118,12 @@ export interface NodeSet<S, K extends string, W, M extends Rendering, H extends
118
118
  orderBy(keys: (node: NodeHandle<S, K>) => Ordering): NodeSet<S, K, W, M, H>;
119
119
  /** Rows gain each relation's answer under the name given. */
120
120
  with<const X extends Withs>(relations: (node: NodeHandle<S, K>) => X & WithCheck<S, K, W, X>): NodeSet<S, K, W & Answers<X>, M, H>;
121
- /** Rows of references: `{ id, $class }`. */
121
+ /** Rows of references, `{ id, $class }`: they read no values, so none is left out. */
122
122
  ref(): NodeSet<S, K, W, 'reference', H>;
123
- /** Rows the reader may not read stay, as `{ id, $class, $withheld }`. */
123
+ /**
124
+ * Rows read as values that the reader may not read stay, as `{ id, $class, $withheld }`. Rows
125
+ * of references are never left out, so they carry no `$withheld`.
126
+ */
124
127
  includeWithheld(): NodeSet<S, K, W, M, true>;
125
128
  union<K2 extends string>(other: ClassHandle<K2>): NodeSet<S, K | K2, W, M, H>;
126
129
  /**
@@ -152,39 +155,75 @@ export interface NodeSet<S, K extends string, W, M extends Rendering, H extends
152
155
  readonly upTo: number;
153
156
  }): Read<Count>;
154
157
  }
158
+ /**
159
+ * A relation's row: under `.includeWithheld()`, a row read `.withEdge()` may also be one whose
160
+ * Edge the reader may not read.
161
+ */
162
+ type RelRowOf<S, K, E, W, M extends Rendering, H extends boolean> = H extends true ? RowOf<S, K, W, M, true> | (W extends {
163
+ readonly $edge: infer Edge;
164
+ } ? RowOf<S, K, Omit<W, '$edge'> & {
165
+ readonly $edge: WithheldEdgeValues<S, E> & (Edge extends EdgeEnds ? EdgeEnds : unknown);
166
+ }, M, false> : never) : RowOf<S, K, W, M, false>;
167
+ /** What `.withEdge()` adds under `$edge`: on a relation that walks, both ends of the Edge too. */
168
+ type EdgeOf<S, E, F extends Followed> = F['reachable'] extends true ? EdgeValues<S, E> & EdgeEnds : EdgeValues<S, E>;
169
+ /** The rows of a relation once it walks: an `$edge` they already carry names both its ends. */
170
+ type Walked<W> = W extends {
171
+ readonly $edge: unknown;
172
+ } ? W & {
173
+ readonly $edge: EdgeEnds;
174
+ } : W;
155
175
  /** A relation from a Node: the Nodes at the far end of its Edges. */
156
- export interface RelSet<S, K extends string, E extends string, W, M extends Rendering, H extends boolean> {
176
+ export interface RelSet<S, K extends string, E extends string, W, M extends Rendering, H extends boolean, F extends Followed = Followed> {
157
177
  /** Its far Classes and Edges: a relation is not a Class handle, so `is` and `union` refuse it. */
158
- readonly '~via': readonly [K, E];
159
- where<const R extends Conditions>(conditions: (node: NodeHandle<S, K>, edge: EdgeHandle<S, E>) => R): RelSet<S, Narrow<K, R>, E, W, M, H>;
160
- orderBy(keys: (node: NodeHandle<S, K>, edge: EdgeHandle<S, E>) => Ordering): RelSet<S, K, E, W, M, H>;
161
- with<const X extends Withs>(relations: (node: NodeHandle<S, K>) => X & WithCheck<S, K, W, X>): RelSet<S, K, E, W & Answers<X>, M, H>;
162
- /** Each row gains `$edge`: the Edge's Class, its slug when it has one, and its Properties. */
178
+ readonly '~via': readonly [K, E, F];
179
+ where<const R extends Conditions>(conditions: (node: NodeHandle<S, K>, edge: EdgeHandle<S, E>) => R): RelSet<S, Narrow<K, R>, E, W, M, H, F>;
180
+ orderBy(keys: (node: NodeHandle<S, K>, edge: EdgeHandle<S, E>) => Ordering): RelSet<S, K, E, W, M, H, F>;
181
+ with<const X extends Withs>(relations: (node: NodeHandle<S, K>) => X & WithCheck<S, K, W, X>): RelSet<S, K, E, W & Answers<X>, M, H, F>;
182
+ /**
183
+ * Each row gains `$edge`: the Edge's Class, its slug when it has one, and its Properties. The
184
+ * Edge is a fact the row reads: when the reader may not read it, the row is left out, `get` and
185
+ * `find` raise `NOT_READABLE`, and `.includeWithheld()` keeps the row with `$withheld` in `$edge`.
186
+ * On a relation that walks (`.reachable()`), `$edge` also names both ends of the Edge.
187
+ */
163
188
  withEdge(): RelSet<S, K, E, W & {
164
- readonly $edge: EdgeValues<S, E>;
165
- }, M, H>;
166
- /** Rows of references: `{ id, $class }`. */
167
- ref(): RelSet<S, K, E, W, 'reference', H>;
168
- includeWithheld(): RelSet<S, K, E, W, M, true>;
169
- distinct(): RelSet<S, K, E, W, M, H>;
189
+ readonly $edge: EdgeOf<S, E, F>;
190
+ }, M, H, F>;
191
+ /**
192
+ * Rows of references, `{ id, $class }`: they read no Node values, so only the Edge `.withEdge()`
193
+ * reads may leave one out.
194
+ */
195
+ ref(): RelSet<S, K, E, W, 'reference', H, F>;
196
+ includeWithheld(): RelSet<S, K, E, W, M, true, F>;
197
+ distinct(): RelSet<S, K, E, W, M, H, F>;
198
+ /**
199
+ * The relation followed one Edge or more: the Nodes it reaches however far, in one snapshot.
200
+ * Its rows are the Edges it follows, each once with the Node it reaches, or with `.distinct()`
201
+ * the Nodes it reaches, each once; the Node it starts from is among them only when a cycle
202
+ * returns to it. `where` holds on each Edge followed and each Node reached; `through` holds on
203
+ * every Node a walk passes through on its way. Followed `incident`, it needs `.distinct()`.
204
+ * It compiles only where a Class the relation reaches can start another of its Edges.
205
+ */
206
+ reachable(this: true extends CanWalk<S, E, F> ? unknown : `✗ no Class this relation reaches starts another of its Edges in this direction: it follows one Edge, so it is not reachable`, options?: {
207
+ readonly through?: (node: NodeHandle<S, K>) => Conditions;
208
+ }): RelSet<S, K, E, Walked<W>, M, H, Followed<F['direction'], F['reached'], true>>;
170
209
  /**
171
210
  * Exactly one per parent; none or a second is `INTEGRITY`, naming the relation; one the reader
172
211
  * may not read is `NOT_READABLE`.
173
212
  */
174
213
  get(): RelationRead<RowOf<S, K, W, M, false>>;
175
214
  find(): RelationRead<RowOf<S, K, W, M, false> | undefined>;
176
- first(): RelationRead<RowOf<S, K, W, M, H> | undefined>;
177
- first(n: number): RelationRead<readonly RowOf<S, K, W, M, H>[]>;
215
+ first(): RelationRead<RelRowOf<S, K, E, W, M, H> | undefined>;
216
+ first(n: number): RelationRead<readonly RelRowOf<S, K, E, W, M, H>[]>;
178
217
  /** Reads n + 1 rows per parent to say whether more exist. */
179
218
  first(n: number, options: {
180
219
  readonly more: true;
181
220
  }): RelationRead<{
182
- readonly rows: readonly RowOf<S, K, W, M, H>[];
221
+ readonly rows: readonly RelRowOf<S, K, E, W, M, H>[];
183
222
  readonly more: boolean;
184
223
  }>;
185
224
  all(options: {
186
225
  readonly max: number;
187
- }): RelationRead<readonly RowOf<S, K, W, M, H>[]>;
226
+ }): RelationRead<readonly RelRowOf<S, K, E, W, M, H>[]>;
188
227
  count(options: {
189
228
  readonly upTo: number;
190
229
  }): RelationRead<Count>;
@@ -205,14 +244,18 @@ export type EdgeRootHandle<S, E extends string> = E extends unknown ? PropsOf<Cl
205
244
  } & {
206
245
  readonly [R in TargetRole<S, E>]: NodeHandle<S, TargetKeys<S, E>>;
207
246
  } : never;
208
- type EdgeRowOf<S, E, M extends Rendering, H extends boolean> = (M extends 'reference' ? EdgeRootRef<S, E> : EdgeRootRow<S, E>) | (H extends true ? WithheldEdgeRow<S, E> : never);
247
+ type EdgeRowOf<S, E, M extends Rendering, H extends boolean> = (M extends 'reference' ? EdgeRootRef<S, E> : EdgeRootRow<S, E, H>) | (H extends true ? WithheldEdgeRow<S, E> : never);
209
248
  /** The Edges of a Class at the root of a read. */
210
249
  export interface EdgeSet<S, E extends string, M extends Rendering, H extends boolean> {
211
250
  readonly '~edge': E;
212
251
  where(conditions: (edge: EdgeRootHandle<S, E>) => Conditions): EdgeSet<S, E, M, H>;
213
252
  orderBy(keys: (edge: EdgeRootHandle<S, E>) => Ordering): EdgeSet<S, E, M, H>;
214
- /** Rows of `{ $class, $source, $target }`, with both ends as references. */
253
+ /** Rows of `{ $class, $source, $target }`, with both ends as references: none is left out. */
215
254
  ref(): EdgeSet<S, E, 'reference', H>;
255
+ /**
256
+ * Keeps in a list a row the reader may not read: its Edge, or an end read as values, withheld.
257
+ * After `.ref()` no row is left out, so none is withheld.
258
+ */
216
259
  includeWithheld(): EdgeSet<S, E, M, true>;
217
260
  get(): Read<EdgeRowOf<S, E, M, false>>;
218
261
  find(): Read<EdgeRowOf<S, E, M, false> | undefined>;
@@ -85,6 +85,12 @@ export declare class Model {
85
85
  covers(end: End, classes: readonly string[]): boolean;
86
86
  /** Whether an end accepts one of `classes`, or one of their parents. */
87
87
  touches(classes: readonly AnyResolvedClass[], end: End): boolean;
88
+ /**
89
+ * Whether a Node of one of `classes` may be one `end` accepts: the end accepts the Class, one of
90
+ * its parents, or one of its subclasses. What a walk asks of the Classes it reaches before it
91
+ * follows another Edge from them.
92
+ */
93
+ meets(classes: readonly AnyResolvedClass[], end: End): boolean;
88
94
  /** The Classes a traversal of `edges` in `direction` reaches. */
89
95
  reached(edges: readonly AnyResolvedClass[], direction: Direction): readonly AnyResolvedClass[];
90
96
  /** Every Property name of a Class, flat or grouped: a relation or a `.with` name avoids them. */