@innovatorstack/harness 0.0.0-stage → 0.1.1

package/src/platform/locks.ts

@@ -0,0 +1,251 @@
+import { assertActiveContext } from "../core/context.js";
+import type { ExecutionContext } from "../core/types.js";
+import { Item } from "../items/item.js";
+import type { SelectQuery } from "../queries/types.js";
+import type { HarnessStorage, ItemTypeDefinition, StoredItem } from "../storage/types.js";
+import { PlatformError, requireSuccess } from "./errors.js";
+import type { RunEvents } from "./events/types.js";
+import { projectItem } from "./projection.js";
+import type { ReferenceCatalog } from "./references/catalog.js";
+import type { PlatformTrace } from "./trace.js";
+import { ItemUnlocks } from "./unlocking.js";
+import { manualVersioning } from "./version-policy.js";
+
+/** Locks are database state, so nested calls and transaction rollback see the same owner. */
+export class ItemLocks {
+    private readonly unlocks: ItemUnlocks;
+
+    constructor(
+        private readonly storage: HarnessStorage,
+        private readonly trace: PlatformTrace,
+        private readonly events: RunEvents,
+        private readonly userId: (() => string) | undefined,
+        private readonly dispatch: (item: Item, context: ExecutionContext) => Promise<Item>,
+        catalog: ReferenceCatalog,
+        select?: SelectQuery,
+    ) {
+        this.unlocks = new ItemUnlocks(storage, trace, events, () => this.owner(), catalog, select);
+    }
+
+    async unlockVersionSources(
+        definition: ItemTypeDefinition,
+        sources: readonly StoredItem[],
+        context: ExecutionContext,
+    ): Promise<void> {
+        await this.unlocks.unlockVersionSources(definition, sources, context);
+    }
+
+    async unlockAfterEdit(
+        definition: ItemTypeDefinition,
+        records: readonly StoredItem[],
+        request: Item,
+        context: ExecutionContext,
+    ): Promise<void> {
+        await this.unlocks.unlockVersionSources(definition, records, context, request);
+    }
+
+    async lockForEdit(
+        definition: ItemTypeDefinition,
+        records: readonly StoredItem[],
+        request: Item,
+        context: ExecutionContext,
+    ): Promise<void> {
+        for (const record of records) {
+            this.assertLockable(record);
+        }
+
+        if (records.some((record) => Boolean(record.properties.locked_by_id))) {
+            return;
+        }
+
+        const event = request.clone();
+        delete event.node.attributes.where;
+        delete event.node.attributes.idlist;
+
+        for (const record of records) {
+            event.setProperty("id", record.id);
+            await this.events(definition, "onBeforeLock", event, true, context);
+            this.assertEditContext(definition, request, event, record.id);
+        }
+
+        for (const record of records) {
+            this.write(definition, record, "lock", context);
+        }
+
+        for (const record of records) {
+            event.setProperty("id", record.id);
+            await this.events(definition, "onAfterLock", event, true, context);
+            this.assertEditContext(definition, request, event, record.id);
+        }
+    }
+
+    private assertEditContext(
+        definition: ItemTypeDefinition,
+        request: Item,
+        event: Item,
+        id: string,
+    ): void {
+        if (
+            event.getType() !== definition.name ||
+            event.getAction() !== request.getAction() ||
+            event.getID() !== id
+        ) {
+            throw new PlatformError(
+                "UnsupportedContextChange",
+                "An implicit lock hook must retain its ItemType, action and target ID.",
+            );
+        }
+    }
+
+    owner(): string {
+        const id = this.userId?.();
+
+        if (!id) {
+            throw new PlatformError(
+                "SessionRequired",
+                "Locking and versionable updates require a configured User session.",
+            );
+        }
+
+        return id;
+    }
+
+    assertOwned(record: StoredItem): void {
+        const owner = this.owner();
+
+        if (String(record.properties.locked_by_id ?? "").toLowerCase() !== owner.toLowerCase()) {
+            throw new PlatformError(
+                "LockOwnership",
+                `Record '${record.type}:${record.id}' must be locked by the current User before updating.`,
+            );
+        }
+    }
+
+    assertAvailable(record: StoredItem): void {
+        const currentOwner = String(record.properties.locked_by_id ?? "");
+
+        if (currentOwner && currentOwner.toLowerCase() !== this.owner().toLowerCase()) {
+            throw new PlatformError(
+                "LockOwnership",
+                `Record '${record.type}:${record.id}' is locked by another User.`,
+            );
+        }
+    }
+
+    private assertLockable(record: StoredItem): void {
+        this.assertAvailable(record);
+
+        if (String(record.properties.not_lockable ?? "0") === "1") {
+            throw new PlatformError(
+                "NotLockable",
+                `Record '${record.type}:${record.id}' cannot be locked in its current state.`,
+            );
+        }
+    }
+
+    async apply(
+        definition: ItemTypeDefinition,
+        record: StoredItem,
+        action: "lock" | "unlock",
+        context: ExecutionContext,
+        enabled = true,
+    ): Promise<StoredItem> {
+        const request = Item.create(definition.name, action);
+        request.setProperty("id", record.id);
+        request.setAttribute("doGetItem", "0");
+
+        if (!enabled) {
+            request.setAttribute("serverEvents", "0");
+        }
+
+        requireSuccess(await this.dispatch(request, context));
+        const current = this.storage.getItem(definition.name, record.id);
+
+        if (!current) {
+            throw new PlatformError("MissingItem", "The lock target disappeared in its event.");
+        }
+
+        return current;
+    }
+
+    async base(
+        definition: ItemTypeDefinition,
+        record: StoredItem,
+        action: "lock" | "unlock",
+        context: ExecutionContext,
+        request: Item,
+    ): Promise<Item> {
+        this.owner();
+        const currentOwner = String(record.properties.locked_by_id ?? "");
+        this.assertAvailable(record);
+
+        if (action === "lock" && String(record.properties.not_lockable ?? "0") === "1") {
+            throw new PlatformError(
+                "NotLockable",
+                `Record '${record.type}:${record.id}' cannot be locked in its current state.`,
+            );
+        }
+
+        if ((action === "lock") === Boolean(currentOwner)) {
+            return new Item({
+                items: [
+                    projectItem(this.storage, definition, record, request.node.attributes.select),
+                ],
+            });
+        }
+
+        const verb = action === "lock" ? "Lock" : "Unlock";
+
+        const event = request.clone();
+        event.setProperty("id", record.id);
+        delete event.node.attributes.where;
+        delete event.node.attributes.idlist;
+        const enabled = request.getAttribute("serverEvents") !== "0";
+        await this.events(definition, `onBefore${verb}`, event, enabled, context);
+
+        if (
+            event.getType() !== definition.name ||
+            event.getAction() !== action ||
+            event.getID() !== record.id
+        ) {
+            throw new PlatformError(
+                "UnsupportedContextChange",
+                "A lock event cannot change the ItemType, action or target ID.",
+            );
+        }
+
+        const after = this.write(definition, record, action, context);
+        const response = new Item({
+            items: [projectItem(this.storage, definition, after, request.node.attributes.select)],
+        });
+        await this.events(definition, `onAfter${verb}`, response, enabled, context);
+
+        return response;
+    }
+
+    private write(
+        definition: ItemTypeDefinition,
+        record: StoredItem,
+        action: "lock" | "unlock",
+        context: ExecutionContext,
+    ): StoredItem {
+        assertActiveContext(context);
+        this.storage.updateItem(definition.name, record.id, {
+            locked_by_id: action === "lock" ? this.owner() : null,
+            ...(action === "unlock" &&
+            definition.isVersionable &&
+            !manualVersioning(this.storage, definition)
+                ? { new_version: 0 }
+                : {}),
+        });
+        const after = this.storage.getItem(definition.name, record.id);
+
+        if (!after) {
+            throw new PlatformError("MissingItem", "Locked record disappeared.");
+        }
+
+        this.trace.record(context, { kind: "mutation", name: action, before: record, after });
+
+        return after;
+    }
+}

