inibase 3.0.0 → 3.1.0

package/dist/expression.js

@@ -0,0 +1,495 @@
+/**
+ * Computed-fields expression language (v1 — id-only).
+ *
+ * Grammar
+ * -------
+ * ```
+ * expression := term (("+" | "-") term)*
+ * term       := factor (("," | "/" | "%") factor)*   // "," = multiply
+ * factor     := integer-literal | path | function-call | "(" expression ")"
+ * path       := id ( "." id )*                       // "." = link/binding hop
+ * function   := "sum" | "count" | "avg" | "min" | "max" "(" expression ")"
+ * ```
+ *
+ * Every symbol is a numeric field `id` (per-table dense counter, nested
+ * children included). There are no decimal literals: `.` is reserved as the
+ * path separator, so `3.4` is a link hop (`field 3`, then `field 4` in the
+ * table `field 3` links to), never the decimal 3.4. Fractional results are
+ * reachable via division (`314 / 100` → 3.14).
+ *
+ * A bare integer that **matches a field id in the table's schema** is that
+ * field's value (ids are locative); a bare integer that matches no field id
+ * is an integer literal. This is what makes both `sum(4, 3.4)` (id 4 =
+ * quantity) and `314 / 100` (no such ids) usable.
+ *
+ * Compiled expressions are persisted with the schema as
+ * `{ expr: string, ast: CompiledExpressionNode }` so key/table renames never
+ * retarget an expression: the AST carries only field ids (+ the id of the
+ * array ancestor a helper iterates), and every key path is re-derived from
+ * the *current* schema at write time.
+ */
+import { createError, isArrayOfObjects } from "./utils.js";
+/** Cap on the raw `computed` string length (bound work at validation). */
+export const COMPUTED_EXPR_MAX_LENGTH = 512;
+/** Cap on the parsed AST depth (protects the parser/evaluator recursion). */
+export const COMPUTED_EXPR_MAX_DEPTH = 64;
+const FN_NAMES = ["sum", "count", "avg", "min", "max"];
+const syntaxError = (language, fieldKey) => createError(language, "COMPUTED_FIELD_SYNTAX", fieldKey);
+function tokenize(source) {
+    const tokens = [];
+    let i = 0;
+    while (i < source.length) {
+        const ch = source[i];
+        if (ch === " " || ch === "\t" || ch === "\n" || ch === "\r") {
+            i++;
+            continue;
+        }
+        if (ch >= "0" && ch <= "9") {
+            let j = i;
+            while (j < source.length && source[j] >= "0" && source[j] <= "9")
+                j++;
+            tokens.push({ t: "num", v: Number(source.slice(i, j)) });
+            i = j;
+            continue;
+        }
+        if ((ch >= "a" && ch <= "z") || (ch >= "A" && ch <= "Z")) {
+            let j = i;
+            while (j < source.length &&
+                ((source[j] >= "a" && source[j] <= "z") ||
+                    (source[j] >= "A" && source[j] <= "Z") ||
+                    (source[j] >= "0" && source[j] <= "9") ||
+                    source[j] === "_"))
+                j++;
+            tokens.push({ t: "ident", v: source.slice(i, j) });
+            i = j;
+            continue;
+        }
+        switch (ch) {
+            case ".":
+                tokens.push({ t: "dot" });
+                i++;
+                continue;
+            case "(":
+                tokens.push({ t: "lp" });
+                i++;
+                continue;
+            case ")":
+                tokens.push({ t: "rp" });
+                i++;
+                continue;
+            case "+":
+            case "-":
+            case ",":
+            case "/":
+            case "%":
+                tokens.push({ t: "op", v: ch });
+                i++;
+                continue;
+            default:
+                throw syntaxError("en", "");
+        }
+    }
+    tokens.push({ t: "eof" });
+    return tokens;
+}
+/**
+ * Parse a `computed` expression into a raw AST. Throws
+ * `COMPUTED_FIELD_SYNTAX` on invalid syntax, oversized input or excessive
+ * nesting.
+ */
+export function parseExpression(source, language = "en", fieldKey = "") {
+    if (typeof source !== "string" || !source.length)
+        throw syntaxError(language, fieldKey);
+    if (source.length > COMPUTED_EXPR_MAX_LENGTH)
+        throw syntaxError(language, fieldKey);
+    const tokens = tokenize(source);
+    let pos = 0;
+    let depth = 0;
+    const peek = () => tokens[pos];
+    const next = () => tokens[pos++];
+    const fail = () => syntaxError(language, fieldKey);
+    const enter = () => {
+        if (++depth > COMPUTED_EXPR_MAX_DEPTH)
+            throw fail();
+    };
+    const leave = () => {
+        depth--;
+    };
+    const expression = () => {
+        enter();
+        let left = term();
+        let token = peek();
+        while (token.t === "op" && (token.v === "+" || token.v === "-")) {
+            const op = next().v;
+            left = {
+                kind: "bin",
+                op: op === "+" ? "add" : "sub",
+                left,
+                right: term(),
+            };
+            token = peek();
+        }
+        leave();
+        return left;
+    };
+    const term = () => {
+        enter();
+        let left = factor();
+        while (peek().t === "op" && [",", "/", "%"].includes(peek().v)) {
+            const op = next().v;
+            const binOp = op === "," ? "mul" : op === "/" ? "div" : "mod";
+            left = { kind: "bin", op: binOp, left, right: factor() };
+        }
+        leave();
+        return left;
+    };
+    const factor = () => {
+        enter();
+        const token = next();
+        if (token.t === "num") {
+            if (peek().t === "dot") {
+                const ids = [token.v];
+                while (peek().t === "dot") {
+                    next();
+                    const seg = next();
+                    if (seg.t !== "num")
+                        throw fail();
+                    ids.push(seg.v);
+                }
+                leave();
+                return { kind: "path", ids };
+            }
+            leave();
+            return { kind: "num", value: token.v };
+        }
+        if (token.t === "ident") {
+            const name = token.v;
+            if (!FN_NAMES.includes(name))
+                throw fail();
+            if (next().t !== "lp")
+                throw fail();
+            const arg = expression();
+            if (next().t !== "rp")
+                throw fail();
+            leave();
+            return { kind: "fn", name: name, arg };
+        }
+        if (token.t === "lp") {
+            const inner = expression();
+            if (next().t !== "rp")
+                throw fail();
+            leave();
+            return inner;
+        }
+        throw fail();
+    };
+    const root = expression();
+    if (next().t !== "eof")
+        throw fail();
+    return root;
+}
+/* ---------------------------------------------------------------------------
+ * Schema index
+ * ------------------------------------------------------------------------- */
+/**
+ * Build the id → {@link FieldRef} index of a schema (nested children included,
+ * using dotted key paths). Container fields (array/object with object
+ * children) are indexed too so unknown ids are detected, but they can't be
+ * referenced by an expression.
+ */
+export function buildFieldIndex(schema) {
+    const index = new Map();
+    const isArrayOfObjectsContainer = (field) => Array.isArray(field.children) && isArrayOfObjects(field.children);
+    const walk = (fields, prefix, ancestors) => {
+        for (const field of fields) {
+            const key = prefix ? `${prefix}.${field.key}` : field.key;
+            if (field.id !== undefined) {
+                let arrayAncestor = null;
+                let nestedInArrayOfArrays = false;
+                for (let i = ancestors.length - 1; i >= 0; i--) {
+                    const ancestor = ancestors[i];
+                    if (ancestor.field.type === "array" &&
+                        isArrayOfObjectsContainer(ancestor.field)) {
+                        arrayAncestor = {
+                            id: ancestor.field.id,
+                            key: ancestor.key,
+                        };
+                        for (let j = i - 1; j >= 0; j--) {
+                            const parent = ancestors[j].field;
+                            if (parent.type === "array" &&
+                                isArrayOfObjectsContainer(parent)) {
+                                nestedInArrayOfArrays = true;
+                                break;
+                            }
+                        }
+                        break;
+                    }
+                }
+                index.set(field.id, {
+                    key,
+                    field,
+                    arrayAncestor,
+                    nestedInArrayOfArrays,
+                });
+            }
+            if (isArrayOfObjectsContainer(field))
+                walk(field.children, key, [...ancestors, { field, key }]);
+        }
+    };
+    walk(schema, "", []);
+    return index;
+}
+const isContainer = (field) => Array.isArray(field.children) && isArrayOfObjects(field.children);
+/** Collect every path node of a (compiled or raw) expression tree. */
+function collectPaths(node) {
+    if (node.kind === "path")
+        return [node];
+    const paths = [];
+    if (node.kind === "bin") {
+        paths.push(...collectPaths(node.left));
+        paths.push(...collectPaths(node.right));
+    }
+    else if (node.kind === "fn")
+        paths.push(...collectPaths(node.arg));
+    return paths;
+}
+async function resolvePathNode(node, ctx, inHelper) {
+    const ids = node.ids;
+    const hop0 = ctx.index.get(ids[0]);
+    if (!hop0)
+        throw createError(ctx.language, "COMPUTED_FIELD_UNKNOWN_FIELD", [
+            ctx.ownKey,
+            ids[0],
+        ]);
+    if (isContainer(hop0.field))
+        throw createError(ctx.language, "COMPUTED_FIELD_INVALID_TARGET", [
+            ctx.ownKey,
+            ids[0],
+        ]);
+    const arrayFieldId = hop0.arrayAncestor?.id ?? null;
+    // A bare (non-helper) reference may only address fields outside arrays;
+    // array contents are reachable exclusively through sum/count/avg/min/max.
+    if (!inHelper && arrayFieldId !== null)
+        throw createError(ctx.language, "COMPUTED_FIELD_INVALID_TARGET", [
+            ctx.ownKey,
+            ids[0],
+        ]);
+    if (inHelper && hop0.arrayAncestor !== null && hop0.nestedInArrayOfArrays)
+        throw createError(ctx.language, "COMPUTED_FIELD_INVALID_TARGET", [
+            ctx.ownKey,
+            ids[0],
+        ]);
+    // Link hops: each hop beyond the first must live in the table the previous
+    // hop's field links to.
+    let currentRef = hop0;
+    for (let i = 1; i < ids.length; i++) {
+        const linkField = currentRef.field;
+        if (linkField.type !== "table" || typeof linkField.table !== "string")
+            throw createError(ctx.language, "COMPUTED_FIELD_INVALID_LINK", [
+                ctx.ownKey,
+                ids[i],
+            ]);
+        const targetIndex = await ctx.getTableIndex(linkField.table);
+        if (!targetIndex)
+            throw createError(ctx.language, "TABLE_NOT_EXISTS", linkField.table);
+        const ref = targetIndex.get(ids[i]);
+        if (!ref)
+            throw createError(ctx.language, "COMPUTED_FIELD_UNKNOWN_FIELD", [
+                ctx.ownKey,
+                ids[i],
+            ]);
+        if (isContainer(ref.field))
+            throw createError(ctx.language, "COMPUTED_FIELD_INVALID_TARGET", [
+                ctx.ownKey,
+                ids[i],
+            ]);
+        currentRef = ref;
+    }
+    return {
+        node: { kind: "path", ids, arrayFieldId },
+        deps: new Set([ids[0]]),
+    };
+}
+async function resolveNode(node, ctx, inHelper) {
+    switch (node.kind) {
+        case "num":
+            // A bare integer that matches an existing field id is that field
+            // (ids are locative, inside helpers included — this is what makes
+            // `sum(5, 4.2)` and `sum(5, 6)` usable); any other bare integer is
+            // an integer literal (`314 / 100`).
+            if (ctx.index.has(node.value))
+                return resolvePathNode({ kind: "path", ids: [node.value] }, ctx, inHelper);
+            return { node: { kind: "num", value: node.value }, deps: new Set() };
+        case "path":
+            return resolvePathNode(node, ctx, inHelper);
+        case "bin": {
+            const left = await resolveNode(node.left, ctx, inHelper);
+            const right = await resolveNode(node.right, ctx, inHelper);
+            const deps = new Set([...left.deps, ...right.deps]);
+            return {
+                node: { kind: "bin", op: node.op, left: left.node, right: right.node },
+                deps,
+            };
+        }
+        case "fn": {
+            if (inHelper)
+                throw createError(ctx.language, "COMPUTED_FIELD_INVALID_TARGET", [
+                    ctx.ownKey,
+                ]);
+            const arg = await resolveNode(node.arg, ctx, true);
+            const paths = collectPaths(arg.node);
+            if (!paths.length)
+                throw createError(ctx.language, "COMPUTED_FIELD_INVALID_TARGET", [
+                    ctx.ownKey,
+                ]);
+            const arrayFieldIds = new Set(paths.map((path) => path.arrayFieldId ?? null));
+            if (arrayFieldIds.size !== 1 || arrayFieldIds.has(null))
+                throw createError(ctx.language, "COMPUTED_FIELD_INVALID_TARGET", [
+                    ctx.ownKey,
+                ]);
+            return {
+                node: {
+                    kind: "fn",
+                    name: node.name,
+                    arrayFieldId: arrayFieldIds.values().next().value,
+                    arg: arg.node,
+                },
+                deps: arg.deps,
+            };
+        }
+    }
+}
+/**
+ * Resolve a raw expression against the schema (and linked tables), returning
+ * the compiled node plus the set of field ids it reads from the current
+ * table (used for dependency ordering / cycle detection between computed
+ * fields).
+ */
+export async function resolveExpression(expression, ctx) {
+    const resolved = await resolveNode(expression, ctx, false);
+    return { ast: resolved.node, deps: resolved.deps };
+}
+/** Every field id a compiled expression reads from the *current* table. */
+export function collectFieldDeps(node) {
+    const deps = new Set();
+    const visit = (n) => {
+        switch (n.kind) {
+            case "num":
+                return;
+            case "path":
+                deps.add(n.ids[0]);
+                return;
+            case "bin":
+                visit(n.left);
+                visit(n.right);
+                return;
+            case "fn":
+                visit(n.arg);
+                return;
+        }
+    };
+    visit(node);
+    return deps;
+}
+/**
+ * Order computed fields so every dependency is evaluated before its dependents.
+ * Throws `COMPUTED_FIELD_CYCLE` when a field (transitively) depends on itself.
+ */
+export function topoSortComputedFields(fields, language) {
+    const byId = new Map(fields.map((field) => [field.id, field]));
+    const remaining = new Set(fields.map((field) => field.id));
+    const ordered = [];
+    const blocked = new Map(); // dependent -> dependencies still missing
+    const indegree = new Map();
+    for (const field of fields) {
+        const dependents = [];
+        for (const depId of field.deps)
+            if (byId.has(depId))
+                dependents.push(depId);
+        blocked.set(field.id, dependents);
+    }
+    const ready = [];
+    for (const [id, deps] of blocked) {
+        indegree.set(id, deps.length);
+        if (deps.length === 0)
+            ready.push(id);
+    }
+    while (ready.length) {
+        const id = ready.shift();
+        const field = byId.get(id);
+        if (!field)
+            continue;
+        ordered.push(field);
+        remaining.delete(id);
+        for (const [otherId, deps] of blocked) {
+            if (!remaining.has(otherId))
+                continue;
+            if (deps.includes(id)) {
+                const nextIndegree = (indegree.get(otherId) ?? 1) - 1;
+                indegree.set(otherId, nextIndegree);
+                if (nextIndegree === 0)
+                    ready.push(otherId);
+            }
+        }
+    }
+    if (remaining.size) {
+        const keys = fields
+            .filter((field) => remaining.has(field.id))
+            .map((field) => field.key);
+        throw createError(language, "COMPUTED_FIELD_CYCLE", keys.join(", "));
+    }
+    return ordered;
+}
+/* ---------------------------------------------------------------------------
+ * Row flattening (shared by the evaluator)
+ * ------------------------------------------------------------------------- */
+/**
+ * Flatten a formatted row into a dot-notation record. Objects are flattened
+ * (`meta.age`), arrays of objects are combined per child key
+ * (`items.quantity` -> array of per-element values) and everything else is
+ * stored under its dotted key.
+ */
+export function flattenRecord(obj, prefix = "") {
+    const out = {};
+    for (const [k, v] of Object.entries(obj)) {
+        const key = prefix ? `${prefix}.${k}` : k;
+        if (v !== null && typeof v === "object" && !Array.isArray(v))
+            Object.assign(out, flattenRecord(v, key));
+        else if (Array.isArray(v) && v.length && isArrayOfObjects(v)) {
+            const combined = {};
+            for (const element of v)
+                for (const [childKey, childValue] of Object.entries(element)) {
+                    if (!combined[childKey])
+                        combined[childKey] = [];
+                    combined[childKey].push(childValue);
+                }
+            for (const [childKey, values] of Object.entries(combined))
+                out[`${key}.${childKey}`] = values;
+        }
+        else
+            out[key] = v;
+    }
+    return out;
+}
+/**
+ * Resolve a dotted key path against a structured frame in place — the direct
+ * read-path counterpart of `flattenRecord`. Walks `obj` segment by segment
+ * and returns `undefined` when any intermediate is null, undefined, a
+ * non-object, or an array (arrays resolve numerically only, so they never
+ * match a dotted segment), mirroring the leaves `flattenRecord` would have
+ * produced without materialising the flattened record.
+ */
+export function resolveFramePath(obj, dottedKey) {
+    if (dottedKey.length === 0)
+        return obj;
+    let cur = obj;
+    for (const segment of dottedKey.split(".")) {
+        if (cur === null ||
+            cur === undefined ||
+            typeof cur !== "object" ||
+            Array.isArray(cur))
+            return undefined;
+        cur = cur[segment];
+    }
+    return cur;
+}

