@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/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.52",
|
|
4
4
|
"description": "Schema-first SDK for defining, composing, and deploying Astrale domains",
|
|
5
5
|
"keywords": [
|
|
6
6
|
"astrale",
|
|
@@ -258,11 +258,11 @@
|
|
|
258
258
|
"registry": "https://registry.npmjs.org/"
|
|
259
259
|
},
|
|
260
260
|
"dependencies": {
|
|
261
|
-
"@astrale-os/kernel-client": "1.0.0-beta.
|
|
262
|
-
"@astrale-os/kernel-core": "1.0.0-beta.
|
|
263
|
-
"@astrale-os/kernel-dsl": "1.0.0-beta.
|
|
264
|
-
"@astrale-os/kernel-protocol": "1.0.0-beta.
|
|
265
|
-
"@astrale-os/kernel-server": "1.0.0-beta.
|
|
261
|
+
"@astrale-os/kernel-client": "1.0.0-beta.36",
|
|
262
|
+
"@astrale-os/kernel-core": "1.0.0-beta.33",
|
|
263
|
+
"@astrale-os/kernel-dsl": "1.0.0-beta.21",
|
|
264
|
+
"@astrale-os/kernel-protocol": "1.0.0-beta.33",
|
|
265
|
+
"@astrale-os/kernel-server": "1.0.0-beta.33",
|
|
266
266
|
"@lucide/icons": "1.34.0",
|
|
267
267
|
"@typescript/native-preview": "7.0.0-dev.20260707.2",
|
|
268
268
|
"cross-spawn": "7.0.6",
|
|
@@ -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"
|