@astrale-os/sdk 0.6.0-beta.63 → 0.6.0-beta.65
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/answer/answer.d.ts +6 -2
- package/dist/application/query/execution/rows.d.ts +1 -1
- package/dist/application/query/execution/rows.js +19 -5
- package/dist/application/query/handles/handles.d.ts +1 -1
- 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 +11 -6
- package/docs/queries.md +7 -4
- package/package.json +1 -1
|
@@ -9,7 +9,7 @@
|
|
|
9
9
|
* carries no Class, so a value is typed by its key alone; a Node item carries its Class (K-C),
|
|
10
10
|
* which a Kernel before K-C leaves out.
|
|
11
11
|
*/
|
|
12
|
-
import type { EdgeKey } from '../../../platform/graph/edge/index.js';
|
|
12
|
+
import type { EdgeKey, EdgeSlug } from '../../../platform/graph/edge/index.js';
|
|
13
13
|
import type { NodeId } from '../../../platform/graph/node/index.js';
|
|
14
14
|
import type { QueryPropertyKey, QueryPropertyValues, QueryRendering } from '../language/query.js';
|
|
15
15
|
/** On request (W8): the roots the caller's view cannot decide, up to the fold's bound. */
|
|
@@ -82,9 +82,13 @@ export type QueryRootItem<R> = R extends {
|
|
|
82
82
|
};
|
|
83
83
|
readonly branches: {};
|
|
84
84
|
};
|
|
85
|
-
/**
|
|
85
|
+
/**
|
|
86
|
+
* One fact a list renders as values: its readable values and the keys it withholds (R9), and an
|
|
87
|
+
* Edge's slug when it has one.
|
|
88
|
+
*/
|
|
86
89
|
export interface QueryFact<Source> {
|
|
87
90
|
readonly fact: NodeId | EdgeKey;
|
|
91
|
+
readonly slug?: EdgeSlug;
|
|
88
92
|
/** By Property key; a key the Domain does not define may appear (a newer Schema). */
|
|
89
93
|
readonly values: QueryPropertyValues<Source>;
|
|
90
94
|
readonly withheld: readonly QueryPropertyKey<Source>[];
|
|
@@ -28,7 +28,7 @@ export declare class Renderer {
|
|
|
28
28
|
constructor(query: string, model: Model, answer: QueryListAnswer<unknown, unknown>);
|
|
29
29
|
/** A Node row, or `undefined` when the reader may not read it and the read does not keep it. */
|
|
30
30
|
node(item: Item, pattern: Pattern): Json | undefined;
|
|
31
|
-
/** An Edge root row: its identity, its values and both ends
|
|
31
|
+
/** An Edge root row: its identity, its slug and values when read as values, and both ends. */
|
|
32
32
|
edge(item: Item, plan: EdgeRootPlan): Json | undefined;
|
|
33
33
|
/** The rows of a root list, Node or Edge, leaving out what the reader may not read. */
|
|
34
34
|
rootRows(items: readonly Item[], root: NodeRootPlan | EdgeRootPlan): readonly Json[];
|
|
@@ -97,14 +97,23 @@ export class Renderer {
|
|
|
97
97
|
row.$edge = this.#edgeValues(item.edge, edge);
|
|
98
98
|
return freeze(row);
|
|
99
99
|
}
|
|
100
|
-
/**
|
|
100
|
+
/**
|
|
101
|
+
* What `.withEdge()` adds: the Edge's Class, and its slug with its values or the names it
|
|
102
|
+
* withholds.
|
|
103
|
+
*/
|
|
101
104
|
#edgeValues(edge, select) {
|
|
102
105
|
if (select === 'reference')
|
|
103
106
|
return freeze({ $class: edge.class });
|
|
104
107
|
const c = this.#known(edge.class);
|
|
108
|
+
const named = { $class: edge.class, ...this.#slug(edge) };
|
|
105
109
|
if (this.#withheld(edge))
|
|
106
|
-
return freeze({
|
|
107
|
-
return freeze({
|
|
110
|
+
return freeze({ ...named, $withheld: this.#names(c) });
|
|
111
|
+
return freeze({ ...named, ...this.#values(edge, c, NO_TAKEN) });
|
|
112
|
+
}
|
|
113
|
+
/** The slug the Kernel gives an Edge it renders as values, when the Edge has one. */
|
|
114
|
+
#slug(edge) {
|
|
115
|
+
const slug = this.#fact(edge)?.slug;
|
|
116
|
+
return slug === undefined ? {} : { $slug: slug };
|
|
108
117
|
}
|
|
109
118
|
#known(key) {
|
|
110
119
|
try {
|
|
@@ -114,10 +123,15 @@ export class Renderer {
|
|
|
114
123
|
return undefined;
|
|
115
124
|
}
|
|
116
125
|
}
|
|
117
|
-
/** An Edge root row: its identity, its values and both ends
|
|
126
|
+
/** An Edge root row: its identity, its slug and values when read as values, and both ends. */
|
|
118
127
|
edge(item, plan) {
|
|
119
128
|
const key = item.fact;
|
|
120
|
-
const identity = {
|
|
129
|
+
const identity = {
|
|
130
|
+
$class: key.class,
|
|
131
|
+
$source: key.source,
|
|
132
|
+
$target: key.target,
|
|
133
|
+
...(plan.select === 'value' ? this.#slug(key) : {}),
|
|
134
|
+
};
|
|
121
135
|
const c = this.#known(key.class);
|
|
122
136
|
if (this.#withheld(key)) {
|
|
123
137
|
if (!plan.withheld)
|
|
@@ -159,7 +159,7 @@ export interface RelSet<S, K extends string, E extends string, W, M extends Rend
|
|
|
159
159
|
where<const R extends Conditions>(conditions: (node: NodeHandle<S, K>, edge: EdgeHandle<S, E>) => R): RelSet<S, Narrow<K, R>, E, W, M, H>;
|
|
160
160
|
orderBy(keys: (node: NodeHandle<S, K>, edge: EdgeHandle<S, E>) => Ordering): RelSet<S, K, E, W, M, H>;
|
|
161
161
|
with<const X extends Withs>(relations: (node: NodeHandle<S, K>) => X & WithCheck<S, K, W, X>): RelSet<S, K, E, W & Answers<X>, M, H>;
|
|
162
|
-
/** Each row gains `$edge`: the Edge's Class and Properties. */
|
|
162
|
+
/** Each row gains `$edge`: the Edge's Class, its slug when it has one, and its Properties. */
|
|
163
163
|
withEdge(): RelSet<S, K, E, W & {
|
|
164
164
|
readonly $edge: EdgeValues<S, E>;
|
|
165
165
|
}, M, H>;
|
|
@@ -3,18 +3,19 @@ import type { AnyResolvedClass, Domain } from '../../../platform/schema/index.js
|
|
|
3
3
|
export declare const NODE_ROOT = "kernel.astrale.ai:class.Node";
|
|
4
4
|
/**
|
|
5
5
|
* Names a Node handle owns (`HandleMembers`): a Property of the same name goes under `$prop`. The
|
|
6
|
-
* list is frozen, as `SDK_KEYS` is
|
|
6
|
+
* list is frozen, as `SDK_KEYS` is: a name added to either moves the Properties or the owner group
|
|
7
|
+
* of that name, in every Domain that has one.
|
|
7
8
|
*/
|
|
8
9
|
export declare const HANDLE_MEMBERS: ReadonlySet<string>;
|
|
9
10
|
/** The group of the Properties whose name a handle member, a row key or an Edge role takes. */
|
|
10
11
|
export declare const PROP_GROUP = "$prop";
|
|
11
12
|
/**
|
|
12
13
|
* The keys the SDK writes on rows besides `id` (`SdkKeys`), all named with `$`: `$class`, `$edge`
|
|
13
|
-
* on a row read `.withEdge()`, `$
|
|
14
|
-
* the reader may not read, and the `$prop`
|
|
15
|
-
* goes under `$` and that name (`ownerGroup`).
|
|
14
|
+
* on a row read `.withEdge()`, `$slug` on an Edge read as values that has one, `$source` and
|
|
15
|
+
* `$target` on an Edge root's row, `$withheld` on a row the reader may not read, and the `$prop`
|
|
16
|
+
* group. Frozen; an owner group named as one of them goes under `$` and that name (`ownerGroup`).
|
|
16
17
|
*/
|
|
17
|
-
export declare const SDK_KEYS: readonly ['$class', '$edge', '$source', '$target', '$withheld', "$prop"];
|
|
18
|
+
export declare const SDK_KEYS: readonly ['$class', '$edge', '$slug', '$source', '$target', '$withheld', "$prop"];
|
|
18
19
|
/**
|
|
19
20
|
* Names a row owns (`RowKeys`): `id` and the SDK's keys. A Property named `id` goes under `$prop`;
|
|
20
21
|
* no Property name starts with `$`. Frozen as `HANDLE_MEMBERS` is.
|
|
@@ -7,18 +7,27 @@ const GENERIC = new Set([NODE_ROOT, 'kernel.astrale.ai:class.Identity']);
|
|
|
7
7
|
const TO_ONE = new Set(['0..1', '1']);
|
|
8
8
|
/**
|
|
9
9
|
* Names a Node handle owns (`HandleMembers`): a Property of the same name goes under `$prop`. The
|
|
10
|
-
* list is frozen, as `SDK_KEYS` is
|
|
10
|
+
* list is frozen, as `SDK_KEYS` is: a name added to either moves the Properties or the owner group
|
|
11
|
+
* of that name, in every Domain that has one.
|
|
11
12
|
*/
|
|
12
13
|
export const HANDLE_MEMBERS = new Set(['id', 'path', 'is', 'isExactly', 'via']);
|
|
13
14
|
/** The group of the Properties whose name a handle member, a row key or an Edge role takes. */
|
|
14
15
|
export const PROP_GROUP = '$prop';
|
|
15
16
|
/**
|
|
16
17
|
* The keys the SDK writes on rows besides `id` (`SdkKeys`), all named with `$`: `$class`, `$edge`
|
|
17
|
-
* on a row read `.withEdge()`, `$
|
|
18
|
-
* the reader may not read, and the `$prop`
|
|
19
|
-
* goes under `$` and that name (`ownerGroup`).
|
|
18
|
+
* on a row read `.withEdge()`, `$slug` on an Edge read as values that has one, `$source` and
|
|
19
|
+
* `$target` on an Edge root's row, `$withheld` on a row the reader may not read, and the `$prop`
|
|
20
|
+
* group. Frozen; an owner group named as one of them goes under `$` and that name (`ownerGroup`).
|
|
20
21
|
*/
|
|
21
|
-
export const SDK_KEYS = [
|
|
22
|
+
export const SDK_KEYS = [
|
|
23
|
+
'$class',
|
|
24
|
+
'$edge',
|
|
25
|
+
'$slug',
|
|
26
|
+
'$source',
|
|
27
|
+
'$target',
|
|
28
|
+
'$withheld',
|
|
29
|
+
PROP_GROUP,
|
|
30
|
+
];
|
|
22
31
|
/**
|
|
23
32
|
* Names a row owns (`RowKeys`): `id` and the SDK's keys. A Property named `id` goes under `$prop`;
|
|
24
33
|
* no Property name starts with `$`. Frozen as `HANDLE_MEMBERS` is.
|
|
@@ -3,6 +3,7 @@
|
|
|
3
3
|
* Class or any subclass the Domain can name (D6), and a Property whose name is taken goes under
|
|
4
4
|
* `$prop` (F6).
|
|
5
5
|
*/
|
|
6
|
+
import type { EdgeSlug } from '../../../platform/graph/edge/index.js';
|
|
6
7
|
import type { NodeId } from '../../../platform/graph/node/index.js';
|
|
7
8
|
import type { ClassOf, Cls, Layout, LayoutOf, PropNamesOf, RequiredEntry, SdkKeys, ValueOfEntry } from './domain.js';
|
|
8
9
|
import type { SourceKeys, SourceRole, TargetKeys, TargetRole } from './relations.js';
|
|
@@ -48,13 +49,17 @@ type EdgeIdentity<E> = {
|
|
|
48
49
|
};
|
|
49
50
|
/** An Edge row: its Class, both ends' ids and its Properties. */
|
|
50
51
|
export type EdgeRow<S, E> = E extends unknown ? EdgeIdentity<ClassOf<S, E>> & ValuesOf<S, E, never> : never;
|
|
51
|
-
/**
|
|
52
|
+
/** An Edge read as values: its slug, absent from an Edge without one and on a Host before beta.39. */
|
|
53
|
+
type Slugged = {
|
|
54
|
+
readonly $slug?: EdgeSlug;
|
|
55
|
+
};
|
|
56
|
+
/** What `.withEdge()` adds to a row under `$edge`: the Edge's Class, its slug and its Properties. */
|
|
52
57
|
export type EdgeValues<S, E> = E extends unknown ? {
|
|
53
58
|
readonly $class: ClassOf<S, E>;
|
|
54
|
-
} & ValuesOf<S, E, never> : never;
|
|
59
|
+
} & Slugged & ValuesOf<S, E, never> : never;
|
|
55
60
|
type Roles<S, E> = SourceRole<S, E> | TargetRole<S, E>;
|
|
56
|
-
/** An Edge row at the root: its values, and both ends' rows by role. */
|
|
57
|
-
export type EdgeRootRow<S, E> = E extends unknown ? EdgeIdentity<ClassOf<S, E>> & ValuesOf<S, E, Roles<S, E>> & {
|
|
61
|
+
/** An Edge row at the root: its slug, its values, and both ends' rows by role. */
|
|
62
|
+
export type EdgeRootRow<S, E> = E extends unknown ? EdgeIdentity<ClassOf<S, E>> & Slugged & ValuesOf<S, E, Roles<S, E>> & {
|
|
58
63
|
readonly [R in SourceRole<S, E>]: Row<S, SourceKeys<S, E>>;
|
|
59
64
|
} & {
|
|
60
65
|
readonly [R in TargetRole<S, E>]: Row<S, TargetKeys<S, E>>;
|
|
@@ -65,8 +70,8 @@ export type EdgeRootRef<S, E> = E extends unknown ? EdgeIdentity<ClassOf<S, E>>
|
|
|
65
70
|
} & {
|
|
66
71
|
readonly [R in TargetRole<S, E>]: Ref<S, TargetKeys<S, E>>;
|
|
67
72
|
} : never;
|
|
68
|
-
/** An Edge the reader may not read (`.includeWithheld()`). */
|
|
69
|
-
export type WithheldEdgeRow<S, E> = E extends unknown ? EdgeIdentity<ClassOf<S, E>> & {
|
|
73
|
+
/** An Edge the reader may not read (`.includeWithheld()`): its slug, which traversal discloses. */
|
|
74
|
+
export type WithheldEdgeRow<S, E> = E extends unknown ? EdgeIdentity<ClassOf<S, E>> & Slugged & {
|
|
70
75
|
readonly $withheld: readonly PropNamesOf<Cls<S, E>>[];
|
|
71
76
|
} : never;
|
|
72
77
|
/** An Edge's identity, as a Mutation or a guard names it. */
|
package/docs/queries.md
CHANGED
|
@@ -159,7 +159,8 @@ Class, or when the Edges listed leave it in different directions.
|
|
|
159
159
|
A relation reads with the root verbs, per parent row: `get`, `find`, `first`,
|
|
160
160
|
`first(n, { more: true })`, `all`, `count` and `exists`. A relation's `get` that finds none, or a second row, raises `INTEGRITY` naming the
|
|
161
161
|
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
|
|
162
|
+
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.
|
|
163
164
|
|
|
164
165
|
`.with((a) => ({ name: read }))` adds each relation's answer to the row under the name given. A
|
|
165
166
|
name a row already carries does not compile, and neither does a `.with` that reads another root:
|
|
@@ -174,12 +175,14 @@ member (`id`, `path`, `is`, `isExactly`, `via`) on handles, and an Edge's roles
|
|
|
174
175
|
the root. A Property named `path` is `row.path` on a row and `a.$prop.path` on a handle. These
|
|
175
176
|
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
177
|
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
|
|
178
|
+
`row.$record.title`. The SDK's row keys (`$class`, `$edge`, `$slug`, `$source`, `$target`, `$withheld`
|
|
179
|
+
and `$prop`) are frozen too, and an owner group that would take one gets one more `$`: an owner named
|
|
179
180
|
`Class` groups under `$$class`.
|
|
180
181
|
|
|
181
182
|
An Edge read at the root answers rows of `{ $class, $source, $target }`, the Edge's Properties,
|
|
182
|
-
and both ends' rows under their roles.
|
|
183
|
+
and both ends' rows under their roles. An Edge that has a slug carries it as `$slug`, withheld or
|
|
184
|
+
not; an Edge read with `.ref()` carries none. A Host older than Kernel beta.39 gives no slug, so
|
|
185
|
+
there a missing `$slug` or `$edge.$slug` does not tell that the Edge has none. `edgeKey(row)` gives the `{ source, target, class }` a
|
|
183
186
|
Mutation or a guard names an Edge by. An Edge root's `get()`, `find()` and `exists()` take no id.
|
|
184
187
|
|
|
185
188
|
An undirected Edge's ends have no order: neither of its roles is kept at a fixed end. A condition
|