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

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 {
@@ -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;
@@ -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;
@@ -30,10 +33,10 @@ export declare class Renderer {
30
33
  node(item: Item, pattern: Pattern): Json | undefined;
31
34
  /** An Edge root row: its identity, its slug and values when read as values, and both ends. */
32
35
  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;
36
+ /** The one row `get` or `find` gives: one the reader may not read is an error, since it exists. */
37
+ one(item: Item, plan: Pattern | EdgeRootPlan): Json;
38
+ /** The rows of a list, Node or Edge, leaving out what the reader may not read. */
39
+ rows(items: readonly Item[], plan: Pattern | EdgeRootPlan): readonly Json[];
37
40
  }
38
41
  /** The answer of a root read with nothing to read: its verb's empty answer. */
39
42
  export declare function emptyResult(query: string, plan: ReadPlan): unknown;
@@ -77,16 +77,36 @@ export class Renderer {
77
77
  #names(c) {
78
78
  return freeze(c === undefined ? [] : [...this.model.propertyNames(c)]);
79
79
  }
80
+ /**
81
+ * What a row may not show, the one rule of every render path and verb: the first fact it shows
82
+ * that the reader may not read. A row shows its own fact, the Edge it reads as values, and an
83
+ * Edge root's ends read as values; an end read as a reference shows no value.
84
+ */
85
+ #unread(item, plan) {
86
+ const shown = 'source' in plan
87
+ ? [
88
+ item,
89
+ plan.source.select === 'value' ? item.source : undefined,
90
+ plan.target.select === 'value' ? item.target : undefined,
91
+ ]
92
+ : [
93
+ item,
94
+ plan.edge === 'value' && item.edge !== undefined
95
+ ? { fact: item.edge }
96
+ : undefined,
97
+ ];
98
+ return shown.find((one) => one !== undefined && this.#withheld(one.fact));
99
+ }
80
100
  /** A Node row, or `undefined` when the reader may not read it and the read does not keep it. */
81
101
  node(item, pattern) {
82
102
  const cls = this.#class(item);
83
103
  const id = item.fact;
84
104
  const layout = this.#layoutClass(cls, pattern.classes);
85
- if (this.#withheld(id)) {
86
- if (!pattern.withheld)
87
- return undefined;
105
+ const unread = this.#unread(item, pattern);
106
+ if (unread !== undefined && !pattern.withheld)
107
+ return undefined;
108
+ if (unread === item)
88
109
  return freeze({ id, $class: cls, $withheld: this.#names(layout) });
89
- }
90
110
  const row = { id, $class: cls };
91
111
  if (pattern.select === 'value')
92
112
  Object.assign(row, this.#values(id, layout, ROW_KEYS));
@@ -98,8 +118,8 @@ export class Renderer {
98
118
  return freeze(row);
99
119
  }
100
120
  /**
101
- * What `.withEdge()` adds: the Edge's Class, and its slug with its values or the names it
102
- * withholds.
121
+ * What `.withEdge()` adds: the Edge's Class, and its slug with its values or, on a row
122
+ * `.includeWithheld()` keeps, the names it withholds.
103
123
  */
104
124
  #edgeValues(edge, select) {
105
125
  if (select === 'reference')
@@ -133,15 +153,17 @@ export class Renderer {
133
153
  ...(plan.select === 'value' ? this.#slug(key) : {}),
134
154
  };
135
155
  const c = this.#known(key.class);
136
- if (this.#withheld(key)) {
137
- if (!plan.withheld)
138
- return undefined;
156
+ const unread = this.#unread(item, plan);
157
+ if (unread !== undefined && !plan.withheld)
158
+ return undefined;
159
+ if (unread === item)
139
160
  return freeze({ ...identity, $withheld: this.#names(c) });
140
- }
141
161
  const roles = new Set([plan.source.role, plan.target.role]);
142
162
  const row = { ...identity };
143
163
  if (plan.select === 'value')
144
164
  Object.assign(row, this.#values(key, c, roles));
165
+ // `#unread` has ruled on the row: an end it let through that the reader may not read, one kept
166
+ // or read as a reference, renders withheld.
145
167
  const end = (rendered, { classes, select }) => {
146
168
  if (rendered === undefined)
147
169
  return undefined;
@@ -173,20 +195,20 @@ export class Renderer {
173
195
  throw this.#integrity(relation, 0);
174
196
  return undefined;
175
197
  }
176
- return this.#one(item, plan);
198
+ return this.one(item, plan);
177
199
  }
178
200
  case 'first':
179
201
  return items[0] === undefined ? undefined : this.node(items[0], plan);
180
202
  case 'firstMore': {
181
203
  const n = plan.bound;
182
- return freeze({ rows: this.#rows(items.slice(0, n), plan), more: items.length > n });
204
+ return freeze({ rows: this.rows(items.slice(0, n), plan), more: items.length > n });
183
205
  }
184
206
  case 'all':
185
207
  if (items.length > plan.bound)
186
208
  throw new QueryError('TOO_MANY', this.query, { limit: 'max', bound: plan.bound });
187
- return this.#rows(items, plan);
209
+ return this.rows(items, plan);
188
210
  default:
189
- return this.#rows(items, plan);
211
+ return this.rows(items, plan);
190
212
  }
191
213
  }
192
214
  #emptyRelation(parent, plan) {
@@ -209,29 +231,22 @@ export class Renderer {
209
231
  #integrity(at, found) {
210
232
  return new QueryError('INTEGRITY', this.query, { ...at, found });
211
233
  }
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) ?? []));
220
- }
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)) ?? []));
234
+ #row(item, plan) {
235
+ return 'source' in plan ? this.edge(item, plan) : this.node(item, plan);
224
236
  }
