@innovatorstack/harness 0.0.0-stage → 0.1.0

package/src/queries/parser.ts

@@ -0,0 +1,352 @@
+import type { StorageValue } from "../storage/types.js";
+import { TokenKind, tokenize } from "./lexer.js";
+import type { Token } from "./lexer.js";
+import { comparison, likePredicate, setPredicate, validatePredicate } from "./predicates.js";
+import { Comparison, queryDepthMax, queryNodesMax, queryValuesMax } from "./types.js";
+import type { Predicate, QueryField } from "./types.js";
+
+type Resolver = (names: readonly string[]) => QueryField;
+
+type Operator = "and" | "or" | "not" | "(";
+
+export class PredicateParser {
+    private offset = 0;
+    private reductions = 0;
+    private readonly tokens: readonly Token[];
+    private readonly values: Predicate[] = [];
+    private readonly operators: Operator[] = [];
+
+    constructor(
+        text: string,
+        private readonly field: Resolver,
+    ) {
+        this.tokens = tokenize(text);
+    }
+
+    parse(): Predicate {
+        let operand = true;
+        let depth = 0;
+
+        while (this.offset < this.tokens.length) {
+            if (operand) {
+                if (this.take("(")) {
+                    this.operators.push("(");
+                    depth += 1;
+                } else if (this.takeWord("not")) {
+                    this.operators.push("not");
+                } else {
+                    this.values.push(this.predicate());
+                    operand = false;
+                }
+            } else if (this.take(")")) {
+                while (this.operators.at(-1) !== "(") {
+                    this.reduce();
+                }
+
+                this.operators.pop();
+                depth -= 1;
+            } else {
+                const operator = this.binaryOperator();
+
+                while (
+                    this.operators.at(-1) !== undefined &&
+                    precedence(this.operators.at(-1)) >= precedence(operator)
+                ) {
+                    this.reduce();
+                }
+
+                this.operators.push(operator);
+                operand = true;
+            }
+
+            if (depth < 0 || depth > queryDepthMax) {
+                this.fail("Unbalanced or excessive query parentheses");
+            }
+        }
+
+        if (operand || depth !== 0) {
+            this.fail("Incomplete query expression");
+        }
+
+        while (this.operators.length > 0) {
+            this.reduce();
+        }
+
+        const result = this.values[0];
+
+        if (!result || this.values.length !== 1) {
+            return this.fail("Invalid query expression");
+        }
+
+        validatePredicate(result);
+
+        return result;
+    }
+
+    scalarList(): readonly StorageValue[] {
+        const values = this.list(false);
+
+        if (this.offset !== this.tokens.length) {
+            this.fail("Unexpected query value");
+        }
+
+        return values;
+    }
+
+    range(): readonly [StorageValue, StorageValue] {
+        const first = this.literal();
+        this.requireWord("and");
+        const last = this.literal();
+
+        if (this.offset !== this.tokens.length) {
+            this.fail("Unexpected range value");
+        }
+
+        return [first, last];
+    }
+
+    private predicate(): Predicate {
+        const field = this.field(this.identifiers());
+        const negate = this.takeWord("not");
+
+        if (this.takeWord("in")) {
+            this.require("(");
+
+            return setPredicate(field, this.list(true), negate);
+        }
+
+        if (this.takeWord("like")) {
+            const pattern = this.literal();
+
+            if (typeof pattern !== "string") {
+                return this.fail("LIKE requires a quoted pattern");
+            }
+
+            return likePredicate(field, pattern, negate);
+        }
+
+        if (this.takeWord("between")) {
+            const first = this.literal();
+            this.requireWord("and");
+            const last = this.literal();
+            const term: Predicate = {
+                kind: "and",
+                terms: [
+                    comparison(field, Comparison.GreaterOrEqual, first),
+                    comparison(field, Comparison.LessOrEqual, last),
+                ],
+            };
+
+            return negate ? { kind: "not", term } : term;
+        }
+
+        if (negate) {
+            return this.fail("NOT must precede IN, LIKE or BETWEEN");
+        }
+
+        if (this.takeWord("is")) {
+            const negate = this.takeWord("not");
+            this.requireWord("null");
+
+            return { kind: "null", field, negate };
+        }
+
+        const token = this.tokens[this.offset++];
+        const operator = comparisonOperator(token?.value);
+
+        if (operator === undefined) {
+            return this.fail("Expected a supported comparison operator");
+        }
+
+        return comparison(field, operator, this.literal());
+    }
+
+    private identifiers(): readonly string[] {
+        const names: string[] = [];
+
+        do {
+            const token = this.tokens[this.offset++];
+
+            if (!token || ![TokenKind.Word, TokenKind.Identifier].includes(token.kind)) {
+                return this.fail("Expected a property identifier");
+            }
+
+            names.push(token.value);
+
+            if (names.length > 3) {
+                return this.fail("Cross-database query qualifiers are not supported");
+            }
+        } while (this.take("."));
+
+        return names;
+    }
+
+    private literal(): StorageValue {
+        if (this.takeWord("null")) {
+            return null;
+        }
+
+        const token = this.tokens[this.offset++];
+
+        if (!token || ![TokenKind.String, TokenKind.Number].includes(token.kind)) {
+            return this.fail("Expected a quoted string, number or NULL literal");
+        }
+
+        return token.value;
+    }
+
+    private list(parenthesized: boolean): readonly StorageValue[] {
+        const values: StorageValue[] = [];
+
+        do {
+            values.push(this.literal());
+
+            if (values.length > queryValuesMax) {
+                return this.fail("Query value limit exceeded");
+            }
+        } while (this.take(","));
+
+        if (parenthesized) {
+            this.require(")");
+        }
+
+        return values;
+    }
+
+    private binaryOperator(): "and" | "or" {
+        if (this.takeWord("and")) {
+            return "and";
+        }
+
+        if (this.takeWord("or")) {
+            return "or";
+        }
+
+        return this.fail("Expected AND, OR or a closing parenthesis");
+    }
+
+    private reduce(): void {
+        this.reductions += 1;
+
+        if (this.reductions > queryNodesMax) {
+            this.fail("Query exceeds its predicate limit");
+        }
+
+        const operator = this.operators.pop();
+        const right = this.values.pop();
+
+        if (!right || operator === undefined || operator === "(") {
+            this.fail("Unbalanced query expression");
+        }
+
+        if (operator === "not") {
+            this.values.push({ kind: "not", term: right });
+
+            return;
+        }
+
+        const left = this.values.pop();
+
+        if (!left) {
+            this.fail("Missing query operand");
+        }
+
+        const terms = left.kind === operator ? [...left.terms, right] : [left, right];
+        this.values.push({ kind: operator, terms });
+    }
+
+    private take(value: string): boolean {
+        const token = this.tokens[this.offset];
+
+        if (token?.kind === TokenKind.Symbol && token.value === value) {
+            this.offset += 1;
+
+            return true;
+        }
+
+        return false;
+    }
+
+    private takeWord(value: string): boolean {
+        const token = this.tokens[this.offset];
+
+        if (token?.kind === TokenKind.Word && token.value.toLowerCase() === value) {
+            this.offset += 1;
+
+            return true;
+        }
+
+        return false;
+    }
+
+    private require(value: string): void {
+        if (!this.take(value)) {
+            this.fail(`Expected '${value}'`);
+        }
+    }
+
+    private requireWord(value: string): void {
+        if (!this.takeWord(value)) {
+            this.fail(`Expected ${value.toUpperCase()}`);
+        }
+    }
+
+    private fail(message: string): never {
+        const position = this.tokens[this.offset]?.position ?? this.tokens.at(-1)?.position ?? 0;
+
+        throw new TypeError(`${message} at query position ${position + 1}.`);
+    }
+}
+
+function precedence(operator: Operator | undefined): number {
+    switch (operator) {
+        case "not": {
+            return 3;
+        }
+        case "and": {
+            return 2;
+        }
+        case "or": {
+            return 1;
+        }
+        case undefined:
+        case "(": {
+            return 0;
+        }
+        default: {
+            const unexpected: never = operator;
+
+            throw new Error(`Unknown query operator ${String(unexpected)}.`);
+        }
+    }
+}
+
+function comparisonOperator(value: string | undefined): Comparison | undefined {
+    switch (value) {
+        case undefined: {
+            return undefined;
+        }
+        case "=": {
+            return Comparison.Equal;
+        }
+        case "!=":
+        case "<>": {
+            return Comparison.NotEqual;
+        }
+        case ">": {
+            return Comparison.Greater;
+        }
+        case ">=": {
+            return Comparison.GreaterOrEqual;
+        }
+        case "<": {
+            return Comparison.Less;
+        }
+        case "<=": {
+            return Comparison.LessOrEqual;
+        }
+        default: {
+            return undefined;
+        }
+    }
+}

