@astrale-os/sdk 0.6.0-beta.64 → 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.
- 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 +11 -4
- package/dist/application/query/execution/error.d.ts +4 -1
- package/dist/application/query/execution/rows.d.ts +11 -8
- package/dist/application/query/execution/rows.js +72 -43
- package/dist/application/query/execution/run.d.ts +4 -3
- package/dist/application/query/execution/run.js +4 -3
- package/dist/application/query/handles/handles.d.ts +21 -7
- package/dist/application/query/handles/model.d.ts +6 -5
- package/dist/application/query/handles/model.js +14 -5
- package/dist/application/query/handles/rows.d.ts +26 -10
- package/dist/application/query/language/query.d.ts +1 -1
- package/dist/platform/schema/kernel-compiled.d.ts +1 -1
- package/dist/platform/schema/kernel-compiled.js +2 -2
- package/docs/queries.md +29 -10
- 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({
|
|
@@ -9,10 +9,13 @@
|
|
|
9
9
|
* carries no Class, so a value is typed by its key alone; a Node item carries its Class (K-C),
|
|
10
10
|
* which a Kernel before K-C leaves out.
|
|
11
11
|
*/
|
|
12
|
-
import type { EdgeKey } from '../../../platform/graph/edge/index.js';
|
|
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;
|
|
@@ -82,9 +85,13 @@ export type QueryRootItem<R> = R extends {
|
|
|
82
85
|
};
|
|
83
86
|
readonly branches: {};
|
|
84
87
|
};
|
|
85
|
-
/**
|
|
88
|
+
/**
|
|
89
|
+
* One fact a list renders as values: its readable values and the keys it withholds (R9), and an
|
|
90
|
+
* Edge's slug when it has one.
|
|
91
|
+
*/
|
|
86
92
|
export interface QueryFact<Source> {
|
|
87
93
|
readonly fact: NodeId | EdgeKey;
|
|
94
|
+
readonly slug?: EdgeSlug;
|
|
88
95
|
/** By Property key; a key the Domain does not define may appear (a newer Schema). */
|
|
89
96
|
readonly values: QueryPropertyValues<Source>;
|
|
90
97
|
readonly withheld: readonly QueryPropertyKey<Source>[];
|
|
@@ -108,7 +115,7 @@ export interface QueryCountAnswer {
|
|
|
108
115
|
readonly more: boolean;
|
|
109
116
|
readonly undecided?: QueryUndecided;
|
|
110
117
|
}
|
|
111
|
-
/** What a Query answers, by its family
|
|
118
|
+
/** What a Query answers, by its family: `list`, `exists` or `count`. */
|
|
112
119
|
export type QueryAnswerOf<Source, Q> = Q extends {
|
|
113
120
|
readonly list: unknown;
|
|
114
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
|
-
/**
|
|
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,
|
|
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;
|
|
@@ -28,12 +31,12 @@ export declare class Renderer {
|
|
|
28
31
|
constructor(query: string, model: Model, answer: QueryListAnswer<unknown, unknown>);
|
|
29
32
|
/** A Node row, or `undefined` when the reader may not read it and the read does not keep it. */
|
|
30
33
|
node(item: Item, pattern: Pattern): Json | undefined;
|
|
31
|
-
/** An Edge root row: its identity, its values and both ends
|
|
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
|
|
34
|
-
|
|
35
|
-
/** The
|
|
36
|
-
|
|
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
|
-
|
|
86
|
-
|
|
87
|
-
|
|
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));
|
|
@@ -97,14 +117,23 @@ export class Renderer {
|
|
|
97
117
|
row.$edge = this.#edgeValues(item.edge, edge);
|
|
98
118
|
return freeze(row);
|
|
99
119
|
}
|
|
100
|
-
/**
|
|
120
|
+
/**
|
|
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.
|
|
123
|
+
*/
|
|
101
124
|
#edgeValues(edge, select) {
|
|
102
125
|
if (select === 'reference')
|
|
103
126
|
return freeze({ $class: edge.class });
|
|
104
127
|
const c = this.#known(edge.class);
|
|
128
|
+
const named = { $class: edge.class, ...this.#slug(edge) };
|
|
105
129
|
if (this.#withheld(edge))
|
|
106
|
-
return freeze({
|
|
107
|
-
return freeze({
|
|
130
|
+
return freeze({ ...named, $withheld: this.#names(c) });
|
|
131
|
+
return freeze({ ...named, ...this.#values(edge, c, NO_TAKEN) });
|
|
132
|
+
}
|
|
133
|
+
/** The slug the Kernel gives an Edge it renders as values, when the Edge has one. */
|
|
134
|
+
#slug(edge) {
|
|
135
|
+
const slug = this.#fact(edge)?.slug;
|
|
136
|
+
return slug === undefined ? {} : { $slug: slug };
|
|
108
137
|
}
|
|
109
138
|
#known(key) {
|
|
110
139
|
try {
|
|
@@ -114,20 +143,27 @@ export class Renderer {
|
|
|
114
143
|
return undefined;
|
|
115
144
|
}
|
|
116
145
|
}
|
|
117
|
-
/** An Edge root row: its identity, its values and both ends
|
|
146
|
+
/** An Edge root row: its identity, its slug and values when read as values, and both ends. */
|
|
118
147
|
edge(item, plan) {
|
|
119
148
|
const key = item.fact;
|
|
120
|
-
const identity = {
|
|
149
|
+
const identity = {
|
|
150
|
+
$class: key.class,
|
|
151
|
+
$source: key.source,
|
|
152
|
+
$target: key.target,
|
|
153
|
+
...(plan.select === 'value' ? this.#slug(key) : {}),
|
|
154
|
+
};
|
|
121
155
|
const c = this.#known(key.class);
|
|
122
|
-
|
|
123
|
-
|
|
124
|
-
|
|
156
|
+
const unread = this.#unread(item, plan);
|
|
157
|
+
if (unread !== undefined && !plan.withheld)
|
|
158
|
+
return undefined;
|
|
159
|
+
if (unread === item)
|
|
125
160
|
return freeze({ ...identity, $withheld: this.#names(c) });
|
|
126
|
-
}
|
|
127
161
|
const roles = new Set([plan.source.role, plan.target.role]);
|
|
128
162
|
const row = { ...identity };
|
|
129
163
|
if (plan.select === 'value')
|
|
130
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.
|
|
131
167
|
const end = (rendered, { classes, select }) => {
|
|
132
168
|
if (rendered === undefined)
|
|
133
169
|
return undefined;
|
|
@@ -159,20 +195,20 @@ export class Renderer {
|
|
|
159
195
|
throw this.#integrity(relation, 0);
|
|
160
196
|
return undefined;
|
|
161
197
|
}
|
|
162
|
-
return this
|
|
198
|
+
return this.one(item, plan);
|
|
163
199
|
}
|
|
164
200
|
case 'first':
|
|
165
201
|
return items[0] === undefined ? undefined : this.node(items[0], plan);
|
|
166
202
|
case 'firstMore': {
|
|
167
203
|
const n = plan.bound;
|
|
168
|
-
return freeze({ rows: this
|
|
204
|
+
return freeze({ rows: this.rows(items.slice(0, n), plan), more: items.length > n });
|
|
169
205
|
}
|
|
170
206
|
case 'all':
|
|
171
207
|
if (items.length > plan.bound)
|
|
172
208
|
throw new QueryError('TOO_MANY', this.query, { limit: 'max', bound: plan.bound });
|
|
173
|
-
return this
|
|
209
|
+
return this.rows(items, plan);
|
|
174
210
|
default:
|
|
175
|
-
return this
|
|
211
|
+
return this.rows(items, plan);
|
|
176
212
|
}
|
|
177
213
|
}
|
|
178
214
|
#emptyRelation(parent, plan) {
|
|
@@ -195,29 +231,22 @@ export class Renderer {
|
|
|
195
231
|
#integrity(at, found) {
|
|
196
232
|
return new QueryError('INTEGRITY', this.query, { ...at, found });
|
|
197
233
|
}
|
|
198
|
-
|
|
199
|
-
|
|
200
|
-
if (this.#withheld(item.fact))
|
|
201
|
-
throw new QueryError('NOT_READABLE', this.query, { class: this.#class(item), id: item.fact });
|
|
202
|
-
return this.node(item, pattern);
|
|
203
|
-
}
|
|
204
|
-
#rows(items, pattern) {
|
|
205
|
-
return freeze(items.flatMap((item) => this.node(item, pattern) ?? []));
|
|
234
|
+
#row(item, plan) {
|
|
235
|
+
return 'source' in plan ? this.edge(item, plan) : this.node(item, plan);
|
|
206
236
|
}
|
|
207
|
-
/** The
|
|
208
|
-
|
|
209
|
-
|
|
210
|
-
|
|
211
|
-
/** The one root row `get` or `find` gives. */
|
|
212
|
-
rootOne(item, root) {
|
|
213
|
-
if (this.#withheld(item.fact)) {
|
|
214
|
-
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)
|
|
215
241
|
throw new QueryError('NOT_READABLE', this.query, {
|
|
216
|
-
class: typeof fact === 'string' ? this.#class(
|
|
217
|
-
id: fact,
|
|
242
|
+
class: typeof unread.fact === 'string' ? this.#class(unread) : unread.fact.class,
|
|
243
|
+
id: unread.fact,
|
|
218
244
|
});
|
|
219
|
-
|
|
220
|
-
|
|
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) ?? []));
|
|
221
250
|
}
|
|
222
251
|
}
|
|
223
252
|
/** The root Classes a root error names. */
|
|
@@ -266,25 +295,25 @@ export function rootResult(query, model, plan, answer) {
|
|
|
266
295
|
const [item] = items;
|
|
267
296
|
if (item === undefined)
|
|
268
297
|
return emptyResult(query, plan);
|
|
269
|
-
return renderer.
|
|
298
|
+
return renderer.one(item, root);
|
|
270
299
|
}
|
|
271
300
|
case 'first':
|
|
272
|
-
return items[0] === undefined ? undefined : renderer.
|
|
301
|
+
return items[0] === undefined ? undefined : renderer.rows(items.slice(0, 1), root)[0];
|
|
273
302
|
case 'firstMore': {
|
|
274
303
|
const n = plan.bound;
|
|
275
|
-
return freeze({ rows: renderer.
|
|
304
|
+
return freeze({ rows: renderer.rows(items.slice(0, n), root), more: items.length > n });
|
|
276
305
|
}
|
|
277
306
|
case 'page':
|
|
278
307
|
return freeze({
|
|
279
|
-
rows: renderer.
|
|
308
|
+
rows: renderer.rows(items, root),
|
|
280
309
|
...(complete || cursor === undefined ? {} : { next: cursor }),
|
|
281
310
|
});
|
|
282
311
|
case 'all':
|
|
283
312
|
if (items.length > plan.bound)
|
|
284
313
|
throw new QueryError('TOO_MANY', query, { limit: 'max', bound: plan.bound });
|
|
285
|
-
return renderer.
|
|
314
|
+
return renderer.rows(items, root);
|
|
286
315
|
default:
|
|
287
|
-
return renderer.
|
|
316
|
+
return renderer.rows(items, root);
|
|
288
317
|
}
|
|
289
318
|
}
|
|
290
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
|
|
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
|
/**
|
|
@@ -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
|
|
331
|
-
*
|
|
332
|
-
*
|
|
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
|
-
/**
|
|
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<
|
|
177
|
-
first(n: number): RelationRead<readonly
|
|
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
|
|
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
|
|
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>;
|
|
@@ -3,18 +3,19 @@ import type { AnyResolvedClass, Domain } from '../../../platform/schema/index.js
|
|
|
3
3
|
export declare const NODE_ROOT = "kernel.astrale.ai:class.Node";
|
|
4
4
|
/**
|
|
5
5
|
* Names a Node handle owns (`HandleMembers`): a Property of the same name goes under `$prop`. The
|
|
6
|
-
* list is frozen, as `SDK_KEYS` is
|
|
6
|
+
* list is frozen, as `SDK_KEYS` is: a name added to either moves the Properties or the owner group
|
|
7
|
+
* of that name, in every Domain that has one.
|
|
7
8
|
*/
|
|
8
9
|
export declare const HANDLE_MEMBERS: ReadonlySet<string>;
|
|
9
10
|
/** The group of the Properties whose name a handle member, a row key or an Edge role takes. */
|
|
10
11
|
export declare const PROP_GROUP = "$prop";
|
|
11
12
|
/**
|
|
12
13
|
* The keys the SDK writes on rows besides `id` (`SdkKeys`), all named with `$`: `$class`, `$edge`
|
|
13
|
-
* on a row read `.withEdge()`, `$
|
|
14
|
-
* the reader may not read, and the `$prop`
|
|
15
|
-
* goes under `$` and that name (`ownerGroup`).
|
|
14
|
+
* on a row read `.withEdge()`, `$slug` on an Edge read as values that has one, `$source` and
|
|
15
|
+
* `$target` on an Edge root's row, `$withheld` on a row the reader may not read, and the `$prop`
|
|
16
|
+
* group. Frozen; an owner group named as one of them goes under `$` and that name (`ownerGroup`).
|
|
16
17
|
*/
|
|
17
|
-
export declare const SDK_KEYS: readonly ['$class', '$edge', '$source', '$target', '$withheld', "$prop"];
|
|
18
|
+
export declare const SDK_KEYS: readonly ['$class', '$edge', '$slug', '$source', '$target', '$withheld', "$prop"];
|
|
18
19
|
/**
|
|
19
20
|
* Names a row owns (`RowKeys`): `id` and the SDK's keys. A Property named `id` goes under `$prop`;
|
|
20
21
|
* no Property name starts with `$`. Frozen as `HANDLE_MEMBERS` is.
|
|
@@ -7,18 +7,27 @@ const GENERIC = new Set([NODE_ROOT, 'kernel.astrale.ai:class.Identity']);
|
|
|
7
7
|
const TO_ONE = new Set(['0..1', '1']);
|
|
8
8
|
/**
|
|
9
9
|
* Names a Node handle owns (`HandleMembers`): a Property of the same name goes under `$prop`. The
|
|
10
|
-
* list is frozen, as `SDK_KEYS` is
|
|
10
|
+
* list is frozen, as `SDK_KEYS` is: a name added to either moves the Properties or the owner group
|
|
11
|
+
* of that name, in every Domain that has one.
|
|
11
12
|
*/
|
|
12
13
|
export const HANDLE_MEMBERS = new Set(['id', 'path', 'is', 'isExactly', 'via']);
|
|
13
14
|
/** The group of the Properties whose name a handle member, a row key or an Edge role takes. */
|
|
14
15
|
export const PROP_GROUP = '$prop';
|
|
15
16
|
/**
|
|
16
17
|
* The keys the SDK writes on rows besides `id` (`SdkKeys`), all named with `$`: `$class`, `$edge`
|
|
17
|
-
* on a row read `.withEdge()`, `$
|
|
18
|
-
* the reader may not read, and the `$prop`
|
|
19
|
-
* goes under `$` and that name (`ownerGroup`).
|
|
18
|
+
* on a row read `.withEdge()`, `$slug` on an Edge read as values that has one, `$source` and
|
|
19
|
+
* `$target` on an Edge root's row, `$withheld` on a row the reader may not read, and the `$prop`
|
|
20
|
+
* group. Frozen; an owner group named as one of them goes under `$` and that name (`ownerGroup`).
|
|
20
21
|
*/
|
|
21
|
-
export const SDK_KEYS = [
|
|
22
|
+
export const SDK_KEYS = [
|
|
23
|
+
'$class',
|
|
24
|
+
'$edge',
|
|
25
|
+
'$slug',
|
|
26
|
+
'$source',
|
|
27
|
+
'$target',
|
|
28
|
+
'$withheld',
|
|
29
|
+
PROP_GROUP,
|
|
30
|
+
];
|
|
22
31
|
/**
|
|
23
32
|
* Names a row owns (`RowKeys`): `id` and the SDK's keys. A Property named `id` goes under `$prop`;
|
|
24
33
|
* no Property name starts with `$`. Frozen as `HANDLE_MEMBERS` is.
|
|
@@ -3,6 +3,7 @@
|
|
|
3
3
|
* Class or any subclass the Domain can name (D6), and a Property whose name is taken goes under
|
|
4
4
|
* `$prop` (F6).
|
|
5
5
|
*/
|
|
6
|
+
import type { EdgeSlug } from '../../../platform/graph/edge/index.js';
|
|
6
7
|
import type { NodeId } from '../../../platform/graph/node/index.js';
|
|
7
8
|
import type { ClassOf, Cls, Layout, LayoutOf, PropNamesOf, RequiredEntry, SdkKeys, ValueOfEntry } from './domain.js';
|
|
8
9
|
import type { SourceKeys, SourceRole, TargetKeys, TargetRole } from './relations.js';
|
|
@@ -48,16 +49,33 @@ type EdgeIdentity<E> = {
|
|
|
48
49
|
};
|
|
49
50
|
/** An Edge row: its Class, both ends' ids and its Properties. */
|
|
50
51
|
export type EdgeRow<S, E> = E extends unknown ? EdgeIdentity<ClassOf<S, E>> & ValuesOf<S, E, never> : never;
|
|
51
|
-
/**
|
|
52
|
+
/** An Edge read as values: its slug, absent from an Edge without one and on a Host before beta.39. */
|
|
53
|
+
type Slugged = {
|
|
54
|
+
readonly $slug?: EdgeSlug;
|
|
55
|
+
};
|
|
56
|
+
/** What `.withEdge()` adds to a row under `$edge`: the Edge's Class, its slug and its Properties. */
|
|
52
57
|
export type EdgeValues<S, E> = E extends unknown ? {
|
|
53
58
|
readonly $class: ClassOf<S, E>;
|
|
54
|
-
} & ValuesOf<S, E, never> : never;
|
|
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;
|
|
55
68
|
type Roles<S, E> = SourceRole<S, E> | TargetRole<S, E>;
|
|
56
|
-
/** An
|
|
57
|
-
|
|
58
|
-
|
|
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>;
|
|
59
77
|
} & {
|
|
60
|
-
readonly [R in TargetRole<S, E>]:
|
|
78
|
+
readonly [R in TargetRole<S, E>]: EndRow<S, TargetKeys<S, E>, H>;
|
|
61
79
|
} : never;
|
|
62
80
|
/** An Edge reference row at the root (`.ref()`): both ends as references. */
|
|
63
81
|
export type EdgeRootRef<S, E> = E extends unknown ? EdgeIdentity<ClassOf<S, E>> & {
|
|
@@ -65,10 +83,8 @@ export type EdgeRootRef<S, E> = E extends unknown ? EdgeIdentity<ClassOf<S, E>>
|
|
|
65
83
|
} & {
|
|
66
84
|
readonly [R in TargetRole<S, E>]: Ref<S, TargetKeys<S, E>>;
|
|
67
85
|
} : never;
|
|
68
|
-
/** An Edge the reader may not read (`.includeWithheld()`). */
|
|
69
|
-
export type WithheldEdgeRow<S, E> = E extends unknown ? EdgeIdentity<ClassOf<S, E>> &
|
|
70
|
-
readonly $withheld: readonly PropNamesOf<Cls<S, E>>[];
|
|
71
|
-
} : 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;
|
|
72
88
|
/** An Edge's identity, as a Mutation or a guard names it. */
|
|
73
89
|
export interface EdgeKey<E extends string = string> {
|
|
74
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:
|
|
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.
|
|
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;
|