225
- /** The one root row `get` or `find` gives. */
226
- rootOne(item, root) {
227
- if (this.#withheld(item.fact)) {
228
- const fact = item.fact;
237
+ /** The one row `get` or `find` gives: one the reader may not read is an error, since it exists. */
238
+ one(item, plan) {
239
+ const unread = this.#unread(item, plan);
240
+ if (unread !== undefined)
229
241
  throw new QueryError('NOT_READABLE', this.query, {
230
- class: typeof fact === 'string' ? this.#class(item) : fact.class,
231
- id: fact,
242
+ class: typeof unread.fact === 'string' ? this.#class(unread) : unread.fact.class,
243
+ id: unread.fact,
232
244
  });
233
- }
234
- return (root.kind === 'nodes' ? this.node(item, root) : this.edge(item, root));
245
+ return this.#row(item, plan);
246
+ }
247
+ /** The rows of a list, Node or Edge, leaving out what the reader may not read. */
248
+ rows(items, plan) {
249
+ return freeze(items.flatMap((item) => this.#row(item, plan) ?? []));
235
250
  }
236
251
  }
237
252
  /** The root Classes a root error names. */
@@ -280,25 +295,25 @@ export function rootResult(query, model, plan, answer) {
280
295
  const [item] = items;
281
296
  if (item === undefined)
282
297
  return emptyResult(query, plan);
283
- return renderer.rootOne(item, root);
298
+ return renderer.one(item, root);
284
299
  }
285
300
  case 'first':
286
- return items[0] === undefined ? undefined : renderer.rootRows(items.slice(0, 1), root)[0];
301
+ return items[0] === undefined ? undefined : renderer.rows(items.slice(0, 1), root)[0];
287
302
  case 'firstMore': {
288
303
  const n = plan.bound;
289
- return freeze({ rows: renderer.rootRows(items.slice(0, n), root), more: items.length > n });
304
+ return freeze({ rows: renderer.rows(items.slice(0, n), root), more: items.length > n });
290
305
  }
291
306
  case 'page':
292
307
  return freeze({
293
- rows: renderer.rootRows(items, root),
308
+ rows: renderer.rows(items, root),
294
309
  ...(complete || cursor === undefined ? {} : { next: cursor }),
295
310
  });
296
311
  case 'all':
297
312
  if (items.length > plan.bound)
298
313
  throw new QueryError('TOO_MANY', query, { limit: 'max', bound: plan.bound });
299
- return renderer.rootRows(items, root);
314
+ return renderer.rows(items, root);
300
315
  default:
301
- return renderer.rootRows(items, root);
316
+ return renderer.rows(items, root);
302
317
  }
303
318
  }
304
319
  /**
@@ -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
  /**
@@ -327,9 +327,10 @@ export async function runQuery(client, domain, query, input, call = {}, declared
327
327
  return (await answer(new Run(client, domain, query.id, declared), built, call));
328
328
  }
329
329
  /**
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.
330
+ * Every row of a page Query for `input`, page after page: past `max` rows answered, `TOO_MANY`. A
331
+ * row a page leaves out does not count, unlike `all({ max })`, which counts every row it reads.
332
+ * Each page is a call of its own, with its own bounds (S11) and its own snapshot, and asks for at
333
+ * most the rows `max` leaves, plus one: the pages read at most `max + 1` rows and those left out.
333
334
  */
