@astrale-os/sdk 0.6.0-beta.65 → 0.6.0-beta.67
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/dist/application/action/context.d.ts +3 -2
- package/dist/application/mutation/authoring/properties.d.ts +2 -3
- package/dist/application/mutation/authoring/properties.js +9 -32
- package/dist/application/query/answer/answer.d.ts +5 -2
- package/dist/application/query/execution/crossings.js +6 -1
- package/dist/application/query/execution/error.d.ts +9 -3
- package/dist/application/query/execution/error.js +3 -1
- package/dist/application/query/execution/rows.d.ts +14 -8
- package/dist/application/query/execution/rows.js +72 -46
- package/dist/application/query/execution/run.d.ts +4 -3
- package/dist/application/query/execution/run.js +13 -3
- package/dist/application/query/handles/handles.d.ts +66 -23
- package/dist/application/query/handles/model.d.ts +6 -0
- package/dist/application/query/handles/model.js +10 -0
- package/dist/application/query/handles/plan.d.ts +6 -1
- package/dist/application/query/handles/reads.d.ts +7 -0
- package/dist/application/query/handles/reads.js +98 -16
- package/dist/application/query/handles/relations.d.ts +31 -3
- package/dist/application/query/handles/rows.d.ts +27 -8
- package/dist/application/query/language/query.d.ts +9 -2
- package/dist/platform/schema/kernel-compiled.d.ts +1 -1
- package/dist/platform/schema/kernel-compiled.js +2 -2
- package/docs/legacy/query-v6.md +1 -1
- package/docs/queries.md +56 -11
- package/package.json +6 -6
package/docs/legacy/query-v6.md
CHANGED
|
@@ -47,7 +47,7 @@ const tasks = await query(openTasks)
|
|
|
47
47
|
| `Query.from({ edges: [assigned_to] })` | `d.assigned_to` |
|
|
48
48
|
| `.filter({ predicate: Property(key).equals(v) })` | `.where((t) => t.status.eq(v))` |
|
|
49
49
|
| `.expand({ via, direction })` | `.via(edge, { direction })`, or a named to-one relation: `t.assignee` |
|
|
50
|
-
| `.select({ kind: 'nodes', projection: { kind: 'reference' } })` | `.
|
|
50
|
+
| `.select({ kind: 'nodes', projection: { kind: 'reference' } })` | `.ref()` |
|
|
51
51
|
| `page: { size }` | `.page({ max })`, called with `{ size, after }` |
|
|
52
52
|
| `pagination: { maximumPages }` | `.all({ max })` |
|
|
53
53
|
| `project(result)` | `output(results, input, { error, is })` |
|
package/docs/queries.md
CHANGED
|
@@ -87,7 +87,7 @@ relations with `with`, and ends with the verb that says how much it reads:
|
|
|
87
87
|
| `first(n)` | Up to `n` rows | |
|
|
88
88
|
| `first(n, { more: true })` | `{ rows, more }`, reading `n + 1` rows | |
|
|
89
89
|
| `page({ max })` | `{ rows, next? }`; only as a Query's single read | |
|
|
90
|
-
| `all({ max })` | Every row | Past `max
|
|
90
|
+
| `all({ max })` | Every row | Past `max` rows read: `TOO_MANY`. |
|
|
91
91
|
| `exists(id?)` | `boolean` | |
|
|
92
92
|
| `count({ upTo })` | `{ count, more }`; `more` says the count reached `upTo` | |
|
|
93
93
|
|
|
@@ -99,6 +99,17 @@ sends, use `find` and raise a declared error from `output` (see [Errors](#errors
|
|
|
99
99
|
`{ id, $class, $withheld }` naming the values withheld. `get` and `find` raise `NOT_READABLE` on
|
|
100
100
|
such a row, since it exists. `d.A.union(d.B)` reads the Nodes of both Classes.
|
|
101
101
|
|
|
102
|
+
A row reads the facts it renders as values: its Node, the Edge `.withEdge()` adds, an Edge root's
|
|
103
|
+
Edge and ends. A reference reads none: the Kernel answers one for every Node or Edge the reader
|
|
104
|
+
traverses, whether or not the reader may read it. So a row read `.ref()` is left out, and `get` and
|
|
105
|
+
`find` raise `NOT_READABLE` on it, only for an Edge `.withEdge()` adds, whatever another part of
|
|
106
|
+
the read renders of its Node. Its Node never carries `$withheld`, `.includeWithheld()` or not.
|
|
107
|
+
|
|
108
|
+
A row left out, because the reader may not read a fact it renders as values, still counts as
|
|
109
|
+
read. So `rows` may be short or empty while `more` is true or `next` is present, `first()` may
|
|
110
|
+
answer `undefined` with a readable row behind it, and `all({ max })` raises `TOO_MANY` past `max`
|
|
111
|
+
rows read, however few it would answer.
|
|
112
|
+
|
|
102
113
|
### Conditions
|
|
103
114
|
|
|
104
115
|
`where` takes one condition or a list, an implicit `and`. A falsy entry of the list is skipped, so
|
|
@@ -160,7 +171,30 @@ A relation reads with the root verbs, per parent row: `get`, `find`, `first`,
|
|
|
160
171
|
`first(n, { more: true })`, `all`, `count` and `exists`. A relation's `get` that finds none, or a second row, raises `INTEGRITY` naming the
|
|
161
172
|
relation. A relation also takes `where`, `orderBy`, `with`, `ref`, `includeWithheld`, `distinct`
|
|
162
173
|
and `withEdge()`, which adds the Edge's Class and Properties to each row under `$edge`, and the
|
|
163
|
-
Edge's slug as `$edge.$slug` when it has one.
|
|
174
|
+
Edge's slug as `$edge.$slug` when it has one. The Edge is then a fact the row reads: when the reader
|
|
175
|
+
may not read it, the row is left out, `get` and `find` raise `NOT_READABLE`, and `.includeWithheld()`
|
|
176
|
+
keeps the row with `$edge` as `{ $class, $slug, $withheld }`.
|
|
177
|
+
|
|
178
|
+
`.reachable()` follows a relation one Edge or more: the Nodes it reaches however far, read in one
|
|
179
|
+
snapshot and inside what the reader may traverse. `issue.parent.reachable()` reads every ancestor
|
|
180
|
+
of an Issue, and `folder.via(d.contains, { direction: 'outgoing' }).reachable()` a whole sub-tree.
|
|
181
|
+
Its rows are the Edges it follows, each once with the Node it reaches, or with `.distinct()` the
|
|
182
|
+
Nodes it reaches, each once however many routes reach them. The Node it starts from is among them
|
|
183
|
+
only when a cycle returns to it, and a cycle ends the walk. `where` still holds on each Edge
|
|
184
|
+
followed and on each Node reached; `reachable({ through: (n) => … })` holds on every Node a walk
|
|
185
|
+
passes through on its way, so a walk stops at a Node `through` does not keep, which it still
|
|
186
|
+
reaches. Every verb and every relation condition (`is`, `some`, `none`, `atLeast`…) reads the
|
|
187
|
+
relation so followed, and `.withEdge()` then names both ends of each Edge as `$edge.$source` and
|
|
188
|
+
`$edge.$target`, since its Edge leaves a Node the walk passed through, not the row's parent.
|
|
189
|
+
|
|
190
|
+
A relation is reachable only where a Class it reaches can start another of its Edges:
|
|
191
|
+
`issue.assignee.reachable()` does not compile, a Person being no source of `assigned_to`. Followed
|
|
192
|
+
`incident`, a walk reaches an Edge from both its ends, so it reads Nodes only: add `.distinct()`.
|
|
193
|
+
A walk of directed and undirected Edge Classes together, or of an undirected Edge whose roles
|
|
194
|
+
accept different Classes, takes `{ direction: 'incident' }`. A relation condition that walks is
|
|
195
|
+
written on a root the Query names by `id` or `path`, or in a `.with`: the Kernel refuses one
|
|
196
|
+
decided at every Node of a Class (`INPUT_INVALID`, naming the tier `unanchored`). A Host that
|
|
197
|
+
predates the member raises `UNSUPPORTED` with `feature: 'reachable'`.
|
|
164
198
|
|
|
165
199
|
`.with((a) => ({ name: read }))` adds each relation's answer to the row under the name given. A
|
|
166
200
|
name a row already carries does not compile, and neither does a `.with` that reads another root:
|
|
@@ -185,6 +219,14 @@ not; an Edge read with `.ref()` carries none. A Host older than Kernel beta.39 g
|
|
|
185
219
|
there a missing `$slug` or `$edge.$slug` does not tell that the Edge has none. `edgeKey(row)` gives the `{ source, target, class }` a
|
|
186
220
|
Mutation or a guard names an Edge by. An Edge root's `get()`, `find()` and `exists()` take no id.
|
|
187
221
|
|
|
222
|
+
Each end read as values is a fact the row reads, as the Edge is. When the reader may not read one
|
|
223
|
+
of them, the row is left out, and `get` and `find` raise `NOT_READABLE` naming the first fact
|
|
224
|
+
unread: the Edge, then the source, then the target. `.includeWithheld()` keeps the row: one whose
|
|
225
|
+
Edge is unread as `{ $class, $source, $target, $slug?, $withheld }`, with no ends, and any other
|
|
226
|
+
with the Edge's values and each unread end as `{ id, $class, $withheld }`, so a kept row's end is
|
|
227
|
+
narrowed before its values are read. An Edge root read with `.ref()` reads its Edge and its ends
|
|
228
|
+
as references, so none of them is a fact the row reads: its rows are never left out.
|
|
229
|
+
|
|
188
230
|
An undirected Edge's ends have no order: neither of its roles is kept at a fixed end. A condition
|
|
189
231
|
on its roles holds when one pairing of the Edge's two ends with its two roles meets the whole
|
|
190
232
|
condition, each end a Node its role accepts:
|
|
@@ -262,9 +304,9 @@ const second = first.next
|
|
|
262
304
|
```
|
|
263
305
|
|
|
264
306
|
`query.all(query, input, { as, max })` reads every row of a page Query, page after page, and
|
|
265
|
-
answers the rows of its `output`; past `max` rows, it raises `TOO_MANY
|
|
266
|
-
|
|
267
|
-
rows than `max` leaves, plus one:
|
|
307
|
+
answers the rows of its `output`; past `max` of those rows, it raises `TOO_MANY`. Unlike
|
|
308
|
+
`all({ max })`, it does not count a row a page leaves out. Each page is a read of its own, at its
|
|
309
|
+
own snapshot and within its own bounds, and asks for no more rows than `max` leaves, plus one:
|
|
268
310
|
|
|
269
311
|
```ts
|
|
270
312
|
const titles = await query.all(articleTitles, undefined, { as: 'caller', max: 5_000 })
|
|
@@ -293,13 +335,13 @@ of that code:
|
|
|
293
335
|
| `REFUSED` | The Kernel refused the read. | `kernelCode`; `retryable`, whether a retry may succeed |
|
|
294
336
|
| `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 |
|
|
295
337
|
| `OUTDATED` | The Host's Registry does not match the Domain's build. | `kernelCode: 'QUERY_EXPECTATION_MISMATCH'` |
|
|
296
|
-
| `UNSUPPORTED` | The Kernel does not serve Query v7,
|
|
338
|
+
| `UNSUPPORTED` | The Kernel does not serve Query v7, its answer leaves out a row's Class, or it does not follow a relation more than one Edge. | `feature: 'v7' \| 'classes' \| 'reachable'` |
|
|
297
339
|
|
|
298
340
|
`isQueryError(error, code?)` recognizes one.
|
|
299
341
|
|
|
300
342
|
A `QueryError` an Action or an inline Workflow does not catch reaches its caller as follows:
|
|
301
343
|
|
|
302
|
-
- One the Kernel refused (`REFUSED`, `OUTDATED`, `UNSUPPORTED` for `v7`, `INPUT_INVALID` with a
|
|
344
|
+
- One the Kernel refused (`REFUSED`, `OUTDATED`, `UNSUPPORTED` for `v7` or `reachable`, `INPUT_INVALID` with a
|
|
303
345
|
`kernelCode`, `TOO_MANY` past the Host's bytes) reaches it as that refusal: the Kernel's public
|
|
304
346
|
code, message and data. A Kernel code outside the public codes reaches it as
|
|
305
347
|
`BACKEND_UNAVAILABLE`.
|
|
@@ -351,8 +393,9 @@ Before a step sends anything, the SDK checks:
|
|
|
351
393
|
grants do; a Class a relation reaches stands for each concrete Class under it, itself when
|
|
352
394
|
concrete. Roots, Kernel Classes and the Domain's own Classes need nothing. A read
|
|
353
395
|
`{ as: 'executor' }` is the Domain's own, which no requirement changes: it is not checked. A
|
|
354
|
-
relation an empty list
|
|
355
|
-
input leaves unbuilt, such as a falsy `where` entry or an
|
|
396
|
+
relation the read leaves out because an empty list decides its condition is checked as if the
|
|
397
|
+
list were not empty. A condition the input leaves unbuilt, such as a falsy `where` entry or an
|
|
398
|
+
`undefined` facet, is not checked.
|
|
356
399
|
|
|
357
400
|
`checkQuery(query, sampleInput, { domain, as? })` from `@astrale-os/sdk/testing` runs both
|
|
358
401
|
checks in a test, without a Kernel, on the first step it builds for its sample input. Give it an
|
|
@@ -389,7 +432,7 @@ root `id.in`, the SDK never splits a read behind its author.
|
|
|
389
432
|
| --- | --- |
|
|
390
433
|
| A value compared with a parent's | A first step reads the parent and the next compares with its value; or read both and filter in `output`. |
|
|
391
434
|
| Two parts of a pattern meeting at one Node | Read both with `.with`, compare in `output`. |
|
|
392
|
-
| Ancestors
|
|
435
|
+
| Ancestors or a sub-tree ordered by depth, or cut at a depth | `.reachable()` reads them at any depth, in no order of depth; for a depth, one step per level reads the next with `id.in`, up to 8 steps. |
|
|
393
436
|
| Sums, averages, groups | Read the values with `all({ max })`, compute in `output`. |
|
|
394
437
|
| Case-insensitive search, locale sorting | A normalized Property the Domain writes, or filter and sort in `output`. |
|
|
395
438
|
| Several unrelated lists | Facets of one Query, each read at its own snapshot. |
|
|
@@ -455,7 +498,9 @@ canonical v7 Query. `mutation.expect.none(range)`, `expect.exists(range)`,
|
|
|
455
498
|
`expect.count(range, n | { atLeast?, atMost? })` or `expect.unchanged(range, ids)`. The Kernel
|
|
456
499
|
decides the guard with the Mutation, on the range's Classes and `where`, and for `unchanged` its
|
|
457
500
|
`orderBy`. A read (`first`, `exists`, `count`…) and a rendered set (`with`, `ref`) are refused:
|
|
458
|
-
their verb, size or rendering would not reach the guard.
|
|
501
|
+
their verb, size or rendering would not reach the guard. So is a range whose condition follows a
|
|
502
|
+
relation more than one Edge (`.reachable()`): the Kernel decides a guard inside the write, where it
|
|
503
|
+
walks no relation. Read the walk in a Query, and guard what it found. Each verb takes `{ name }` last, and a
|
|
459
504
|
refusal carries the failed precondition's name as `failure.precondition`.
|
|
460
505
|
|
|
461
506
|
A guard states what the Schema cannot: a condition across Nodes at commit, a count that no
|
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.67",
|
|
4
4
|
"description": "Schema-first SDK for defining, composing, and deploying Astrale domains",
|
|
5
5
|
"keywords": [
|
|
6
6
|
"astrale",
|
|
@@ -262,11 +262,11 @@
|
|
|
262
262
|
"registry": "https://registry.npmjs.org/"
|
|
263
263
|
},
|
|
264
264
|
"dependencies": {
|
|
265
|
-
"@astrale-os/kernel-client": "1.0.0-beta.
|
|
266
|
-
"@astrale-os/kernel-core": "1.0.0-beta.
|
|
267
|
-
"@astrale-os/kernel-dsl": "1.0.0-beta.
|
|
268
|
-
"@astrale-os/kernel-protocol": "1.0.0-beta.
|
|
269
|
-
"@astrale-os/kernel-server": "1.0.0-beta.
|
|
265
|
+
"@astrale-os/kernel-client": "1.0.0-beta.45",
|
|
266
|
+
"@astrale-os/kernel-core": "1.0.0-beta.42",
|
|
267
|
+
"@astrale-os/kernel-dsl": "1.0.0-beta.30",
|
|
268
|
+
"@astrale-os/kernel-protocol": "1.0.0-beta.42",
|
|
269
|
+
"@astrale-os/kernel-server": "1.0.0-beta.42",
|
|
270
270
|
"@lucide/icons": "1.34.0",
|
|
271
271
|
"@typescript/native-preview": "7.0.0-dev.20260707.2",
|
|
272
272
|
"cross-spawn": "7.0.6",
|