package/src/queries/predicates.ts

@@ -0,0 +1,85 @@
+import type { StorageValue } from "../storage/types.js";
+import { like } from "./like.js";
+import { queryDepthMax, queryNodesMax, queryTextMax, queryValuesMax } from "./types.js";
+import type { Comparison, Predicate, QueryField } from "./types.js";
+import { valueKey } from "./values.js";
+
+export function comparison(
+    field: QueryField,
+    operator: Comparison,
+    value: StorageValue,
+): Predicate {
+    validateValue(field, value);
+
+    return { kind: "compare", field, operator, value };
+}
+
+export function setPredicate(
+    field: QueryField,
+    values: readonly StorageValue[],
+    negate = false,
+): Predicate {
+    if (values.length > queryValuesMax) {
+        throw new TypeError("Query set exceeds its value limit.");
+    }
+
+    for (const value of values) {
+        validateValue(field, value);
+    }
+
+    return { kind: "set", field, values, negate };
+}
+
+export function likePredicate(field: QueryField, pattern: string, negate = false): Predicate {
+    if (!["text", "identifier"].includes(field.kind)) {
+        throw new TypeError("LIKE requires a text or item-ID property.");
+    }
+
+    like("", pattern);
+
+    return { kind: "like", field, pattern, negate };
+}
+
+export function validatePredicate(root: Predicate): void {
+    const pending = [{ node: root, depth: 0 }];
+    let visited = 0;
+    let values = 0;
+
+    while (pending.length > 0) {
+        const frame = pending.pop();
+
+        if (!frame) {
+            throw new Error("A query frame must exist while validation is pending.");
+        }
+
+        visited += 1;
+
+        if (visited > queryNodesMax || frame.depth > queryDepthMax) {
+            throw new TypeError("Query exceeds its predicate or nesting limit.");
+        }
+
+        if (frame.node.kind === "not") {
+            pending.push({ node: frame.node.term, depth: frame.depth + 1 });
+        } else if (frame.node.kind === "and" || frame.node.kind === "or") {
+            for (const node of frame.node.terms) {
+                pending.push({ node, depth: frame.depth + 1 });
+            }
+        } else if (frame.node.kind === "set") {
+            values += frame.node.values.length;
+        } else if (frame.node.kind !== "constant" && frame.node.kind !== "null") {
+            values += 1;
+        }
+
+        if (values > queryValuesMax) {
+            throw new TypeError("Query exceeds its parameter limit.");
+        }
+    }
+}
+
+function validateValue(field: QueryField, value: StorageValue): void {
+    if (typeof value === "string" && value.length > queryTextMax) {
+        throw new TypeError("Query values exceed their text limit.");
+    }
+
+    valueKey(field.kind, value);
+}