334
335
  export async function runEveryPage(client, domain, query, input, max, declared) {
335
336
  const built = build(domain, query, input);
@@ -10,7 +10,7 @@ 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
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';
13
+ import type { Count, 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;
@@ -152,6 +152,15 @@ export interface NodeSet<S, K extends string, W, M extends Rendering, H extends
152
152
  readonly upTo: number;
153
153
  }): Read<Count>;
154
154
  }
155
+ /**
156
+ * A relation's row: under `.includeWithheld()`, a row read `.withEdge()` may also be one whose
157
+ * Edge the reader may not read.
158
+ */
159
+ type RelRowOf<S, K, E, W, M extends Rendering, H extends boolean> = H extends true ? RowOf<S, K, W, M, true> | (W extends {
160
+ readonly $edge: unknown;
161
+ } ? RowOf<S, K, Omit<W, '$edge'> & {
162
+ readonly $edge: WithheldEdgeValues<S, E>;
163
+ }, M, false> : never) : RowOf<S, K, W, M, false>;
155
164
  /** A relation from a Node: the Nodes at the far end of its Edges. */
156
165
  export interface RelSet<S, K extends string, E extends string, W, M extends Rendering, H extends boolean> {
157
166
  /** Its far Classes and Edges: a relation is not a Class handle, so `is` and `union` refuse it. */
@@ -159,7 +168,11 @@ export interface RelSet<S, K extends string, E extends string, W, M extends Rend
159
168
  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
169
  orderBy(keys: (node: NodeHandle<S, K>, edge: EdgeHandle<S, E>) => Ordering): RelSet<S, K, E, W, M, H>;
161
170
  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. */
171
+ /**
172
+ * Each row gains `$edge`: the Edge's Class, its slug when it has one, and its Properties. The
173
+ * Edge is a fact the row reads: when the reader may not read it, the row is left out, `get` and
174
+ * `find` raise `NOT_READABLE`, and `.includeWithheld()` keeps the row with `$withheld` in `$edge`.
175
+ */
163
176
  withEdge(): RelSet<S, K, E, W & {
164
177
  readonly $edge: EdgeValues<S, E>;
165
178
  }, M, H>;
@@ -173,18 +186,18 @@ export interface RelSet<S, K extends string, E extends string, W, M extends Rend
173
186
  */
174
187
  get(): RelationRead<RowOf<S, K, W, M, false>>;
175
188
  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>[]>;
189
+ first(): RelationRead<RelRowOf<S, K, E, W, M, H> | undefined>;
190
+ first(n: number): RelationRead<readonly RelRowOf<S, K, E, W, M, H>[]>;
178
191
  /** Reads n + 1 rows per parent to say whether more exist. */
179
192
  first(n: number, options: {
180
193
  readonly more: true;
181
194
  }): RelationRead<{
182
- readonly rows: readonly RowOf<S, K, W, M, H>[];
195
+ readonly rows: readonly RelRowOf<S, K, E, W, M, H>[];
183
196
  readonly more: boolean;
184
197
  }>;
185
198
  all(options: {
186
199
  readonly max: number;
187
- }): RelationRead<readonly RowOf<S, K, W, M, H>[]>;
200
+ }): RelationRead<readonly RelRowOf<S, K, E, W, M, H>[]>;
188
201
  count(options: {
189
202
  readonly upTo: number;
190
203
  }): RelationRead<Count>;
@@ -205,7 +218,7 @@ export type EdgeRootHandle<S, E extends string> = E extends unknown ? PropsOf<Cl
205
218
  } & {
206
219
  readonly [R in TargetRole<S, E>]: NodeHandle<S, TargetKeys<S, E>>;
207
220
  } : 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);
221
+ 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
222
  /** The Edges of a Class at the root of a read. */
