inibase 3.0.0 → 3.1.0

package/dist/index.js

@@ -5,6 +5,7 @@ import { glob, mkdir, readdir, readFile, rename, rm, stat, unlink, writeFile, }
 import { basename, join, parse, resolve } from "node:path";
 import { inspect } from "node:util";
 import Inison from "inison";
+import { buildFieldIndex, collectFieldDeps, parseExpression, resolveExpression, resolveFramePath, topoSortComputedFields, } from "./expression.js";
 import * as File from "./file.js";
 import { DatabaseJournal, Journal } from "./journal.js";
 import * as Utils from "./utils.js";
@@ -23,6 +24,15 @@ export const ERROR_CODES = [
     "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",
 ];
 // hide ExperimentalWarning glob()
 // Guard against non-Node environments (e.g. accidental import in a browser bundle)
@@ -31,6 +41,75 @@ if (typeof process !== "undefined" &&
     process.removeAllListeners("warning");
 }
 export const globalConfig = {};
+/**
+ * Batch-scoped link-hop reader for computed-field evaluation: a dry pass
+ * records every (table, column, id) triple the expressions need, each
+ * distinct triple is resolved exactly once by the engine's `readLinkedRow`
+ * (deduplicated across rows and fields of the batch), and subsequent passes
+ * are served from a warm per-(table, column) cache.
+ */
+class LinkedRowReader {
+    readRow;
+    pending = new Map();
+    cache = new Map();
+    constructor(readRow) {
+        this.readRow = readRow;
+    }
+    get hasPending() {
+        return this.pending.size > 0;
+    }
+    record(table, column, id) {
+        const key = `${table}\u0000${column}`;
+        let ids = this.pending.get(key);
+        if (!ids)
+            this.pending.set(key, (ids = new Set()));
+        ids.add(id);
+    }
+    async read(table, column, id) {
+        const key = `${table}\u0000${column}`;
+        let map = this.cache.get(key);
+        if (!map) {
+            map = await this.resolve(key, this.pending.get(key) ?? new Set());
+            this.pending.delete(key);
+            this.cache.set(key, map);
+        }
+        return map.get(id) ?? null;
+    }
+    /** Resolve every pending bucket now (called between the collection pass
+     *  and the real evaluation pass). */
+    async resolveAll() {
+        for (const [key, ids] of this.pending)
+            this.cache.set(key, await this.resolve(key, ids));
+        this.pending.clear();
+    }
+    async resolve(key, ids) {
+        const separator = key.indexOf("\u0000");
+        const table = key.slice(0, separator);
+        const column = key.slice(separator + 1);
+        const map = new Map();
+        // One engine read per distinct triple; the buckets' triples are
+        // independent so they resolve concurrently. A missing row caches as
+        // null so repeated dangling hops fail once, exactly like a direct
+        // readLinkedRow would per hop.
+        await Promise.all(Array.from(ids).map(async (id) => {
+            map.set(id, await this.readRow(table, column, id));
+        }));
+        return map;
+    }
+}
+/** True when an expression tree contains any link hop (multi-segment path). */
+function astHasHops(node) {
+    switch (node.kind) {
+        case "num":
+            return false;
+        case "path":
+            return node.ids.length > 1;
+        case "bin":
+            return astHasHops(node.left) || astHasHops(node.right);
+        case "fn":
+            return astHasHops(node.arg);
+    }
+}
 /**
  * @param {string} database - Database name
  * @param {string} [mainFolder="."] - Main folder path
@@ -46,6 +125,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. */
     idDensity = new Map();
+    /** 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. */
+    computedPlanCache = new Map();
     databasePath;
     uniqueMap;
     schemaFileExtension = process.env.INIBASE_SCHEMA_EXTENSION ?? "json";
