@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/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 +11 -4
- package/dist/application/query/execution/error.d.ts +4 -1
- package/dist/application/query/execution/rows.d.ts +11 -8
- package/dist/application/query/execution/rows.js +72 -43
- package/dist/application/query/execution/run.d.ts +4 -3
- package/dist/application/query/execution/run.js +4 -3
- package/dist/application/query/handles/handles.d.ts +21 -7
- package/dist/application/query/handles/model.d.ts +6 -5
- package/dist/application/query/handles/model.js +14 -5
- package/dist/application/query/handles/rows.d.ts +26 -10
- package/dist/application/query/language/query.d.ts +1 -1
- package/dist/platform/schema/kernel-compiled.d.ts +1 -1
- package/dist/platform/schema/kernel-compiled.js +2 -2
- package/docs/queries.md +29 -10
- package/package.json +6 -6
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,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`
|
|
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.
|
|
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
|
|
263
|
-
|
|
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
|
|
352
|
-
input leaves unbuilt, such as a falsy `where` entry or an
|
|
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.
|
|
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.
|
|
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.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",
|