@innovatorstack/harness 0.0.0-stage → 0.1.0

package/src/platform/queries/fields.ts

@@ -0,0 +1,160 @@
+import { dataDepthMax } from "../../core/limits.js";
+import type { AmlPropertyCondition } from "../../items/logical.js";
+import type { QueryField, ReferencePath, ValueKind } from "../../queries/types.js";
+import type {
+    HarnessStorage,
+    ItemTypeDefinition,
+    PropertyDefinition,
+    StorageValue,
+    StoredItem,
+} from "../../storage/types.js";
+import { PlatformError } from "../errors.js";
+
+export function resolveField(
+    storage: HarnessStorage,
+    definition: ItemTypeDefinition,
+    names: readonly string[],
+): QueryField {
+    const name = names.at(-1);
+    const qualifier = names.slice(0, -1).join(".").toLowerCase();
+    const qualifiers = [definition.name, definition.tableName ?? definition.name].flatMap(
+        (name) => [name, `innovator.${name}`, `dbo.${name}`],
+    );
+
+    if (!name || (qualifier && !qualifiers.some((value) => value.toLowerCase() === qualifier))) {
+        throw new PlatformError(
+            "UnsupportedWhere",
+            `Where qualifier does not refer to '${definition.name}'.`,
+        );
+    }
+
+    if (name.toLowerCase() === "id") {
+        return { name: "id", column: "id", kind: "identifier", path: [] };
+    }
+
+    const property = definition.properties.find(
+        (property) => property.name.toLowerCase() === name.toLowerCase(),
+    );
+
+    if (!property) {
+        throw new PlatformError(
+            "UnknownProperty",
+            `Unknown selector '${definition.name}.${name}'.`,
+        );
+    }
+
+    const path: ReferencePath[] = [];
+    let current = { definition, property };
+    const visited = new Set<string>();
+
+    while (current.property.dataType === "foreign") {
+        const key = `${current.definition.id}:${current.property.name}`;
+
+        if (visited.has(key) || path.length >= dataDepthMax) {
+            throw new PlatformError(
+                "ForeignPropertyCycle",
+                `Invalid foreign selector '${definition.name}.${name}'.`,
+            );
+        }
+
+        visited.add(key);
+        const next = foreignTarget(storage, current.definition, current.property);
+        path.push({ property: next.source.name, target: next.definition.name });
+        current = next;
+    }
+
+    if (current.property.isFederated) {
+        throw new PlatformError(
+            "UnsupportedFederatedPredicate",
+            `Filtering '${definition.name}.${name}' requires federation query support.`,
+        );
+    }
+
+    return {
+        name: property.name,
+        column: current.property.name,
+        kind: valueKind(current.property),
+        path,
+    };
+}
+
+export function fieldValue(storage: HarnessStorage, record: StoredItem, field: QueryField) {
+    let current: StoredItem | undefined = record;
+
+    for (const reference of field.path) {
+        const id: StorageValue | undefined = current?.properties[reference.property];
+        current = typeof id === "string" ? storage.getItem(reference.target, id) : undefined;
+    }
+
+    return field.column === "id"
+        ? (current?.id ?? null)
+        : (current?.properties[field.column] ?? null);
+}
+
+function foreignTarget(
+    storage: HarnessStorage,
+    definition: ItemTypeDefinition,
+    property: PropertyDefinition,
+) {
+    const source = definition.properties.find(
+        (candidate) => candidate.id?.toLowerCase() === property.dataSource?.toLowerCase(),
+    );
+    const target = storage
+        .listItemTypes()
+        .find((candidate) => candidate.id.toLowerCase() === source?.dataSource?.toLowerCase());
+    const targetProperty = target?.properties.find(
+        (candidate) => candidate.id?.toLowerCase() === property.foreignProperty?.toLowerCase(),
+    );
+
+    if (!source || !target || !targetProperty) {
+        throw new PlatformError(
+            "InvalidForeignProperty",
+            `Cannot resolve foreign selector '${definition.name}.${property.name}'.`,
+        );
+    }
+
+    return { source, definition: target, property: targetProperty };
+}
+
+function valueKind(property: PropertyDefinition): ValueKind {
+    if (property.dataType === "item" || property.name === "id") {
+        return "identifier";
+    }
+
+    if (["integer", "boolean", "float"].includes(property.dataType)) {
+        return "number";
+    }
+
+    if (property.dataType === "decimal" || property.dataType === "date") {
+        return property.dataType;
+    }
+
+    return "text";
+}
+
+export function selectorType(
+    storage: HarnessStorage,
+    definition: ItemTypeDefinition,
+    condition: AmlPropertyCondition,
+): ItemTypeDefinition {
+    const property = definition.properties.find((property) => property.name === condition.name);
+    const selector = condition.item;
+    const target = selector ? storage.getItemType(selector.type) : undefined;
+    const operator = (condition.attributes.condition ?? "eq").toLowerCase();
+
+    if (
+        property?.dataType !== "item" ||
+        !target ||
+        !selector ||
+        (selector.attributes.action ?? "get") !== "get" ||
+        target.id.toLowerCase() !== property.dataSource?.toLowerCase() ||
+        !["eq", "ne", "in", "not in"].includes(operator)
+    ) {
+        throw new PlatformError(
+            "InvalidSelector",
+            `Invalid nested selector for '${definition.name}.${condition.name}'.`,
+        );
+    }
+
+    return target;
+}

