@astrale-os/sdk 0.6.0-beta.50 → 0.6.0-beta.52
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +1 -1
- package/dist/application/action/context.d.ts +9 -1
- package/dist/application/query/execution/crossings.js +87 -61
- package/dist/application/query/execution/rows.js +6 -0
- package/dist/application/query/execution/run.d.ts +14 -4
- package/dist/application/query/execution/run.js +58 -14
- package/dist/application/query/handles/handles.d.ts +14 -0
- package/dist/application/query/handles/plan.d.ts +2 -2
- package/dist/application/query/handles/reads.d.ts +2 -2
- package/dist/application/query/handles/reads.js +15 -8
- package/dist/execution/invocation/capabilities/bind.d.ts +3 -2
- package/dist/execution/invocation/capabilities/bind.js +25 -12
- package/dist/execution/service/create.js +0 -1
- package/dist/execution/workflows/receiver.d.ts +0 -3
- package/dist/execution/workflows/receiver.js +0 -1
- package/dist/execution/workflows/steps.d.ts +0 -3
- package/dist/execution/workflows/steps.js +2 -2
- package/dist/platform/schema/kernel-compiled.d.ts +1 -1
- package/dist/platform/schema/kernel-compiled.js +2 -2
- package/dist/testing/query.d.ts +7 -2
- package/dist/testing/query.js +4 -3
- package/docs/queries.md +32 -15
- package/package.json +11 -11
package/README.md
CHANGED
|
@@ -228,7 +228,7 @@ An admitted or pending Execution is not proof that the schema change completed.
|
|
|
228
228
|
|
|
229
229
|
### Prerequisites
|
|
230
230
|
|
|
231
|
-
- Node.js 26.
|
|
231
|
+
- Node.js 26.13.0 (default) or Node.js 24; published packages require Node.js 24 or later
|
|
232
232
|
- pnpm 12.1.0
|
|
233
233
|
|
|
234
234
|
### Setup
|
|
@@ -7,7 +7,7 @@ import type { HandlerDependencies } from '../dependency/index.js';
|
|
|
7
7
|
import type { DeclaredErrorFactory, DeclaredErrors, NoDeclaredErrors } from '../error/index.js';
|
|
8
8
|
import type { IntegrationClients, Integrations } from '../integration/index.js';
|
|
9
9
|
import type { Mutation, MutationExecutor, MutationInputOf, MutationOutputOf, DefinedMutation } from '../mutation/index.js';
|
|
10
|
-
import type { InputOf, OutputOf, QueryDefinition, QueryExecutor, DefinedQuery, QueryOptions } from '../query/index.js';
|
|
10
|
+
import type { InputOf, OutputOf, Page, QueryDefinition, QueryExecutor, DefinedQuery, QueryOptions } from '../query/index.js';
|
|
11
11
|
export type ResolvedCallable = ResolvedFunction | ResolvedMethod;
|
|
12
12
|
/** Bearer-free caller evidence established before an Action or Workflow runs. */
|
|
13
13
|
export interface AuthenticatedCaller {
|
|
@@ -64,6 +64,14 @@ export interface DomainQuery<DomainValue extends Domain = Domain, As extends Aut
|
|
|
64
64
|
<R extends DefinedQuery>(query: R, input: InputOf<R>, options: QueryOptions<R, As>): Promise<OutputOf<R>>;
|
|
65
65
|
<Output>(query: QueryDefinition<DomainValue, void, Output>): Promise<Output>;
|
|
66
66
|
<Input, Output>(query: QueryDefinition<DomainValue, Input, Output>, input: Input): Promise<Output>;
|
|
67
|
+
/**
|
|
68
|
+
* Every row of a page Query, page after page; past `max` rows, `TOO_MANY`, as `all({ max })`.
|
|
69
|
+
* Each page is a read of its own, at its own snapshot.
|
|
70
|
+
*/
|
|
71
|
+
readonly all: <R extends DefinedQuery>(query: R, input: InputOf<R>, options: '~page' extends keyof R ? {
|
|
72
|
+
readonly as: As;
|
|
73
|
+
readonly max: number;
|
|
74
|
+
} : never) => Promise<OutputOf<R> extends Page<infer Row> ? readonly Row[] : never>;
|
|
67
75
|
}
|
|
68
76
|
/**
|
|
69
77
|
* Writes under the authority `as` names. A defined Mutation names it on every call; a Mutation of
|
|
@@ -1,15 +1,22 @@
|
|
|
1
1
|
/**
|
|
2
|
-
* The Classes a
|
|
3
|
-
*
|
|
4
|
-
*
|
|
5
|
-
*
|
|
6
|
-
*
|
|
7
|
-
*
|
|
8
|
-
*
|
|
2
|
+
* The Classes a read for the caller crosses, checked against what its Domain declares (S12). A
|
|
3
|
+
* read `as: 'caller'` is a delegation: the Kernel answers what both the caller and the Domain's
|
|
4
|
+
* ceiling admit, and leaves out the rest without saying so. S12 raises, at lowering and before
|
|
5
|
+
* anything is sent, each relation that ceiling narrows whatever the graph holds:
|
|
6
|
+
*
|
|
7
|
+
* - a relation that crosses a Class of a direct dependency other than the Kernel, whose read and
|
|
8
|
+
* traverse rules both admit only some callers, needs `read` or `traverse` declared on it: either
|
|
9
|
+
* lets the Domain traverse it (RAC-PER-PARTY-TRAVERSAL);
|
|
10
|
+
* - a relation's condition that tests a value of such a Class, whose read rule admits only some
|
|
11
|
+
* callers, needs `read` declared on it: the Kernel drops what it cannot decide (FORMULA-GATE).
|
|
12
|
+
*
|
|
13
|
+
* A rule that admits every caller (`true`, or none) needs nothing (AUTH-OPEN-LEAF). A requirement
|
|
14
|
+
* covers its own Class only, as the Kernel's grants do. A Class reached stands for each concrete
|
|
15
|
+
* Class under it the Domain can name, itself when concrete. A read `as: 'executor'` is the
|
|
16
|
+
* Domain's own, which no requirement changes: S12 does not check it. It reads the document as
|
|
17
|
+
* written, so an empty list the input gives refuses what any other list does.
|
|
9
18
|
*/
|
|
10
19
|
import { Key } from '@astrale-os/kernel-dsl/v1/addressing';
|
|
11
|
-
/** What a relation needs on each foreign Class it crosses. */
|
|
12
|
-
const NEEDED = ['read', 'traverse'];
|
|
13
20
|
/**
|
|
14
21
|
* The Kernel's origin. Its Classes need nothing, even when the Domain declares it a dependency, but
|
|
15
22
|
* the dependency Classes under an abstract one (`Identity`, `Node`) each do.
|
|
@@ -74,94 +81,113 @@ export class Crossings {
|
|
|
74
81
|
this.#branches(query, branch.with, plan?.branches, relation);
|
|
75
82
|
}
|
|
76
83
|
}
|
|
77
|
-
/**
|
|
78
|
-
|
|
84
|
+
/**
|
|
85
|
+
* The traversals a condition holds, at any depth, and the values it tests of the `tested`
|
|
86
|
+
* Classes. An end of an Edge (`source`, `target`) is another subject, whose values go unchecked.
|
|
87
|
+
*/
|
|
88
|
+
#where(query, value, at, tested) {
|
|
79
89
|
const where = value;
|
|
80
90
|
switch (where?.op) {
|
|
81
91
|
case 'and':
|
|
82
|
-
case 'or':
|
|
92
|
+
case 'or': {
|
|
93
|
+
const within = tested !== undefined && where.op === 'and'
|
|
94
|
+
? { ...tested, classes: this.#narrowed(tested.classes, where) }
|
|
95
|
+
: tested;
|
|
83
96
|
for (const operand of where.operands)
|
|
84
|
-
this.#where(query, operand, at);
|
|
97
|
+
this.#where(query, operand, at, within);
|
|
85
98
|
return;
|
|
99
|
+
}
|
|
86
100
|
case 'not':
|
|
101
|
+
return this.#where(query, where.operand, at, tested);
|
|
87
102
|
case 'source':
|
|
88
103
|
case 'target':
|
|
89
104
|
return this.#where(query, where.operand, at);
|
|
90
105
|
case 'exists':
|
|
91
106
|
return this.#traversal(query, where, at === undefined ? 'a condition' : `${at}'s condition`);
|
|
92
107
|
}
|
|
108
|
+
const property = where?.property;
|
|
109
|
+
if (tested === undefined || typeof property !== 'string')
|
|
110
|
+
return;
|
|
111
|
+
for (const c of tested.classes)
|
|
112
|
+
if ([...c.properties].some((p) => p.key === property))
|
|
113
|
+
this.#require(query, tested.relation, c, property);
|
|
93
114
|
}
|
|
94
115
|
/** The Edge Classes of `via`, the Node Classes they reach, then the traversal's own conditions. */
|
|
95
116
|
#traversal(query, traversal, label) {
|
|
96
117
|
const via = traversal.via;
|
|
97
118
|
const direction = traversal.direction;
|
|
98
|
-
const
|
|
119
|
+
const known = via.flatMap((key) => this.#known(key));
|
|
99
120
|
const relation = `${label} (via ${via.join(', ')}, ${direction})`;
|
|
100
|
-
const
|
|
101
|
-
|
|
121
|
+
const edges = [...new Set(known.flatMap((c) => this.#concreteOf(c)))];
|
|
122
|
+
const reached = this.model.reached(known, direction).flatMap((c) => this.#concreteOf(c));
|
|
123
|
+
const nodes = this.#narrowed([...new Set(reached)], traversal.node);
|
|
124
|
+
for (const c of [...edges, ...nodes])
|
|
102
125
|
this.#require(query, relation, c);
|
|
103
|
-
this.#where(query, traversal.edge, label);
|
|
104
|
-
this.#where(query, traversal.node, label);
|
|
126
|
+
this.#where(query, traversal.edge, label, { relation, classes: edges });
|
|
127
|
+
this.#where(query, traversal.node, label, { relation, classes: nodes });
|
|
105
128
|
}
|
|
106
129
|
/**
|
|
107
|
-
* The
|
|
108
|
-
*
|
|
109
|
-
* named Classes that satisfy it: an `isExactly` keeps its Class alone.
|
|
130
|
+
* The concrete Classes a condition keeps: an `is` or `isExactly` conjunct, or an `or` of them,
|
|
131
|
+
* keeps those it names; one under a `not` drops them.
|
|
110
132
|
*/
|
|
111
|
-
#narrowed(
|
|
112
|
-
let
|
|
113
|
-
for (const condition of conjuncts(
|
|
114
|
-
const
|
|
133
|
+
#narrowed(classes, where) {
|
|
134
|
+
let kept = classes;
|
|
135
|
+
for (const condition of conjuncts(where)) {
|
|
136
|
+
const dropped = condition.op === 'not' ? namedClasses(condition.operand) : undefined;
|
|
137
|
+
const named = dropped ?? namedClasses(condition);
|
|
115
138
|
if (named === undefined)
|
|
116
139
|
continue;
|
|
117
|
-
|
|
118
|
-
|
|
119
|
-
classes = classes.flatMap((c) => is.some((n) => this.model.satisfies(c).has(n.key))
|
|
120
|
-
? [c]
|
|
121
|
-
: all.filter((n) => this.model.satisfies(n).has(c.key)));
|
|
140
|
+
kept = kept.filter((c) => named.some((n) => (n.exact ? c.key === n.key : this.#satisfies(c).has(n.key))) !==
|
|
141
|
+
(dropped !== undefined));
|
|
122
142
|
}
|
|
123
|
-
return
|
|
143
|
+
return kept;
|
|
124
144
|
}
|
|
125
|
-
|
|
126
|
-
|
|
127
|
-
|
|
128
|
-
|
|
129
|
-
|
|
130
|
-
return;
|
|
131
|
-
}
|
|
145
|
+
/**
|
|
146
|
+
* Throw unless a read for the caller may cross `c`, or test its `value`, as the Domain's own read
|
|
147
|
+
* may: `c` is no direct dependency's, or a rule it needs admits every caller, or is declared.
|
|
148
|
+
*/
|
|
149
|
+
#require(query, relation, c, value) {
|
|
132
150
|
const alias = this.#dependencies.get(c.ref.origin);
|
|
133
|
-
|
|
151
|
+
const needed = value === undefined ? ['read', 'traverse'] : ['read'];
|
|
152
|
+
if (alias === undefined || needed.some((operation) => this.#admits(c, operation)))
|
|
134
153
|
return;
|
|
135
|
-
const
|
|
136
|
-
|
|
137
|
-
|
|
138
|
-
|
|
139
|
-
|
|
140
|
-
|
|
141
|
-
|
|
142
|
-
|
|
143
|
-
|
|
144
|
-
|
|
145
|
-
|
|
154
|
+
const [what, why, operation] = value === undefined
|
|
155
|
+
? [
|
|
156
|
+
`crosses ${c.key}`,
|
|
157
|
+
'read and traverse rules admit only some callers, and on which the Domain declares ' +
|
|
158
|
+
'neither read nor traverse, so a read as the caller leaves it out',
|
|
159
|
+
'traverse',
|
|
160
|
+
]
|
|
161
|
+
: [
|
|
162
|
+
`tests ${value} of ${c.key}`,
|
|
163
|
+
'read rule admits only some callers, and on which the Domain declares no read, so a ' +
|
|
164
|
+
'read as the caller drops what that test cannot decide',
|
|
165
|
+
'read',
|
|
166
|
+
];
|
|
167
|
+
throw new UndeclaredCrossing(query, `Query ${query}: ${relation} ${what}, a Class of the dependency ${alias} whose ${why}. ` +
|
|
168
|
+
`Its requirements need { class: ${c.key}, operations: ['${operation}'] } in classes.`);
|
|
146
169
|
}
|
|
147
|
-
/**
|
|
148
|
-
|
|
149
|
-
|
|
150
|
-
|
|
170
|
+
/**
|
|
171
|
+
* Whether a read for the caller may `operation` a Class as the Domain's own read may: its rule
|
|
172
|
+
* admits every caller (`true`, or none), or the Domain declares the operation on that Class.
|
|
173
|
+
*/
|
|
174
|
+
#admits(c, operation) {
|
|
175
|
+
const rule = c.policies[operation];
|
|
176
|
+
return rule === undefined || rule === true || this.#declared.get(c.key)?.has(operation) === true;
|
|
151
177
|
}
|
|
152
|
-
/**
|
|
153
|
-
|
|
154
|
-
|
|
178
|
+
/**
|
|
179
|
+
* The concrete Classes a Node or Edge of `c` can be of: `c` when concrete, and each concrete Class
|
|
180
|
+
* of the Domain or a dependency under it, as an open Class has.
|
|
181
|
+
*/
|
|
182
|
+
#concreteOf(c) {
|
|
183
|
+
const under = this.#concrete.filter((k) => k.key !== c.key && this.#satisfies(k).has(c.key));
|
|
184
|
+
return c.abstract ? under : [c, ...under];
|
|
155
185
|
}
|
|
156
186
|
/** The keys a Class satisfies, the Kernel's `Edge` included for an Edge Class. */
|
|
157
187
|
#satisfies(c) {
|
|
158
188
|
const keys = this.model.satisfies(c);
|
|
159
189
|
return c.kind === 'edge' ? new Set([...keys, EDGE]) : keys;
|
|
160
190
|
}
|
|
161
|
-
/** Whether a relation may cross a Class: the Domain's own, or a dependency's it declares. */
|
|
162
|
-
#served(c) {
|
|
163
|
-
return !this.#dependencies.has(c.ref.origin) || this.#missing(c).length === 0;
|
|
164
|
-
}
|
|
165
191
|
/** The Class a key names, when the Domain can name it: the Kernel refuses any other. */
|
|
166
192
|
#known(key) {
|
|
167
193
|
try {
|
|
@@ -163,6 +163,10 @@ export class Renderer {
|
|
|
163
163
|
}
|
|
164
164
|
case 'first':
|
|
165
165
|
return items[0] === undefined ? undefined : this.node(items[0], plan);
|
|
166
|
+
case 'firstMore': {
|
|
167
|
+
const n = plan.bound;
|
|
168
|
+
return freeze({ rows: this.#rows(items.slice(0, n), plan), more: items.length > n });
|
|
169
|
+
}
|
|
166
170
|
case 'all':
|
|
167
171
|
if (items.length > plan.bound)
|
|
168
172
|
throw new QueryError('TOO_MANY', this.query, { limit: 'max', bound: plan.bound });
|
|
@@ -182,6 +186,8 @@ export class Renderer {
|
|
|
182
186
|
case 'firstN':
|
|
183
187
|
case 'all':
|
|
184
188
|
return freeze([]);
|
|
189
|
+
case 'firstMore':
|
|
190
|
+
return freeze({ rows: freeze([]), more: false });
|
|
185
191
|
default:
|
|
186
192
|
return undefined;
|
|
187
193
|
}
|
|
@@ -19,7 +19,10 @@ export type QueryOptions<R, As extends string> = {
|
|
|
19
19
|
readonly as: As;
|
|
20
20
|
} & ('~page' extends keyof R ? QueryPageOptions : {});
|
|
21
21
|
type Step = (...parameters: readonly unknown[]) => unknown;
|
|
22
|
-
/**
|
|
22
|
+
/**
|
|
23
|
+
* One Query call: its reads so far, against S11, and, read for the caller, the Classes they cross,
|
|
24
|
+
* against S12.
|
|
25
|
+
*/
|
|
23
26
|
export declare class Run {
|
|
24
27
|
#private;
|
|
25
28
|
readonly client: QueryClient;
|
|
@@ -29,7 +32,8 @@ export declare class Run {
|
|
|
29
32
|
constructor(client: QueryClient, domain: Domain, query: string, declared?: readonly DeclaredClass[]);
|
|
30
33
|
/**
|
|
31
34
|
* S11, before a step sends: its reads, its verbs' bounds, its rows and each property `in` its
|
|
32
|
-
* documents write. Then S12: each foreign Class its relations
|
|
35
|
+
* documents write. Then S12, given the Domain's requirements: each foreign Class its relations
|
|
36
|
+
* cross.
|
|
33
37
|
*/
|
|
34
38
|
admit(plans: readonly ReadPlan[]): void;
|
|
35
39
|
/** One read's result: its verb's empty answer, or its documents' answers merged and rendered. */
|
|
@@ -63,10 +67,16 @@ export declare function planStep(run: Run, built: unknown, single: boolean, earl
|
|
|
63
67
|
* Run a Query for `input` against `domain`, the resolved Domain it was written for: what `build`
|
|
64
68
|
* returns, each of its steps in order, then its `output`. A page Query takes its call's `size`
|
|
65
69
|
* and `after`. A read the Kernel refuses raises a `QueryError`; `output` raises the Query's
|
|
66
|
-
* declared errors.
|
|
67
|
-
*
|
|
70
|
+
* declared errors. Read for the caller, with the Class requirements the Domain's build `declared`,
|
|
71
|
+
* each step's relations are checked against them first (S12).
|
|
68
72
|
*/
|
|
69
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
|
+
/**
|
|
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.
|
|
78
|
+
*/
|
|
79
|
+
export declare function runEveryPage<R extends DefinedQuery>(client: QueryClient, domain: Domain, query: R, input: InputOf<R>, max: number, declared?: readonly DeclaredClass[]): Promise<readonly unknown[]>;
|
|
70
80
|
/**
|
|
71
81
|
* The context a Query's `output`, or a defined Mutation's `reject`, receives: its declared errors,
|
|
72
82
|
* and `is`, which narrows a row by Class.
|
|
@@ -19,7 +19,10 @@ const IN_FLIGHT = 8;
|
|
|
19
19
|
const STALE_RESENDS = 3;
|
|
20
20
|
/** A refusal's protocol code by name, for one that gives no reason. */
|
|
21
21
|
const CODE_NAMES = new Map(Object.entries(errors.CODES).map(([name, code]) => [code, name]));
|
|
22
|
-
/**
|
|
22
|
+
/**
|
|
23
|
+
* One Query call: its reads so far, against S11, and, read for the caller, the Classes they cross,
|
|
24
|
+
* against S12.
|
|
25
|
+
*/
|
|
23
26
|
export class Run {
|
|
24
27
|
client;
|
|
25
28
|
domain;
|
|
@@ -38,7 +41,8 @@ export class Run {
|
|
|
38
41
|
}
|
|
39
42
|
/**
|
|
40
43
|
* S11, before a step sends: its reads, its verbs' bounds, its rows and each property `in` its
|
|
41
|
-
* documents write. Then S12: each foreign Class its relations
|
|
44
|
+
* documents write. Then S12, given the Domain's requirements: each foreign Class its relations
|
|
45
|
+
* cross.
|
|
42
46
|
*/
|
|
43
47
|
admit(plans) {
|
|
44
48
|
this.#reads += plans.length;
|
|
@@ -276,25 +280,27 @@ function pageCall(query, call, max) {
|
|
|
276
280
|
throw new TypeError(`Query ${query}: after is the cursor a page returned as next.`);
|
|
277
281
|
return { size: size ?? max, ...(after === undefined ? {} : { after }) };
|
|
278
282
|
}
|
|
279
|
-
/**
|
|
280
|
-
|
|
281
|
-
* returns, each of its steps in order, then its `output`. A page Query takes its call's `size`
|
|
282
|
-
* and `after`. A read the Kernel refuses raises a `QueryError`; `output` raises the Query's
|
|
283
|
-
* declared errors. With the Class requirements
|
|
284
|
-
* the Domain's build `declared`, each step's relations are checked against them first (S12).
|
|
285
|
-
*/
|
|
286
|
-
export async function runQuery(client, domain, query, input, call = {}, declared) {
|
|
283
|
+
/** What `build` returns for `input`, against the handles of `domain`. */
|
|
284
|
+
function build(domain, query, input) {
|
|
287
285
|
const spec = querySpecOf(query);
|
|
288
286
|
if (spec === undefined)
|
|
289
287
|
throw new TypeError(`Not a Query v7: define one with defineQuery<Schema>()(id, { build }); got ${describe(query)}.`);
|
|
290
|
-
const run = new Run(client, domain, query.id, declared);
|
|
291
288
|
const built = spec.build(input, handlesOf(domain), stepsFor(query.id));
|
|
289
|
+
return { query, input, spec, built };
|
|
290
|
+
}
|
|
291
|
+
/** The `max` of a Query whose single read is a page; `undefined` for any other Query. */
|
|
292
|
+
function pageBoundOf(built) {
|
|
293
|
+
if (!isRead(built))
|
|
294
|
+
return undefined;
|
|
295
|
+
const plan = planOf(built);
|
|
296
|
+
return plan.verb === 'page' ? plan.bound : undefined;
|
|
297
|
+
}
|
|
298
|
+
/** One call of a built Query: each of its steps in order, or its single read, then `output`. */
|
|
299
|
+
async function answer(run, { query, input, spec, built }, call) {
|
|
292
300
|
const steps = stepsOf(built);
|
|
293
301
|
let answered;
|
|
294
302
|
if (steps === undefined) {
|
|
295
|
-
|
|
296
|
-
const options = pageCall(query.id, call, page ? planOf(built).bound : undefined);
|
|
297
|
-
answered = await runStep(run, built, true, options, {});
|
|
303
|
+
answered = await runStep(run, built, true, pageCall(query.id, call, pageBoundOf(built)), {});
|
|
298
304
|
}
|
|
299
305
|
else {
|
|
300
306
|
pageCall(query.id, call, undefined);
|
|
@@ -309,6 +315,44 @@ export async function runQuery(client, domain, query, input, call = {}, declared
|
|
|
309
315
|
return answered;
|
|
310
316
|
return spec.output(answered, input, outputContext(query, run.model));
|
|
311
317
|
}
|
|
318
|
+
/**
|
|
319
|
+
* Run a Query for `input` against `domain`, the resolved Domain it was written for: what `build`
|
|
320
|
+
* returns, each of its steps in order, then its `output`. A page Query takes its call's `size`
|
|
321
|
+
* and `after`. A read the Kernel refuses raises a `QueryError`; `output` raises the Query's
|
|
322
|
+
* declared errors. Read for the caller, with the Class requirements the Domain's build `declared`,
|
|
323
|
+
* each step's relations are checked against them first (S12).
|
|
324
|
+
*/
|
|
325
|
+
export async function runQuery(client, domain, query, input, call = {}, declared) {
|
|
326
|
+
const built = build(domain, query, input);
|
|
327
|
+
return (await answer(new Run(client, domain, query.id, declared), built, call));
|
|
328
|
+
}
|
|
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.
|
|
333
|
+
*/
|
|
334
|
+
export async function runEveryPage(client, domain, query, input, max, declared) {
|
|
335
|
+
const built = build(domain, query, input);
|
|
336
|
+
const bound = pageBoundOf(built.built);
|
|
337
|
+
if (bound === undefined)
|
|
338
|
+
throw new TypeError(`Query ${query.id} is not a page: query.all reads every page of a Query whose single read is page({ max }).`);
|
|
339
|
+
if (!Number.isSafeInteger(max) || max < 1)
|
|
340
|
+
throw new TypeError(`Query ${query.id}: max is a whole number from 1; got ${describe(max)}.`);
|
|
341
|
+
const rows = [];
|
|
342
|
+
let after;
|
|
343
|
+
for (;;) {
|
|
344
|
+
const size = Math.min(bound, max + 1 - rows.length);
|
|
345
|
+
const call = after === undefined ? { size } : { size, after };
|
|
346
|
+
const run = new Run(client, domain, query.id, declared);
|
|
347
|
+
const page = (await answer(run, built, call));
|
|
348
|
+
rows.push(...page.rows);
|
|
349
|
+
if (rows.length > max)
|
|
350
|
+
throw new QueryError('TOO_MANY', query.id, { limit: 'max', bound: max });
|
|
351
|
+
if (page.next === undefined)
|
|
352
|
+
return Object.freeze(rows);
|
|
353
|
+
after = page.next;
|
|
354
|
+
}
|
|
355
|
+
}
|
|
312
356
|
/**
|
|
313
357
|
* The context a Query's `output`, or a defined Mutation's `reject`, receives: its declared errors,
|
|
314
358
|
* and `is`, which narrows a row by Class.
|
|
@@ -175,6 +175,13 @@ export interface RelSet<S, K extends string, E extends string, W, M extends Rend
|
|
|
175
175
|
find(): RelationRead<RowOf<S, K, W, M, false> | undefined>;
|
|
176
176
|
first(): RelationRead<RowOf<S, K, W, M, H> | undefined>;
|
|
177
177
|
first(n: number): RelationRead<readonly RowOf<S, K, W, M, H>[]>;
|
|
178
|
+
/** Reads n + 1 rows per parent to say whether more exist. */
|
|
179
|
+
first(n: number, options: {
|
|
180
|
+
readonly more: true;
|
|
181
|
+
}): RelationRead<{
|
|
182
|
+
readonly rows: readonly RowOf<S, K, W, M, H>[];
|
|
183
|
+
readonly more: boolean;
|
|
184
|
+
}>;
|
|
178
185
|
all(options: {
|
|
179
186
|
readonly max: number;
|
|
180
187
|
}): RelationRead<readonly RowOf<S, K, W, M, H>[]>;
|
|
@@ -211,6 +218,13 @@ export interface EdgeSet<S, E extends string, M extends Rendering, H extends boo
|
|
|
211
218
|
find(): Read<EdgeRowOf<S, E, M, false> | undefined>;
|
|
212
219
|
first(): Read<EdgeRowOf<S, E, M, H> | undefined>;
|
|
213
220
|
first(n: number): Read<readonly EdgeRowOf<S, E, M, H>[]>;
|
|
221
|
+
/** Reads n + 1 rows to say whether more exist. */
|
|
222
|
+
first(n: number, options: {
|
|
223
|
+
readonly more: true;
|
|
224
|
+
}): Read<{
|
|
225
|
+
readonly rows: readonly EdgeRowOf<S, E, M, H>[];
|
|
226
|
+
readonly more: boolean;
|
|
227
|
+
}>;
|
|
214
228
|
page(options: {
|
|
215
229
|
readonly max: number;
|
|
216
230
|
}): PageRead<EdgeRowOf<S, E, M, H>>;
|
|
@@ -10,7 +10,7 @@ import type { Scope } from './terms.js';
|
|
|
10
10
|
/** The verbs of a root read; `document` is the escape hatch (D23). */
|
|
11
11
|
export type Verb = 'get' | 'find' | 'first' | 'firstN' | 'firstMore' | 'page' | 'all' | 'exists' | 'count' | 'document';
|
|
12
12
|
/** The verbs of a relation, per parent. */
|
|
13
|
-
export type RelationVerb = 'get' | 'find' | 'first' | 'firstN' | 'all' | 'exists' | 'count';
|
|
13
|
+
export type RelationVerb = 'get' | 'find' | 'first' | 'firstN' | 'firstMore' | 'all' | 'exists' | 'count';
|
|
14
14
|
export type Rendering = 'value' | 'reference';
|
|
15
15
|
/** How a pattern's rows are answered. */
|
|
16
16
|
export interface Pattern {
|
|
@@ -30,7 +30,7 @@ export interface BranchPlan extends Pattern {
|
|
|
30
30
|
/** The relation as an integrity error names it: its name, or `via(<Edge keys>)`. */
|
|
31
31
|
readonly relation: string;
|
|
32
32
|
readonly verb: RelationVerb;
|
|
33
|
-
/** `first(n)`: n; `all`: max; `count`: upTo. */
|
|
33
|
+
/** `first(n)` and `first(n, { more })`: n; `all`: max; `count`: upTo. */
|
|
34
34
|
readonly bound?: number;
|
|
35
35
|
/** Its condition matches nothing: it is not sent, and every parent gets the empty answer. */
|
|
36
36
|
readonly empty: boolean;
|
|
@@ -41,7 +41,7 @@ export declare class Relation {
|
|
|
41
41
|
/** Exactly one per parent: two rows, to see a second. */
|
|
42
42
|
get(): RelationRead;
|
|
43
43
|
find(): RelationRead;
|
|
44
|
-
first(n?: unknown): RelationRead;
|
|
44
|
+
first(n?: unknown, written?: unknown): RelationRead;
|
|
45
45
|
all(written: unknown): RelationRead;
|
|
46
46
|
count(written: unknown): RelationRead;
|
|
47
47
|
/** A boolean per parent in a `.with`; a condition in a `where`. */
|
|
@@ -97,7 +97,7 @@ export declare class EdgeSet {
|
|
|
97
97
|
includeWithheld(): EdgeSet;
|
|
98
98
|
get(): RootRead;
|
|
99
99
|
find(): RootRead;
|
|
100
|
-
first(n?: unknown): RootRead;
|
|
100
|
+
first(n?: unknown, written?: unknown): RootRead;
|
|
101
101
|
page(written: unknown): RootRead;
|
|
102
102
|
all(written: unknown): RootRead;
|
|
103
103
|
exists(): RootRead;
|
|
@@ -56,6 +56,10 @@ function options(value, what) {
|
|
|
56
56
|
throw new TypeError(`${what} takes an options object; got ${describe(value)}.`);
|
|
57
57
|
return value;
|
|
58
58
|
}
|
|
59
|
+
/** Whether `first(n, written)` also says if more rows exist: `{ more: true }`. */
|
|
60
|
+
function withMore(written) {
|
|
61
|
+
return (written !== undefined && options(written, 'first').more === true);
|
|
62
|
+
}
|
|
59
63
|
// ─── Handles ───────────────────────────────────────────────────────────────────────────────────
|
|
60
64
|
/**
|
|
61
65
|
* The Property handles of some Classes by name: each Class's flat Properties, and on one Class
|
|
@@ -513,11 +517,13 @@ export class Relation {
|
|
|
513
517
|
find() {
|
|
514
518
|
return this.#read('find', 2);
|
|
515
519
|
}
|
|
516
|
-
first(n) {
|
|
520
|
+
first(n, written) {
|
|
517
521
|
if (n === undefined)
|
|
518
522
|
return this.#read('first', 1);
|
|
519
523
|
const bound = integer(n, 'first', 1);
|
|
520
|
-
return
|
|
524
|
+
return withMore(written)
|
|
525
|
+
? this.#read('firstMore', bound + 1, bound)
|
|
526
|
+
: this.#read('firstN', bound, bound);
|
|
521
527
|
}
|
|
522
528
|
all(written) {
|
|
523
529
|
const max = integer(options(written, 'all').max, 'all({ max })', 1);
|
|
@@ -734,10 +740,9 @@ export class NodeSet {
|
|
|
734
740
|
if (n === undefined)
|
|
735
741
|
return this.#list('first', 1);
|
|
736
742
|
const bound = integer(n, 'first', 1);
|
|
737
|
-
|
|
738
|
-
|
|
739
|
-
|
|
740
|
-
return this.#list('firstN', bound, bound);
|
|
743
|
+
return withMore(written)
|
|
744
|
+
? this.#list('firstMore', bound + 1, bound)
|
|
745
|
+
: this.#list('firstN', bound, bound);
|
|
741
746
|
}
|
|
742
747
|
page(written) {
|
|
743
748
|
const max = integer(options(written, 'page').max, 'page({ max })', 1);
|
|
@@ -946,11 +951,13 @@ export class EdgeSet {
|
|
|
946
951
|
find() {
|
|
947
952
|
return this.#rows('find', 2);
|
|
948
953
|
}
|
|
949
|
-
first(n) {
|
|
954
|
+
first(n, written) {
|
|
950
955
|
if (n === undefined)
|
|
951
956
|
return this.#rows('first', 1);
|
|
952
957
|
const bound = integer(n, 'first', 1);
|
|
953
|
-
return
|
|
958
|
+
return withMore(written)
|
|
959
|
+
? this.#rows('firstMore', bound + 1, bound)
|
|
960
|
+
: this.#rows('firstN', bound, bound);
|
|
954
961
|
}
|
|
955
962
|
page(written) {
|
|
956
963
|
const max = integer(options(written, 'page').max, 'page({ max })', 1);
|
|
@@ -6,8 +6,9 @@ import type { InvocationSessions } from '../admission/index.js';
|
|
|
6
6
|
/**
|
|
7
7
|
* Bind what code acting under `sessions` holds: self-default Kernel and graph, and dependency
|
|
8
8
|
* invokers per authority. An Action and a durable Step receive these same capabilities. A Query's
|
|
9
|
-
* reads are checked against the Class requirements the Domain's build `declared`
|
|
9
|
+
* reads for the caller are checked against the Class requirements the Domain's build `declared`
|
|
10
|
+
* (S12); its reads as the executor are the Domain's own, which no requirement changes.
|
|
10
11
|
*/
|
|
11
12
|
export declare function bindCapabilities(domain: Domain, sessions: Readonly<Record<'caller' | 'self', BoundClientSession>>, declared?: readonly DeclaredClass[]): DomainCapabilities;
|
|
12
|
-
export declare function bindCapabilities(domain: Domain, sessions: Readonly<Record<'self', BoundClientSession
|
|
13
|
+
export declare function bindCapabilities(domain: Domain, sessions: Readonly<Record<'self', BoundClientSession>>): DomainCapabilities<Domain, 'self'>;
|
|
13
14
|
export declare function bindCapabilities(domain: Domain, sessions: InvocationSessions, declared?: readonly DeclaredClass[]): DomainCapabilities | DomainCapabilities<Domain, 'self'>;
|
|
@@ -3,31 +3,44 @@ import { executeMutation } from '../../../application/mutation/execution/execute
|
|
|
3
3
|
import { bindMutation } from '../../../application/mutation/execution/executor.js';
|
|
4
4
|
import { querySpecOf } from '../../../application/query/defined/define.js';
|
|
5
5
|
import { bindQuery } from '../../../application/query/execution/executor.js';
|
|
6
|
-
import { runQuery } from '../../../application/query/execution/run.js';
|
|
6
|
+
import { runEveryPage, runQuery } from '../../../application/query/execution/run.js';
|
|
7
|
+
import { describe } from '../../../application/query/handles/terms.js';
|
|
7
8
|
import { bindDependencies } from '../dependency/index.js';
|
|
8
9
|
export function bindCapabilities(domain, sessions, declared) {
|
|
9
10
|
const graph = bindGraph(sessions, domain);
|
|
10
11
|
const graphUnder = (options) => options === undefined ? graph.self : graph[authorityOf(sessions, options)];
|
|
12
|
+
const sessionUnder = (options) => sessions[authorityOf(sessions, options)];
|
|
13
|
+
// A read as the executor is the Domain's own: no requirement it declares changes it (S12).
|
|
14
|
+
const declaredUnder = (options) => authorityOf(sessions, options) === 'caller' ? declared : undefined;
|
|
15
|
+
const query = async (definition, input, options) => {
|
|
16
|
+
if (mutationSpecOf(definition) !== undefined)
|
|
17
|
+
throw new TypeError(`Mutation ${definition.id} writes: call it with mutate, not query.`);
|
|
18
|
+
if (querySpecOf(definition) === undefined)
|
|
19
|
+
return graphUnder(options).query(definition, input);
|
|
20
|
+
if (options === undefined)
|
|
21
|
+
throw new TypeError(`Query ${definition.id} is called with { as: 'executor' | 'caller' }.`);
|
|
22
|
+
const { size, after } = options;
|
|
23
|
+
return runQuery(sessionUnder(options), domain, definition, input, { ...(size === undefined ? {} : { size }), ...(after === undefined ? {} : { after }) }, declaredUnder(options));
|
|
24
|
+
};
|
|
25
|
+
const all = async (definition, input, options) => {
|
|
26
|
+
if (querySpecOf(definition) === undefined)
|
|
27
|
+
throw new TypeError(`query.all reads a page Query v7, defined with defineQuery<Schema>()(id, { build }); got ${describe(definition)}.`);
|
|
28
|
+
if (options === undefined)
|
|
29
|
+
throw new TypeError(`Query ${definition.id} is called with { as: 'executor' | 'caller', max } by query.all.`);
|
|
30
|
+
const { max } = options;
|
|
31
|
+
return runEveryPage(sessionUnder(options), domain, definition, input, max, declaredUnder(options));
|
|
32
|
+
};
|
|
11
33
|
return Object.freeze({
|
|
12
34
|
kernel: Object.freeze({ ...sessions.self, ...sessions }),
|
|
13
35
|
dependencies: bindDependencies(domain, sessions),
|
|
14
36
|
graph,
|
|
15
|
-
query:
|
|
16
|
-
if (mutationSpecOf(definition) !== undefined)
|
|
17
|
-
throw new TypeError(`Mutation ${definition.id} writes: call it with mutate, not query.`);
|
|
18
|
-
if (querySpecOf(definition) === undefined)
|
|
19
|
-
return graphUnder(options).query(definition, input);
|
|
20
|
-
if (options === undefined)
|
|
21
|
-
throw new TypeError(`Query ${definition.id} is called with { as: 'executor' | 'caller' }.`);
|
|
22
|
-
const { size, after } = options;
|
|
23
|
-
return runQuery(sessions[authorityOf(sessions, options)], domain, definition, input, { ...(size === undefined ? {} : { size }), ...(after === undefined ? {} : { after }) }, declared);
|
|
24
|
-
},
|
|
37
|
+
query: Object.freeze(Object.assign(query, { all })),
|
|
25
38
|
mutate: async (definition, input, options) => {
|
|
26
39
|
if (mutationSpecOf(definition) === undefined)
|
|
27
40
|
return graphUnder(options).mutate(definition, input);
|
|
28
41
|
if (options === undefined)
|
|
29
42
|
throw new TypeError(`Mutation ${definition.id} is called with { as: 'executor' | 'caller' }.`);
|
|
30
|
-
return executeMutation(
|
|
43
|
+
return executeMutation(sessionUnder(options), domain, definition, input);
|
|
31
44
|
},
|
|
32
45
|
});
|
|
33
46
|
}
|
|
@@ -70,7 +70,6 @@ export function createService(input) {
|
|
|
70
70
|
return createDurableReceiver({
|
|
71
71
|
workflows: runtime.loaded.registry.workflows,
|
|
72
72
|
domain: runtime.loaded.domain,
|
|
73
|
-
declared: runtime.loaded.release.build.requirements.capabilities.classes ?? [],
|
|
74
73
|
identity: selectedIdentity,
|
|
75
74
|
serving: configuration,
|
|
76
75
|
integrations: runtime.clients,
|
|
@@ -1,5 +1,4 @@
|
|
|
1
1
|
import type { IntegrationClientFactory, Integrations } from '../../application/integration/index.js';
|
|
2
|
-
import type { DeclaredClass } from '../../application/query/execution/crossings.js';
|
|
3
2
|
import type { RuntimeWorkflow } from '../../application/runtime/workflows.js';
|
|
4
3
|
import type { Domain } from '../../platform/schema/index.js';
|
|
5
4
|
import type { Identity } from '../identity/index.js';
|
|
@@ -18,8 +17,6 @@ export interface DurableReceiver {
|
|
|
18
17
|
export declare function createDurableReceiver(input: {
|
|
19
18
|
readonly workflows: readonly RuntimeWorkflow[];
|
|
20
19
|
readonly domain: Domain;
|
|
21
|
-
/** The Class requirements the Domain's build declares, which a Step's Query reads are checked against. */
|
|
22
|
-
readonly declared?: readonly DeclaredClass[];
|
|
23
20
|
readonly identity: Identity;
|
|
24
21
|
readonly serving: AdmittedDurableServing;
|
|
25
22
|
/** Integration clients of the initialized Runtime, which every Step holds. */
|
|
@@ -19,7 +19,6 @@ export function createDurableReceiver(input) {
|
|
|
19
19
|
const steps = sessionSteps({
|
|
20
20
|
executor: executor.bind(input.identity),
|
|
21
21
|
domain: input.domain,
|
|
22
|
-
declared: input.declared ?? [],
|
|
23
22
|
integrations: input.integrations,
|
|
24
23
|
});
|
|
25
24
|
const declared = new Map(input.workflows
|