@innovatorstack/harness 0.0.0-stage → 0.1.1

package/src/items/item.ts

@@ -0,0 +1,218 @@
+import { getOwn, setOwn } from "../core/data.js";
+import type { StorageValue } from "../storage/types.js";
+import type { AmlLogicalGroup } from "./logical.js";
+import { cloneItemPayload } from "./origins.js";
+
+export { AmlLogicalOperator } from "./logical.js";
+export type { AmlLogicalGroup, AmlLogicalTerm, AmlPropertyCondition } from "./logical.js";
+
+export interface ItemNode {
+    type: string;
+    attributes: Record<string, string>;
+    properties: Record<string, StorageValue>;
+    propertyItems: Record<string, ItemNode>;
+    propertyAttributes: Record<string, Record<string, string>>;
+    relationships: ItemNode[];
+    logical?: readonly AmlLogicalGroup[];
+}
+
+export interface ItemError {
+    readonly code: string;
+    readonly message: string;
+}
+
+export interface ItemPayload {
+    items: ItemNode[];
+    error?: ItemError;
+    result?: string;
+    messages?: readonly ItemMessage[];
+}
+
+export interface ItemMessage {
+    readonly name: string;
+    readonly value: string;
+}
+
+export function itemNode(type: string, action?: string): ItemNode {
+    return {
+        type,
+        attributes: action ? { action } : {},
+        properties: {},
+        propertyItems: {},
+        propertyAttributes: {},
+        relationships: [],
+    };
+}
+
+export class Item {
+    constructor(readonly payload: ItemPayload) {}
+
+    static create(type: string, action?: string): Item {
+        return new Item({ items: [itemNode(type, action)] });
+    }
+
+    static error(message: string, code = "ApplicationError"): Item {
+        return new Item({ items: [], error: { code, message } });
+    }
+
+    isError(): boolean {
+        return this.payload.error !== undefined;
+    }
+
+    getErrorString(): string {
+        return this.payload.error?.message ?? "";
+    }
+
+    getErrorCode(): string {
+        return this.payload.error?.code ?? "";
+    }
+
+    getResult(): string {
+        return this.payload.result ?? "";
+    }
+
+    getPropertyAttribute(property: string, attribute: string, fallback = ""): string {
+        const attributes = getOwn(this.node.propertyAttributes, property);
+
+        return attributes ? (getOwn(attributes, attribute) ?? fallback) : fallback;
+    }
+
+    setPropertyAttribute(property: string, attribute: string, value: string): void {
+        let attributes = getOwn(this.node.propertyAttributes, property);
+
+        if (!attributes) {
+            attributes = {};
+            setOwn(this.node.propertyAttributes, property, attributes);
+        }
+
+        setOwn(attributes, attribute, value);
+    }
+
+    getItemCount(): number {
+        if (this.isError()) {
+            return -1;
+        }
+
+        return this.payload.items.length;
+    }
+
+    getItemByIndex(index: number): Item {
+        const node = this.payload.items[index];
+
+        if (!node) {
+            throw new RangeError(`Item index ${index} is outside this collection.`);
+        }
+
+        return new Item({ items: [node] });
+    }
+
+    getID(): string {
+        return this.node.attributes.id ?? "";
+    }
+
+    getType(): string {
+        return this.node.type;
+    }
+
+    setType(type: string): void {
+        this.node.type = type;
+    }
+
+    getAction(): string {
+        return this.getAttribute("action", "get");
+    }
+
+    setAction(action: string): void {
+        this.setAttribute("action", action);
+    }
+
+    getAttribute(name: string, fallback = ""): string {
+        if (name === "type") {
+            return this.node.type;
+        }
+
+        return getOwn(this.node.attributes, name) ?? fallback;
+    }
+
+    setAttribute(name: string, value: string): void {
+        if (name === "type") {
+            this.node.type = value;
+
+            return;
+        }
+
+        setOwn(this.node.attributes, name, value);
+    }
+
+    getProperty(name: string, fallback = ""): string {
+        if (name === "id") {
+            return this.getID() || fallback;
+        }
+
+        const value = getOwn(this.node.properties, name);
+
+        if (value === null || value === undefined) {
+            return fallback;
+        }
+
+        return String(value);
+    }
+
+    setProperty(name: string, value: StorageValue): void {
+        if (name === "id") {
+            if (typeof value !== "string") {
+                throw new TypeError("Item ID must be a string.");
+            }
+
+            this.node.attributes.id = value;
+        } else {
+            delete this.node.propertyItems[name];
+            setOwn(this.node.properties, name, value);
+        }
+    }
+
+    setPropertyItem(name: string, item: Item): void {
+        delete this.node.properties[name];
+        setOwn(this.node.propertyItems, name, item.node);
+    }
+
+    getPropertyItem(name: string): Item | undefined {
+        const node = getOwn(this.node.propertyItems, name);
+
+        if (node) {
+            return new Item({ items: [node] });
+        }
+
+        return undefined;
+    }
+
+    addRelationship(item: Item): void {
+        this.node.relationships.push(item.node);
+    }
+
+    getRelationships(type?: string): Item {
+        return new Item({
+            items: this.node.relationships.filter(
+                (node) => type === undefined || node.type.toLowerCase() === type.toLowerCase(),
+            ),
+        });
+    }
+
+    clone(): Item {
+        return new Item(cloneItemPayload(this.payload));
+    }
+
+    get node(): ItemNode {
+        if (this.isError() || this.payload.items.length !== 1) {
+            throw new TypeError("This operation requires one non-error Item.");
+        }
+
+        const node = this.payload.items[0];
+
+        if (!node) {
+            throw new TypeError("Item is missing its context.");
+        }
+
+        return node;
+    }
+}

