inibase 3.1.1 → 3.2.0

package/README.md

@@ -798,6 +798,20 @@ await db.sum("user", "age");
 
 // get the sum of column "age" by criteria (where "isActive" is equal to "false") in "user" table
 await db.sum("user", ["age", ...], { isActive: false });
+
+// aggregate over the elements of an array-of-objects column: `items.quantity`
+// counts every element of every row's `items` (single array path per call;
+// `product` here is an *element* predicate, matching elements whose linked
+// product is the given row)
+await db.sum("orders", "items.quantity", { product: "id-of-widget" }, { nested: true });
+
+// multiple columns share one predicate and return a record
+await db.sum(
+	"orders",
+	["items.quantity", "items.lineTotal"],
+	{ product: "id-of-widget" },
+	{ nested: true },
+); // => { "items.quantity": 5, "items.lineTotal": 1295 }
 ```
 
 </blockquote>
@@ -910,6 +924,68 @@ const posted = await db.post(
 // posted.totalCentsLive === 847  (2*price(widget) + 1*price(gadget))
 ```
 
+A child of an array-of-objects column can itself be computed. It is evaluated
+once **per element** and stored in its own element cell, so it works like any
+other element child in queries — including `sum` with `{ nested: true }`:
+
+```ts
+// ids are assigned per table in schema order: status=1, items=2, product=3,
+// quantity=4, lineTotal=5
+await db.createTable("orders", [
+	{ key: "status", type: "number" },
+	{
+		key: "items",
+		type: "array",
+		children: [
+			{ key: "product", type: "table", table: "product" },
+			{ key: "quantity", type: "number" },
+			// lineTotal = quantity × product.price  ("4 * 3.2": id 4 = quantity,
+			// hop to the linked product's price, id 2 in `product`)
+			{ key: "lineTotal", type: "number", computed: "4 * 3.2" },
+		],
+	},
+]);
+
+const posted = await db.post(
+	"orders",
+	{
+		status: 1,
+		items: [
+			{ product: "id-of-widget", quantity: 2 },
+			{ product: "id-of-gadget", quantity: 1 },
+		],
+	},
+	undefined,
+	true,
+);
+// posted.items[0].lineTotal === 2 * price(widget)
+// posted.items[1].lineTotal === 1 * price(gadget)
+
+// per-product revenue without touching the line items yourself:
+await db.sum("orders", "items.lineTotal", { product: "id-of-widget" }, { nested: true });
+```
+
+A top-level computed may read a computed child through a helper
+(`{ key: "totalCents", type: "number", computed: "sum(5)" }`) — the children
+are derived first, in dependency order.
+
+**Element expressions (child computeds).**
+
+- Every reference must be a sibling child of the same array root — top-level
+  columns and siblings of a *different* array are rejected
+  (`COMPUTED_FIELD_INVALID_TARGET`), and helpers (`sum`/`avg`/...) are not
+  allowed inside element expressions.
+- Link hops are supported (`4 * 3.2` = sibling `quantity` × linked
+  `product.price`).
+- The element field must be `type: "number"`.
+- A **missing/null** operand in an element evaluates to `0` for that element
+  (it never aborts the write and never stores null). A genuinely dangling link
+  (a link to a missing row) still raises `COMPUTED_FIELD_DANGLING_LINK`, same
+  as top-level computeds.
+- `updateTable` backfills element cells when a child computed is added or its
+  expression changes; the backfill resolves links from the persisted element
+  values and follows the same missing-operand → `0` rule.
+
 **Expression language (v1, integer-only).**
 
 - Operators: `+` `-` `*` `/` `%`; `( )` for grouping. Multiplication
