@astrale-os/sdk 0.6.0-beta.41 → 0.6.0-beta.43

package/dist/application/query/handles/model.js

@@ -0,0 +1,246 @@
+import { load } from '@astrale-os/kernel-dsl/v1/compiled/generated';
+import { kernelCompiledSchema } from '../../../platform/schema/kernel-compiled.js';
+/** The key of the graph's root Class, which every Node Class satisfies. */
+export const NODE_ROOT = 'kernel.astrale.ai:class.Node';
+/** An end names its relation only if it accepts specific Classes (S2). */
+const GENERIC = new Set([NODE_ROOT, 'kernel.astrale.ai:class.Identity']);
+const TO_ONE = new Set(['0..1', '1']);
+/**
+ * Names a Node handle owns (`HandleMembers`): a Property of the same name goes under `$prop`. The
+ * list is frozen, as `SDK_KEYS` is, so no SDK release moves a Property or an owner group.
+ */
+export const HANDLE_MEMBERS = new Set(['id', 'path', 'is', 'isExactly', 'via']);
+/** The group of the Properties whose name a handle member, a row key or an Edge role takes. */
+export const PROP_GROUP = '$prop';
+/**
+ * The keys the SDK writes on rows besides `id` (`SdkKeys`), all named with `$`: `$class`, `$edge`
+ * on a row read `.withEdge()`, `$source` and `$target` on an Edge root's row, `$withheld` on a row
+ * the reader may not read, and the `$prop` group. Frozen; an owner group named as one of them
+ * goes under `$` and that name (`ownerGroup`).
+ */
+export const SDK_KEYS = ['$class', '$edge', '$source', '$target', '$withheld', PROP_GROUP];
+/**
+ * Names a row owns (`RowKeys`): `id` and the SDK's keys. A Property named `id` goes under `$prop`;
+ * no Property name starts with `$`. Frozen as `HANDLE_MEMBERS` is.
+ */
+export const ROW_KEYS = new Set(['id', ...SDK_KEYS]);
+const OWNER = /:class\.([^.]+)\.property\./;
+let kernel;
+/**
+ * The Kernel's Classes, realized once from its compiled Schema reduced to them: a Worker reaches
+ * them without the Kernel's builder or its Functions' value programs.
+ */
+export function kernelClasses() {
+    kernel ??= load(JSON.parse(kernelCompiledSchema))
+        .classes;
+    return kernel;
+}
+/** The Class model of one resolved Domain. */
+export class Model {
+    origin;
+    #byKey = new Map();
+    #edges = [];
+    #satisfied = new Map();
+    #ends = new Map();
+    #relations = new Map();
+    #layouts = new Map();
+    constructor(domain) {
+        this.origin = domain.origin;
+        const add = (c) => {
+            if (this.#byKey.has(c.key))
+                return;
+            this.#byKey.set(c.key, c);
+            if (c.kind === 'edge')
+                this.#edges.push(c);
+        };
+        Object.values(domain.classes).forEach(add);
+        for (const dependency of Object.values(domain.dependencies))
+            Object.values(dependency.classes).forEach(add);
+        Object.values(kernelClasses()).forEach(add);
+    }
+    /** One Class of the model, by key. */
+    classOf(key) {
+        const c = this.#byKey.get(key);
+        if (c === undefined)
+            throw new TypeError(`${key} is not a Class this Domain declares or depends on`);
+        return c;
+    }
+    /** The keys a Class satisfies: its own and its parents', transitively, and the graph root. */
+    satisfies(c) {
+        const cached = this.#satisfied.get(c.key);
+        if (cached !== undefined)
+            return cached;
+        const keys = new Set(c.kind === 'node' ? [NODE_ROOT] : []);
+        const walk = (k) => {
+            if (keys.has(k.key))
+                return;
+            keys.add(k.key);
+            for (const parent of k.extends)
+                walk(parent);
+        };
+        walk(c);
+        this.#satisfied.set(c.key, keys);
+        return keys;
+    }
+    /** Both ends of an Edge Class. */
+    ends(edge) {
+        const cached = this.#ends.get(edge.key);
+        if (cached !== undefined)
+            return cached;
+        if (edge.kind !== 'edge')
+            throw new TypeError(`${edge.key} is not an Edge Class`);
+        const endpoints = edge.definition.endpoints;
+        const [source, target] = Array.isArray(endpoints)
+            ? endpoints
+            : [
+                endpoints.source,
+                endpoints.target,
+            ];
+        const end = (e) => ({
+            role: e.role,
+            accepts: e.accepts.map((a) => `${a.origin}:class.${a.name}`),
+            count: e.outgoing ?? e.incoming ?? e.incident ?? '',
+        });
+        const ends = { source: end(source), target: end(target) };
+        this.#ends.set(edge.key, ends);
+        return ends;
+    }
+    /** The Classes an end accepts that the Domain can name. */
+    far(end) {
+        return end.accepts.flatMap((key) => this.#byKey.get(key) ?? []);
+    }
+    /** Whether an end accepts one of `classes`, or one of their parents. */
+    touches(classes, end) {
+        return classes.some((c) => end.accepts.some((key) => this.satisfies(c).has(key)));
+    }
+    /** The Classes a traversal of `edges` in `direction` reaches. */
+    reached(edges, direction) {
+        const out = new Set();
+        for (const edge of edges) {
+            const { source, target } = this.ends(edge);
+            if (direction !== 'incoming')
+                this.far(target).forEach((c) => out.add(c));
+            if (direction !== 'outgoing')
+                this.far(source).forEach((c) => out.add(c));
+        }
+        return [...out];
+    }
+    /** Every Property name of a Class, flat or grouped: a relation or a `.with` name avoids them. */
+    propertyNames(c) {
+        return new Set([...c.properties].map((p) => p.name));
+    }
+    /**
+     * The named to-one relations of a Class (S2): one per to-one end that accepts the Class or a
+     * parent, named by the far end's role when that end accepts specific Classes. The Domain's own
+     * relations shadow its dependencies'; a name that clashes with a Property or a handle member
+     * names nothing, and a name several ends claim is ambiguous.
+     */
+    relations(c) {
+        const cached = this.#relations.get(c.key);
+        if (cached !== undefined)
+            return cached;
+        const satisfied = this.satisfies(c);
+        const candidates = [];
+        const specific = (end) => !end.accepts.some((key) => GENERIC.has(key));
+        const accepts = (end) => end.accepts.some((key) => satisfied.has(key));
+        for (const edge of this.#edges) {
+            const { source, target } = this.ends(edge);
+            const own = edge.key.startsWith(`${this.origin}:`);
+            if (TO_ONE.has(source.count) && accepts(source) && specific(target))
+                candidates.push({
+                    name: target.role,
+                    edge,
+                    direction: 'outgoing',
+                    far: this.far(target),
+                    own,
+                });
+            if (TO_ONE.has(target.count) && accepts(target) && specific(source))
+                candidates.push({
+                    name: source.role,
+                    edge,
+                    direction: 'incoming',
+                    far: this.far(source),
+                    own,
+                });
+        }
+        const ownNames = new Set(candidates.filter((x) => x.own).map((x) => x.name));
+        const kept = candidates.filter((x) => x.own || !ownNames.has(x.name));
+        const taken = this.propertyNames(c);
+        const out = new Map();
+        for (const x of kept) {
+            if (taken.has(x.name) || HANDLE_MEMBERS.has(x.name))
+                continue;
+            const previous = out.get(x.name);
+            if (previous === undefined)
+                out.set(x.name, x);
+            else if ('ambiguous' in previous || !sameRelation(previous, x))
+                out.set(x.name, { name: x.name, ambiguous: true });
+        }
+        this.#relations.set(c.key, out);
+        return out;
+    }
+    /**
+     * Where each Property of a Class goes when `taken` names are a row's or a handle's (F6). A name
+     * keeps its only Property, or the Class's own among inherited duplicates: flat, or under
+     * `$prop` when the name is taken. Each duplicate it does not keep goes under its owner.
+     */
+    layout(c, taken) {
+        const id = `${c.key}\u0000${[...taken].sort().join(',')}`;
+        const cached = this.#layouts.get(id);
+        if (cached !== undefined)
+            return cached;
+        const byName = new Map();
+        for (const p of c.properties) {
+            const keys = byName.get(p.name) ?? [];
+            if (!keys.includes(p.key))
+                keys.push(p.key);
+            byName.set(p.name, keys);
+        }
+        const flat = new Map();
+        const groups = new Map();
+        const add = (group, name, key) => {
+            const members = groups.get(group) ?? new Map();
+            members.set(name, key);
+            groups.set(group, members);
+        };
+        for (const [name, keys] of byName) {
+            const own = keys.filter((key) => key.startsWith(`${c.key}.property.`));
+            const kept = keys.length === 1 ? keys[0] : own.length === 1 ? own[0] : undefined;
+            if (kept !== undefined && taken.has(name))
+                add(PROP_GROUP, name, kept);
+            else if (kept !== undefined)
+                flat.set(name, kept);
+            for (const key of keys) {
+                const owner = key === kept ? undefined : OWNER.exec(key)?.[1];
+                if (owner !== undefined)
+                    add(ownerGroup(owner), name, key);
+            }
+        }
+        const layout = { flat, groups };
+        this.#layouts.set(id, layout);
+        return layout;
+    }
+}
+/**
+ * The group of an owner's duplicates: `$` and its name in lower camel case, escaped with one more
+ * `$` when that is one of the SDK's keys: an owner named `Class` groups under `$$class`
+ * (`OwnerGroup`).
+ */
+function ownerGroup(owner) {
+    const group = `$${owner.charAt(0).toLowerCase()}${owner.slice(1)}`;
+    return SDK_KEYS.some((key) => key === group) ? `$${group}` : group;
+}
+/** Two candidates the types see as one: the same name, Edge and far Classes. */
+function sameRelation(a, b) {
+    return a.edge === b.edge && a.far.length === b.far.length && a.far.every((c, i) => c === b.far[i]);
+}
+const models = new WeakMap();
+/** The Class model of a resolved Domain, built once. */
+export function modelOf(domain) {
+    let model = models.get(domain);
+    if (model === undefined) {
+        model = new Model(domain);
+        models.set(domain, model);
+    }
+    return model;
+}

package/dist/application/query/handles/plan.d.ts

@@ -0,0 +1,99 @@
+/**
+ * What a read lowers to: its canonical v7 document, and the plan the recipe runtime answers it
+ * by (WP-S3): the verb, its bound, and for each pattern the Classes its rows may be, how they
+ * render and the relations they carry. A read whose condition can match nothing is `empty`: it
+ * has no document, and the runtime answers it without sending. When the input folds a condition
+ * (an empty list), the read keeps its document as written: the one S12 checks.
+ */
+import type { AnyQuery } from '../language/query.js';
+import type { Scope } from './terms.js';
+/** The verbs of a root read; `document` is the escape hatch (D23). */
+export type Verb = 'get' | 'find' | 'first' | 'firstN' | 'firstMore' | 'page' | 'all' | 'exists' | 'count' | 'document';
+/** The verbs of a relation, per parent. */
+export type RelationVerb = 'get' | 'find' | 'first' | 'firstN' | 'all' | 'exists' | 'count';
+export type Rendering = 'value' | 'reference';
+/** How a pattern's rows are answered. */
+export interface Pattern {
+    /** The keys of the Classes its rows may be, after narrowing (S3): the layout of each row. */
+    readonly classes: readonly string[];
+    readonly select: Rendering;
+    /** Rows the reader may not read stay, as `{ id, $class, $withheld }`. */
+    readonly withheld: boolean;
+    readonly branches: readonly BranchPlan[];
+}
+/** A relation a row carries, under its `.with` key. */
+export interface BranchPlan extends Pattern {
+    /** The `.with` key the answer goes under. */
+    readonly key: string;
+    /** The Branch's name in the document. */
+    readonly name: string;
+    /** The relation as an integrity error names it: its name, or `via(<Edge keys>)`. */
+    readonly relation: string;
+    readonly verb: RelationVerb;
+    /** `first(n)`: n; `all`: max; `count`: upTo. */
+    readonly bound?: number;
+    /** Its condition matches nothing: it is not sent, and every parent gets the empty answer. */
+    readonly empty: boolean;
+    /** Each row carries `$edge` (`.withEdge()`). */
+    readonly edge: boolean;
+}
+export interface NodeRootPlan extends Pattern {
+    readonly kind: 'nodes';
+}
+/** One end of an Edge root: its role on the rows, and the Classes it accepts. */
+export interface EndPlan {
+    readonly role: string;
+    readonly classes: readonly string[];
+}
+export interface EdgeRootPlan {
+    readonly kind: 'edges';
+    readonly classes: readonly string[];
+    readonly select: Rendering;
+    readonly withheld: boolean;
+    readonly source: EndPlan;
+    readonly target: EndPlan;
+}
+/** The plan of a root read. */
+export interface ReadPlan {
+    readonly verb: Verb;
+    /** `first(n)` and `first(n, { more })`: n; `page` and `all`: max; `count`: upTo. */
+    readonly bound?: number;
+    /** Its condition matches nothing: answered without sending. */
+    readonly empty: boolean;
+    /** Absent when `empty`. */
+    readonly document?: AnyQuery;
+    /** The document as written, when the input folds it: as no empty list folds it. */
+    readonly written?: AnyQuery;
+    /** Absent for `document`, whose rows are unknown. */
+    readonly root?: NodeRootPlan | EdgeRootPlan;
+    /** The id or path `get`, `find` or `exists` was given, as `NOT_FOUND` names it. */
+    readonly target?: string;
+}
+/** A read of a root: what a verb on a Class handle, or `d.document`, returns. */
+export declare class RootRead {
+    readonly plan: ReadPlan;
+    constructor(plan: ReadPlan);
+}
+/** A Branch of a document and its plan, once its parent names it. */
+export interface LoweredBranch {
+    readonly plan: BranchPlan;
+    /** Absent when the plan is `empty`. */
+    readonly branch?: Readonly<Record<string, unknown>>;
+    /** The Branch as written, when the input folds it or a Branch under it. */
+    readonly written?: Readonly<Record<string, unknown>>;
+}
+/** A read of a relation, per parent: what a `.with` takes. */
+export declare class RelationRead {
+    /** The handle it was read from: a `.with` takes only its own handle's relations. */
+    readonly scope: Scope;
+    readonly lower: (key: string, name: string) => LoweredBranch;
+    constructor(
+    /** The handle it was read from: a `.with` takes only its own handle's relations. */
+    scope: Scope, lower: (key: string, name: string) => LoweredBranch);
+}
+/** Whether a value is a read a recipe runs (a root read). */
+export declare function isRead(value: unknown): value is RootRead;
+/** The plan of a root read. */
+export declare function planOf(read: unknown): ReadPlan;
+/** The canonical document of a root read; an `empty` read has none. */
+export declare function lower(read: unknown): AnyQuery | undefined;

package/dist/application/query/handles/plan.js

@@ -0,0 +1,37 @@
+/** A read of a root: what a verb on a Class handle, or `d.document`, returns. */
+export class RootRead {
+    plan;
+    constructor(plan) {
+        this.plan = plan;
+        Object.freeze(this);
+    }
+}
+/** A read of a relation, per parent: what a `.with` takes. */
+export class RelationRead {
+    scope;
+    lower;
+    constructor(
+    /** The handle it was read from: a `.with` takes only its own handle's relations. */
+    scope, lower) {
+        this.scope = scope;
+        this.lower = lower;
+        Object.freeze(this);
+    }
+}
+/** Whether a value is a read a recipe runs (a root read). */
+export function isRead(value) {
+    return value instanceof RootRead;
+}
+/** The plan of a root read. */
+export function planOf(read) {
+    if (!(read instanceof RootRead)) {
+        if (read instanceof RelationRead)
+            throw new TypeError('A relation read is answered per parent: read it inside a `.with`.');
+        throw new TypeError('Not a read: a read ends with a verb (get, find, first, page, all, exists, count).');
+    }
+    return read.plan;
+}
+/** The canonical document of a root read; an `empty` read has none. */
+export function lower(read) {
+    return planOf(read).document;
+}

package/dist/application/query/handles/reads.d.ts

@@ -0,0 +1,106 @@
+/**
+ * The handles' runtime: Node, relation and Edge sets, and the handles their callbacks receive.
+ * Each verb lowers its read to canonical v7 JSON and a plan (`plan.ts`). Sets are immutable:
+ * every method returns a new set.
+ */
+import type { AnyResolvedClass } from '../../../platform/schema/index.js';
+import type { Direction, Model } from './model.js';
+import type { Context } from './terms.js';
+import { RelationRead, RootRead } from './plan.js';
+import { Condition } from './terms.js';
+/**
+ * The one Class a Class handle names, as a write takes it: `d.<Class>`, on which no method was
+ * called. `undefined` for a value that is no set of roots.
+ */
+export declare function handleClass(value: unknown): AnyResolvedClass | undefined;
+/**
+ * A guard's range (S7), the roots of a Class handle after `where`, `union` and `orderBy`, as a
+ * read: of whether one exists, or, `ordered`, of them in their order. `undefined` for a value that
+ * is no set of roots; a set whose rows render (`with`, `pick`, `includeWithheld`) is refused.
+ */
+export declare function rangeRead(value: unknown, ordered: boolean): RootRead | undefined;
+/** A Node handle: its Properties, its named to-one relations, and the methods every Node has. */
+export declare function nodeHandle(model: Model, classes: readonly AnyResolvedClass[], context: Context): object;
+/** A condition that is also a relation read: `exists()` is a boolean in `.with`. */
+declare class Exists extends Condition {
+    readonly read: RelationRead;
+    constructor(condition: Condition, read: RelationRead);
+}
+/** A relation from a Node: the Nodes at the far end of its Edges. */
+export declare class Relation {
+    #private;
+    private constructor();
+    static of(model: Model, name: string, edges: readonly AnyResolvedClass[], direction: Direction, far: readonly AnyResolvedClass[], context: Context): Relation;
+    where(conditions: unknown): Relation;
+    orderBy(keys: unknown): Relation;
+    with(relations: unknown): Relation;
+    withEdge(): Relation;
+    pick(): Relation;
+    includeWithheld(): Relation;
+    distinct(): Relation;
+    /** Exactly one per parent: two rows, to see a second. */
+    get(): RelationRead;
+    find(): RelationRead;
+    first(n?: unknown): RelationRead;
+    all(written: unknown): RelationRead;
+    count(written: unknown): RelationRead;
+    /** A boolean per parent in a `.with`; a condition in a `where`. */
+    exists(): Exists;
+    /** The relation reaches this Node. */
+    is(target: unknown): Condition;
+    some(conditions?: unknown): Condition;
+    none(conditions?: unknown): Condition;
+    atLeast(n: unknown, conditions?: unknown): Condition;
+    atMost(n: unknown, conditions?: unknown): Condition;
+    exactly(n: unknown, conditions?: unknown): Condition;
+    /** No Edge of the relation fails the conditions: `none` of their negation, on one side. */
+    every(conditions: unknown): Condition;
+}
+/** The Nodes of a Class, or of a union of Classes, at the root of a read. */
+export declare class NodeSet {
+    #private;
+    private constructor();
+    static of(model: Model, cls: AnyResolvedClass): NodeSet;
+    /** Its Classes, after narrowing. */
+    get classes(): readonly AnyResolvedClass[];
+    /** No method was called on it but `union`: a Class handle, as `is` and `union` take one. */
+    get pristine(): boolean;
+    /** The range a guard reads (S7); a set whose rows render is none. */
+    static range(set: NodeSet, ordered: boolean): RootRead;
+    where(conditions: unknown): NodeSet;
+    orderBy(keys: unknown): NodeSet;
+    with(relations: unknown): NodeSet;
+    pick(): NodeSet;
+    includeWithheld(): NodeSet;
+    union(other: unknown): NodeSet;
+    /** Exactly one: two rows, to see a second. */
+    get(id?: unknown): RootRead;
+    find(id?: unknown): RootRead;
+    first(n?: unknown, written?: unknown): RootRead;
+    page(written: unknown): RootRead;
+    all(written: unknown): RootRead;
+    exists(id?: unknown): RootRead;
+    count(written: unknown): RootRead;
+}
+/** The Edges of a Class at the root of a read: its Properties, and both ends by role. */
+export declare class EdgeSet {
+    #private;
+    private constructor();
+    static of(model: Model, edge: AnyResolvedClass): EdgeSet;
+    get edge(): AnyResolvedClass;
+    get pristine(): boolean;
+    /** The range a guard reads (S7); a set whose rows render is none. */
+    static range(set: EdgeSet, ordered: boolean): RootRead;
+    where(conditions: unknown): EdgeSet;
+    orderBy(keys: unknown): EdgeSet;
+    pick(): EdgeSet;
+    includeWithheld(): EdgeSet;
+    get(): RootRead;
+    find(): RootRead;
+    first(n?: unknown): RootRead;
+    page(written: unknown): RootRead;
+    all(written: unknown): RootRead;
+    exists(): RootRead;
+    count(written: unknown): RootRead;
+}
+export {};