package/src/platform/projection.ts

@@ -0,0 +1,262 @@
+import { setOwn, getOwn } from "../core/data.js";
+import { dataBytesMax, dataDepthMax, dataNodesMax } from "../core/limits.js";
+import { itemNode } from "../items/item.js";
+import type { ItemNode } from "../items/item.js";
+import type { HarnessStorage, ItemTypeDefinition, StoredItem } from "../storage/types.js";
+import { PlatformError } from "./errors.js";
+import { projectedProperties } from "./query.js";
+
+interface Selection {
+    readonly name: string;
+    readonly children?: readonly Selection[];
+}
+
+type VisibleItem = (definition: ItemTypeDefinition, record: StoredItem) => boolean;
+
+/** Read projection only; business actions and events remain in the dispatcher. */
+export function projectItem(
+    storage: HarnessStorage,
+    definition: ItemTypeDefinition,
+    record: StoredItem,
+    expression?: string,
+): ItemNode {
+    return compileProjection(storage, definition, expression)(record);
+}
+
+export function compileProjection(
+    storage: HarnessStorage,
+    definition: ItemTypeDefinition,
+    expression?: string,
+    visible?: VisibleItem,
+): (record: StoredItem) => ItemNode {
+    const selection = expression ? new SelectParser(expression).parse() : undefined;
+    const pending = [{ definition, fields: selection ?? [] }];
+
+    while (pending.length > 0) {
+        const frame = pending.pop();
+
+        if (!frame) {
+            throw new Error("A projection frame must exist while metadata validation is pending.");
+        }
+
+        for (const field of frame.fields) {
+            if (field.name === "*" || field.name === "id") {
+                if (field.children) {
+                    throw new PlatformError(
+                        "UnsupportedSelect",
+                        "Only item properties can expand.",
+                    );
+                }
+
+                continue;
+            }
+
+            const property = frame.definition.properties.find(
+                (property) => property.name === field.name,
+            );
+
+            if (!property) {
+                throw new PlatformError(
+                    "UnknownProperty",
+                    `Unknown property '${frame.definition.name}.${field.name}'.`,
+                );
+            }
+
+            if (field.children) {
+                const target = storage
+                    .listItemTypes()
+                    .find((type) => type.id === property.dataSource);
+
+                if (property.dataType !== "item" || !target) {
+                    throw new PlatformError(
+                        "UnsupportedSelect",
+                        `Property '${field.name}' has no ItemType target to expand.`,
+                    );
+                }
+
+                pending.push({ definition: target, fields: field.children });
+            }
+        }
+    }
+
+    return (record) => project(storage, definition, record, selection, visible);
+}
+
+function project(
+    storage: HarnessStorage,
+    definition: ItemTypeDefinition,
+    record: StoredItem,
+    selection: readonly Selection[] | undefined,
+    visible: VisibleItem | undefined,
+): ItemNode {
+    const node = projectionNode(storage, definition, record, selection);
+    const pending = [{ node, definition, record, selection, depth: 0 }];
+    let visited = 0;
+
+    while (pending.length > 0) {
+        const frame = pending.pop();
+
+        if (!frame) {
+            throw new Error("A projection frame must exist while expansion is pending.");
+        }
+
+        visited += 1;
+
+        if (visited > dataNodesMax || frame.depth > dataDepthMax) {
+            throw new PlatformError(
+                "UnsupportedSelect",
+                "Projection exceeds its work or nesting limit.",
+            );
+        }
+
+        for (const field of frame.selection ?? []) {
+            if (!field.children) {
+                continue;
+            }
+
+            const target = expansionTarget(storage, frame.definition, frame.record, field.name);
+
+            if (!target || (visible && !visible(target.definition, target.record))) {
+                continue;
+            }
+
+            const node = projectionNode(storage, target.definition, target.record, field.children);
+            setOwn(frame.node.propertyItems, field.name, node);
+            pending.push({ ...target, node, selection: field.children, depth: frame.depth + 1 });
+        }
+    }
+
+    return node;
+}
+
+function projectionNode(
+    storage: HarnessStorage,
+    definition: ItemTypeDefinition,
+    record: StoredItem,
+    selection: readonly Selection[] | undefined,
+): ItemNode {
+    const node = itemNode(definition.name);
+    const names = selection?.some((field) => field.name === "*")
+        ? undefined
+        : selection?.map((field) => field.name);
+    node.attributes.id = record.id;
+    node.properties = projectedProperties(storage, definition, record, names);
+
+    return node;
+}
+
+function expansionTarget(
+    storage: HarnessStorage,
+    definition: ItemTypeDefinition,
+    record: StoredItem,
+    name: string,
+): { definition: ItemTypeDefinition; record: StoredItem } | undefined {
+    const property = definition.properties.find((property) => property.name === name);
+    const targetType = storage.listItemTypes().find((type) => type.id === property?.dataSource);
+
+    if (property?.dataType !== "item" || !targetType) {
+        throw new PlatformError(
+            "UnsupportedSelect",
+            `'${definition.name}.${name}' has no ItemType target to expand.`,
+        );
+    }
+
+    const id = getOwn(record.properties, name);
+
+    if (id === undefined || id === null || id === "") {
+        return undefined;
+    }
+
+    const target = typeof id === "string" ? storage.getItem(targetType.name, id) : undefined;
+
+    if (!target) {
+        throw new PlatformError(
+            "MissingReference",
+            `Cannot expand '${definition.name}.${name}': target '${id}' is missing.`,
+        );
+    }
+
+    return { definition: targetType, record: target };
+}
+
+class SelectParser {
+    private offset = 0;
+
+    constructor(private readonly expression: string) {}
+
+    parse(): readonly Selection[] {
+        if (this.expression.length > dataBytesMax) {
+            this.fail();
+        }
+
+        const fields: Selection[] = [];
+        const pending = [{ fields, expectsField: true }];
+        let count = 0;
+
+        while (this.offset <= this.expression.length) {
+            const frame = pending.at(-1);
+
+            if (!frame) {
+                throw new Error("A select frame must exist while parsing is pending.");
+            }
+
+            this.whitespace();
+
+            if (frame.expectsField) {
+                count += 1;
+
+                if (count > dataNodesMax || pending.length > dataDepthMax) {
+                    this.fail();
+                }
+
+                const name = /^(?:[A-Za-z_][\w]*|\*)/.exec(this.expression.slice(this.offset))?.[0];
+
+                if (!name) {
+                    this.fail();
+                }
+
+                this.offset += name.length;
+                this.whitespace();
+                frame.expectsField = false;
+
+                if (this.expression[this.offset] === "(") {
+                    if (name === "*") {
+                        this.fail();
+                    }
+
+                    const children: Selection[] = [];
+                    frame.fields.push({ name, children });
+                    pending.push({ fields: children, expectsField: true });
+                    this.offset += 1;
+                } else {
+                    frame.fields.push({ name });
+                }
+            } else if (this.expression[this.offset] === ",") {
+                frame.expectsField = true;
+                this.offset += 1;
+            } else if (this.expression[this.offset] === ")" && pending.length > 1) {
+                pending.pop();
+                this.offset += 1;
+            } else if (this.offset === this.expression.length && pending.length === 1) {
+                return fields;
+            } else {
+                this.fail();
+            }
+        }
+
+        return this.fail();
+    }
+
+    private whitespace(): void {
+        while (/\s/.test(this.expression[this.offset] ?? "")) {
+            this.offset += 1;
+        }
+    }
+
+    private fail(): never {
+        throw new PlatformError(
+            "UnsupportedSelect",
+            `Invalid select '${this.expression}' at position ${this.offset + 1}.`,
+        );
+    }
+}