package/src/queries/types.ts

@@ -0,0 +1,82 @@
+import type { StorageValue, StoredItem } from "../storage/types.js";
+
+export enum Comparison {
+    Equal = "eq",
+    NotEqual = "ne",
+    Greater = "gt",
+    GreaterOrEqual = "ge",
+    Less = "lt",
+    LessOrEqual = "le",
+}
+
+export type ValueKind = "text" | "identifier" | "number" | "decimal" | "date";
+
+export interface ReferencePath {
+    readonly property: string;
+    readonly target: string;
+}
+
+export interface QueryField {
+    readonly name: string;
+    readonly column: string;
+    readonly kind: ValueKind;
+    readonly path: readonly ReferencePath[];
+}
+
+export type Predicate =
+    | { readonly kind: "constant"; readonly value: boolean }
+    | {
+          readonly kind: "compare";
+          readonly field: QueryField;
+          readonly operator: Comparison;
+          readonly value: StorageValue;
+      }
+    | { readonly kind: "null"; readonly field: QueryField; readonly negate: boolean }
+    | {
+          readonly kind: "set";
+          readonly field: QueryField;
+          readonly values: readonly StorageValue[];
+          readonly negate: boolean;
+      }
+    | {
+          readonly kind: "like";
+          readonly field: QueryField;
+          readonly pattern: string;
+          readonly negate: boolean;
+      }
+    | { readonly kind: "and"; readonly terms: readonly Predicate[] }
+    | { readonly kind: "or"; readonly terms: readonly Predicate[] }
+    | { readonly kind: "not"; readonly term: Predicate };
+
+export interface QueryOrder {
+    readonly field: QueryField;
+    readonly descending: boolean;
+}
+
+/** Internal optimization; custom storage uses the same final predicate evaluator. */
+export type SelectQuery = (
+    type: string,
+    predicate: Predicate,
+    spend: (units: number) => void,
+) => readonly StoredItem[];
+
+export const selectQuery = Symbol("Harness storage selection");
+
+export const queryNodesMax = 512;
+export const queryDepthMax = 64;
+export const queryValuesMax = 10_000;
+export const queryTextMax = 64 * 1024;
+
+export function conjunction(terms: readonly Predicate[]): Predicate {
+    if (terms.length === 0) {
+        return { kind: "constant", value: true };
+    }
+
+    const only = terms[0];
+
+    if (terms.length === 1 && only) {
+        return only;
+    }
+
+    return { kind: "and", terms };
+}

package/src/queries/values.ts

