@astrale-os/sdk 0.5.0-beta.13 → 0.5.0-beta.131

package/dist/application/query/define.d.ts

@@ -0,0 +1,48 @@
+import type { QueryAST } from '@astrale-os/kernel-core/graph/query';
+import type { AnyResolvedClass } from '@astrale-os/kernel-dsl/v1';
+import type { Domain, schema } from '../../platform/schema/index.js';
+import type { ProjectedCompositeQuery, QueryComposition, QueryPlan, QueryPlanOutput, RawCompositeQuery } from './composite/index.js';
+import type { CompositeQueryDefinition, CollectionQueryDefinition, QueryDefinition, RealizedQuery, SingleQueryDefinition } from './query.js';
+import type { PaginatedQuery, ProjectedQuery, RawQuery, SingleQuery } from './single/index.js';
+import { type CollectionQuerySpec } from './collection/metadata.js';
+type AuthoredRaw<Input, Ast extends QueryAST> = Omit<RawQuery<Input, Ast>, 'kind' | 'page'> & {
+    readonly page?: {
+        readonly size: number;
+    };
+};
+type AuthoredProjected<Input, Output, Ast extends QueryAST> = Omit<ProjectedQuery<Input, Output, Ast>, 'kind' | 'page'> & {
+    readonly page?: {
+        readonly size: number;
+    };
+};
+type AuthoredPaginated<Input, Output, Ast extends QueryAST> = Omit<PaginatedQuery<Input, Output, Ast>, 'kind' | 'page'> & {
+    readonly page?: {
+        readonly size: number;
+    };
+};
+type ResolvedDomainOf<Schema extends schema.DomainSchema> = Extract<schema.DomainOf<Schema>, Domain>;
+interface SingleQueryProjector<Schema extends schema.DomainSchema> {
+    <Input, Ast extends QueryAST>(project: (domain: ResolvedDomainOf<Schema>) => AuthoredRaw<Input, Ast>): SingleQueryDefinition<ResolvedDomainOf<Schema>, Input, RawQuery<Input, Ast> extends SingleQuery<Input, infer Output> ? Output : never>;
+    <Input, Output, Ast extends QueryAST>(project: (domain: ResolvedDomainOf<Schema>) => AuthoredProjected<Input, Output, Ast>): SingleQueryDefinition<ResolvedDomainOf<Schema>, Input, Output>;
+    <Input, Output, Ast extends QueryAST>(project: (domain: ResolvedDomainOf<Schema>) => AuthoredPaginated<Input, Output, Ast>): SingleQueryDefinition<ResolvedDomainOf<Schema>, Input, Output>;
+}
+interface CollectionQueryProjector<Schema extends schema.DomainSchema> {
+    <Class extends AnyResolvedClass>(project: (domain: ResolvedDomainOf<Schema>) => CollectionQuerySpec<Class>): CollectionQueryDefinition<ResolvedDomainOf<Schema>, Class>;
+}
+type AuthoredInferredComposite<Input, Composed, Plan extends QueryPlan<unknown>, Output, DomainValue extends Domain> = Omit<ProjectedCompositeQuery<Input, Composed, Output, DomainValue>, 'kind' | 'compose' | 'project'> & {
+    compose(builder: QueryComposition<DomainValue>, input: Input): Plan;
+    project(value: QueryPlanOutput<Plan>, input: Input): Output;
+};
+interface CompositeQueryProjector<Schema extends schema.DomainSchema> {
+    <Plan extends QueryPlan<unknown>, Output>(project: (domain: ResolvedDomainOf<Schema>) => AuthoredInferredComposite<void, QueryPlanOutput<Plan>, Plan, Output, ResolvedDomainOf<Schema>>): CompositeQueryDefinition<ResolvedDomainOf<Schema>, void, Output>;
+    <Input, Output>(project: (domain: ResolvedDomainOf<Schema>) => Omit<RawCompositeQuery<Input, Output, ResolvedDomainOf<Schema>>, 'kind'>): CompositeQueryDefinition<ResolvedDomainOf<Schema>, Input, Output>;
+    <Input, Composed, Output, Plan extends QueryPlan<Composed> = QueryPlan<Composed>>(project: (domain: ResolvedDomainOf<Schema>) => AuthoredInferredComposite<Input, Composed, Plan, Output, ResolvedDomainOf<Schema>>): CompositeQueryDefinition<ResolvedDomainOf<Schema>, Input, Output>;
+}
+/** Define one inert single Query recipe projected from its exact loaded Domain. */
+export declare function defineQuery<Schema extends schema.DomainSchema>(): SingleQueryProjector<Schema>;
+/** Define one reusable complete polymorphic Class-extent Query. */
+export declare function defineCollectionQuery<Schema extends schema.DomainSchema>(): CollectionQueryProjector<Schema>;
+/** Define one inert composite Query recipe projected from its exact loaded Domain. */
+export declare function defineCompositeQuery<Schema extends schema.DomainSchema>(): CompositeQueryProjector<Schema>;
+export declare function realizeQuery<DomainValue extends Domain, Input, Output>(query: QueryDefinition<DomainValue, Input, Output>, domain: DomainValue): RealizedQuery<Input, Output>;
+export {};