package/src/platform/queries/conditions.ts

@@ -0,0 +1,69 @@
+import type { AmlPropertyCondition } from "../../items/logical.js";
+import { PredicateParser } from "../../queries/parser.js";
+import { comparison, likePredicate, setPredicate } from "../../queries/predicates.js";
+import { Comparison } from "../../queries/types.js";
+import type { Predicate, QueryField } from "../../queries/types.js";
+import { PlatformError } from "../errors.js";
+
+export function propertyPredicate(field: QueryField, property: AmlPropertyCondition): Predicate {
+    const condition = (property.attributes.condition ?? "eq").trim().toLowerCase();
+    const value = property.attributes.is_null === "1" ? null : property.value;
+
+    if (value === undefined) {
+        throw new PlatformError("InvalidSelector", `Selector '${property.name}' needs a value.`);
+    }
+
+    if (condition === "is null" || condition === "is not null" || condition === "is") {
+        const negate =
+            condition === "is"
+                ? String(value).trim().toLowerCase() === "not null"
+                : condition === "is not null";
+
+        if (
+            condition === "is" &&
+            !["null", "not null"].includes(String(value).trim().toLowerCase())
+        ) {
+            throw new PlatformError("UnsupportedCondition", "IS requires NULL or NOT NULL.");
+        }
+
+        return { kind: "null", field, negate };
+    }
+
+    if (condition === "in" || condition === "not in") {
+        const values = new PredicateParser(String(value), () => field).scalarList();
+
+        return setPredicate(field, values, condition === "not in");
+    }
+
+    if (condition === "between" || condition === "not between") {
+        const [first, last] = new PredicateParser(String(value), () => field).range();
+        const term: Predicate = {
+            kind: "and",
+            terms: [
+                comparison(field, Comparison.GreaterOrEqual, first),
+                comparison(field, Comparison.LessOrEqual, last),
+            ],
+        };
+
+        return condition === "not between" ? { kind: "not", term } : term;
+    }
+
+    if (condition === "like" || condition === "not like") {
+        return likePredicate(field, String(value), condition === "not like");
+    }
+
+    const operator = Object.values(Comparison).find((operator: string) => operator === condition);
+
+    if (operator === undefined) {
+        throw new PlatformError(
+            "UnsupportedCondition",
+            `Property condition '${condition}' is not implemented.`,
+        );
+    }
+
+    if (value === null && (operator === Comparison.Equal || operator === Comparison.NotEqual)) {
+        return { kind: "null", field, negate: operator === Comparison.NotEqual };
+    }
+
+    return comparison(field, operator, value);
+}

