@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.
@@ -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' } })` | `.pick()` |
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 left out, because the reader may not read its Node, its Edge or an Edge root's end read as
103
- values, still counts as read. So `rows` may be short or empty while `more` is true or `next` is
104
- present, `first()` may answer `undefined` with a readable row behind it, and `all({ max })` raises
105
- `TOO_MANY` past `max` rows read, however few it would answer.
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 ends as references,
201
- so they are not facts the row reads; its Edge still 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.
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, or its answer leaves out a row's Class. | `feature: 'v7' \| 'classes'` |
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, a sub-tree at any depth | One step per level reads the next with `id.in`, up to 8 steps. |
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. Each verb takes `{ name }` last, and a
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.66",
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.44",
266
- "@astrale-os/kernel-core": "1.0.0-beta.41",
267
- "@astrale-os/kernel-dsl": "1.0.0-beta.29",
268
- "@astrale-os/kernel-protocol": "1.0.0-beta.41",
269
- "@astrale-os/kernel-server": "1.0.0-beta.41",
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",