package/dist/application/query/define.js

@@ -0,0 +1,162 @@
+import { Query } from '@astrale-os/kernel-core/graph/query';
+import { isDomain } from '@astrale-os/kernel-dsl/v1/domain';
+import { requireUniqueCollectionValues } from './collection/identity.js';
+import { COLLECTION_QUERY_LIMITS } from './collection/limits.js';
+import { realizeCollectionQuery, registerCollectionQuery, } from './collection/metadata.js';
+import { queryResult } from './single/index.js';
+const DEFAULT_PAGE_SIZE = 256;
+const MAXIMUM_PAGES = 1_024;
+const projectors = new WeakMap();
+const realized = new WeakMap();
+/** Define one inert single Query recipe projected from its exact loaded Domain. */
+export function defineQuery() {
+    return ((project) => recipe('query', project));
+}
+/** Define one reusable complete polymorphic Class-extent Query. */
+export function defineCollectionQuery() {
+    return ((project) => {
+        const definition = defineQuery()((domain) => {
+            const specification = realizeCollectionQuery(definition, domain);
+            const selected = specification.class;
+            if (selected.kind === 'node') {
+                return {
+                    id: specification.id,
+                    page: { size: COLLECTION_QUERY_LIMITS.pageSize },
+                    pagination: { maximumPages: COLLECTION_QUERY_LIMITS.maximumPages },
+                    build: () => Query.from({ nodes: [selected] }).select({
+                        kind: 'nodes',
+                        projection: { kind: 'value' },
+                    }),
+                    project: (pages) => requireUniqueCollectionValues(queryResult.completeNodeValues(pages, specification.id), `Collection Query ${specification.id}`),
+                };
+            }
+            return {
+                id: specification.id,
+                page: { size: COLLECTION_QUERY_LIMITS.pageSize },
+                pagination: { maximumPages: COLLECTION_QUERY_LIMITS.maximumPages },
+                build: () => Query.from({ edges: [selected] }).select({
+                    kind: 'edges',
+                    projection: { edge: 'value', source: 'reference', target: 'reference' },
+                }),
+                project: (pages) => requireUniqueCollectionValues(Object.freeze(pages.flatMap((page) => queryResult.edgeItems(page, specification.id).map((item) => {
+                    if (item.edge.kind !== 'value') {
+                        throw new TypeError(`Collection Query ${specification.id} must project Edge values.`);
+                    }
+                    return item.edge.value;
+                }))), `Collection Query ${specification.id}`),
+            };
+        });
+        registerCollectionQuery(definition, project);
+        return definition;
+    });
+}
+/** Define one inert composite Query recipe projected from its exact loaded Domain. */
+export function defineCompositeQuery() {
+    return ((project) => recipe('composite-query', project));
+}
+export function realizeQuery(query, domain) {
+    const project = projectors.get(query);
+    if (project === undefined)
+        throw new TypeError('Query must be produced by defineQuery.');
+    if (!isDomain(domain))
+        throw new TypeError('Query projection requires an admitted Domain.');
+    let byDomain = realized.get(query);
+    const cached = byDomain?.get(domain);
+    if (cached !== undefined)
+        return cached;
+    const authored = project(domain);
+    if (isPromiseLike(authored))
+        throw new TypeError('Query projection must be synchronous.');
+    const admitted = query.kind === 'query' ? admitSingle(authored) : admitComposite(authored);
+    if (byDomain === undefined) {
+        byDomain = new WeakMap();
+        realized.set(query, byDomain);
+    }
+    byDomain.set(domain, admitted);
+    return admitted;
+}
+function recipe(kind, project) {
+    if (typeof project !== 'function')
+        throw new TypeError('Query projection must be a function.');
+    const definition = Object.freeze({ kind });
+    projectors.set(definition, project);
+    return definition;
+}
+function admitSingle(definition) {
+    definitionBase(definition, 'build');
+    const page = pageOf(definition.page);
+    const pagination = definition.pagination;
+    if (pagination !== undefined) {
+        if (typeof definition.project !== 'function') {
+            throw new TypeError('Paginated Query requires a project function.');
+        }
+        if (pagination === null ||
+            typeof pagination !== 'object' ||
+            Array.isArray(pagination) ||
+            Reflect.ownKeys(pagination).length !== 1 ||
+            !Object.hasOwn(pagination, 'maximumPages')) {
+            throw new TypeError('Query pagination is invalid.');
+        }
+        const maximumPages = Reflect.get(pagination, 'maximumPages');
+        if (!Number.isSafeInteger(maximumPages) ||
+            maximumPages < 1 ||
+            maximumPages > MAXIMUM_PAGES) {
+            throw new TypeError(`Query pagination must be bounded from 1 through ${MAXIMUM_PAGES}.`);
+        }
+    }
+    return Object.freeze({ ...definition, page, kind: 'single' });
+}
+function admitComposite(definition) {
+    definitionBase(definition, 'compose');
+    if (Object.hasOwn(definition, 'page') || Object.hasOwn(definition, 'pagination')) {
+        throw new TypeError('Composite Query cannot declare pagination.');
+    }
+    return Object.freeze({ ...definition, kind: 'composite' });
+}
+function definitionBase(definition, operation) {
+    if (definition === null || typeof definition !== 'object' || Array.isArray(definition))
+        invalid();
+    if (typeof definition.id !== 'string' ||
+        definition.id.length === 0 ||
+        definition.id.trim() !== definition.id ||
+        typeof definition[operation] !== 'function') {
+        invalid();
+    }
+    for (const optional of ['prepare', 'project', 'reject']) {
+        if (definition[optional] !== undefined && typeof definition[optional] !== 'function')
+            invalid();
+    }
+    const allowed = new Set([
+        'id',
+        operation,
+        'prepare',
+        'project',
+        'reject',
+        ...(operation === 'build' ? ['page', 'pagination'] : []),
+    ]);
+    if (Reflect.ownKeys(definition).some((key) => typeof key !== 'string' || !allowed.has(key))) {
+        invalid();
+    }
+}
+function pageOf(input) {
+    if (input === undefined)
+        return Object.freeze({ size: DEFAULT_PAGE_SIZE });
+    if (input === null ||
+        typeof input !== 'object' ||
+        Array.isArray(input) ||
+        Reflect.ownKeys(input).length !== 1 ||
+        !Object.hasOwn(input, 'size') ||
+        !Number.isSafeInteger(Reflect.get(input, 'size')) ||
+        Reflect.get(input, 'size') < 1) {
+        throw new TypeError('Query page size must be a positive safe integer.');
+    }
+    return Object.freeze({ size: Reflect.get(input, 'size') });
+}
+function invalid() {
+    throw new TypeError('Query definition is invalid.');
+}
+function isPromiseLike(input) {
+    return (input !== null &&
+        (typeof input === 'object' || typeof input === 'function') &&
+        typeof input.then === 'function');
+}