package/src/platform/queries/order.ts

@@ -0,0 +1,105 @@
+import { TokenKind, tokenize } from "../../queries/lexer.js";
+import type { QueryOrder } from "../../queries/types.js";
+import { compareValues } from "../../queries/values.js";
+import type { HarnessStorage, ItemTypeDefinition, StoredItem } from "../../storage/types.js";
+import { PlatformError } from "../errors.js";
+import { fieldValue, resolveField } from "./fields.js";
+
+export function orderBy(
+    storage: HarnessStorage,
+    definition: ItemTypeDefinition,
+    expression: string | undefined,
+): readonly QueryOrder[] {
+    if (!expression) {
+        return [];
+    }
+
+    const tokens = tokenize(expression);
+    const orders: QueryOrder[] = [];
+    let offset = 0;
+
+    while (offset < tokens.length) {
+        const names: string[] = [];
+
+        while (true) {
+            const token = tokens[offset++];
+
+            if (!token || ![TokenKind.Word, TokenKind.Identifier].includes(token.kind)) {
+                throw new PlatformError(
+                    "UnsupportedOrder",
+                    "ORDER BY requires property identifiers.",
+                );
+            }
+
+            names.push(token.value);
+
+            if (tokens[offset]?.value !== ".") {
+                break;
+            }
+
+            offset += 1;
+        }
+
+        const direction =
+            tokens[offset]?.kind === TokenKind.Word
+                ? tokens[offset]?.value.toLowerCase()
+                : undefined;
+
+        if (direction === "asc" || direction === "desc") {
+            offset += 1;
+        }
+
+        orders.push({
+            field: resolveField(storage, definition, names),
+            descending: direction === "desc",
+        });
+
+        if (offset < tokens.length && tokens[offset++]?.value !== ",") {
+            throw new PlatformError("UnsupportedOrder", "Unsupported ORDER BY syntax.");
+        }
+
+        if (tokens.at(-1)?.value === ",") {
+            throw new PlatformError("UnsupportedOrder", "ORDER BY cannot end with a comma.");
+        }
+    }
+
+    return orders;
+}
+
+export function orderRows(
+    storage: HarnessStorage,
+    rows: readonly StoredItem[],
+    orders: readonly QueryOrder[],
+    spend: (units: number) => void,
+): StoredItem[] {
+    return [...rows].sort((left, right) => {
+        for (const order of orders) {
+            const a = fieldValue(storage, left, order.field);
+            const b = fieldValue(storage, right, order.field);
+            spend(String(a ?? "").length + String(b ?? "").length + 1);
+            let difference = compareValues(order.field.kind, a, b);
+
+            difference ??= nullOrder(a, b);
+
+            if (difference !== 0) {
+                return order.descending ? -difference : difference;
+            }
+        }
+
+        spend(1);
+
+        if (left.id === right.id) {
+            return 0;
+        }
+
+        return left.id < right.id ? -1 : 1;
+    });
+}
+
+function nullOrder(left: unknown, right: unknown): number {
+    if (left === right) {
+        return 0;
+    }
+
+    return left === null ? -1 : 1;
+}

package/src/platform/queries/paging.ts

