@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.
- package/dist/application/action/context.d.ts +3 -2
- package/dist/application/mutation/authoring/properties.d.ts +2 -3
- package/dist/application/mutation/authoring/properties.js +9 -32
- package/dist/application/query/answer/answer.d.ts +5 -2
- package/dist/application/query/execution/crossings.js +6 -1
- package/dist/application/query/execution/error.d.ts +9 -3
- package/dist/application/query/execution/error.js +3 -1
- package/dist/application/query/execution/rows.d.ts +14 -8
- package/dist/application/query/execution/rows.js +72 -46
- package/dist/application/query/execution/run.d.ts +4 -3
- package/dist/application/query/execution/run.js +13 -3
- package/dist/application/query/handles/handles.d.ts +66 -23
- package/dist/application/query/handles/model.d.ts +6 -0
- package/dist/application/query/handles/model.js +10 -0
- package/dist/application/query/handles/plan.d.ts +6 -1
- package/dist/application/query/handles/reads.d.ts +7 -0
- package/dist/application/query/handles/reads.js +98 -16
- package/dist/application/query/handles/relations.d.ts +31 -3
- package/dist/application/query/handles/rows.d.ts +27 -8
- package/dist/application/query/language/query.d.ts +9 -2
- package/dist/platform/schema/kernel-compiled.d.ts +1 -1
- package/dist/platform/schema/kernel-compiled.js +2 -2
- package/docs/legacy/query-v6.md +1 -1
- package/docs/queries.md +56 -11
- package/package.json +6 -6
|
@@ -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
|
|
70
|
-
*
|
|
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("
|
|
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
|
-
|
|
6
|
-
const
|
|
7
|
-
|
|
8
|
-
|
|
9
|
-
|
|
10
|
-
|
|
11
|
-
|
|
12
|
-
|
|
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
|
-
/**
|
|
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
|
|
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
|
-
|
|
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
|
-
/**
|
|
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
|
-
/**
|
|
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
|
-
:
|
|
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,
|
|
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
|
-
/**
|
|
15
|
-
interface
|
|
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
|
-
/**
|
|
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
|
|
34
|
-
|
|
35
|
-
/** The
|
|
36
|
-
|
|
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
|
-
/**
|
|
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
|
-
|
|
86
|
-
|
|
87
|
-
|
|
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
|
|
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
|
|
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(
|
|
136
|
+
return freeze(identity);
|
|
107
137
|
const c = this.#known(edge.class);
|
|
108
|
-
const named = {
|
|
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
|
-
|
|
137
|
-
|
|
138
|
-
|
|
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
|
|
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
|
|
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
|
|
219
|
+
return this.rows(items, plan);
|
|
188
220
|
default:
|
|
189
|
-
return this
|
|
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
|
-
|
|
213
|
-
|
|
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
|
|
222
|
-
|
|
223
|
-
|
|
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(
|
|
231
|
-
id: fact,
|
|
252
|
+
class: typeof unread.fact === 'string' ? this.#class(unread) : unread.fact.class,
|
|
253
|
+
id: unread.fact,
|
|
232
254
|
});
|
|
233
|
-
|
|
234
|
-
|
|
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.
|
|
308
|
+
return renderer.one(item, root);
|
|
284
309
|
}
|
|
285
310
|
case 'first':
|
|
286
|
-
return items[0] === undefined ? undefined : renderer.
|
|
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.
|
|
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.
|
|
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.
|
|
324
|
+
return renderer.rows(items, root);
|
|
300
325
|
default:
|
|
301
|
-
return renderer.
|
|
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
|
|
76
|
-
*
|
|
77
|
-
*
|
|
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
|
|
331
|
-
*
|
|
332
|
-
*
|
|
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
|
|
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
|
-
/**
|
|
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
|
-
/**
|
|
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:
|
|
165
|
-
}, M, H>;
|
|
166
|
-
/**
|
|
167
|
-
|
|
168
|
-
|
|
169
|
-
|
|
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<
|
|
177
|
-
first(n: number): RelationRead<readonly
|
|
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
|
|
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
|
|
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. */
|