package/dist/application/query/execution/execute.d.ts

@@ -0,0 +1,14 @@
+import type { QueryPageRequest, QueryResponse } from '@astrale-os/kernel-client/graph';
+import type { QueryAST, QueryResultFor } from '@astrale-os/kernel-core/graph/query';
+import type { Domain } from '../../../platform/schema/index.js';
+import type { CompositeQuery } from '../composite/index.js';
+import type { QueryDefinition } from '../query.js';
+export interface QueryClient {
+    query<Ast extends QueryAST>(ast: Ast, options: {
+        readonly page: QueryPageRequest;
+        readonly expected?: Domain['closure'];
+    }): Promise<QueryResponse<QueryResultFor<Ast>>>;
+}
+export declare function executeQuery<DomainValue extends Domain, Output>(client: QueryClient, domain: DomainValue, query: QueryDefinition<DomainValue, void, Output>): Promise<Output>;
+export declare function executeQuery<DomainValue extends Domain, Input, Output>(client: QueryClient, domain: DomainValue, query: QueryDefinition<DomainValue, Input, Output>, input: Input): Promise<Output>;
+export type ExecutableCompositeQuery = CompositeQuery<unknown, unknown, unknown>;

package/dist/application/query/execution/execute.js

@@ -0,0 +1,74 @@
+import { COLLECTION_QUERY_LIMITS } from '../collection/limits.js';
+import { compileCollectionUnion, partitionCollectionUnion } from '../collection/union.js';
+import { createQueryComposition, executeQueryPlan } from '../composite/index.js';
+import { realizeQuery } from '../define.js';
+import { queryFailure } from '../failure.js';
+import { completeSelection, queryResult } from '../single/index.js';
+import { executePages } from './pages.js';
+export async function executeQuery(client, domain, query, input) {
+    if (client === null || typeof client !== 'object' || typeof client.query !== 'function') {
+        throw new TypeError('Query execution requires a Client query capability.');
+    }
+    const execute = (ast, options) => client.query(ast, { ...options, expected: domain.closure });
+    const operation = realizeQuery(query, domain);
+    try {
+        if (operation.kind === 'single') {
+            return (await runSingle(execute, operation, input));
+        }
+        const prepared = operation.prepare?.(input) ?? input;
+        const session = createQueryComposition();
+        const composed = operation.compose(session.builder, prepared);
+        if (isPromiseLike(composed))
+            throw new TypeError('Composite Query composition must be synchronous.');
+        const plan = session.close(composed);
+        const result = await executeQueryPlan(plan, (child, childInput) => runSingle(execute, realizeSingle(child, domain), childInput), (definitions, outputPath) => runCollectionUnion(execute, domain, definitions, outputPath));
+        return (operation.project === undefined ? result : operation.project(result, prepared));
+    }
+    catch (cause) {
+        const expected = queryFailure(cause);
+        if (operation.reject !== undefined && expected !== undefined) {
+            return operation.reject(expected);
+        }
+        throw cause;
+    }
+}
+async function runCollectionUnion(execute, domain, definitions, outputPath) {
+    const compiled = compileCollectionUnion(domain, definitions, outputPath);
+    const pages = await executePages(execute, compiled.ast, { size: COLLECTION_QUERY_LIMITS.pageSize }, { maximumPages: COLLECTION_QUERY_LIMITS.maximumPages });
+    const context = outputPath.length === 0 ? 'collection union' : outputPath.join('.');
+    const values = compiled.kind === 'node'
+        ? queryResult.completeNodeValues(pages, context)
+        : Object.freeze(pages.flatMap((page) => queryResult.edgeItems(page, context).map((item) => {
+            if (item.edge.kind !== 'value') {
+                throw new TypeError(`${context} must project Edge values.`);
+            }
+            return item.edge.value;
+        })));
+    return partitionCollectionUnion(domain, compiled, values);
+}
+function realizeSingle(definition, domain) {
+    const operation = realizeQuery(definition, domain);
+    if (operation.kind !== 'single')
+        throw new TypeError('Composite Query leaves must be single.');
+    return operation;
+}
+async function runSingle(execute, definition, input) {
+    const prepared = definition.prepare?.(input) ?? input;
+    const ast = definition.build(prepared);
+    if (definition.pagination !== undefined) {
+        const collected = await executePages(execute, ast, definition.page, definition.pagination);
+        return definition.project(collected, prepared, {
+            ast,
+            complete: completeSelection(collected),
+        });
+    }
+    const response = await execute(ast, { page: definition.page });
+    return definition.project === undefined
+        ? response.result
+        : definition.project(response.result, prepared, { ast });
+}
+function isPromiseLike(input) {
+    return (input !== null &&
+        (typeof input === 'object' || typeof input === 'function') &&
+        typeof input.then === 'function');
+}