@@ -0,0 +1,66 @@
+import type { ItemMessage, ItemNode } from "../../items/item.js";
+import type { StoredItem } from "../../storage/types.js";
+import { PlatformError } from "../errors.js";
+
+export interface PageSelection {
+    readonly records: readonly StoredItem[];
+    readonly relationships?: ReadonlyMap<string, readonly ItemNode[]>;
+    readonly messages?: readonly ItemMessage[];
+}
+
+export function pageRows(request: ItemNode, records: readonly StoredItem[]): PageSelection {
+    const size = integer(request.attributes.pagesize, "pagesize");
+    const page = integer(request.attributes.page, "page") ?? 1;
+    const maximum = integer(request.attributes.maxRecords, "maxRecords");
+
+    if (
+        (request.attributes.action ?? "get") !== "get" &&
+        (size !== undefined || maximum !== undefined || request.attributes.page !== undefined)
+    ) {
+        throw new PlatformError(
+            "UnsupportedAttribute",
+            "Paging attributes are only supported on get requests.",
+        );
+    }
+
+    if (size === undefined && page !== 1) {
+        throw new PlatformError("InvalidPaging", "page requires pagesize.");
+    }
+
+    const bounded = maximum === undefined ? records : records.slice(0, maximum);
+
+    if (size === undefined) {
+        return { records: bounded };
+    }
+
+    const offset = (page - 1) * size;
+
+    if (!Number.isSafeInteger(offset)) {
+        throw new PlatformError(
+            "InvalidPaging",
+            "The page offset exceeds the supported integer range.",
+        );
+    }
+
+    return {
+        records: bounded.slice(offset, offset + size),
+        messages: [
+            { name: "itemmax", value: String(bounded.length) },
+            { name: "pagemax", value: String(Math.ceil(bounded.length / size)) },
+        ],
+    };
+}
+
+function integer(value: string | undefined, name: string): number | undefined {
+    if (value === undefined || value === "") {
+        return undefined;
+    }
+
+    const number = Number(value);
+
+    if (!/^\d+$/u.test(value) || !Number.isSafeInteger(number) || number < 1) {
+        throw new PlatformError("InvalidPaging", `${name} must be a positive safe integer.`);
+    }
+
+    return number;
+}

package/src/platform/queries/planner.ts

