@astrale-os/sdk 0.6.0-beta.64 → 0.6.0-beta.66

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/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`: `TOO_MANY`. |
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,11 @@ 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.
106
+
102
107
  ### Conditions
103
108
 
104
109
  `where` takes one condition or a list, an implicit `and`. A falsy entry of the list is skipped, so
@@ -159,7 +164,10 @@ Class, or when the Edges listed leave it in different directions.
159
164
  A relation reads with the root verbs, per parent row: `get`, `find`, `first`,
160
165
  `first(n, { more: true })`, `all`, `count` and `exists`. A relation's `get` that finds none, or a second row, raises `INTEGRITY` naming the
161
166
  relation. A relation also takes `where`, `orderBy`, `with`, `ref`, `includeWithheld`, `distinct`
162
- and `withEdge()`, which adds the Edge's Class and Properties to each row under `$edge`.
167
+ and `withEdge()`, which adds the Edge's Class and Properties to each row under `$edge`, and the
168
+ Edge's slug as `$edge.$slug` when it has one. The Edge is then a fact the row reads: when the reader
169
+ may not read it, the row is left out, `get` and `find` raise `NOT_READABLE`, and `.includeWithheld()`
170
+ keeps the row with `$edge` as `{ $class, $slug, $withheld }`.
163
171
 
164
172
  `.with((a) => ({ name: read }))` adds each relation's answer to the row under the name given. A
165
173
  name a row already carries does not compile, and neither does a `.with` that reads another root:
@@ -174,14 +182,24 @@ member (`id`, `path`, `is`, `isExactly`, `via`) on handles, and an Edge's roles
174
182
  the root. A Property named `path` is `row.path` on a row and `a.$prop.path` on a handle. These
175
183
  names are frozen, and no Property name starts with `$`, so a Property never moves. Two Properties of one name that two parent Classes declare, when the Class
176
184
  declares none of its own, each go under `$` and their owner's name in lower camel case:
177
- `row.$record.title`. The SDK's row keys (`$class`, `$edge`, `$source`, `$target`, `$withheld` and
178
- `$prop`) are frozen too, and an owner group that would take one gets one more `$`: an owner named
185
+ `row.$record.title`. The SDK's row keys (`$class`, `$edge`, `$slug`, `$source`, `$target`, `$withheld`
186
+ and `$prop`) are frozen too, and an owner group that would take one gets one more `$`: an owner named
179
187
  `Class` groups under `$$class`.
180
188
 
181
189
  An Edge read at the root answers rows of `{ $class, $source, $target }`, the Edge's Properties,
182
- and both ends' rows under their roles. `edgeKey(row)` gives the `{ source, target, class }` a
190
+ and both ends' rows under their roles. An Edge that has a slug carries it as `$slug`, withheld or
191
+ not; an Edge read with `.ref()` carries none. A Host older than Kernel beta.39 gives no slug, so
192
+ there a missing `$slug` or `$edge.$slug` does not tell that the Edge has none. `edgeKey(row)` gives the `{ source, target, class }` a
183
193
  Mutation or a guard names an Edge by. An Edge root's `get()`, `find()` and `exists()` take no id.
184
194
 
195
+ Each end read as values is a fact the row reads, as the Edge is. When the reader may not read one
196
+ of them, the row is left out, and `get` and `find` raise `NOT_READABLE` naming the first fact
197
+ unread: the Edge, then the source, then the target. `.includeWithheld()` keeps the row: one whose
198
+ Edge is unread as `{ $class, $source, $target, $slug?, $withheld }`, with no ends, and any other
199
+ 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.
202
+
185
203
  An undirected Edge's ends have no order: neither of its roles is kept at a fixed end. A condition
186
204
  on its roles holds when one pairing of the Edge's two ends with its two roles meets the whole
187
205
  condition, each end a Node its role accepts:
@@ -259,9 +277,9 @@ const second = first.next
259
277
  ```
260
278
 
261
279
  `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:
280
+ answers the rows of its `output`; past `max` of those rows, it raises `TOO_MANY`. Unlike
281
+ `all({ max })`, it does not count a row a page leaves out. Each page is a read of its own, at its
282
+ own snapshot and within its own bounds, and asks for no more rows than `max` leaves, plus one:
265
283
 
266
284
  ```ts
267
285
  const titles = await query.all(articleTitles, undefined, { as: 'caller', max: 5_000 })
@@ -348,8 +366,9 @@ Before a step sends anything, the SDK checks:
348
366
  grants do; a Class a relation reaches stands for each concrete Class under it, itself when
349
367
  concrete. Roots, Kernel Classes and the Domain's own Classes need nothing. A read
350
368
  `{ as: 'executor' }` is the Domain's own, which no requirement changes: it is not checked. A
351
- relation an empty list folds away is checked as if the list were not empty. A condition the
352
- input leaves unbuilt, such as a falsy `where` entry or an `undefined` facet, is not checked.
369
+ relation the read leaves out because an empty list decides its condition is checked as if the
370
+ list were not empty. A condition the input leaves unbuilt, such as a falsy `where` entry or an
371
+ `undefined` facet, is not checked.
353
372
 
354
373
  `checkQuery(query, sampleInput, { domain, as? })` from `@astrale-os/sdk/testing` runs both
355
374
  checks in a test, without a Kernel, on the first step it builds for its sample input. Give it an
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@astrale-os/sdk",
3
- "version": "0.6.0-beta.64",
3
+ "version": "0.6.0-beta.66",
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.43",
266
- "@astrale-os/kernel-core": "1.0.0-beta.40",
267
- "@astrale-os/kernel-dsl": "1.0.0-beta.28",
268
- "@astrale-os/kernel-protocol": "1.0.0-beta.40",
269
- "@astrale-os/kernel-server": "1.0.0-beta.40",
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",
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",