package/dist/application/query/execution/executor.d.ts

@@ -0,0 +1,14 @@
+import type { Domain, schema } from '../../../platform/schema/index.js';
+import type { QueryDefinition } from '../query.js';
+import type { QueryClient } from './execute.js';
+/** Invocation-bound executor for authored Query definitions. */
+export interface QueryExecutor<DomainValue extends Domain = Domain> {
+    <Output>(query: QueryDefinition<DomainValue, void, Output>): Promise<Output>;
+    <Input, Output>(query: QueryDefinition<DomainValue, Input, Output>, input: Input): Promise<Output>;
+}
+type ExecutableDomain<DomainValue extends Domain> = DomainValue extends {
+    readonly source: infer Source extends schema.DomainSchema;
+} ? Extract<schema.DomainOf<Source>, Domain> : DomainValue;
+/** Private Runtime binding to one Client and the exact loaded root Domain. */
+export declare function bindQuery<DomainValue extends Domain>(client: QueryClient, domain: DomainValue): QueryExecutor<ExecutableDomain<DomainValue>>;
+export {};

package/dist/application/query/execution/executor.js

@@ -0,0 +1,7 @@
+import { executeQuery } from './execute.js';
+/** Private Runtime binding to one Client and the exact loaded root Domain. */
+export function bindQuery(client, domain) {
+    const executable = domain;
+    const execute = (query, input) => executeQuery(client, executable, query, input);
+    return execute;
+}