@@ -0,0 +1,244 @@
+import { spendContext } from "../../core/context.js";
+import type { ExecutionContext } from "../../core/types.js";
+import { Item } from "../../items/item.js";
+import type { ItemNode } from "../../items/item.js";
+import { AmlLogicalOperator } from "../../items/logical.js";
+import type { AmlLogicalGroup, AmlPropertyCondition } from "../../items/logical.js";
+import { PredicateParser } from "../../queries/parser.js";
+import { comparison, setPredicate, validatePredicate } from "../../queries/predicates.js";
+import {
+    Comparison,
+    conjunction,
+    queryDepthMax,
+    queryNodesMax,
+    queryTextMax,
+} from "../../queries/types.js";
+import type { Predicate } from "../../queries/types.js";
+import type { HarnessStorage, ItemTypeDefinition } from "../../storage/types.js";
+import { PlatformError, requireSuccess } from "../errors.js";
+import { propertyPredicate } from "./conditions.js";
+import { resolveField, selectorType } from "./fields.js";
+
+export type ApplyQueryItem = (item: Item, context: ExecutionContext) => Promise<Item>;
+
+export async function requestPredicate(
+    storage: HarnessStorage,
+    definition: ItemTypeDefinition,
+    request: ItemNode,
+    context: ExecutionContext,
+    apply: ApplyQueryItem,
+): Promise<Predicate> {
+    const terms: Predicate[] = [];
+    const field = (names: readonly string[]) => resolveField(storage, definition, names);
+
+    if (request.attributes.where) {
+        try {
+            terms.push(new PredicateParser(request.attributes.where, field).parse());
+        } catch (error) {
+            if (error instanceof PlatformError) {
+                throw error;
+            }
+
+            throw new PlatformError(
+                "UnsupportedWhere",
+                `Unsupported where expression: ${error instanceof Error ? error.message : String(error)}`,
+                { cause: error },
+            );
+        }
+    }
+
+    if (request.attributes.id !== undefined) {
+        terms.push(
+            propertyPredicate(field(["id"]), {
+                name: "id",
+                attributes: request.propertyAttributes.id ?? {},
+                value: request.attributes.id,
+            }),
+        );
+    }
+
+    if (request.attributes.idlist !== undefined) {
+        if (request.attributes.idlist.length > queryTextMax) {
+            throw new PlatformError("InvalidSelector", "idlist exceeds its input limit.");
+        }
+
+        const ids = request.attributes.idlist
+            .split(",")
+            .map((id) => id.trim())
+            .filter(Boolean);
+        terms.push(setPredicate(field(["id"]), ids));
+    }
+
+    if ((request.attributes.action ?? "get") === "get") {
+        terms.push(...(await getCriteria(storage, definition, request, context, apply)));
+    }
+
+    const predicate = conjunction(terms);
+    validatePredicate(predicate);
+
+    if (definition.isVersionable && !mentionsGeneration(predicate)) {
+        return conjunction([predicate, comparison(field(["is_current"]), Comparison.Equal, 1)]);
+    }
+
+    return predicate;
+}
+
+async function logicalPredicate(
+    storage: HarnessStorage,
+    definition: ItemTypeDefinition,
+    group: AmlLogicalGroup,
+    context: ExecutionContext,
+    apply: ApplyQueryItem,
+): Promise<Predicate> {
+    interface Frame {
+        readonly group: AmlLogicalGroup;
+        readonly terms: Predicate[];
+        index: number;
+    }
+
+    const pending: Frame[] = [{ group, terms: [], index: 0 }];
+    let visited = 0;
+
+    while (pending.length > 0) {
+        const frame = pending.at(-1);
+
+        if (!frame || pending.length > queryDepthMax || ++visited > queryNodesMax * 2) {
+            throw new PlatformError(
+                "UnsupportedCondition",
+                "Logical criteria exceed their nesting limit.",
+            );
+        }
+
+        spendContext(context);
+        const term = frame.group.terms[frame.index++];
+
+        if (!term) {
+            const result = groupPredicate(frame.group.operator, frame.terms);
+            pending.pop();
+            const parent = pending.at(-1);
+
+            if (!parent) {
+                return result;
+            }
+
+            parent.terms.push(result);
+        } else if ("operator" in term) {
+            pending.push({ group: term, terms: [], index: 0 });
+        } else if (term.item) {
+            frame.terms.push(await nestedPredicate(storage, definition, term, context, apply));
+        } else {
+            frame.terms.push(
+                propertyPredicate(resolveField(storage, definition, [term.name]), term),
+            );
+        }
+    }
+
+    throw new Error("A logical query must produce one predicate.");
+}
+
+function groupPredicate(operator: AmlLogicalOperator, terms: readonly Predicate[]): Predicate {
+    if (terms.length === 0) {
+        throw new PlatformError("InvalidSelector", "Logical groups must contain criteria.");
+    }
+
+    if (operator === AmlLogicalOperator.Not) {
+        return { kind: "not", term: conjunction(terms) };
+    }
+
+    return { kind: operator, terms };
+}
+
+async function nestedPredicate(
+    storage: HarnessStorage,
+    definition: ItemTypeDefinition,
+    condition: AmlPropertyCondition,
+    context: ExecutionContext,
+    apply: ApplyQueryItem,
+): Promise<Predicate> {
+    selectorType(storage, definition, condition);
+    const selector = condition.item;
+
+    if (!selector) {
+        throw new Error("A validated item selector must retain its request.");
+    }
+
+    const operator = (condition.attributes.condition ?? "eq").toLowerCase();
+    const result = await apply(new Item({ items: [selector] }), context);
+    requireSuccess(result);
+    const ids = result.payload.items.map((node) => node.attributes.id ?? "");
+
+    return setPredicate(
+        resolveField(storage, definition, [condition.name]),
+        ids,
+        operator === "ne" || operator === "not in",
+    );
+}
+
+function mentionsGeneration(root: Predicate): boolean {
+    const pending = [root];
+
+    while (pending.length > 0) {
+        const node = pending.pop();
+
+        if (!node) {
+            throw new Error("A predicate must exist while field inspection is pending.");
+        }
+
+        if (node.kind === "and" || node.kind === "or") {
+            pending.push(...node.terms);
+        } else if (node.kind === "not") {
+            pending.push(node.term);
+        } else if (
+            node.kind !== "constant" &&
+            node.field.path.length === 0 &&
+            ["id", "generation", "is_current"].includes(node.field.name)
+        ) {
+            return true;
+        }
+    }
+
+    return false;
+}
+
+async function getCriteria(
+    storage: HarnessStorage,
+    definition: ItemTypeDefinition,
+    request: ItemNode,
+    context: ExecutionContext,
+    apply: ApplyQueryItem,
+): Promise<Predicate[]> {
+    const terms: Predicate[] = [];
+    const field = (names: readonly string[]) => resolveField(storage, definition, names);
+
+    for (const [name, value] of Object.entries(request.properties)) {
+        if (name === "id" && request.attributes.id !== undefined && value === "") {
+            continue;
+        }
+
+        terms.push(
+            propertyPredicate(field([name]), {
+                name,
+                value,
+                attributes: request.propertyAttributes[name] ?? {},
+            }),
+        );
+    }
+
+    for (const [name, item] of Object.entries(request.propertyItems)) {
+        terms.push(
+            await nestedPredicate(
+                storage,
+                definition,
+                { name, item, attributes: request.propertyAttributes[name] ?? {} },
+                context,
+                apply,
+            ),
+        );
+    }
+
+    for (const group of request.logical ?? []) {
+        terms.push(await logicalPredicate(storage, definition, group, context, apply));
+    }
+
+    return terms;
+}