@@ -168,9 +253,13 @@ export default class Inibase {
         }
         if (schema) {
             const lastSchemaID = { value: 0 };
+            // Compile computed expressions only after ids are assigned (the
+            // persisted AST carries ids, making it rename-proof), and before
+            // the schema is written so a bad expression never lands on disk.
+            schema = await this.compileComputedFields(Utils.addIdToSchema(schema, lastSchemaID));
             await File.write(join(tablePath, `schema.${this.schemaFileExtension}`), this.schemaFileExtension === "json"
-                ? JSON.stringify(Utils.addIdToSchema(schema, lastSchemaID), null, 2)
-                : Inison.stringify(Utils.addIdToSchema(schema, lastSchemaID)));
+                ? JSON.stringify(schema, null, 2)
+                : Inison.stringify(schema));
             await File.write(join(tablePath, `${lastSchemaID.value}.schema`), "");
         }
         else
@@ -180,6 +269,9 @@ export default class Inibase {
         await File.syncDir(tablePath);
         await File.syncDir(join(tablePath, ".tmp"));
         this.idDensity.set(tableName, true);
+        // Defensive: a table of the same name may have had a cached plan from
+        // before a delete+recreate.
+        this.computedPlanCache.delete(tableName);
     }
     // Function to replace the string in one schema file
     async replaceStringInFile(filePath, targetString, replaceString) {
@@ -240,6 +332,18 @@ export default class Inibase {
                 value: schemaIdFilePath ? Number(parse(schemaIdFilePath).name) : 0,
             };
             schema = Utils.addIdToSchema(schema, lastSchemaID);
+            // Compile computed expressions now that ids are assigned (the
+            // persisted AST only stores ids, so later renames never retarget
+            // an expression). Compilation happens before any file surgery so
+            // a bad expression aborts the migration cleanly.
+            schema = await this.compileComputedFields(schema);
+            // Row count is needed for the computed backfill below, so read the
+            // pagination before the schema is rewritten.
+            let totalLines = 0;
+            for await (const paginationFileName of glob("*.pagination", {
+                cwd: tablePath,
+            }))
+                totalLines = parse(paginationFileName).name.split("-").map(Number)[1];
             // if schema file exists, update columns files names based on field id
             if ((await File.isExists(join(tablePath, `schema.${this.schemaFileExtension}`))) &&
                 table.schema?.length) {
@@ -255,6 +359,46 @@ export default class Inibase {
                         }
                     }));
             }