package/dist/application/query/execution/index.d.ts

@@ -0,0 +1,2 @@
+export { executeQuery, type QueryClient } from './execute.js';
+export type { QueryExecutor } from './executor.js';

package/dist/application/query/execution/index.js

@@ -0,0 +1 @@
+export { executeQuery } from './execute.js';

package/dist/application/query/execution/pages.d.ts

@@ -0,0 +1 @@
+export { pages as executePages } from '../single/pagination.js';

package/dist/application/query/execution/pages.js

@@ -0,0 +1 @@
+export { pages as executePages } from '../single/pagination.js';

package/dist/application/query/execution/projection.d.ts

@@ -0,0 +1,3 @@
+import type { QueryAST, QueryResultFor } from '@astrale-os/kernel-core/graph/query';
+import type { ProjectedQuery, QueryProjectionContext } from '../single/index.js';
+export declare function projectQuery<Input, Output, Ast extends QueryAST>(definition: ProjectedQuery<Input, Output, Ast>, result: QueryResultFor<Ast>, input: Input, context: QueryProjectionContext<Ast>): Output;

package/dist/application/query/execution/projection.js

@@ -0,0 +1,3 @@
+export function projectQuery(definition, result, input, context) {
+    return definition.project(result, input, context);
+}

package/dist/application/query/failure.d.ts

@@ -0,0 +1,10 @@
+export interface QueryFailure extends Error {
+    readonly code: string;
+}
+export type QueryPaginationErrorCode = 'QUERY_PAGINATION_LIMIT' | 'QUERY_PAGINATION_CURSOR_REPEATED';
+export declare class QueryPaginationError extends Error implements QueryFailure {
+    readonly code: QueryPaginationErrorCode;
+    readonly name = "QueryPaginationError";
+    constructor(code: QueryPaginationErrorCode, message: string);
+}
+export declare function queryFailure(input: unknown): QueryFailure | undefined;

package/dist/application/query/failure.js

@@ -0,0 +1,14 @@
+export class QueryPaginationError extends Error {
+    code;
+    name = 'QueryPaginationError';
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+    }
+}
+export function queryFailure(input) {
+    if (!(input instanceof Error))
+        return undefined;
+    const code = input.code;
+    return typeof code === 'string' && code.startsWith('QUERY_') ? input : undefined;
+}

package/dist/application/query/index.d.ts

@@ -0,0 +1,10 @@
+export { defineCollectionQuery, defineCompositeQuery, defineQuery, realizeQuery } from './define.js';
+export type { CollectionQuerySpec } from './collection/metadata.js';
+export { executeQuery, type QueryClient, type QueryExecutor } from './execution/index.js';
+export { QueryPaginationError, type QueryFailure, type QueryPaginationErrorCode, } from './failure.js';
+export type { CollectionQueryDefinition, CollectionValue, CompositeQueryDefinition, QueryAstOf, QueryDefinition, QueryInputOf, QueryOutputOf, SingleQueryDefinition, } from './query.js';
+export { queryResult } from './single/index.js';
+export type { CompleteQueryProjectionContext, PaginatedQuery, ProjectedQuery, QueryPages, QueryPagination, QueryProjectionContext, RawQuery, SingleQuery, } from './single/index.js';
+export type { CompositeQuery, ProjectedCompositeQuery, QueryComposition, QueryPlan, QueryPlanInput, QueryPlanOutput, QueryPlanValue, RawCompositeQuery, } from './composite/index.js';
+/** Canonical Query language and authoring values accept DSL ResolvedClass directly. */
+export * from '@astrale-os/kernel-core/graph/query';

package/dist/application/query/index.js

@@ -0,0 +1,6 @@
+export { defineCollectionQuery, defineCompositeQuery, defineQuery, realizeQuery } from './define.js';
+export { executeQuery } from './execution/index.js';
+export { QueryPaginationError, } from './failure.js';
+export { queryResult } from './single/index.js';
+/** Canonical Query language and authoring values accept DSL ResolvedClass directly. */
+export * from '@astrale-os/kernel-core/graph/query';

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