@@ -0,0 +1,104 @@
+import type { StorageValue } from "../storage/types.js";
+import { dateKey } from "./date.js";
+import { compareDecimals, decimalKey } from "./decimal.js";
+import type { ValueKind } from "./types.js";
+
+export function valueKey(kind: ValueKind, value: StorageValue): StorageValue {
+    if (value === null) {
+        return null;
+    }
+
+    if (kind === "number") {
+        const result = Number(value);
+
+        if (String(value).trim() === "" || !Number.isFinite(result)) {
+            throw new TypeError("Numeric predicates require finite numeric values.");
+        }
+
+        return result;
+    }
+
+    const text = String(value);
+
+    switch (kind) {
+        case "decimal": {
+            return decimalKey(text);
+        }
+        case "date": {
+            return dateKey(text);
+        }
+        case "identifier": {
+            return text.toLowerCase();
+        }
+        case "text": {
+            return text;
+        }
+        default: {
+            const unexpected: never = kind;
+
+            throw new TypeError(`Unknown query value kind '${String(unexpected)}'.`);
+        }
+    }
+}
+
+export function compareValues(
+    kind: ValueKind,
+    left: StorageValue,
+    right: StorageValue,
+): number | null {
+    const a = valueKey(kind, left);
+    const b = valueKey(kind, right);
+
+    if (a === null || b === null) {
+        return null;
+    }
+
+    if (a === b) {
+        return 0;
+    }
+
+    if (kind === "decimal") {
+        return compareDecimals(String(a), String(b));
+    }
+
+    if (kind === "date") {
+        return BigInt(a) < BigInt(b) ? -1 : 1;
+    }
+
+    if (typeof a === "number" && typeof b === "number") {
+        return a < b ? -1 : 1;
+    }
+
+    return compareText(String(a), String(b));
+}
+
+function compareText(left: string, right: string): number {
+    const a = left[Symbol.iterator]();
+    const b = right[Symbol.iterator]();
+
+    while (true) {
+        const first = a.next();
+        const second = b.next();
+
+        if (first.done || second.done) {
+            if (first.done && second.done) {
+                return 0;
+            }
+
+            return first.done ? -1 : 1;
+        }
+
+        const firstCode = first.value.codePointAt(0);
+        const secondCode = second.value.codePointAt(0);
+
+        if (firstCode === undefined || secondCode === undefined) {
+            throw new Error("String iteration must yield one Unicode code point.");
+        }
+
+        const difference = firstCode - secondCode;
+
+        if (difference !== 0) {
+            return Math.sign(difference);
+        }
+    }
+}

package/src/storage/documents.ts

@@ -0,0 +1,20 @@
+import type { HarnessStorage, PackageDocument } from "./types.js";
+
+export const selectDocument = Symbol("selectDocument");
+
+interface DocumentLookup {
+    [selectDocument](path: string): PackageDocument | undefined;
+}
+
+function hasDocumentLookup(storage: HarnessStorage): storage is HarnessStorage & DocumentLookup {
+    return selectDocument in storage && typeof storage[selectDocument] === "function";
+}
+
+/** Native adapters can select one source document without loading the complete package export. */
+export function findDocument(storage: HarnessStorage, path: string): PackageDocument | undefined {
+    if (hasDocumentLookup(storage)) {
+        return storage[selectDocument](path);
+    }
+
+    return storage.listDocuments().find((document) => document.path === path);
+}

package/src/storage/metadata-epoch.ts

@@ -0,0 +1,20 @@
+import type { HarnessStorage } from "./types.js";
+
+const epochs = new WeakMap<HarnessStorage, number>();
+
+/** Only storage with fully owned metadata writes may opt into derived catalog reuse. */
+export function trackMetadata(storage: HarnessStorage): void {
+    epochs.set(storage, 0);
+}
+
+export function changeMetadata(storage: HarnessStorage): void {
+    const current = epochs.get(storage);
+
+    if (current !== undefined) {
+        epochs.set(storage, current + 1);
+    }
+}
+
+export function metadataEpoch(storage: HarnessStorage): number | undefined {
+    return epochs.get(storage);
+}

package/src/storage/package-transaction.ts

@@ -0,0 +1,25 @@
+import type { HarnessStorage } from "./types.js";
+
+export const packageTransaction = Symbol("packageTransaction");
+
+interface PackageTransaction {
+    [packageTransaction]<Result>(write: () => Result): Result;
+}
+
+function hasPackageTransaction(
+    storage: HarnessStorage,
+): storage is HarnessStorage & PackageTransaction {
+    return packageTransaction in storage && typeof storage[packageTransaction] === "function";
+}
+
+/** An adapter can share one synchronous write boundary across a complete package import. */
+export function withPackageTransaction<Result>(
+    storage: HarnessStorage,
+    write: () => Result,
+): Result {
+    if (hasPackageTransaction(storage)) {
+        return storage[packageTransaction](write);
+    }
+
+    return write();
+}