package/src/platform/queries/engine.ts

@@ -0,0 +1,69 @@
+import { spendContext } from "../../core/context.js";
+import type { ExecutionContext } from "../../core/types.js";
+import type { ItemNode } from "../../items/item.js";
+import { evaluate } from "../../queries/evaluate.js";
+import type { SelectQuery } from "../../queries/types.js";
+import type { HarnessStorage, ItemTypeDefinition, StoredItem } from "../../storage/types.js";
+import { fieldValue } from "./fields.js";
+import { orderBy, orderRows } from "./order.js";
+import { pageRows } from "./paging.js";
+import type { PageSelection } from "./paging.js";
+import { requestPredicate } from "./planner.js";
+import type { ApplyQueryItem } from "./planner.js";
+import { RelationshipQueries } from "./relationships.js";
+
+/** Schema resolution and execution policy are shared; SQLite only optimizes predicate selection. */
+export class ItemQueries {
+    constructor(
+        private readonly storage: HarnessStorage,
+        private readonly apply: ApplyQueryItem,
+        private readonly select?: SelectQuery,
+        private readonly visible?: (
+            definition: ItemTypeDefinition,
+            records: readonly StoredItem[],
+            context: ExecutionContext,
+        ) => readonly StoredItem[],
+    ) {}
+
+    async run(
+        definition: ItemTypeDefinition,
+        request: ItemNode,
+        context: ExecutionContext,
+    ): Promise<PageSelection> {
+        const predicate = await requestPredicate(
+            this.storage,
+            definition,
+            request,
+            context,
+            this.apply,
+        );
+        const orders = orderBy(this.storage, definition, request.attributes.orderBy);
+        const spend = (units: number) => {
+            spendContext(context, units);
+        };
+        const candidates = this.select
+            ? this.select(definition.name, predicate, spend)
+            : this.storage.listItems(definition.name);
+        const filtered = candidates.filter((record) =>
+            evaluate(predicate, (field) => fieldValue(this.storage, record, field), spend),
+        );
+        const matching =
+            (request.attributes.action ?? "get") === "get" && this.visible
+                ? this.visible(definition, filtered, context)
+                : filtered;
+
+        if (request.relationships.length === 0 || (request.attributes.action ?? "get") !== "get") {
+            return pageRows(request, orderRows(this.storage, matching, orders, spend));
+        }
+
+        const nested = await new RelationshipQueries(this.storage, this.apply).select(
+            definition,
+            request,
+            matching,
+            context,
+        );
+        const page = pageRows(request, orderRows(this.storage, nested.records, orders, spend));
+
+        return { ...page, relationships: nested.relationships };
+    }
+}