@@ -0,0 +1,35 @@
+import type { QueryAST, QueryResult } from '@astrale-os/kernel-core/graph/query';
+import type { AnyResolvedClass, ResolvedClass } from '@astrale-os/kernel-dsl/v1';
+import type { Edge } from '../../platform/graph/edge/index.js';
+import type { Node } from '../../platform/graph/node/index.js';
+import type { Domain } from '../../platform/schema/index.js';
+import type { CompositeQuery } from './composite/index.js';
+import type { QueryLifecycle, SingleQuery } from './single/index.js';
+declare const QUERY_DOMAIN: unique symbol;
+declare const QUERY_INPUT: unique symbol;
+declare const QUERY_OUTPUT: unique symbol;
+declare const COLLECTION_QUERY_CLASS: unique symbol;
+/** Inert Domain-bound Query recipe. Its projector is retained privately by the SDK. */
+export interface QueryDefinition<DomainValue extends Domain = Domain, Input = unknown, Output = QueryResult> {
+    readonly kind: 'query' | 'composite-query';
+    readonly [QUERY_DOMAIN]: (domain: DomainValue) => DomainValue;
+    readonly [QUERY_INPUT]?: Input;
+    readonly [QUERY_OUTPUT]?: Output;
+}
+export interface SingleQueryDefinition<DomainValue extends Domain = Domain, Input = unknown, Output = QueryResult> extends QueryDefinition<DomainValue, Input, Output> {
+    readonly kind: 'query';
+}
+export type CollectionValue<Class extends AnyResolvedClass> = Class extends ResolvedClass<'node'> ? Node : Class extends ResolvedClass<'edge'> ? Edge : never;
+/** Closed complete-Class Query recipe admitted for explicit physical union planning. */
+export interface CollectionQueryDefinition<DomainValue extends Domain = Domain, Class extends AnyResolvedClass = AnyResolvedClass> extends SingleQueryDefinition<DomainValue, void, readonly CollectionValue<Class>[]> {
+    readonly [COLLECTION_QUERY_CLASS]: Class;
+}
+export interface CompositeQueryDefinition<DomainValue extends Domain = Domain, Input = unknown, Output = unknown> extends QueryDefinition<DomainValue, Input, Output> {
+    readonly kind: 'composite-query';
+}
+/** Canonical admitted operation produced by realizing one Query recipe. */
+export type RealizedQuery<Input, Output = QueryResult, Ast extends QueryAST = QueryAST> = SingleQuery<Input, Output, Ast> | CompositeQuery<Input, unknown, Output, Domain>;
+export type QueryInputOf<Value> = Value extends QueryDefinition<infer _Domain, infer Input, infer _Output> ? Input : Value extends QueryLifecycle<infer Input, infer _Output> ? Input : never;
+export type QueryOutputOf<Value> = Value extends QueryDefinition<infer _Domain, infer _Input, infer Output> ? Output : Value extends QueryLifecycle<infer _Input, infer Output> ? Output : never;
+export type QueryAstOf<Value> = Value extends RealizedQuery<unknown, unknown, infer Ast> ? Ast : never;
+export {};

package/dist/application/query/query.js

@@ -0,0 +1 @@
+export {};

package/dist/application/query/single/index.d.ts

@@ -0,0 +1,4 @@
+export { queryResult } from './node.js';
+export { pages, type QueryPageExecutor } from './pagination.js';
+export { completeSelection } from './selection.js';
+export type { AuthoredSingleQuery, CompleteQueryProjectionContext, PaginatedQuery, ProjectedQuery, QueryLifecycle, QueryPages, QueryPagination, QueryProjectionContext, RawQuery, SingleQuery, } from './query.js';

package/dist/application/query/single/index.js

@@ -0,0 +1,3 @@
+export { queryResult } from './node.js';
+export { pages } from './pagination.js';
+export { completeSelection } from './selection.js';

package/dist/application/query/single/node.d.ts