package/src/platform/queries/relationships.ts

@@ -0,0 +1,130 @@
+import { spendContext } from "../../core/context.js";
+import type { ExecutionContext } from "../../core/types.js";
+import { Item } from "../../items/item.js";
+import type { ItemNode } from "../../items/item.js";
+import { AmlLogicalOperator } from "../../items/logical.js";
+import type { HarnessStorage, ItemTypeDefinition, StoredItem } from "../../storage/types.js";
+import { PlatformError, requireSuccess } from "../errors.js";
+import { relationshipType } from "../relationship-type.js";
+import type { ApplyQueryItem } from "./planner.js";
+import { validateEmptyQuery } from "./validation.js";
+
+export interface RelationshipSelection {
+    readonly records: readonly StoredItem[];
+    readonly relationships: ReadonlyMap<string, readonly ItemNode[]>;
+}
+
+export class RelationshipQueries {
+    constructor(
+        private readonly storage: HarnessStorage,
+        private readonly apply: ApplyQueryItem,
+    ) {}
+
+    async select(
+        definition: ItemTypeDefinition,
+        request: ItemNode,
+        records: readonly StoredItem[],
+        context: ExecutionContext,
+    ): Promise<RelationshipSelection> {
+        for (const child of request.relationships) {
+            const target = relationshipType(this.storage, definition, child.type);
+
+            if (records.length === 0) {
+                validateEmptyQuery(this.storage, target, child);
+            }
+
+            if ((child.attributes.action ?? "get") !== "get") {
+                throw new PlatformError(
+                    "InvalidSelector",
+                    "Nested get requires relationship gets.",
+                );
+            }
+        }
+
+        const included: StoredItem[] = [];
+        const relationships = new Map<string, readonly ItemNode[]>();
+
+        for (const parent of records) {
+            let matches = true;
+            const children: ItemNode[] = [];
+
+            for (const child of request.relationships) {
+                spendContext(context);
+                const result = await this.get(child, parent, context);
+                children.push(...result.payload.items);
+
+                if (criteria(child) && result.payload.items.length === 0) {
+                    matches = false;
+                }
+            }
+
+            if (matches) {
+                included.push(parent);
+                relationships.set(parent.id, children);
+            }
+        }
+
+        return { records: included, relationships };
+    }
+
+    private async get(
+        request: ItemNode,
+        parent: StoredItem,
+        context: ExecutionContext,
+    ): Promise<Item> {
+        const scoped = new Item({ items: [request] }).clone().node;
+        scoped.logical = [
+            ...(scoped.logical ?? []),
+            {
+                operator: AmlLogicalOperator.And,
+                terms: [{ name: "source_id", attributes: {}, value: parent.id }],
+            },
+        ];
+        const result = requireSuccess(await this.apply(new Item({ items: [scoped] }), context));
+
+        for (const child of result.payload.items) {
+            const stored = this.storage.getItem(request.type, child.attributes.id ?? "");
+
+            if (
+                child.type.toLowerCase() !== request.type.toLowerCase() ||
+                String(stored?.properties.source_id).toLowerCase() !== parent.id.toLowerCase()
+            ) {
+                throw new PlatformError(
+                    "RelationshipSource",
+                    "A nested query returned a relationship outside its parent scope.",
+                );
+            }
+        }
+
+        return result;
+    }
+}
+
+function criteria(request: ItemNode): boolean {
+    const pending = [request];
+
+    while (pending.length > 0) {
+        const node = pending.pop();
+
+        if (!node) {
+            throw new Error("A relationship criterion must exist while inspection is pending.");
+        }
+
+        if (node.attributes.isCriteria === "0") {
+            continue;
+        }
+
+        if (
+            Object.keys(node.properties).length > 0 ||
+            Object.keys(node.propertyItems).length > 0 ||
+            (node.logical?.length ?? 0) > 0 ||
+            ["where", "id", "idlist"].some((name) => node.attributes[name] !== undefined)
+        ) {
+            return true;
+        }
+
+        pending.push(...node.relationships);
+    }
+
+    return false;
+}