210
223
  export interface EdgeSet<S, E extends string, M extends Rendering, H extends boolean> {
211
224
  readonly '~edge': E;
@@ -213,6 +226,7 @@ export interface EdgeSet<S, E extends string, M extends Rendering, H extends boo
213
226
  orderBy(keys: (edge: EdgeRootHandle<S, E>) => Ordering): EdgeSet<S, E, M, H>;
214
227
  /** Rows of `{ $class, $source, $target }`, with both ends as references. */
215
228
  ref(): EdgeSet<S, E, 'reference', H>;
229
+ /** Keeps in a list a row the reader may not read: its Edge, or an end read as values, withheld. */
216
230
  includeWithheld(): EdgeSet<S, E, M, true>;
217
231
  get(): Read<EdgeRowOf<S, E, M, false>>;
218
232
  find(): Read<EdgeRowOf<S, E, M, false> | undefined>;
@@ -57,12 +57,25 @@ type Slugged = {
57
57
  export type EdgeValues<S, E> = E extends unknown ? {
58
58
  readonly $class: ClassOf<S, E>;
59
59
  } & Slugged & ValuesOf<S, E, never> : never;
60
+ /** An Edge the reader may not read: its slug, which traversal discloses, and the names withheld. */
61
+ type UnreadEdge<S, E> = Slugged & {
62
+ readonly $withheld: readonly PropNamesOf<Cls<S, E>>[];
63
+ };
64
+ /** `$edge` on a row `.includeWithheld()` keeps though the reader may not read its Edge. */
65
+ export type WithheldEdgeValues<S, E> = E extends unknown ? {
66
+ readonly $class: ClassOf<S, E>;
67
+ } & UnreadEdge<S, E> : never;
60
68
  type Roles<S, E> = SourceRole<S, E> | TargetRole<S, E>;
61
- /** An Edge row at the root: its slug, its values, and both ends' rows by role. */
62
- export type EdgeRootRow<S, E> = E extends unknown ? EdgeIdentity<ClassOf<S, E>> & Slugged & ValuesOf<S, E, Roles<S, E>> & {
63
- readonly [R in SourceRole<S, E>]: Row<S, SourceKeys<S, E>>;
69
+ /** An end read as values: one `.includeWithheld()` keeps may be one the reader may not read. */
70
+ type EndRow<S, K, H extends boolean> = Row<S, K> | (H extends true ? WithheldRow<S, K> : never);
71
+ /**
72
+ * An Edge row at the root: its slug, its values, and both ends' rows by role. `H` is
73
+ * `.includeWithheld()`, under which either end may be withheld.
74
+ */
75
+ export type EdgeRootRow<S, E, H extends boolean = false> = E extends unknown ? EdgeIdentity<ClassOf<S, E>> & Slugged & ValuesOf<S, E, Roles<S, E>> & {
76
+ readonly [R in SourceRole<S, E>]: EndRow<S, SourceKeys<S, E>, H>;
64
77
  } & {
65
- readonly [R in TargetRole<S, E>]: Row<S, TargetKeys<S, E>>;
78
+ readonly [R in TargetRole<S, E>]: EndRow<S, TargetKeys<S, E>, H>;
66
79
  } : never;
67
80
  /** An Edge reference row at the root (`.ref()`): both ends as references. */
68
81
  export type EdgeRootRef<S, E> = E extends unknown ? EdgeIdentity<ClassOf<S, E>> & {
@@ -70,10 +83,8 @@ export type EdgeRootRef<S, E> = E extends unknown ? EdgeIdentity<ClassOf<S, E>>
70
83
  } & {
71
84
  readonly [R in TargetRole<S, E>]: Ref<S, TargetKeys<S, E>>;
72
85
  } : never;
73
- /** An Edge the reader may not read (`.includeWithheld()`): its slug, which traversal discloses. */
74
- export type WithheldEdgeRow<S, E> = E extends unknown ? EdgeIdentity<ClassOf<S, E>> & Slugged & {
75
- readonly $withheld: readonly PropNamesOf<Cls<S, E>>[];
76
- } : never;
86
+ /** An Edge row at the root the reader may not read (`.includeWithheld()`). */
87
+ export type WithheldEdgeRow<S, E> = E extends unknown ? EdgeIdentity<ClassOf<S, E>> & UnreadEdge<S, E> : never;
77
88
  /** An Edge's identity, as a Mutation or a guard names it. */
78
89
  export interface EdgeKey<E extends string = string> {
79
90
  readonly source: NodeId;
@@ -307,7 +307,7 @@ type QueryOver<D extends Domain, L extends Size> = D extends Domain ? {
307
307
  readonly count: Range<D>;
308
308
  readonly upTo: number;
309
309
  } : never;
310
- /** A Query of the Domain, as its canonical JSON: the root fold names its family. */
310
+ /** A Query of the Domain, as its canonical JSON: its family is `list`, `exists` or `count`. */
311
311
  export type Query<Source> = QueryOver<QueryDomainOf<Source>, UnsizedList>;
312
312
  /** A Query whose every list is sized by `limit`: the document a defined Query reads (W1). */
313
313
  export type SizedQuery<Source> = QueryOver<QueryDomainOf<Source>, SizedList>;
@@ -1,2 +1,2 @@
1
- /** Generated from the Kernel Schema of @astrale-os/kernel-core 1.0.0-beta.40, reduced to its Classes. Regenerate with pnpm sync:kernel-schema. */
1
+ /** Generated from the Kernel Schema of @astrale-os/kernel-core 1.0.0-beta.41, reduced to its Classes. Regenerate with pnpm sync:kernel-schema. */
2
2
  export declare const kernelCompiledSchema: string;