@@ -0,0 +1,18 @@
+import type { Node, NodeId } from '@astrale-os/kernel-core/graph/node';
+import type { QueryEdgeItemFor, QueryEdgeProjection, QueryResult } from '@astrale-os/kernel-core/graph/query';
+declare function nodeValues(result: QueryResult, context: string): readonly Node[];
+declare function nodeIds(result: QueryResult, context: string): readonly NodeId[];
+declare function edgeItems(result: QueryResult, context: string): readonly QueryEdgeItemFor<QueryEdgeProjection>[];
+export declare const queryResult: Readonly<{
+    nodeValues: typeof nodeValues;
+    completeNodeValues: (results: readonly QueryResult[], context: string) => readonly Node[];
+    nodeIds: typeof nodeIds;
+    completeNodeIds: (results: readonly QueryResult[], context: string) => readonly NodeId[];
+    exactlyOneNode(result: QueryResult, context: string): Node;
+    optionalNode(result: QueryResult, context: string): Node | undefined;
+    edgeItems: typeof edgeItems;
+    optionalEdgeTarget(result: QueryResult, context: string): Node | undefined;
+    exactlyOneEdgeTarget(result: QueryResult, context: string): Node;
+    exactlyOneEdgeSource(result: QueryResult, context: string): Node;
+}>;
+export {};

package/dist/application/query/single/node.js

@@ -0,0 +1,86 @@
+function nodeValues(result, context) {
+    if (result.kind === 'graph') {
+        if (result.selection.kind !== 'node')
+            invalid(`Expected a Node ${context} query result.`);
+        const byId = new Map(result.graph.nodes.map((node) => [node.id, node]));
+        return Object.freeze(result.selection.ids.map((id) => {
+            const node = byId.get(id);
+            if (node === undefined)
+                invalid(`${context} graph omits selected Node ${id}.`);
+            return node;
+        }));
+    }
+    if (result.kind !== 'nodes')
+        invalid(`Expected a Node ${context} query result.`);
+    return Object.freeze(result.nodes.map((projection) => {
+        if (projection.kind !== 'value')
+            invalid(`Expected ${context} query to project Node values.`);
+        return projection.value;
+    }));
+}
+function nodeIds(result, context) {
+    if (result.kind === 'graph') {
+        if (result.selection.kind !== 'node')
+            invalid(`Expected a Node ${context} query result.`);
+        return result.selection.ids;
+    }
+    if (result.kind !== 'nodes')
+        invalid(`Expected a Node ${context} query result.`);
+    return Object.freeze(result.nodes.map((projection) => projection.value.id));
+}
+function edgeItems(result, context) {
+    if (result.kind !== 'edges')
+        invalid(`Expected an Edge ${context} query result.`);
+    return result.edges;
+}
+export const queryResult = Object.freeze({
+    nodeValues,
+    completeNodeValues: (results, context) => Object.freeze(results.flatMap((result) => nodeValues(result, context))),
+    nodeIds,
+    completeNodeIds: (results, context) => Object.freeze(results.flatMap((result) => nodeIds(result, context))),
+    exactlyOneNode(result, context) {
+        const values = nodeValues(result, context);
+        if (values.length !== 1)
+            invalid(`${context} must resolve exactly one Node.`);
+        return values[0];
+    },
+    optionalNode(result, context) {
+        const values = nodeValues(result, context);
+        if (values.length > 1)
+            invalid(`${context} must resolve at most one Node.`);
+        return values[0];
+    },
+    edgeItems,
+    optionalEdgeTarget(result, context) {
+        const items = edgeItems(result, context);
+        if (items.length > 1)
+            invalid(`${context} must resolve at most one Edge.`);
+        const target = items[0]?.target;
+        if (target === undefined)
+            return undefined;
+        if (target.kind !== 'value')
+            invalid(`${context} must project its target value.`);
+        return target.value;
+    },
+    exactlyOneEdgeTarget(result, context) {
+        const items = edgeItems(result, context);
+        if (items.length !== 1)
+            invalid(`${context} must resolve exactly one Edge.`);
+        const target = items[0].target;
+        if (target.kind !== 'value')
+            invalid(`${context} must project its target value.`);
+        return target.value;
+    },
+    exactlyOneEdgeSource(result, context) {
+        const items = edgeItems(result, context);
+        if (items.length !== 1)
+            invalid(`${context} must resolve exactly one Edge.`);
+        const source = items[0].source;
+        if (source.kind !== 'value')
+            invalid(`${context} must project its source value.`);
+        return source.value;
+    },
+});
+function invalid(message) {
+    throw new TypeError(message);
+}

package/dist/application/query/single/pagination.d.ts

@@ -0,0 +1,9 @@
+import type { QueryPageRequest, QueryResponse } from '@astrale-os/kernel-client/graph';
+import type { QueryAST, QueryResultFor } from '@astrale-os/kernel-core/graph/query';
+import type { QueryPages, QueryPagination } from './query.js';
+export interface QueryPageExecutor {
+    <Query extends QueryAST>(ast: Query, options: {
+        readonly page: QueryPageRequest;
+    }): Promise<QueryResponse<QueryResultFor<Query>>>;
+}
+export declare function pages<Query extends QueryAST>(execute: QueryPageExecutor, ast: Query, page: Readonly<Pick<QueryPageRequest, 'size'>>, pagination: QueryPagination): Promise<QueryPages<Query>>;

