@astrale-os/sdk 0.6.0-beta.66 → 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/query/execution/crossings.js +6 -1
- package/dist/application/query/execution/error.d.ts +5 -2
- package/dist/application/query/execution/error.js +3 -1
- package/dist/application/query/execution/rows.d.ts +4 -1
- package/dist/application/query/execution/rows.js +30 -19
- package/dist/application/query/execution/run.js +9 -0
- package/dist/application/query/handles/handles.d.ts +49 -20
- 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 +8 -0
- package/dist/application/query/language/query.d.ts +8 -1
- package/dist/platform/schema/kernel-compiled.d.ts +1 -1
- package/dist/platform/schema/kernel-compiled.js +1 -1
- package/docs/legacy/query-v6.md +1 -1
- package/docs/queries.md +39 -10
- 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
|
@@ -99,10 +99,16 @@ 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
|
|
103
|
-
|
|
104
|
-
|
|
105
|
-
`
|
|
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.
|
|
106
112
|
|
|
107
113
|
### Conditions
|
|
108
114
|
|
|
@@ -169,6 +175,27 @@ Edge's slug as `$edge.$slug` when it has one. The Edge is then a fact the row re
|
|
|
169
175
|
may not read it, the row is left out, `get` and `find` raise `NOT_READABLE`, and `.includeWithheld()`
|
|
170
176
|
keeps the row with `$edge` as `{ $class, $slug, $withheld }`.
|
|
171
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'`.
|
|
198
|
+
|
|
172
199
|
`.with((a) => ({ name: read }))` adds each relation's answer to the row under the name given. A
|
|
173
200
|
name a row already carries does not compile, and neither does a `.with` that reads another root:
|
|
174
201
|
read it as a facet of the Query.
|
|
@@ -197,8 +224,8 @@ of them, the row is left out, and `get` and `find` raise `NOT_READABLE` naming t
|
|
|
197
224
|
unread: the Edge, then the source, then the target. `.includeWithheld()` keeps the row: one whose
|
|
198
225
|
Edge is unread as `{ $class, $source, $target, $slug?, $withheld }`, with no ends, and any other
|
|
199
226
|
with the Edge's values and each unread end as `{ id, $class, $withheld }`, so a kept row's end is
|
|
200
|
-
narrowed before its values are read. An Edge root read with `.ref()` reads its
|
|
201
|
-
so
|
|
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.
|
|
202
229
|
|
|
203
230
|
An undirected Edge's ends have no order: neither of its roles is kept at a fixed end. A condition
|
|
204
231
|
on its roles holds when one pairing of the Edge's two ends with its two roles meets the whole
|
|
@@ -308,13 +335,13 @@ of that code:
|
|
|
308
335
|
| `REFUSED` | The Kernel refused the read. | `kernelCode`; `retryable`, whether a retry may succeed |
|
|
309
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 |
|
|
310
337
|
| `OUTDATED` | The Host's Registry does not match the Domain's build. | `kernelCode: 'QUERY_EXPECTATION_MISMATCH'` |
|
|
311
|
-
| `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'` |
|
|
312
339
|
|
|
313
340
|
`isQueryError(error, code?)` recognizes one.
|
|
314
341
|
|
|
315
342
|
A `QueryError` an Action or an inline Workflow does not catch reaches its caller as follows:
|
|
316
343
|
|
|
317
|
-
- 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
|
|
318
345
|
`kernelCode`, `TOO_MANY` past the Host's bytes) reaches it as that refusal: the Kernel's public
|
|
319
346
|
code, message and data. A Kernel code outside the public codes reaches it as
|
|
320
347
|
`BACKEND_UNAVAILABLE`.
|
|
@@ -405,7 +432,7 @@ root `id.in`, the SDK never splits a read behind its author.
|
|
|
405
432
|
| --- | --- |
|
|
406
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`. |
|
|
407
434
|
| Two parts of a pattern meeting at one Node | Read both with `.with`, compare in `output`. |
|
|
408
|
-
| 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. |
|
|
409
436
|
| Sums, averages, groups | Read the values with `all({ max })`, compute in `output`. |
|
|
410
437
|
| Case-insensitive search, locale sorting | A normalized Property the Domain writes, or filter and sort in `output`. |
|
|
411
438
|
| Several unrelated lists | Facets of one Query, each read at its own snapshot. |
|
|
@@ -471,7 +498,9 @@ canonical v7 Query. `mutation.expect.none(range)`, `expect.exists(range)`,
|
|
|
471
498
|
`expect.count(range, n | { atLeast?, atMost? })` or `expect.unchanged(range, ids)`. The Kernel
|
|
472
499
|
decides the guard with the Mutation, on the range's Classes and `where`, and for `unchanged` its
|
|
473
500
|
`orderBy`. A read (`first`, `exists`, `count`…) and a rendered set (`with`, `ref`) are refused:
|
|
474
|
-
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
|
|
475
504
|
refusal carries the failed precondition's name as `failure.precondition`.
|
|
476
505
|
|
|
477
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",
|