@@ -941,10 +1017,14 @@ const posted = await db.post(
   `avg`/`min`/`max` over no values throw `COMPUTED_FIELD_ARITHMETIC`.
 - Non-numeric operands, division/modulo by zero, and arithmetic over missing
   (null) values throw `COMPUTED_FIELD_ARITHMETIC`; a link to a missing row
-  throws `COMPUTED_FIELD_DANGLING_LINK`.
-- Only top-level schema fields can be computed in v1; array contents are
-  reachable through helpers. Missing link values make a single bare path
-  evaluate to null (stored empty).
+  throws `COMPUTED_FIELD_DANGLING_LINK`. (Element expressions are the one
+  exception: a missing/null operand there evaluates that element to `0` — see
+  above.)
+- Child computeds (see above) extend the v1 rules to element fields of
+  array-of-objects columns; array contents stay reachable from top-level
+  helpers. Only one level of nesting is computed.
+- Missing link values make a single bare path evaluate to null (stored
+  empty).
 
 </blockquote>
 </details>

package/dist/expression.d.ts

@@ -118,6 +118,15 @@ export interface ResolveContext {
     index: Map<number, FieldRef>;
     /** Fetch (and cache) the id index of another table, or undefined. */
     getTableIndex: (tableName: string) => Promise<Map<number, FieldRef> | undefined>;
+    /**
+     * When set, the expression being compiled belongs to an *element* of the
+     * array-of-objects field with this id (a child computed field). Every
+     * referenced field must be a sibling child of that same array; top-level
+     * fields and helpers are rejected.
+     */
+    elementContext?: {
+        arrayRootId: number;
+    } | null;
 }
 /**
  * Resolve a raw expression against the schema (and linked tables), returning

package/dist/expression.js

@@ -267,14 +267,27 @@ async function resolvePathNode(node, ctx, inHelper) {
             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)
+    if (ctx.elementContext) {
+        // Child computed field: every reference must be a sibling child of the
+        // computed field's own array root (helpers that recurse into other
+        // arrays and reads of top-level columns are invalid here).
+        if (hop0.arrayAncestor?.id !== ctx.elementContext.arrayRootId)
+            throw createError(ctx.language, "COMPUTED_FIELD_INVALID_TARGET", [
+                ctx.ownKey,
+                ids[0],
+            ]);
+        if (hop0.nestedInArrayOfArrays)
+            throw createError(ctx.language, "COMPUTED_FIELD_INVALID_TARGET", [
+                ctx.ownKey,
+                ids[0],
+            ]);
+    }
+    else if (!inHelper && arrayFieldId !== null)
         throw createError(ctx.language, "COMPUTED_FIELD_INVALID_TARGET", [
             ctx.ownKey,
             ids[0],
         ]);
-    if (inHelper && hop0.arrayAncestor !== null && hop0.nestedInArrayOfArrays)
+    else if (inHelper && hop0.arrayAncestor !== null && hop0.nestedInArrayOfArrays)
         throw createError(ctx.language, "COMPUTED_FIELD_INVALID_TARGET", [
             ctx.ownKey,
             ids[0],
@@ -332,7 +345,7 @@ async function resolveNode(node, ctx, inHelper) {
             };
         }
         case "fn": {
-            if (inHelper)
+            if (inHelper || ctx.elementContext)
                 throw createError(ctx.language, "COMPUTED_FIELD_INVALID_TARGET", [
                     ctx.ownKey,
                 ]);

package/dist/index.d.ts

@@ -29,6 +29,16 @@ export interface Options {
     columns?: string[] | string;
     sort?: Record<string, 1 | -1 | "asc" | "ASC" | "desc" | "DESC"> | string[] | string;
 }
+/** Options for the aggregate actions (`sum`, and later avg/min/max). */
+export interface AggregateOptions {
+    /**
+     * Aggregate over the *elements* of an array-of-objects column instead of
+     * whole rows. The summed columns must be single-level child paths of the
+     * same array root (e.g. `"items.quantity"`); `where` keys that resolve as
+     * children of that root become per-element predicates.
+     */
+    nested?: boolean;
+}
 export interface TableConfig {
     compression?: boolean;
     cache?: boolean;
@@ -183,6 +193,12 @@ export default class Inibase {
      * persisted `{ expr, ast }` spec).
      */
     private computedExprOf;
+    /**
+     * Every computed field of a schema as dotted keys (computed children of an
+     * array-of-objects column use their full path, e.g. `items.lineTotal`),
+     * with its raw expression — used for updateTable change detection.
+     */
+    private computedEntries;
     /**
      * Compile every `computed` expression of a schema (which must already have
      * ids assigned) into its persisted `{ expr, ast }` form, in dependency
@@ -229,6 +245,9 @@ export default class Inibase {
     /** Merge evaluated per-line computed values into a `pathesContents` map
      *  as line-numbered replace records (encoded cells). */
     private mergeComputedLineRecords;
+    /** Compare a freshly evaluated cell value against a stored (already
+     *  decoded) one — both are scalar or index-aligned element arrays. */
+    private sameCellValue;
     private isSimpleField;
     private processSimpleField;
     /**
@@ -407,6 +426,15 @@ export default class Inibase {
      */
     sum(tableName: string, columns: string, where?: number | string | (number | string)[] | Criteria): Promise<number>;
     sum(tableName: string, columns: string[], where?: number | string | (number | string)[] | Criteria): Promise<Record<string, number>>;
+    /**
+     * Element-wise aggregation over an array-of-objects column (`nested` mode).
+     *
+     * `where` keys that resolve as children of the array root become per-element
+     * predicates (AND); everything else is a row-level filter. Only elements
+     * passing every element predicate, inside rows passing the row filters, are
+     * accumulated.
+     */
+    private sumNested;
     /**
      * Generate average of column(s) in a table
      *

package/dist/index.js

@@ -364,14 +364,14 @@ export default class Inibase {
             // 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 oldComputed = new Map(this.computedEntries(table.schema ?? []).map(({ key, expr }) => [
+                key,
+                expr,
+            ]));
             const changedComputedKeys = new Set(totalLines > 0
-                ? schema
-                    .filter((field) => typeof field.computed !== "undefined" &&
-                    oldComputed.get(field.key) !== this.computedExprOf(field))
-                    .map((field) => field.key)
+                ? this.computedEntries(schema)
+                    .filter(({ key, expr }) => oldComputed.get(key) !== expr)
+                    .map(({ key }) => key)
                 : []);
             const backfillReplacers = changedComputedKeys.size
                 ? await (async () => {
@@ -1026,6 +1026,25 @@ export default class Inibase {
         const computed = field.computed;
         return typeof computed === "string" ? computed : (computed?.expr ?? "");
     }
+    /**
+     * Every computed field of a schema as dotted keys (computed children of an
+     * array-of-objects column use their full path, e.g. `items.lineTotal`),
+     * with its raw expression — used for updateTable change detection.
+     */
+    computedEntries(schema) {
+        const out = [];
+        const walk = (fields, prefix) => {
+            for (const field of fields) {
+                const key = prefix ? `${prefix}.${field.key}` : field.key;
+                if (typeof field.computed !== "undefined")
+                    out.push({ key, expr: this.computedExprOf(field) });
+                if (field.children && Utils.isArrayOfObjects(field.children))
+                    walk(field.children, key);
+            }
+        };
+        walk(schema, "");
+        return out;
+    }
     /**
      * Compile every `computed` expression of a schema (which must already have
      * ids assigned) into its persisted `{ expr, ast }` form, in dependency
@@ -1033,27 +1052,67 @@ export default class Inibase {
      * 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 entries = [];
         const index = buildFieldIndex(schema);
+        const walk = (fields, prefix) => {
+            for (const field of fields) {
+                const key = prefix ? `${prefix}.${field.key}` : field.key;
+                if (typeof field.computed !== "undefined") {
+                    const ref = index.get(field.id);
+                    entries.push({
+                        field,
+                        key,
+                        elementRoot: ref?.arrayAncestor
+                            ? { id: ref.arrayAncestor.id, key: ref.arrayAncestor.key }
+                            : null,
+                    });
+                }
+                if (field.children && Utils.isArrayOfObjects(field.children))
+                    walk(field.children, key);
+            }
+        };
+        walk(schema, "");
+        if (!entries.length)
+            return schema;
         const ctx = {
             language: this.language,
             ownKey: "",
             index,
             getTableIndex: async (target) => this.tableFieldIndex(target),
+            elementContext: null,
         };
         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);
+        for (const entry of entries) {
+            const ref = index.get(entry.field.id);
+            if (!ref)
+                throw this.createError("COMPUTED_FIELD_INVALID_TARGET", entry.key);
+            if (entry.elementRoot) {
+                // Element computed field (a child of an array-of-objects
+                // column): must hold a plain value (never a container), and v1
+                // keeps them numeric so writes are always summable.
+                if ((ref.nestedInArrayOfArrays && ref.arrayAncestor) ||
+                    entry.field.type !== "number")
+                    throw this.createError("COMPUTED_FIELD_INVALID_TARGET", entry.key);
+                ctx.elementContext = {
+                    arrayRootId: entry.elementRoot.id,
+                };
+            }
+            else {
+                // Top-level computed field: cannot live inside an array.
+                if (ref.arrayAncestor)
+                    throw this.createError("COMPUTED_FIELD_INVALID_TARGET", entry.key);
+                ctx.elementContext = null;
+            }
+            ctx.ownKey = entry.key;
+            const raw = parseExpression(this.computedExprOf(entry.field), this.language, entry.key);
             const { ast, deps } = await resolveExpression(raw, ctx);
-            resolved.push({ field, ast, deps });
+            resolved.push({
+                field: entry.field,
+                key: entry.key,
+                elementRoot: entry.elementRoot,
+                ast,
+                deps,
+            });
         }
         const ordered = topoSortComputedFields(resolved.map(({ field, deps }) => ({
             id: field.id,
@@ -1065,14 +1124,27 @@ export default class Inibase {
             const entry = resolved.find(({ field }) => field.id === meta.id);
             if (!entry)
                 continue;
-            specByKey.set(meta.key, {
+            specByKey.set(entry.key, {
                 expr: this.computedExprOf(entry.field),
                 ast: entry.ast,
             });
         }
-        return schema.map((field) => typeof field.computed !== "undefined"
-            ? { ...field, computed: specByKey.get(field.key) }
-            : field);
+        const applySpecs = (fields, prefix) => fields.map((field) => {
+            const key = prefix ? `${prefix}.${field.key}` : field.key;
+            let next = field;
+            if (typeof field.computed !== "undefined") {
+                const spec = specByKey.get(key);
+                if (spec)
+                    next = { ...field, computed: spec };
+            }
+            if (field.children && Utils.isArrayOfObjects(field.children))
+                next = {
+                    ...next,
+                    children: applySpecs(field.children, key),
+                };
+            return next;
+        });
+        return applySpecs(schema, "");
     }
     /**
      * Build the evaluation plan (topological order + id index) for a table's
@@ -1098,6 +1170,7 @@ export default class Inibase {
             language: this.language,
             ownKey: "",
             index,
+            elementContext: null,
             getTableIndex: async (target) => {
                 let cached = indexCache.get(target);
                 if (!cached) {
@@ -1108,29 +1181,46 @@ export default class Inibase {
                 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,
-                });
+        // Collect every computed field: top-level ones and, when a schema
+        // carries them, the computed children of array-of-objects columns.
+        const walk = async (fieldsSchema, prefix) => {
+            for (const field of fieldsSchema) {
+                const key = prefix ? `${prefix}.${field.key}` : field.key;
+                if (typeof field.computed !== "undefined") {
+                    const ref = index.get(field.id);
+                    const elementRoot = ref?.arrayAncestor
+                        ? { id: ref.arrayAncestor.id, key: ref.arrayAncestor.key }
+                        : null;
+                    const computed = field.computed;
+                    if (typeof computed === "string") {
+                        ctx.ownKey = key;
+                        ctx.elementContext = elementRoot
+                            ? { arrayRootId: elementRoot.id }
+                            : null;
+                        const raw = parseExpression(computed, this.language, key);
+                        const { ast, deps } = await resolveExpression(raw, ctx);
+                        fields.push({
+                            id: field.id,
+                            key,
+                            ast,
+                            deps,
+                            elementRoot,
+                        });
+                    }
+                    else
+                        fields.push({
+                            id: field.id,
+                            key,
+                            ast: computed.ast,
+                            deps: collectFieldDeps(computed.ast),
+                            elementRoot,
+                        });
+                }
+                if (field.children && Utils.isArrayOfObjects(field.children))
+                    await walk(field.children, key);
             }
-            else
-                fields.push({
-                    id: field.id,
-                    key: field.key,
-                    ast: computed.ast,
-                    deps: collectFieldDeps(computed.ast),
-                });
-        }
+        };
+        await walk(s, "");
         if (!fields.length) {
             if (schema === undefined)
                 this.computedPlanCache.set(tableName, null);
@@ -1206,6 +1296,42 @@ export default class Inibase {
             collect,
         };
         for (const field of plan.fields) {
+            if (field.elementRoot) {
+                // Element computed field (child of an array-of-objects column):
+                // evaluate once per element (frame = element, strip =
+                // `${rootKey}.`), write back into the element so other computed
+                // fields and the flatten pass see it, and report the
+                // per-element array under the dotted column key. Missing
+                // operands read as 0 (`env.nullAsZero`), never an error.
+                const rootKey = field.elementRoot.key;
+                const childKey = field.key.slice(rootKey.length + 1);
+                const elements = Array.isArray(env.row[rootKey])
+                    ? env.row[rootKey]
+                    : [];
+                const savedFrame = env.frame;
+                const savedStrip = env.strip;
+                const savedNullAsZero = env.nullAsZero;
+                env.strip = `${rootKey}.`;
+                env.ownKey = field.key;
+                env.nullAsZero = true;
+                const values = [];
+                for (const element of elements) {
+                    if (!Utils.isObject(element)) {
+                        values.push(0);
+                        continue;
+                    }
+                    env.frame = element;
+                    const value = await this.evaluateNode(field.ast, env);
+                    const written = value === null || value === undefined ? 0 : value;
+                    element[childKey] = written;
+                    values.push(written);
+                }
+                env.frame = savedFrame;
+                env.strip = savedStrip;
+                env.nullAsZero = savedNullAsZero;
+                out[field.key] = values;
+                continue;
+            }
             env.strip = "";
             env.ownKey = field.key;
             const value = await this.evaluateNode(field.ast, env);
@@ -1223,7 +1349,7 @@ export default class Inibase {
             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);
+                return this.applyBinaryOp(node.op, a, b, env.ownKey, env.collect, env.nullAsZero);
             }
             case "fn": {
                 const arrayRef = env.index.get(node.arrayFieldId);
@@ -1283,7 +1409,12 @@ export default class Inibase {
                 strip = "";
             }
             else {
-                // `value` is the id of the row this hop lives in.
+                // `value` is the id of the row this hop lives in. Rows that
+                // came off disk are eagerly resolved by processSchemaData, so
+                // table children may already be linked objects — unwrap those
+                // back to their id before the hop lookup. Nothing else hops.
+                if (typeof value === "object" && value !== null)
+                    value = value.id;
                 if (value === undefined ||
                     value === null ||
                     value === "" ||
@@ -1302,8 +1433,7 @@ export default class Inibase {
                         ? (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))
+                if (!env.collect && (row === undefined || row === null))
                     throw this.createError("COMPUTED_FIELD_DANGLING_LINK", [
                         env.ownKey,
                         table,
@@ -1352,18 +1482,28 @@ export default class Inibase {
             ]);
         return num;
     }
-    applyBinaryOp(op, a, b, ownKey, collect = false) {
+    applyBinaryOp(op, a, b, ownKey, collect = false, nullAsZero = 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;
+            // Element computed evaluation treats a missing operand as the
+            // value 0 (per the element-sum feature), so a single missing
+            // child never aborts the write.
+            if (nullAsZero) {
+                if (a === null || a === undefined)
+                    a = 0;
+                if (b === null || b === undefined)
+                    b = 0;
+            }
+        }
+        if (a === null || a === undefined || b === null || b === undefined)
             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) {
@@ -1447,9 +1587,11 @@ export default class Inibase {
             if (existing) {
                 let matches = true;
                 for (const [line, values] of entries) {
+                    if (!Object.hasOwn(values, field.key))
+                        continue;
+                    const lineValue = values[field.key];
                     const old = existing[Number(line)]?.[field.key];
-                    const fresh = File.encode(values[field.key]);
-                    if (old === undefined || File.encode(old) !== fresh) {
+                    if (old === undefined || !this.sameCellValue(lineValue, old)) {
                         matches = false;
                         break;
                     }
@@ -1459,10 +1601,26 @@ export default class Inibase {
             }
             const content = pathesContents[path] ?? {};
             for (const [line, values] of entries)
-                content[Number(line)] = File.encode(values[field.key]);
+                if (Object.hasOwn(values, field.key) && values[field.key] !== undefined)
+                    content[Number(line)] = File.encode(values[field.key]);
             pathesContents[path] = content;
         }
     }
+    /** Compare a freshly evaluated cell value against a stored (already
+     *  decoded) one — both are scalar or index-aligned element arrays. */
+    sameCellValue(fresh, stored) {
+        if (fresh === stored)
+            return true;
+        if (Array.isArray(fresh) &&
+            Array.isArray(stored) &&
+            fresh.length === stored.length) {
+            for (let i = 0; i < fresh.length; i++)
+                if (fresh[i] !== stored[i])
+                    return false;
+            return true;
+        }
+        return File.encode(fresh) === File.encode(stored);
+    }
     // Helper function to determine if a field is simple
     isSimpleField(fieldType) {
         const complexTypes = ["array", "object", "table"];
@@ -3214,20 +3372,30 @@ export default class Inibase {
             }
         }
     }
-    async sum(tableName, columns, where) {
+    async sum(tableName, columns, where, options) {
         this.validateName(tableName);
         if (!Array.isArray(columns))
             columns = [columns];
-        for (const column of columns)
-            this.validateName(column);
+        for (const column of columns) {
+            // Nested columns are dotted child paths (validated structurally by
+            // `sumNested`); everything else must be a plain safe name.
+            if (!options?.nested)
+                this.validateName(column);
+        }
         await this.throwErrorIfTableEmpty(tableName);
         const RETURN = {};
         const tablePath = join(this.databasePath, tableName);
+        if (options?.nested) {
+            const nested = await this.sumNested(tableName, columns, where, tablePath);
+            return columns.length > 1 ? nested : Object.values(nested)[0];
+        }
         for await (const column of columns) {
             const columnPath = join(tablePath, `${column}${this.getFileExtension(tableName)}`);
             if (await File.isExists(columnPath)) {
                 if (where) {
-                    const lineNumbers = await this.get(tableName, where, undefined, undefined, true);
+                    // `{ perPage: -1 }` so criteria matching is never capped by
+                    // the default page size (15): every matching row counts.
+                    const lineNumbers = await this.get(tableName, where, { perPage: -1 }, undefined, true);
                     RETURN[column] = lineNumbers
                         ? await File.sum(columnPath, lineNumbers)
                         : 0;
@@ -3238,6 +3406,168 @@ export default class Inibase {
         }
         return columns.length > 1 ? RETURN : Object.values(RETURN)[0];
     }
+    /**
+     * Element-wise aggregation over an array-of-objects column (`nested` mode).
+     *
+     * `where` keys that resolve as children of the array root become per-element
+     * predicates (AND); everything else is a row-level filter. Only elements
+     * passing every element predicate, inside rows passing the row filters, are
+     * accumulated.
+     */
+    async sumNested(tableName, columns, where, tablePath) {
+        const tablePathSafe = tablePath ?? join(this.databasePath, tableName);
+        const schema = globalConfig[this.databasePath].tables?.get(tableName)?.schema ?? [];
+        const RETURN = {};
+        // Resolve the array-of-objects root from the summed columns (v1: exactly
+        // one nesting level, e.g. "items.quantity" -> root "items").
+        let rootKey = null;
+        let rootField = null;
+        const targetFields = new Map();
+        for (const column of columns) {
+            const dot = column.indexOf(".");
+            if (dot <= 0 || dot === column.length - 1 || column.indexOf(".", dot + 1) !== -1)
+                throw this.createError("INVALID_PARAMETERS", [
+                    `sum nested: '${column}' must be a single-level child path of an array-of-objects column`,
+                ]);
+            const rk = column.slice(0, dot);
+            if (rootKey !== null && rk !== rootKey)
+                throw this.createError("INVALID_PARAMETERS", [
+                    "sum nested: all summed columns must share the same array root",
+                ]);
+            rootKey = rk;
+            // NB: `getField` on a single segment that resolves to an
+            // array-of-objects field returns its *first child*, so resolve the
+            // root field directly from the top-level schema.
+            rootField = schema.find((f) => f.key === rk) ?? null;
+            const okRoot = rootField &&
+                rootField.type === "array" &&
+                Array.isArray(rootField.children) &&
+                Utils.isArrayOfObjects(rootField.children);
+            if (!okRoot)
+                throw this.createError("INVALID_PARAMETERS", [
+                    `sum nested: '${rk}' is not an array-of-objects column`,
+                ]);
+            const child = Utils.getField(column, schema);
+            if (!child || child.type === "array" || child.type === "object")
+                throw this.createError("INVALID_PARAMETERS", [
+                    `sum nested: '${column}' does not resolve to a scalar child`,
+                ]);
+            targetFields.set(column, child);
+        }
+        if (!rootKey)
+            return RETURN;
+        // Split `where` into element predicates (children of the root) and a
+        // row-level filter (everything else, incl. `and`/`or` groups).
+        const elementPredicates = [];
+        const rowWhere = {};
+        let idWhere;
+        if (where && Utils.isObject(where)) {
+            for (const [key, value] of Object.entries(where)) {
+                if (key === "and" || key === "or") {
+                    rowWhere[key] = value;
+                    continue;
+                }
+                const candidate = key.startsWith(`${rootKey}.`)
+                    ? key
+                    : `${rootKey}.${key}`;
+                const child = Utils.getField(candidate, schema);
+                if (child) {
+                    if (Utils.isObject(value))
+                        throw this.createError("INVALID_PARAMETERS", [
+                            `sum nested: element predicate '${key}' must be a scalar, not an object`,
+                        ]);
+                    const [operator, comparedValue] = typeof value === "string"
+                        ? Utils.FormatObjectCriteriaValue(value)
+                        : ["=", value];
+                    if (operator === "[]" || operator === "![]")
+                        throw this.createError("INVALID_PARAMETERS", [
+                            `sum nested: operator '${operator}' is not supported on element predicates`,
+                        ]);
+                    elementPredicates.push({
+                        field: child,
+                        operator,
+                        comparedValue,
+                    });
+                }
+                else {
+                    if (!Utils.getField(key, schema))
+                        throw this.createError("INVALID_PARAMETERS", [
+                            `sum nested: criteria key '${key}' matches neither the array root nor a row column`,
+                        ]);
+                    rowWhere[key] = value;
+                }
+            }
+        }
+        else if (typeof where === "number" ||
+            typeof where === "string" ||
+            Array.isArray(where)) {
+            idWhere = where;
+        }
+        // Row-level narrowing (ids or criteria). `undefined` lines = whole file.
+        let lines;
+        if (idWhere !== undefined)
+            lines = (await this.get(tableName, idWhere, { perPage: -1 }, undefined, true));
+        else if (Object.keys(rowWhere).length)
+            lines = (await this.get(tableName, rowWhere, { perPage: -1 }, undefined, true));
+        if (lines === null) {
+            for (const column of columns)
+                RETURN[column] = 0;
+            return RETURN;
+        }
+        const fieldOpt = (field) => ({
+            ...field,
+            databasePath: this.databasePath,
+        });
+        const ext = this.getFileExtension(tableName);
+        // Element predicate cells, read once for every summed column.
+        const predCells = new Map();
+        for (const p of elementPredicates) {
+            const path = join(tablePathSafe, `${rootKey}.${p.field.key}${ext}`);
+            if (!(await File.isExists(path)))
+                continue;
+            const cell = (await File.get(path, lines, fieldOpt(p.field)));
+            if (cell)
+                predCells.set(p.field.key, cell);
+        }
+        for (const [column, child] of targetFields) {
+            const path = join(tablePathSafe, `${column}${ext}`);
+            if (!(await File.isExists(path))) {
+                RETURN[column] = 0;
+                continue;
+            }
+            const cell = (await File.get(path, lines, fieldOpt(child)));
+            if (!cell) {
+                RETURN[column] = 0;
+                continue;
+            }
+            let sum = 0;
+            for (const [lineStr, values] of Object.entries(cell)) {
+                if (!Array.isArray(values))
+                    continue;
+                for (let i = 0; i < values.length; i++) {
+                    const v = values[i];
+                    if (v === null || v === undefined)
+                        continue;
+                    let matches = true;
+                    for (const p of elementPredicates) {
+                        const pv = predCells.get(p.field.key)?.[Number(lineStr)]?.[i];
+                        if (pv === undefined || !UtilsServer.compare(p.operator, pv, p.comparedValue, p.field.type)) {
+                            matches = false;
+                            break;
+                        }
+                    }
+                    if (!matches)
+                        continue;
+                    const num = Number(v);
+                    if (Number.isNaN(num))
+                        continue;
+                    sum += num;
+                }
+            }
+            RETURN[column] = sum;
+        }
+        return RETURN;
+    }
     async avg(tableName, columns, where) {
         this.validateName(tableName);
         if (!Array.isArray(columns))
@@ -3251,7 +3581,7 @@ export default class Inibase {
             const columnPath = join(tablePath, `${column}${this.getFileExtension(tableName)}`);
             if (await File.isExists(columnPath)) {
                 if (where) {
-                    const lineNumbers = await this.get(tableName, where, undefined, undefined, true);
+                    const lineNumbers = await this.get(tableName, where, { perPage: -1 }, undefined, true);
                     RETURN[column] = lineNumbers
                         ? await File.avg(columnPath, lineNumbers)
                         : 0;
@@ -3275,7 +3605,7 @@ export default class Inibase {
             const columnPath = join(tablePath, `${column}${this.getFileExtension(tableName)}`);
             if (await File.isExists(columnPath)) {
                 if (where) {
-                    const lineNumbers = await this.get(tableName, where, undefined, undefined, true);
+                    const lineNumbers = await this.get(tableName, where, { perPage: -1 }, undefined, true);
                     RETURN[column] = lineNumbers
                         ? await File.max(columnPath, lineNumbers)
                         : 0;
@@ -3299,7 +3629,7 @@ export default class Inibase {
             const columnPath = join(tablePath, `${column}${this.getFileExtension(tableName)}`);
             if (await File.isExists(columnPath)) {
                 if (where) {
-                    const lineNumbers = await this.get(tableName, where, undefined, undefined, true);
+                    const lineNumbers = await this.get(tableName, where, { perPage: -1 }, undefined, true);
                     RETURN[column] = lineNumbers
                         ? await File.min(columnPath, lineNumbers)
                         : 0;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "inibase",
-  "version": "3.1.1",
+  "version": "3.2.0",
   "type": "module",
   "author": {
     "name": "Karim Amahtil",
@@ -88,7 +88,7 @@
     "benchmark": "./benchmark/run.js",
     "benchmark:durability": "tsx ./benchmark/durability.ts",
     "benchmark:computed": "tsx ./benchmark/computed.ts",
-    "test": "tsx ./tests/inibase.test.ts && tsx ./tests/inibase.advanced.test.ts && tsx ./tests/transaction.test.ts && tsx ./tests/durability.test.ts && tsx ./tests/expression.test.ts && tsx ./tests/utils.test.ts",
+    "test": "tsx ./tests/inibase.test.ts && tsx ./tests/inibase.advanced.test.ts && tsx ./tests/transaction.test.ts && tsx ./tests/durability.test.ts && tsx ./tests/expression.test.ts && tsx ./tests/utils.test.ts && tsx ./tests/sum.nested.test.ts && tsx ./tests/computed.child.test.ts",
     "test:durability": "tsx ./tests/durability.test.ts",
     "test:transaction": "tsx ./tests/transaction.test.ts",
     "test:utils": "tsx ./tests/utils.test.ts",