package/dist/application/query/single/pagination.js

@@ -0,0 +1,24 @@
+import { QueryPaginationError } from '../failure.js';
+export async function pages(execute, ast, page, pagination) {
+    const collected = [];
+    const cursors = new Set();
+    let response = await execute(ast, { page });
+    const kind = response.result.kind;
+    while (true) {
+        if (response.result.kind !== kind) {
+            throw new TypeError(`Paginated Query result kind changed from ${kind} to ${response.result.kind}.`);
+        }
+        collected.push(response.result);
+        const cursor = response.page.next;
+        if (cursor === undefined)
+            return Object.freeze(collected);
+        if (cursors.has(cursor)) {
+            throw new QueryPaginationError('QUERY_PAGINATION_CURSOR_REPEATED', 'Paginated Query returned a repeated continuation cursor.');
+        }
+        cursors.add(cursor);
+        if (collected.length >= pagination.maximumPages) {
+            throw new QueryPaginationError('QUERY_PAGINATION_LIMIT', `Paginated Query exceeded its ${pagination.maximumPages}-page bound.`);
+        }
+        response = await execute(ast, { page: { size: page.size, after: cursor } });
+    }
+}

package/dist/application/query/single/query.d.ts

@@ -0,0 +1,47 @@
+import type { QueryPageRequest } from '@astrale-os/kernel-client/graph';
+import type { QueryAST, QueryResult, QueryResultFor, QuerySelectionFor } from '@astrale-os/kernel-core/graph/query';
+import type { QueryFailure } from '../failure.js';
+declare const QUERY_INPUT: unique symbol;
+declare const QUERY_OUTPUT: unique symbol;
+export interface QueryLifecycle<Input, Output> {
+    readonly id: string;
+    readonly [QUERY_INPUT]?: Input;
+    readonly [QUERY_OUTPUT]?: Output;
+    prepare?(input: Input): Input;
+    reject?(failure: QueryFailure): Output;
+}
+export interface QueryProjectionContext<Query extends QueryAST> {
+    readonly ast: Query;
+}
+export interface CompleteQueryProjectionContext<Query extends QueryAST> extends QueryProjectionContext<Query> {
+    readonly complete: QuerySelectionFor<QueryResultFor<Query>>;
+}
+export interface QueryPagination {
+    readonly maximumPages: number;
+}
+export type QueryPages<Query extends QueryAST = QueryAST> = readonly [
+    QueryResultFor<Query>,
+    ...QueryResultFor<Query>[]
+];
+export interface SingleQueryBase<Input, Output, Query extends QueryAST> extends QueryLifecycle<Input, Output> {
+    readonly kind: 'single';
+    readonly page: Readonly<Pick<QueryPageRequest, 'size'>>;
+    build(input: Input): Query;
+}
+export interface RawQuery<Input, Query extends QueryAST = QueryAST> extends SingleQueryBase<Input, QueryResultFor<Query>, Query> {
+    readonly pagination?: undefined;
+    readonly project?: undefined;
+}
+export interface ProjectedQuery<Input, Output, Query extends QueryAST = QueryAST> extends SingleQueryBase<Input, Output, Query> {
+    readonly pagination?: undefined;
+    project(result: QueryResultFor<Query>, input: Input, context: QueryProjectionContext<Query>): Output;
+}
+export interface PaginatedQuery<Input, Output, Query extends QueryAST = QueryAST> extends SingleQueryBase<Input, Output, Query> {
+    readonly pagination: QueryPagination;
+    project(pages: QueryPages<Query>, input: Input, context: CompleteQueryProjectionContext<Query>): Output;
+}
+export type SingleQuery<Input, Output = QueryResult, Query extends QueryAST = QueryAST> = RawQuery<Input, Query> | ProjectedQuery<Input, Output, Query> | PaginatedQuery<Input, Output, Query>;
+export type AuthoredSingleQuery<Input, Output, Query extends QueryAST> = Omit<SingleQuery<Input, Output, Query>, 'kind' | 'page'> & {
+    readonly page?: Readonly<Pick<QueryPageRequest, 'size'>>;
+};
+export {};

package/dist/application/query/single/query.js

@@ -0,0 +1 @@
+export {};