@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.
@@ -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
- /** One fact a list renders as values: its readable values and the keys it withholds (R9). */
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 by role. */
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
- /** What `.withEdge()` adds: the Edge's Class, and its values or the names it withholds. */
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({ $class: edge.class, $withheld: this.#names(c) });
107
- return freeze({ $class: edge.class, ...this.#values(edge, c, NO_TAKEN) });
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 by role. */
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 = { $class: key.class, $source: key.source, $target: key.target };
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, so no SDK release moves a Property or an owner group.
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()`, `$source` and `$target` on an Edge root's row, `$withheld` on a row
14
- * the reader may not read, and the `$prop` group. Frozen; an owner group named as one of them
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, so no SDK release moves a Property or an owner group.
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()`, `$source` and `$target` on an Edge root's row, `$withheld` on a row
18
- * the reader may not read, and the `$prop` group. Frozen; an owner group named as one of them
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 = ['$class', '$edge', '$source', '$target', '$withheld', PROP_GROUP];
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
- /** What `.withEdge()` adds to a row under `$edge`: the Edge's Class and its Properties. */
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` and
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. `edgeKey(row)` gives the `{ source, target, class }` a
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
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@astrale-os/sdk",
3
- "version": "0.6.0-beta.63",
3
+ "version": "0.6.0-beta.65",
4
4
  "description": "Schema-first SDK for defining, composing, and deploying Astrale domains",
5
5
  "keywords": [
6
6
  "astrale",