@astrale-os/sdk 0.6.0-beta.50 → 0.6.0-beta.51
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/testing/query.d.ts +7 -2
- package/dist/testing/query.js +4 -3
- package/docs/queries.md +32 -15
- package/package.json +6 -6
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
|
|
@@ -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 { DurableExecution, DurableStepAuthority } from '../../application/workflow/index.js';
|
|
4
3
|
import type { BoundClientSession } from '../../platform/client/session/index.js';
|
|
5
4
|
import type { Domain } from '../../platform/schema/index.js';
|
|
@@ -30,8 +29,6 @@ export type StepAuthorities = (attempt: StepAttempt) => StepAuthorityBinding;
|
|
|
30
29
|
export declare function sessionSteps(input: {
|
|
31
30
|
readonly executor: Executor;
|
|
32
31
|
readonly domain: Domain;
|
|
33
|
-
/** The Class requirements the Domain's build declares: a Query's reads are checked against them. */
|
|
34
|
-
readonly declared: readonly DeclaredClass[];
|
|
35
32
|
readonly integrations: IntegrationClientFactory<Integrations>;
|
|
36
33
|
}): StepAuthorities;
|
|
37
34
|
/**
|
|
@@ -8,7 +8,7 @@ import { stepCalls } from './integrations.js';
|
|
|
8
8
|
* an Action over the keyed Session, and the Runtime's Integration clients over the same keys.
|
|
9
9
|
*/
|
|
10
10
|
export function sessionSteps(input) {
|
|
11
|
-
const { executor, domain,
|
|
11
|
+
const { executor, domain, integrations } = input;
|
|
12
12
|
return ({ execution, next, lifetime }) => {
|
|
13
13
|
const session = executor(execution.kernel, execution.id, lifetime);
|
|
14
14
|
try {
|
|
@@ -19,7 +19,7 @@ export function sessionSteps(input) {
|
|
|
19
19
|
});
|
|
20
20
|
const auth = bindIntegrationAuthentication(lifetime, bound);
|
|
21
21
|
const authority = Object.freeze({
|
|
22
|
-
...bindCapabilities(domain, { self }
|
|
22
|
+
...bindCapabilities(domain, { self }),
|
|
23
23
|
integrations: integrations(stepCalls({ next, lifetime, auth })),
|
|
24
24
|
});
|
|
25
25
|
return Object.freeze({
|
package/dist/testing/query.d.ts
CHANGED
|
@@ -7,11 +7,16 @@ export interface CheckQueryOptions {
|
|
|
7
7
|
* against, or its Schema alone, which holds no requirements, so S12 is not checked.
|
|
8
8
|
*/
|
|
9
9
|
readonly domain: DomainDefinitionIdentity | schema.DomainSchema;
|
|
10
|
+
/**
|
|
11
|
+
* The authority the Query is called with. `caller`, the default, checks S12 as a read for the
|
|
12
|
+
* caller is checked; `executor` reads as the Domain itself, which S12 does not check.
|
|
13
|
+
*/
|
|
14
|
+
readonly as?: 'executor' | 'caller';
|
|
10
15
|
}
|
|
11
16
|
/**
|
|
12
17
|
* Build a Query for `sampleInput` and lower its first step, as a call would, without a Kernel:
|
|
13
18
|
* it throws what the call would raise before sending, a bound past S11 (`QueryError` `TOO_MANY` or
|
|
14
|
-
* `INPUT_INVALID`), a relation
|
|
15
|
-
* step that does not build.
|
|
19
|
+
* `INPUT_INVALID`), a relation of a read for the caller that the Domain's definition does not
|
|
20
|
+
* declare (S12), or a step that does not build.
|
|
16
21
|
*/
|
|
17
22
|
export declare function checkQuery<R extends DefinedQuery>(query: R, sampleInput: InputOf<R>, options: CheckQueryOptions): void;
|
package/dist/testing/query.js
CHANGED
|
@@ -11,8 +11,8 @@ const NO_KERNEL = Object.freeze({
|
|
|
11
11
|
/**
|
|
12
12
|
* Build a Query for `sampleInput` and lower its first step, as a call would, without a Kernel:
|
|
13
13
|
* it throws what the call would raise before sending, a bound past S11 (`QueryError` `TOO_MANY` or
|
|
14
|
-
* `INPUT_INVALID`), a relation
|
|
15
|
-
* step that does not build.
|
|
14
|
+
* `INPUT_INVALID`), a relation of a read for the caller that the Domain's definition does not
|
|
15
|
+
* declare (S12), or a step that does not build.
|
|
16
16
|
*/
|
|
17
17
|
export function checkQuery(query, sampleInput, options) {
|
|
18
18
|
const spec = querySpecOf(query);
|
|
@@ -22,7 +22,8 @@ export function checkQuery(query, sampleInput, options) {
|
|
|
22
22
|
const domain = schemaApi.resolve(definition?.schema ?? options?.domain);
|
|
23
23
|
// A definition types its requirements as written; the check reads any.
|
|
24
24
|
const requirements = definition?.requirements;
|
|
25
|
-
const
|
|
25
|
+
const checked = definition !== undefined && options?.as !== 'executor';
|
|
26
|
+
const declared = checked ? (requirements?.classes ?? []) : undefined;
|
|
26
27
|
const run = new Run(NO_KERNEL, domain, query.id, declared);
|
|
27
28
|
const build = spec.build;
|
|
28
29
|
const built = build(sampleInput, handlesOf(domain), stepsFor(query.id));
|
package/docs/queries.md
CHANGED
|
@@ -156,8 +156,8 @@ with `.via(edge, { direction })`, where `direction` is `outgoing`, `incoming` or
|
|
|
156
156
|
`.via([e1, e2])` reads several Edge Classes. `direction` is required when both ends accept the
|
|
157
157
|
Class, or when the Edges listed leave it in different directions.
|
|
158
158
|
|
|
159
|
-
A relation reads with the root verbs, per parent row: `get`, `find`, `first`,
|
|
160
|
-
`exists`. A relation's `get` that finds none, or a second row, raises `INTEGRITY` naming the
|
|
159
|
+
A relation reads with the root verbs, per parent row: `get`, `find`, `first`,
|
|
160
|
+
`first(n, { more: true })`, `all`, `count` and `exists`. A relation's `get` that finds none, or a second row, raises `INTEGRITY` naming the
|
|
161
161
|
relation. A relation also takes `where`, `orderBy`, `with`, `ref`, `includeWithheld`, `distinct`
|
|
162
162
|
and `withEdge()`, which adds the Edge's Class and Properties to each row under `$edge`.
|
|
163
163
|
|
|
@@ -180,8 +180,7 @@ declares none of its own, each go under `$` and their owner's name in lower came
|
|
|
180
180
|
|
|
181
181
|
An Edge read at the root answers rows of `{ $class, $source, $target }`, the Edge's Properties,
|
|
182
182
|
and both ends' rows under their roles. `edgeKey(row)` gives the `{ source, target, class }` a
|
|
183
|
-
Mutation or a guard names an Edge by. An Edge root's `get()`, `find()` and `exists()` take no id
|
|
184
|
-
and its `first(n)` takes no `{ more }`.
|
|
183
|
+
Mutation or a guard names an Edge by. An Edge root's `get()`, `find()` and `exists()` take no id.
|
|
185
184
|
|
|
186
185
|
An undirected Edge's ends have no order: neither of its roles is kept at a fixed end. A condition
|
|
187
186
|
on its roles holds when one pairing of the Edge's two ends with its two roles meets the whole
|
|
@@ -259,10 +258,20 @@ const second = first.next
|
|
|
259
258
|
: undefined
|
|
260
259
|
```
|
|
261
260
|
|
|
261
|
+
`query.all(query, input, { as, max })` reads every row of a page Query, page after page, and
|
|
262
|
+
answers the rows of its `output`; past `max` rows, it raises `TOO_MANY` as `all({ max })` does.
|
|
263
|
+
Each page is a read of its own, at its own snapshot and within its own bounds, and asks for no more
|
|
264
|
+
rows than `max` leaves, plus one:
|
|
265
|
+
|
|
266
|
+
```ts
|
|
267
|
+
const titles = await query.all(articleTitles, undefined, { as: 'caller', max: 5_000 })
|
|
268
|
+
```
|
|
269
|
+
|
|
262
270
|
A durable Workflow reads in a Step, as its executor:
|
|
263
271
|
`step.query('load-article', articleById, input.article, { as: 'executor' })`. The output is
|
|
264
|
-
journaled, and a replay returns it. A `QueryError` other than `REFUSED
|
|
265
|
-
|
|
272
|
+
journaled, and a replay returns it. A `QueryError` other than `REFUSED` fails the Step at once,
|
|
273
|
+
and a replay throws it again; so does the `TypeError` of an undeclared crossing (S12) a journal
|
|
274
|
+
holds. A Step reads as the Domain itself, which S12 does not check. A `REFUSED` read
|
|
266
275
|
is a failed attempt like any Kernel refusal: a permanent one exhausts the Step at once, and a
|
|
267
276
|
stale snapshot spends no attempt. An inline Workflow calls `query(query, input, { as })` from its
|
|
268
277
|
context, as an Action does, inside a named `step.run`.
|
|
@@ -277,7 +286,7 @@ of that code:
|
|
|
277
286
|
| `NOT_FOUND` | A root `get` found nothing. | `class`; `target` when the read named one |
|
|
278
287
|
| `NOT_READABLE` | `get` or `find` met a fact the reader may not read. | `class`; `id`, a Node's id or an Edge's key |
|
|
279
288
|
| `INTEGRITY` | A relation's `get` found none, or a second row came where one is allowed. | `relation`; `parent` for a relation; `found: 0 \| 2` |
|
|
280
|
-
| `TOO_MANY` | Past a verb's `max
|
|
289
|
+
| `TOO_MANY` | Past a verb's `max` or `query.all`'s, a verb bound of 83,332, the Query's 100,000 rows or its 32 reads; or an answer past the bytes one response may carry. | `limit: 'max' \| 'rows' \| 'reads' \| 'bytes'`; `bound` |
|
|
281
290
|
| `REFUSED` | The Kernel refused the read. | `kernelCode`; `retryable`, whether a retry may succeed |
|
|
282
291
|
| `INPUT_INVALID` | The SDK or the Kernel refused the document the Query built, before reading anything. | `kernelCode`, `phase` and `path` when the Kernel names them; `limit: 'in'` for an `in` past 16 values |
|
|
283
292
|
| `OUTDATED` | The Host's Registry does not match the Domain's build. | `kernelCode: 'QUERY_EXPECTATION_MISMATCH'` |
|
|
@@ -327,17 +336,25 @@ Before a step sends anything, the SDK checks:
|
|
|
327
336
|
the read raises `TOO_MANY`. An `in` takes at most 16 values; past them, it raises
|
|
328
337
|
`INPUT_INVALID`. Fewer than 2 or more than 8 steps do not compile, and `steps` throws a
|
|
329
338
|
`TypeError` when `build` calls it.
|
|
330
|
-
- **Requirements (S12).** A
|
|
331
|
-
|
|
332
|
-
|
|
333
|
-
|
|
339
|
+
- **Requirements (S12).** A read `{ as: 'caller' }` answers only what both the caller and the
|
|
340
|
+
Domain may observe, and leaves out the rest without saying so. Of a Class of a direct
|
|
341
|
+
dependency whose read and traverse rules both admit only some callers, a relation that crosses
|
|
342
|
+
it needs `read` or `traverse` on it in the Domain's `requirements({ classes })`. Of one whose
|
|
343
|
+
read rule admits only some callers, a relation's condition that tests one of its values needs
|
|
344
|
+
`read` on it: the Kernel drops what that test cannot decide. Otherwise the call throws a
|
|
345
|
+
`TypeError` naming the Query, the relation and the requirement to add. A rule that admits every
|
|
346
|
+
caller (`true`, or none) needs nothing. A requirement covers its own Class only, as the Kernel's
|
|
347
|
+
grants do; a Class a relation reaches stands for each concrete Class under it, itself when
|
|
348
|
+
concrete. Roots, Kernel Classes and the Domain's own Classes need nothing. A read
|
|
349
|
+
`{ as: 'executor' }` is the Domain's own, which no requirement changes: it is not checked. A
|
|
334
350
|
relation an empty list folds away is checked as if the list were not empty. A condition the
|
|
335
351
|
input leaves unbuilt, such as a falsy `where` entry or an `undefined` facet, is not checked.
|
|
336
352
|
|
|
337
|
-
`checkQuery(query, sampleInput, { domain })` from `@astrale-os/sdk/testing` runs both
|
|
338
|
-
a test, without a Kernel, on the first step it builds for its sample input. Give it an
|
|
339
|
-
builds every optional condition, and test later steps through a call. Given the
|
|
340
|
-
definition it checks S12
|
|
353
|
+
`checkQuery(query, sampleInput, { domain, as? })` from `@astrale-os/sdk/testing` runs both
|
|
354
|
+
checks in a test, without a Kernel, on the first step it builds for its sample input. Give it an
|
|
355
|
+
input that builds every optional condition, and test later steps through a call. Given the
|
|
356
|
+
Domain's definition it checks S12 as a read for the caller is checked; `as: 'executor'` and the
|
|
357
|
+
Schema alone skip S12.
|
|
341
358
|
|
|
342
359
|
Neither check sees an answer's size. One answer is bounded in bytes, 16 MiB by default, by the Host
|
|
343
360
|
that sends it and by the Kernel client that receives it (`maximumResponseBytes`). Over HTTP, past
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@astrale-os/sdk",
|
|
3
|
-
"version": "0.6.0-beta.
|
|
3
|
+
"version": "0.6.0-beta.51",
|
|
4
4
|
"description": "Schema-first SDK for defining, composing, and deploying Astrale domains",
|
|
5
5
|
"keywords": [
|
|
6
6
|
"astrale",
|
|
@@ -275,11 +275,11 @@
|
|
|
275
275
|
"@astrale-os/ox": "0.1.4",
|
|
276
276
|
"@astrale/commitlint-config": "npm:@jsr/astrale__commitlint-config@~2.0.5",
|
|
277
277
|
"@astrale/typescript-config": "npm:@jsr/astrale__typescript-config@~2.0.0",
|
|
278
|
-
"@cloudflare/workers-types": "^5.
|
|
278
|
+
"@cloudflare/workers-types": "^5.20261023.1",
|
|
279
279
|
"@commitlint/cli": "~21.2.2",
|
|
280
280
|
"@commitlint/config-conventional": "~21.2.2",
|
|
281
281
|
"@hono/node-server": "^2.1.1",
|
|
282
|
-
"@hono/node-server-v1": "npm:@hono/node-server@1.19.
|
|
282
|
+
"@hono/node-server-v1": "npm:@hono/node-server@1.19.10",
|
|
283
283
|
"@restatedev/restate-sdk": "1.17.0",
|
|
284
284
|
"@restatedev/restate-sdk-cloudflare-workers": "1.17.0",
|
|
285
285
|
"@types/cross-spawn": "6.0.6",
|
|
@@ -288,12 +288,12 @@
|
|
|
288
288
|
"husky": "~9.1.7",
|
|
289
289
|
"lint-staged": "~17.3.0",
|
|
290
290
|
"mermaid": "^11.16.1",
|
|
291
|
-
"miniflare": "5.
|
|
292
|
-
"oxfmt": "0.
|
|
291
|
+
"miniflare": "5.20261023.0-beta",
|
|
292
|
+
"oxfmt": "0.67.0",
|
|
293
293
|
"oxlint": "1.78.0",
|
|
294
294
|
"preact": "^10.29.8",
|
|
295
295
|
"tsx": "^4.23.12",
|
|
296
|
-
"vite": "^8.2.
|
|
296
|
+
"vite": "^8.2.4",
|
|
297
297
|
"vitest": "^5.0.1",
|
|
298
298
|
"yaml": "^2.9.0",
|
|
299
299
|
"zod": "4.4.3"
|