+            // Computed-field backfill: a computed expression that is added or
+            // changed by this migration must be (re)derived for every existing
+            // row. Evaluation happens BEFORE the schema is rewritten, so a
+            // failed migration (dangling link, arithmetic error, unknown
+            // field, ...) leaves the old schema and column values untouched.
+            const oldComputed = new Map((table.schema ?? [])
+                .filter((field) => typeof field.computed !== "undefined")
+                .map((field) => [field.key, this.computedExprOf(field)]));
+            const changedComputedKeys = new Set(totalLines > 0
+                ? schema
+                    .filter((field) => typeof field.computed !== "undefined" &&
+                    oldComputed.get(field.key) !== this.computedExprOf(field))
+                    .map((field) => field.key)
+                : []);
+            const backfillReplacers = changedComputedKeys.size
+                ? await (async () => {
+                    const plan = await this.buildComputedPlan(tableName, schema);
+                    if (!plan)
+                        return undefined;
+                    const lineNumbers = Array.from({ length: totalLines }, (_, index) => index + 1);
+                    const existing = await this.processSchemaData(tableName, schema.filter((field) => typeof field.computed === "undefined"), lineNumbers);
+                    return this.evaluateComputedRows(tableName, plan, existing);
+                })()
+                : undefined;
+            // Publish the backfilled values before the schema write.
+            if (backfillReplacers) {
+                const backfillRenameList = [];
+                for (const key of changedComputedKeys) {
+                    const lines = {};
+                    for (const [line, values] of Object.entries(backfillReplacers))
+                        if (Object.hasOwn(values, key))
+                            lines[Number(line)] = File.encode(values[key]);
+                    if (!Object.keys(lines).length)
+                        continue;
+                    backfillRenameList.push(await File.replace(join(tablePath, `${key}${this.getFileExtension(tableName)}`), lines));
+                }
+                for (const [tmp, live] of backfillRenameList)
+                    if (tmp && live)
+                        await rename(tmp, live);
+            }
             // Data-bearing schema writes go through File.write so they are
             // fsynced before updateTable returns.
             await File.write(join(tablePath, `schema.${this.schemaFileExtension}`), this.schemaFileExtension === "json"
@@ -271,11 +415,6 @@ export default class Inibase {
             // files padded with one empty line per existing row so appends keep
             // line-aligned with the other column files (decode("") is
             // undefined/null, matching the "no value yet" semantics).
-            let totalLines = 0;
-            for await (const paginationFileName of glob("*.pagination", {
-                cwd: tablePath,
-            }))
-                totalLines = parse(paginationFileName).name.split("-").map(Number)[1];
             await Promise.allSettled(schema.map(async ({ key }) => {
                 const filePath = join(tablePath, `${key}${this.getFileExtension(tableName)}`);
                 if (!(await File.isExists(filePath)))
@@ -380,6 +519,12 @@ export default class Inibase {
         // change survives a crash.
         await File.syncDir(config?.name ? this.databasePath : tablePath);
         globalConfig[this.databasePath].tables?.delete(tableName);
+        // The schema on disk changed under the DDL lock: drop the cached plan
+        // (also under the old name when the table was renamed) so the next DML
+        // rebuilds from the reloaded schema.
+        this.computedPlanCache.delete(tableName);
+        if (config?.name && config.name !== tableName)
+            this.computedPlanCache.delete(config.name);
     }
     /**
      * Get table schema and config
@@ -405,6 +550,9 @@ export default class Inibase {
                 },
                 timestamp: await File.getFileDate(join(tablePath, `schema.${this.schemaFileExtension}`)),
             });
+        // A reload means the on-disk schema changed (create/update/external
+        // edit): the cached computed plan is derived from it.
+        this.computedPlanCache.delete(tableName);
         return globalConfig[this.databasePath].tables?.get(tableName);
     }
     async getTableSchema(tableName) {
@@ -477,6 +625,13 @@ export default class Inibase {
         }
         if (Utils.isObject(data)) {
             for (const field of schema) {
+                // Computed columns are never user-settable: their value is
+                // always derived by the engine at write time.
+                if (typeof field.computed !== "undefined") {
+                    if (Object.hasOwn(data, field.key))
+                        throw this.createError("COMPUTED_FIELD_SETTABLE", field.key);
+                    continue;
+                }
                 if (!Object.hasOwn(data, field.key) ||
                     data[field.key] === null ||
                     data[field.key] === undefined ||
@@ -860,6 +1015,454 @@ export default class Inibase {
         }
         return RETURN;
     }
+    /* -----------------------------------------------------------------------
+     * Computed fields
+     * --------------------------------------------------------------------- */
+    /**
+     * Extract the raw expression from a field's `computed` property (string or
+     * persisted `{ expr, ast }` spec).
+     */
+    computedExprOf(field) {
+        const computed = field.computed;
+        return typeof computed === "string" ? computed : (computed?.expr ?? "");
+    }
+    /**
+     * 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.
+     */
+    async compileComputedFields(schema) {
+        const computedFields = schema.filter((field) => typeof field.computed !== "undefined");
+        if (!computedFields.length)
+            return schema;
+        const index = buildFieldIndex(schema);
+        const ctx = {
+            language: this.language,
+            ownKey: "",
+            index,
+            getTableIndex: async (target) => this.tableFieldIndex(target),
+        };
+        const resolved = [];
+        for (const field of computedFields) {
+            // Computed fields are evaluated from the row of the table they
+            // belong to, so v1 restricts them to top-level schema fields.
+            const ref = index.get(field.id);
+            if (!ref || ref.arrayAncestor)
+                throw this.createError("COMPUTED_FIELD_INVALID_TARGET", field.key);
+            ctx.ownKey = field.key;
+            const raw = parseExpression(this.computedExprOf(field), this.language, field.key);
+            const { ast, deps } = await resolveExpression(raw, ctx);
+            resolved.push({ field, ast, deps });
+        }
+        const ordered = topoSortComputedFields(resolved.map(({ field, deps }) => ({
+            id: field.id,
+            key: field.key,
+            deps,
+        })), this.language);
+        const specByKey = new Map();
+        for (const meta of ordered) {
+            const entry = resolved.find(({ field }) => field.id === meta.id);
+            if (!entry)
+                continue;
+            specByKey.set(meta.key, {
+                expr: this.computedExprOf(entry.field),
+                ast: entry.ast,
+            });
+        }
+        return schema.map((field) => typeof field.computed !== "undefined"
+            ? { ...field, computed: specByKey.get(field.key) }
+            : field);
+    }
+    /**
+     * Build the evaluation plan (topological order + id index) for a table's
+     * computed fields. Throws on cycles or unresolvable expressions.
+     */
+    async buildComputedPlan(tableName, schema) {
+        // Plans only depend on the persisted schema (compiled, id-based ASTs),
+        // so cache per table and invalidate on schema changes. The explicit
+        // `schema` argument (backfill during updateTable) always bypasses the
+        // cache — the caller owns that freshly-migrated schema.
+        if (schema === undefined) {
+            const cached = this.computedPlanCache.get(tableName);
+            if (cached !== undefined)
+                return cached;
+        }
+        const s = schema ?? globalConfig[this.databasePath].tables?.get(tableName)?.schema;
+        if (!s)
+            return null;
+        const index = buildFieldIndex(s);
+        const fields = [];
+        const indexCache = new Map();
+        const ctx = {
+            language: this.language,
+            ownKey: "",
+            index,
+            getTableIndex: async (target) => {
+                let cached = indexCache.get(target);
+                if (!cached) {
+                    cached = await this.tableFieldIndex(target);
+                    if (cached)
+                        indexCache.set(target, cached);
+                }
+                return cached;
+            },
+        };
+        for (const field of s) {
+            if (typeof field.computed === "undefined")
+                continue;
+            const computed = field.computed;
+            if (typeof computed === "string") {
+                ctx.ownKey = field.key;
+                const raw = parseExpression(computed, this.language, field.key);
+                const { ast, deps } = await resolveExpression(raw, ctx);
+                fields.push({
+                    id: field.id,
+                    key: field.key,
+                    ast,
+                    deps,
+                });
+            }
+            else
+                fields.push({
+                    id: field.id,
+                    key: field.key,
+                    ast: computed.ast,
+                    deps: collectFieldDeps(computed.ast),
+                });
+        }
+        if (!fields.length) {
+            if (schema === undefined)
+                this.computedPlanCache.set(tableName, null);
+            return null;
+        }
+        const ordered = topoSortComputedFields(fields.map(({ id, key, deps }) => ({ id, key, deps })), this.language);
+        const byId = new Map(fields.map((f) => [f.id, f]));
+        const planFields = ordered.map((meta) => byId.get(meta.id));
+        const plan = {
+            fields: planFields,
+            index,
+            hasHops: planFields.some((field) => astHasHops(field.ast)),
+        };
+        if (schema === undefined)
+            this.computedPlanCache.set(tableName, plan);
+        return plan;
+    }
+    /** Id index of a table's schema (link targets are re-resolved at write
+     *  time, so renames never retarget a compiled expression). */
+    async tableFieldIndex(tableName) {
+        const schema = await this.getTableSchema(tableName);
+        return schema ? buildFieldIndex(schema) : undefined;
+    }
+    /**
+     * 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.
+     */
+    async evaluateComputedRows(tableName, plan, rows) {
+        const out = {};
+        const indexCache = new Map([
+            [tableName, plan.index],
+        ]);
+        const entries = Object.entries(rows);
+        const reader = plan.hasHops ? this.createLinkReader() : null;
+        if (reader) {
+            for (const [, row] of entries)
+                await this.evaluateRowComputed(tableName, plan, row, indexCache, reader, true);
+            if (reader.hasPending)
+                await reader.resolveAll();
+        }
+        for (const [line, row] of entries)
+            out[Number(line)] = await this.evaluateRowComputed(tableName, plan, row, indexCache, reader ?? undefined);
+        return out;
+    }
+    createLinkReader() {
+        return new LinkedRowReader((table, column, id) => this.readLinkedRow(table, id, column));
+    }
+    /** Evaluate every computed field of one row (topological order) and merge
+     *  the results back into the row so dependent fields see them. */
+    async evaluateRowComputed(tableName, plan, row, indexCache, links, collect = false) {
+        const out = {};
+        // One structured frame per row, shared by every computed field: paths
+        // resolve against the row in place (direct key-path reads), so no
+        // flattened copy is ever built. Freshly evaluated values are written
+        // back into the row — computed fields are top-level keys, so dependent
+        // fields see earlier results through the same key-path reads.
+        const env = {
+            table: tableName,
+            index: plan.index,
+            frame: row,
+            row,
+            strip: "",
+            ownKey: "",
+            indexCache,
+            links,
+            collect,
+        };
+        for (const field of plan.fields) {
+            env.strip = "";
+            env.ownKey = field.key;
+            const value = await this.evaluateNode(field.ast, env);
+            out[field.key] = value;
+            row[field.key] = value;
+        }
+        return out;
+    }
+    async evaluateNode(node, env) {
+        switch (node.kind) {
+            case "num":
+                return node.value;
+            case "path":
+                return this.evaluatePath(node, env);
+            case "bin": {
+                const a = await this.evaluateNode(node.left, env);
+                const b = await this.evaluateNode(node.right, env);
+                return this.applyBinaryOp(node.op, a, b, env.ownKey, env.collect);
+            }
+            case "fn": {
+                const arrayRef = env.index.get(node.arrayFieldId);
+                const arrayKey = arrayRef?.key;
+                const raw = arrayKey ? env.row[arrayKey] : undefined;
+                // formatData turns a missing/empty array-of-objects into `{}`;
+                // treat anything that is not an actual array as empty.
+                const elements = Array.isArray(raw) ? raw : [];
+                const values = [];
+                // Reuse the env object across elements (only frame/strip
+                // change) to avoid allocating a frame per element. Elements
+                // are walked in place via direct key-path reads, so nothing is
+                // flattened or cached.
+                const savedFrame = env.frame;
+                const savedStrip = env.strip;
+                const stripPrefix = arrayKey ? `${arrayKey}.` : "";
+                for (const element of elements) {
+                    if (!Utils.isObject(element))
+                        continue;
+                    env.frame = element;
+                    env.strip = stripPrefix;
+                    const value = await this.evaluateNode(node.arg, env);
+                    if (value === null || value === undefined)
+                        continue;
+                    const num = this.coerceNumber(value, env.ownKey);
+                    values.push(num);
+                }
+                env.frame = savedFrame;
+                env.strip = savedStrip;
+                return this.aggregate(node.name, values, elements.length, env.ownKey, env.collect);
+            }
+        }
+    }
+    /** Evaluate a path (`ids`, dot-separated link hops) against the current
+     *  frame. Returns `null` when an intermediate link value is missing. */
+    async evaluatePath(node, env) {
+        const ids = node.ids;
+        let table = env.table;
+        let index = env.index;
+        let frame = env.frame;
+        let strip = env.strip;
+        let value;
+        let ref;
+        for (let i = 0; i < ids.length; i++) {
+            ref = index.get(ids[i]);
+            if (!ref)
+                throw this.createError("COMPUTED_FIELD_UNKNOWN_FIELD", [
+                    env.ownKey,
+                    ids[i],
+                ]);
+            const key = strip && ref.key.startsWith(strip)
+                ? ref.key.slice(strip.length)
+                : ref.key;
+            if (i === 0) {
+                // Direct key-path read: walk the structured frame in place.
+                value = resolveFramePath(frame, key);
+                strip = "";
+            }
+            else {
+                // `value` is the id of the row this hop lives in.
+                if (value === undefined ||
+                    value === null ||
+                    value === "" ||
+                    (typeof value === "object" && value !== null))
+                    return null;
+                // A transaction cannot read a dependency table it has already
+                // staged (no read-your-writes past its commit point).
+                if (this.transaction?.tables.has(table))
+                    throw this.createError("INVALID_PARAMETERS");
+                // Batched link-hop reads: during the collection pass a hop
+                // only records its (table, column, id) triple; the real pass
+                // is served from the reader's warm cache. Without a reader
+                // this is the plain per-hop engine read.
+                const row = env.links
+                    ? env.collect
+                        ? (env.links.record(table, ref.key, value), null)
+                        : await env.links.read(table, ref.key, value)
+                    : await this.readLinkedRow(table, value, ref.key);
+                if (!env.collect &&
+                    (row === undefined || row === null))
+                    throw this.createError("COMPUTED_FIELD_DANGLING_LINK", [
+                        env.ownKey,
+                        table,
+                    ]);
+                // The linked row is the next frame, walked in place (no
+                // flattened copy). readLinkedRow already fetched only the
+                // `ref.key` column, so the frame is minimal.
+                frame = row;
+                value = row ? resolveFramePath(frame, ref.key) : null;
+                index = (await this.indexFor(table, env.indexCache)) ?? index;
+            }
+            if (i < ids.length - 1) {
+                if (ref.field.type !== "table" || typeof ref.field.table !== "string")
+                    throw this.createError("COMPUTED_FIELD_INVALID_LINK", [
+                        env.ownKey,
+                        ids[i + 1],
+                    ]);
+                table = ref.field.table;
+                index = (await this.indexFor(table, env.indexCache)) ?? index;
+            }
+        }
+        return value === undefined ? null : value;
+    }
+    /** Id index lookup with a shared per-evaluation cache. */
+    async indexFor(tableName, cache) {
+        const cached = cache.get(tableName);
+        if (cached)
+            return cached;
+        const index = await this.tableFieldIndex(tableName);
+        if (index)
+            cache.set(tableName, index);
+        return index;
+    }
+    /** Read a single column of one linked row via `get`, or null when the
+     *  row does not exist (dangling link). */
+    async readLinkedRow(tableName, id, column) {
+        const row = await this.get(tableName, id, { columns: [column] }, true);
+        return row ?? null;
+    }
+    coerceNumber(value, ownKey) {
+        const num = Number(value);
+        if (!Number.isFinite(num))
+            throw this.createError("COMPUTED_FIELD_ARITHMETIC", [
+                ownKey,
+                `non-numeric value '${String(value)}'`,
+            ]);
+        return num;
+    }
+    applyBinaryOp(op, a, b, ownKey, collect = false) {
+        if (a === null || a === undefined || b === null || b === undefined) {
+            // Collection passes must tolerate unresolved (null) link hops:
+            // the pass only discovers which links are needed, so a neutral
+            // result is fine. Real evaluation still throws.
+            if (collect)
+                return 0;
+            throw this.createError("COMPUTED_FIELD_ARITHMETIC", [
+                ownKey,
+                "missing or null operand",
+            ]);
+        }
+        const an = this.coerceNumber(a, ownKey);
+        const bn = this.coerceNumber(b, ownKey);
+        switch (op) {
+            case "add":
+                return an + bn;
+            case "sub":
+                return an - bn;
+            case "mul":
+                return an * bn;
+            case "div":
+                if (bn === 0)
+                    throw this.createError("COMPUTED_FIELD_ARITHMETIC", [
+                        ownKey,
+                        "division by zero",
+                    ]);
+                return an / bn;
+            case "mod":
+                if (bn === 0)
+                    throw this.createError("COMPUTED_FIELD_ARITHMETIC", [
+                        ownKey,
+                        "modulo by zero",
+                    ]);
+                return an % bn;
+        }
+    }
+    aggregate(name, values, elementCount, ownKey, collect = false) {
+        switch (name) {
+            case "count":
+                // Aggregates iterate the row's actual array, so count is the
+                // element count (regardless of value presence).
+                return elementCount;
+            case "sum":
+                return values.reduce((acc, v) => acc + v, 0);
+            case "avg": {
+                if (!values.length) {
+                    // Collection passes may have skipped every value of an
+                    // array whose elements only held unresolved link hops.
+                    if (collect)
+                        return 0;
+                    throw this.createError("COMPUTED_FIELD_ARITHMETIC", [
+                        ownKey,
+                        "average over no values",
+                    ]);
+                }
+                return values.reduce((acc, v) => acc + v, 0) / values.length;
+            }
+            case "min": {
+                if (!values.length) {
+                    if (collect)
+                        return 0;
+                    throw this.createError("COMPUTED_FIELD_ARITHMETIC", [
+                        ownKey,
+                        "min over no values",
+                    ]);
+                }
+                return Math.min(...values);
+            }
+            case "max": {
+                if (!values.length) {
+                    if (collect)
+                        return 0;
+                    throw this.createError("COMPUTED_FIELD_ARITHMETIC", [
+                        ownKey,
+                        "max over no values",
+                    ]);
+                }
+                return Math.max(...values);
+            }
+        }
+    }
+    /** Merge evaluated per-line computed values into a `pathesContents` map
+     *  as line-numbered replace records (encoded cells). */
+    mergeComputedLineRecords(tableName, plan, evaluated, pathesContents, existing) {
+        for (const field of plan.fields) {
+            const path = join(this.databasePath, tableName, `${field.key}${this.getFileExtension(tableName)}`);
+            const entries = Object.entries(evaluated);
+            // When the pre-update rows are available, compare each column's
+            // re-evaluated line values against the stored ones (deterministic
+            // encode). A column that is identical for every evaluated line is
+            // left untouched — no content buffer, no File.replace, no fsync.
+            if (existing) {
+                let matches = true;
+                for (const [line, values] of entries) {
+                    const old = existing[Number(line)]?.[field.key];
+                    const fresh = File.encode(values[field.key]);
+                    if (old === undefined || File.encode(old) !== fresh) {
+                        matches = false;
+                        break;
+                    }
+                }
+                if (matches)
+                    continue;
+            }
+            const content = pathesContents[path] ?? {};
+            for (const [line, values] of entries)
+                content[Number(line)] = File.encode(values[field.key]);
+            pathesContents[path] = content;
+        }
+    }
     // Helper function to determine if a field is simple
     isSimpleField(fieldType) {
         const complexTypes = ["array", "object", "table"];
@@ -2059,6 +2662,20 @@ export default class Inibase {
                 clonedData.updatedAt = undefined;
             }
             clonedData = this.formatData(clonedData, globalConfig[this.databasePath].tables?.get(tableName)?.schema ?? [], false);
+            // Derived columns: evaluate every computed expression against the
+            // final formatted row (the row is pieced back in place so helpers
+            // iterate the real array values and dependent fields see each
+            // other). Evaluation happens before any file is touched.
+            const computedPlan = await this.buildComputedPlan(tableName);
+            if (computedPlan) {
+                const rows = Array.isArray(clonedData)
+                    ? clonedData
+                    : [clonedData];
+                // Evaluate every row against the shared plan in one batch:
+                // link hops are read once per distinct (table, column, id)
+                // across the whole post instead of once per hop.
+                await this.evaluateComputedRows(tableName, computedPlan, Object.fromEntries(rows.map((row, index) => [index, row])));
+            }
             const pathesContents = this.joinPathesContents(tableName, globalConfig[this.databasePath].tables?.get(tableName)?.config.prepend
                 ? Array.isArray(clonedData)
                     ? clonedData.toReversed()
@@ -2168,12 +2785,37 @@ export default class Inibase {
                 ...(({ id, ...restOfData }) => restOfData)(clonedData),
                 updatedAt: Date.now(),
             });
+            // Derived columns: a where-less put rewrites every row, so each
+            // computed expression must be re-evaluated against the existing
+            // row overlaid with the payload. The plan itself is schema-only.
+            const computedPlan = await this.buildComputedPlan(tableName);
             try {
                 if (this.transaction)
                     await this.ensureTxnLock(tableName);
                 else
                     await File.lock(join(tablePath, ".tmp"));
                 const { total } = await this.resolvePagination(tableName);
+                if (computedPlan) {
+                    const lineNumbers = Array.from({ length: total }, (_, index) => index + 1);
+                    const schema = globalConfig[this.databasePath].tables?.get(tableName)?.schema ??
+                        [];
+                    // Read every stored column (computed ones included) so the
+                    // merge can skip columns whose re-evaluated values are
+                    // unchanged — no rewrite, no fsync for them.
+                    const existing = await this.processSchemaData(tableName, schema, lineNumbers);
+                    const payloadRows = (Array.isArray(clonedData) ? clonedData : [clonedData]).map((row) => Object.fromEntries(Object.entries(row).filter(([, v]) => v !== "undefined")));
+                    const mergedRows = {};
+                    for (let index = 0; index < lineNumbers.length; index++) {
+                        const line = lineNumbers[index];
+                        mergedRows[line] = {
+                            ...(existing[line] ?? {}),
+                            ...(payloadRows[index % payloadRows.length] ?? {}),
+                            updatedAt: Date.now(),
+                        };
+                    }
+                    const evaluated = await this.evaluateComputedRows(tableName, computedPlan, mergedRows);
+                    this.mergeComputedLineRecords(tableName, computedPlan, evaluated, pathesContents, existing);
+                }
                 await Promise.allSettled(Object.entries(pathesContents).map(async ([path, content]) => renameList.push(await File.replace(path, content, total))));
                 if (this.transaction) {
                     // Stage instead of publishing: row count is unchanged so
@@ -2233,6 +2875,9 @@ export default class Inibase {
                     return obj;
                 }, {}),
             ]));
+            // Derived columns re-evaluate the target lines: existing values +
+            // payload overlay feed the expressions, results go back per line.
+            const computedPlan = await this.buildComputedPlan(tableName);
             try {
                 // One global lock per table serializes every writer; inside a
                 // transaction the lock is held for the whole txn.
@@ -2240,6 +2885,30 @@ export default class Inibase {
                     await this.ensureTxnLock(tableName);
                 else
                     await File.lock(join(tablePath, ".tmp"));
+                if (computedPlan) {
+                    const whereLines = Array.isArray(where) ? where : [where];
+                    const schema = globalConfig[this.databasePath].tables?.get(tableName)?.schema ??
+                        [];
+                    // Read every stored column (computed ones included) so the
+                    // merge can skip columns whose re-evaluated values are
+                    // unchanged — no rewrite, no fsync for them.
+                    const existing = await this.processSchemaData(tableName, schema, whereLines);
+                    const payloadRows = (Array.isArray(clonedData) ? clonedData : [clonedData]).map((row) => Object.fromEntries(Object.entries(row).filter(([, v]) => v !== "undefined")));
+                    const evaluated = {};
+                    const indexCache = new Map([
+                        [tableName, computedPlan.index],
+                    ]);
+                    for (let index = 0; index < whereLines.length; index++) {
+                        const line = whereLines[index];
+                        const merged = {
+                            ...(existing[line] ?? {}),
+                            ...(payloadRows[index] ?? {}),
+                            updatedAt: Date.now(),
+                        };
+                        evaluated[line] = await this.evaluateRowComputed(tableName, computedPlan, merged, indexCache);
+                    }
+                    this.mergeComputedLineRecords(tableName, computedPlan, evaluated, pathesContents, existing);
+                }
                 await Promise.allSettled(Object.entries(pathesContents).map(async ([path, content]) => renameList.push(await File.replace(path, content))));
                 if (this.transaction) {
                     await this.stageTxnOp(tableName, renameList, null);