package/src/items/logical.ts

@@ -0,0 +1,145 @@
+import type { ItemNode } from "./item.js";
+
+export enum AmlLogicalOperator {
+    And = "and",
+    Or = "or",
+    Not = "not",
+}
+
+export interface AmlPropertyCondition {
+    readonly name: string;
+    readonly attributes: Readonly<Record<string, string>>;
+    readonly value?: string | number | null;
+    readonly item?: ItemNode;
+}
+
+export interface AmlLogicalGroup {
+    readonly operator: AmlLogicalOperator;
+    readonly terms: readonly AmlLogicalTerm[];
+    /** Repeated direct properties share the root's implicit AND without adding an XML tag. */
+    readonly implicit?: boolean;
+}
+
+export type AmlLogicalTerm = AmlLogicalGroup | AmlPropertyCondition;
+
+export function logicalOperator(name: string): AmlLogicalOperator | undefined {
+    switch (name) {
+        case "and": {
+            return AmlLogicalOperator.And;
+        }
+        case "or": {
+            return AmlLogicalOperator.Or;
+        }
+        case "not": {
+            return AmlLogicalOperator.Not;
+        }
+        default: {
+            return undefined;
+        }
+    }
+}
+
+/** Item nodes are attached to the caller's work stack; logical decoding never recurses. */
+export function decodeLogical(
+    value: unknown,
+    item: (value: unknown) => ItemNode,
+): readonly AmlLogicalGroup[] {
+    if (!Array.isArray(value)) {
+        throw new TypeError("Logical AML requires an array of groups.");
+    }
+
+    const roots: AmlLogicalGroup[] = [];
+    const pending: {
+        readonly input: unknown;
+        readonly output: AmlLogicalTerm[];
+        readonly depth: number;
+    }[] = [];
+
+    for (let index = value.length - 1; index >= 0; index -= 1) {
+        const input: unknown = value[index];
+        pending.push({ input, output: roots, depth: 0 });
+    }
+
+    let visited = 0;
+
+    while (pending.length > 0) {
+        const frame = pending.pop();
+
+        if (!frame || !record(frame.input) || ++visited > 100_000 || frame.depth > 128) {
+            throw new TypeError("Logical AML exceeds its node or nesting limit.");
+        }
+
+        const operator =
+            typeof frame.input.operator === "string"
+                ? logicalOperator(frame.input.operator)
+                : undefined;
+
+        if (frame.input.operator !== undefined && operator === undefined) {
+            throw new TypeError("Invalid logical AML operator.");
+        }
+
+        if (operator !== undefined) {
+            const terms: AmlLogicalTerm[] = [];
+            const implicit = frame.input.implicit === true;
+
+            if (
+                !Array.isArray(frame.input.terms) ||
+                (implicit && (operator !== AmlLogicalOperator.And || frame.depth !== 0))
+            ) {
+                throw new TypeError("Invalid logical AML group.");
+            }
+
+            frame.output.push({ operator, terms, ...(implicit ? { implicit } : {}) });
+
+            for (let index = frame.input.terms.length - 1; index >= 0; index -= 1) {
+                const input: unknown = frame.input.terms[index];
+                pending.push({ input, output: terms, depth: frame.depth + 1 });
+            }
+        } else {
+            if (frame.depth === 0) {
+                throw new TypeError("Top-level logical AML must contain groups.");
+            }
+
+            frame.output.push(decodeCondition(frame.input, item));
+        }
+    }
+
+    return roots;
+}
+
+function decodeCondition(
+    value: Record<string, unknown>,
+    item: (value: unknown) => ItemNode,
+): AmlPropertyCondition {
+    if (typeof value.name !== "string" || !record(value.attributes)) {
+        throw new TypeError("Logical criteria need a property name and attributes.");
+    }
+
+    const attributes: Record<string, string> = {};
+
+    for (const [name, text] of Object.entries(value.attributes)) {
+        if (typeof text !== "string") {
+            throw new TypeError("Logical property attributes must contain text.");
+        }
+
+        Object.defineProperty(attributes, name, { value: text, enumerable: true });
+    }
+
+    if (value.item !== undefined && value.item !== null) {
+        return { name: value.name, attributes, item: item(value.item) };
+    }
+
+    if (
+        value.value !== null &&
+        typeof value.value !== "string" &&
+        (typeof value.value !== "number" || !Number.isFinite(value.value))
+    ) {
+        throw new TypeError("Logical properties require a scalar value or nested Item.");
+    }
+
+    return { name: value.name, attributes, value: value.value };
+}
+
+function record(value: unknown): value is Record<string, unknown> {
+    return value !== null && typeof value === "object" && !Array.isArray(value);
+}