package/dist/index.d.ts

@@ -1,4 +1,5 @@
 import "dotenv/config";
+import { type ComputedFieldSpec } from "./expression.js";
 import { type JournalFileOp } from "./journal.js";
 export interface Data {
     id?: string | number;
@@ -16,6 +17,10 @@ export type Field = {
     unique?: boolean | number | string;
     children?: FieldType | FieldType[] | Schema;
     regex?: string;
+    /** Computed-fields expression (see the README). Either a raw expression
+     *  string, or the persisted `{ expr, ast }` spec written by Inibase once
+     *  the expression has been compiled. */
+    computed?: string | ComputedFieldSpec;
 };
 export type Schema = Field[];
 export interface Options {
@@ -73,7 +78,7 @@ declare global {
         entries<T extends object>(o: T): Entries<T>;
     }
 }
-export declare const ERROR_CODES: readonly ["GROUP_UNIQUE", "FIELD_UNIQUE", "FIELD_REQUIRED", "NO_SCHEMA", "TABLE_EMPTY", "INVALID_ID", "INVALID_TYPE", "INVALID_PARAMETERS", "NO_ENV", "TABLE_EXISTS", "TABLE_NOT_EXISTS", "INVALID_REGEX_MATCH", "INVALID_NAME"];
+export declare const ERROR_CODES: readonly ["GROUP_UNIQUE", "FIELD_UNIQUE", "FIELD_REQUIRED", "NO_SCHEMA", "TABLE_EMPTY", "INVALID_ID", "INVALID_TYPE", "INVALID_PARAMETERS", "NO_ENV", "TABLE_EXISTS", "TABLE_NOT_EXISTS", "INVALID_REGEX_MATCH", "INVALID_NAME", "COMPUTED_FIELD_SYNTAX", "COMPUTED_FIELD_UNKNOWN_FIELD", "COMPUTED_FIELD_INVALID_LINK", "COMPUTED_FIELD_INVALID_TARGET", "COMPUTED_FIELD_CONFLICT", "COMPUTED_FIELD_CYCLE", "COMPUTED_FIELD_SETTABLE", "COMPUTED_FIELD_DANGLING_LINK", "COMPUTED_FIELD_ARITHMETIC"];
 export type ErrorCode = (typeof ERROR_CODES)[number];
 export type ErrorLang = "en" | "ar" | "fr" | "es";
 export declare const globalConfig: {
@@ -100,6 +105,12 @@ export default class Inibase {
      *  resolve numeric ids to line numbers arithmetically instead of scanning
      *  the id file. Set false by any partial row deletion. */
     private idDensity;
+    /** Per-table computed-plan cache (null = table has no computed fields).
+     *  A plan depends only on the table's persisted schema (compiled ASTs are
+     *  id-based and rename-proof), so it is rebuilt only when the schema
+     *  changes: see the invalidation in `getTable`'s reload branch,
+     *  `createTable` and `updateTableLocked`. Bounded by the number of tables. */
+    private readonly computedPlanCache;
     private databasePath;
     private uniqueMap;
     private schemaFileExtension;
@@ -167,6 +178,57 @@ export default class Inibase {
     private joinPathesContents;
     private _processSchemaDataHelper;
     private processSchemaData;
+    /**
+     * Extract the raw expression from a field's `computed` property (string or
+     * persisted `{ expr, ast }` spec).
+     */
+    private computedExprOf;
+    /**
+     * Compile every `computed` expression of a schema (which must already have
+     * ids assigned) into its persisted `{ expr, ast }` form, in dependency
+     * order. Throws `COMPUTED_FIELD_CYCLE` on cyclic fields. Used by DDL so the
+     * on-disk schema always carries compiled ASTs.
+     */
+    private compileComputedFields;
+    /**
+     * Build the evaluation plan (topological order + id index) for a table's
+     * computed fields. Throws on cycles or unresolvable expressions.
+     */
+    private buildComputedPlan;
+    /** Id index of a table's schema (link targets are re-resolved at write
+     *  time, so renames never retarget a compiled expression). */
+    private tableFieldIndex;
+    /**
+     * Evaluate a batch of (merged) rows against the table's computed fields.
+     * Returns `lineNo -> { computedKey -> value }` in dependency order.
+     *
+     * Batched link-hop reads: when the plan contains any link hop, a dry
+     * collection pass records every (table, column, id) triple the rows'
+     * expressions need (no file I/O), each distinct triple is then resolved
+     * exactly once — deduplicated across rows and fields — and a final pass
+     * evaluates against the warm cache. Plans without hops run the single
+     * evaluation pass unchanged.
+     */
+    private evaluateComputedRows;
+    private createLinkReader;
+    /** Evaluate every computed field of one row (topological order) and merge
+     *  the results back into the row so dependent fields see them. */
+    private evaluateRowComputed;
+    private evaluateNode;
+    /** Evaluate a path (`ids`, dot-separated link hops) against the current
+     *  frame. Returns `null` when an intermediate link value is missing. */
+    private evaluatePath;
+    /** Id index lookup with a shared per-evaluation cache. */
+    private indexFor;
+    /** Read a single column of one linked row via `get`, or null when the
+     *  row does not exist (dangling link). */
+    private readLinkedRow;
+    private coerceNumber;
+    private applyBinaryOp;
+    private aggregate;
+    /** Merge evaluated per-line computed values into a `pathesContents` map
+     *  as line-numbered replace records (encoded cells). */
+    private mergeComputedLineRecords;
     private isSimpleField;
     private processSimpleField;
     /**