package/src/items/origins.ts

@@ -0,0 +1,139 @@
+import { cloneData } from "../core/data.js";
+import { dataDepthMax, dataNodesMax } from "../core/limits.js";
+import type { ItemNode, ItemPayload } from "./item.js";
+import type { AmlLogicalTerm } from "./logical.js";
+
+type Frame =
+    | { readonly node: ItemNode; readonly depth: number }
+    | { readonly term: AmlLogicalTerm; readonly depth: number };
+
+const origins = new WeakMap<ItemNode, symbol>();
+
+export function itemOrigin(node: ItemNode): symbol | undefined {
+    return origins.get(node);
+}
+
+export function bindItemOrigin(node: ItemNode, origin: symbol): void {
+    origins.set(node, origin);
+}
+
+/** Origin metadata belongs to pending Items, never to business AML or stored records. */
+export function cloneItemPayload(payload: ItemPayload): ItemPayload {
+    const result = cloneData(payload);
+    const copied = itemNodes(result);
+
+    for (const original of itemNodes(payload)) {
+        const next = copied.next();
+
+        if (next.done) {
+            throw new Error("An Item clone must retain the complete source tree.");
+        }
+
+        const origin = origins.get(original);
+
+        if (origin !== undefined) {
+            origins.set(next.value, origin);
+        }
+    }
+
+    if (!copied.next().done) {
+        throw new Error("An Item clone cannot introduce new source nodes.");
+    }
+
+    return result;
+}
+
+// Shared wire order: logical Items, ordinal property Items, then ordered relationships.
+export function* itemNodes(payload: ItemPayload): Generator<ItemNode> {
+    if (payload.items.length > dataNodesMax) {
+        throw new TypeError("Item origins exceed their root limit.");
+    }
+
+    const pending: Frame[] = [];
+
+    for (let index = payload.items.length - 1; index >= 0; index -= 1) {
+        const node = payload.items[index];
+
+        if (node) {
+            pending.push({ node, depth: 0 });
+        }
+    }
+
+    let visited = 0;
+
+    while (pending.length > 0) {
+        const frame = pending.pop();
+
+        if (
+            !frame ||
+            ++visited > dataNodesMax ||
+            frame.depth > dataDepthMax ||
+            pending.length > dataNodesMax
+        ) {
+            throw new TypeError("Item origins exceed their node or nesting limit.");
+        }
+
+        if ("term" in frame) {
+            appendLogical(frame.term, frame.depth, pending);
+            continue;
+        }
+
+        yield frame.node;
+        appendChildren(frame.node, frame.depth, pending);
+
+        if (pending.length > dataNodesMax) {
+            throw new TypeError("Item origins exceed their pending node limit.");
+        }
+    }
+}
+
+function appendChildren(node: ItemNode, depth: number, pending: Frame[]): void {
+    const names = Object.keys(node.propertyItems).sort().reverse();
+    const children = node.relationships.length + names.length + (node.logical?.length ?? 0);
+
+    if (children > dataNodesMax - pending.length) {
+        throw new TypeError("Item origins exceed their pending node limit.");
+    }
+
+    for (let index = node.relationships.length - 1; index >= 0; index -= 1) {
+        const child = node.relationships[index];
+
+        if (child) {
+            pending.push({ node: child, depth: depth + 1 });
+        }
+    }
+
+    for (const name of names) {
+        const child = node.propertyItems[name];
+
+        if (child) {
+            pending.push({ node: child, depth: depth + 1 });
+        }
+    }
+
+    for (let index = (node.logical?.length ?? 0) - 1; index >= 0; index -= 1) {
+        const term = node.logical?.[index];
+
+        if (term) {
+            pending.push({ term, depth: depth + 1 });
+        }
+    }
+}
+
+function appendLogical(term: AmlLogicalTerm, depth: number, pending: Frame[]): void {
+    if ("operator" in term) {
+        if (term.terms.length > dataNodesMax - pending.length) {
+            throw new TypeError("Item origins exceed their pending node limit.");
+        }
+
+        for (let index = term.terms.length - 1; index >= 0; index -= 1) {
+            const child = term.terms[index];
+
+            if (child) {
+                pending.push({ term: child, depth: depth + 1 });
+            }
+        }
+    } else if (term.item) {
+        pending.push({ node: term.item, depth: depth + 1 });
+    }
+}

package/src/items/xml.ts

@@ -0,0 +1,187 @@
+import { setOwn } from "../core/data.js";
+import { childElements, textContent } from "../packages/elements.js";
+import { parseAml } from "../packages/parser.js";
+import type { AmlElement } from "../packages/types.js";
+import { Item, itemNode } from "./item.js";
+import type { ItemNode } from "./item.js";
+import { AmlLogicalOperator, logicalOperator } from "./logical.js";
+import type { AmlLogicalGroup, AmlLogicalTerm, AmlPropertyCondition } from "./logical.js";
+
+type Frame =
+    | {
+          readonly kind: "item";
+          readonly element: AmlElement;
+          readonly node: ItemNode;
+          readonly logical: AmlLogicalGroup[];
+          readonly repeated: AmlLogicalTerm[];
+          relationshipsSeen: boolean;
+      }
+    | { readonly kind: "group"; readonly element: AmlElement; readonly terms: AmlLogicalTerm[] };
+
+/** Items and logical groups share one work stack, including nested item-property criteria. */
+export function itemNodeFromElement(element: AmlElement): ItemNode {
+    const pending: Frame[] = [];
+    const root = appendItem(element, pending);
+
+    while (pending.length > 0) {
+        const frame = pending.pop();
+
+        if (!frame) {
+            throw new Error("An AML frame must exist while conversion is pending.");
+        }
+
+        for (const property of childElements(frame.element)) {
+            const operator = logicalOperator(property.name);
+
+            if (operator !== undefined) {
+                const terms: AmlLogicalTerm[] = [];
+                const group = { operator, terms };
+
+                if (Object.keys(property.attributes).length > 0 || textContent(property).trim()) {
+                    throw new TypeError("Logical groups cannot contain attributes or mixed text.");
+                }
+
+                if (frame.kind === "item") {
+                    frame.logical.push(group);
+                    frame.node.logical = frame.logical;
+                } else {
+                    frame.terms.push(group);
+                }
+
+                pending.push({ kind: "group", element: property, terms });
+            } else if (frame.kind === "item" && property.name === "Relationships") {
+                readRelationships(frame, property, pending);
+            } else {
+                const condition = readProperty(property, pending);
+
+                if (frame.kind === "group") {
+                    frame.terms.push(condition);
+                } else {
+                    storeProperty(frame, condition);
+                }
+            }
+        }
+    }
+
+    return root;
+}
+
+function readRelationships(
+    frame: Extract<Frame, { kind: "item" }>,
+    property: AmlElement,
+    pending: Frame[],
+): void {
+    if (
+        frame.relationshipsSeen ||
+        Object.keys(property.attributes).length > 0 ||
+        textContent(property).trim()
+    ) {
+        throw new TypeError("Relationships requires one unadorned Item collection.");
+    }
+
+    frame.relationshipsSeen = true;
+    setOwn(frame.node.propertyAttributes, "Relationships", {});
+
+    for (const child of childElements(property)) {
+        frame.node.relationships.push(appendItem(child, pending));
+    }
+}
+
+function appendItem(element: AmlElement, pending: Frame[]): ItemNode {
+    const type = element.attributes.type;
+
+    if (element.name !== "Item" || !type) {
+        throw new TypeError("Expected a typed AML Item.");
+    }
+
+    const node = itemNode(type);
+    node.attributes = { ...element.attributes };
+    delete node.attributes.type;
+    pending.push({
+        kind: "item",
+        element,
+        node,
+        logical: [],
+        repeated: [],
+        relationshipsSeen: false,
+    });
+
+    return node;
+}
+
+function readProperty(property: AmlElement, pending: Frame[]): AmlPropertyCondition {
+    for (const attribute of Object.keys(property.attributes)) {
+        if (
+            !["is_null", "condition", "type", "keyed_name", "name", "xml:lang"].includes(attribute)
+        ) {
+            throw new TypeError(`Unsupported AML property attribute '${attribute}'.`);
+        }
+    }
+
+    const nested = childElements(property);
+
+    if (nested.length > 0) {
+        const element = nested[0];
+
+        if (nested.length !== 1 || !element || textContent(property).trim()) {
+            throw new TypeError("Only one nested Item is supported in a property.");
+        }
+
+        return {
+            name: property.name,
+            attributes: { ...property.attributes },
+            item: appendItem(element, pending),
+        };
+    }
+
+    return {
+        name: property.name,
+        attributes: { ...property.attributes },
+        value: property.attributes.is_null === "1" ? null : textContent(property),
+    };
+}
+
+function storeProperty(
+    frame: Extract<Frame, { kind: "item" }>,
+    condition: AmlPropertyCondition,
+): void {
+    const { node, logical, repeated } = frame;
+    const { name, attributes } = condition;
+    const duplicate =
+        Object.hasOwn(node.properties, name) ||
+        Object.hasOwn(node.propertyItems, name) ||
+        (name === "id" && node.attributes.id !== undefined);
+
+    if (duplicate) {
+        if (repeated.length === 0) {
+            logical.push({ operator: AmlLogicalOperator.And, terms: repeated, implicit: true });
+            node.logical = logical;
+        }
+
+        repeated.push(condition);
+
+        return;
+    }
+
+    setOwn(node.propertyAttributes, name, { ...attributes });
+
+    if (condition.item) {
+        setOwn(node.propertyItems, name, condition.item);
+    } else if (name === "id" && (!attributes.condition || attributes.condition === "eq")) {
+        node.attributes.id = String(condition.value ?? "");
+    } else {
+        const value = condition.value;
+
+        if (value === undefined || (typeof value === "object" && value !== null)) {
+            throw new TypeError("An AML property must retain its scalar value.");
+        }
+
+        setOwn(node.properties, name, value);
+    }
+}
+
+export function parseItems(xml: string): Item[] {
+    return parseAml(xml, "<request>").items.map(
+        (element) => new Item({ items: [itemNodeFromElement(element)] }),
+    );
+}