inibase 3.1.1 → 3.3.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/file.d.ts

@@ -1,5 +1,21 @@
 import { type ComparisonOperator, type Field } from "./index.js";
 export declare const DURABLE: boolean;
+/**
+ * Run `fn` with a per-logical-task lock-owner store on its AsyncLocalStorage
+ * context. Every await continuation below `fn` then shares that store, so
+ * nested/reentrant acquisitions (put/delete id->line recursion, journal
+ * recovery re-locks, transaction flows) see the SAME store the outermost
+ * acquisition recorded as owner.
+ *
+ * Do NOT replace this with an enterWith() from inside lock(): that store is
+ * created in lock()'s own frame and (a) never propagates back to the caller's
+ * await continuation — every recursion then waits on its OWN lock until the
+ * watchdog (LOCK_WAIT_TIMEOUT) — and (b) can leak into sibling tasks, which
+ * then pass the writer lock as "reentrant" and re-race the Sep-2026 commit
+ * interleave (ENOENT renames, duplicate ids). `run()` gives clean per-op
+ * isolation and correct same-chain propagation.
+ */
+export declare const runWithLockStore: <T>(fn: () => T) => T;
 export declare const lock: (folderPath: string, prefix?: string, ttl?: number) => Promise<void>;
 /**
  * Non-blocking lock acquisition (used by the read path and the open-time

package/dist/file.js

@@ -1,3 +1,4 @@
+import { AsyncLocalStorage } from "node:async_hooks";
 import { access, appendFile, copyFile, constants as fsConstants, open, readFile, stat, unlink, } from "node:fs/promises";
 import { hostname } from "node:os";
 import { join, resolve } from "node:path";
@@ -31,6 +32,87 @@ const LOCK_RETRY_MS = 13;
 // multiple times (e.g. post() -> get() -> sort-cache). Depth 1 is a real
 // filesystem acquisition; deeper acquisitions just bump the counter.
 const lockDepths = new Map();
+// In-process serialization: sibling tasks (e.g. two concurrent HTTP requests
+// posting to the same table) must QUEUE behind the holder instead of passing
+// straight through the depth counter. That bypass is exactly what let
+// concurrent writers share the fixed `.tmp/<column>` staging path and race the
+// pagination rename (diverged column files, duplicate ids, lost rows in the
+// Sep-2026 pteam incident). Reentrancy from the *same* logical task (post() ->
+// get() -> ensureTableRecovered re-lock, transaction flows) still bumps the
+// depth without touching the filesystem, proven by the AsyncLocalStorage
+// context recorded at acquisition time.
+const lockReleaseWaiters = new Map();
+const lockOwners = new Map();
+// Upper bound on in-process wait time: converts a wedged or undetectable
+// holder into a visible error instead of a silent hang. 0 disables it.
+const LOCK_WAIT_TIMEOUT_MS = Number(process.env.INIBASE_LOCK_WAIT_TIMEOUT_MS ?? 120_000);
+const lockContext = new AsyncLocalStorage();
+// Resolve once the holder releases so the waiter can re-race for the lock.
+const waitForLockRelease = (resolvedPath) => new Promise((resolveWaiter, rejectWaiter) => {
+    let waiters = lockReleaseWaiters.get(resolvedPath);
+    if (!waiters) {
+        waiters = new Set();
+        lockReleaseWaiters.set(resolvedPath, waiters);
+    }
+    let timer = null;
+    const wake = (error) => {
+        waiters.delete(wake);
+        if (timer)
+            clearTimeout(timer);
+        error ? rejectWaiter(error) : resolveWaiter();
+    };
+    waiters.add(wake);
+    if (LOCK_WAIT_TIMEOUT_MS > 0)
+        timer = setTimeout(() => wake(new Error(`LOCK_WAIT_TIMEOUT: ${resolvedPath}`)), LOCK_WAIT_TIMEOUT_MS);
+});
+// The AsyncLocalStorage store of this task chain (created on first acquire).
+const currentLockStore = () => {
+    let store = lockContext.getStore();
+    if (!store) {
+        store = new Set();
+        lockContext.enterWith(store);
+    }
+    return store;
+};
+/**
+ * Run `fn` with a per-logical-task lock-owner store on its AsyncLocalStorage
+ * context. Every await continuation below `fn` then shares that store, so
+ * nested/reentrant acquisitions (put/delete id->line recursion, journal
+ * recovery re-locks, transaction flows) see the SAME store the outermost
+ * acquisition recorded as owner.
+ *
+ * Do NOT replace this with an enterWith() from inside lock(): that store is
+ * created in lock()'s own frame and (a) never propagates back to the caller's
+ * await continuation — every recursion then waits on its OWN lock until the
+ * watchdog (LOCK_WAIT_TIMEOUT) — and (b) can leak into sibling tasks, which
+ * then pass the writer lock as "reentrant" and re-race the Sep-2026 commit
+ * interleave (ENOENT renames, duplicate ids). `run()` gives clean per-op
+ * isolation and correct same-chain propagation.
+ */
+export const runWithLockStore = (fn) => {
+    if (lockContext.getStore())
+        return fn();
+    const store = new Set();
+    return lockContext.run(store, fn);
+};
+// True when this task already owns the lock (depth > 0 and the recorded owner
+// context is this task's context). Bumps the depth and returns.
+const isReentrant = (resolvedPath) => {
+    if (!lockDepths.get(resolvedPath))
+        return false;
+    if (lockOwners.get(resolvedPath) !== lockContext.getStore())
+        return false;
+    lockDepths.set(resolvedPath, lockDepths.get(resolvedPath) + 1);
+    return true;
+};
+const notifyLockReleased = (resolvedPath) => {
+    const waiters = lockReleaseWaiters.get(resolvedPath);
+    if (!waiters)
+        return;
+    lockReleaseWaiters.delete(resolvedPath);
+    for (const wake of waiters)
+        wake();
+};
 const lockFilePathFor = (folderPath, prefix) => join(folderPath, `${prefix ?? ""}.locked`);
 const lockOwnerState = async (lockFilePath) => {
     try {
@@ -67,12 +149,16 @@ const stealableLock = async (lockFilePath, mtimeMs, ttl) => {
 export const lock = async (folderPath, prefix, ttl = DEFAULT_LOCK_TTL_MS) => {
     const lockFilePath = lockFilePathFor(folderPath, prefix);
     const resolvedPath = resolve(lockFilePath);
-    const depth = lockDepths.get(resolvedPath);
-    if (depth) {
-        lockDepths.set(resolvedPath, depth + 1);
-        return;
-    }
     for (;;) {
+        // Same logical task already holds it -> reentrant depth bump.
+        if (isReentrant(resolvedPath))
+            return;
+        // A different in-process task holds it -> wait for the release, then
+        // re-race for the filesystem lock like any process.
+        if (lockDepths.get(resolvedPath)) {
+            await waitForLockRelease(resolvedPath);
+            continue;
+        }
         try {
             const lockFile = await open(lockFilePath, "wx");
             try {
@@ -100,6 +186,7 @@ export const lock = async (folderPath, prefix, ttl = DEFAULT_LOCK_TTL_MS) => {
                 }
             }
             lockDepths.set(resolvedPath, 1);
+            lockOwners.set(resolvedPath, currentLockStore());
             return;
         }
         catch (error) {
@@ -129,11 +216,10 @@ export const lock = async (folderPath, prefix, ttl = DEFAULT_LOCK_TTL_MS) => {
 export const tryLock = async (folderPath, prefix, ttl = DEFAULT_LOCK_TTL_MS) => {
     const lockFilePath = lockFilePathFor(folderPath, prefix);
     const resolvedPath = resolve(lockFilePath);
-    const depth = lockDepths.get(resolvedPath);
-    if (depth) {
-        lockDepths.set(resolvedPath, depth + 1);
+    if (isReentrant(resolvedPath))
         return true;
-    }
+    if (lockDepths.get(resolvedPath))
+        return false; // held by another in-process task: non-blocking
     for (let attempt = 0; attempt < 2; attempt++) {
         try {
             const lockFile = await open(lockFilePath, "wx");
@@ -157,6 +243,7 @@ export const tryLock = async (folderPath, prefix, ttl = DEFAULT_LOCK_TTL_MS) =>
                 }
             }
             lockDepths.set(resolvedPath, 1);
+            lockOwners.set(resolvedPath, currentLockStore());
             return true;
         }
         catch (error) {
@@ -183,12 +270,15 @@ export const unlock = async (folderPath, prefix) => {
         return;
     }
     lockDepths.delete(resolvedPath);
+    lockOwners.delete(resolvedPath);
     try {
         await unlink(lockFilePath);
     }
     catch {
         // Already released (stolen by a foreign-host stealer or cleaned up).
     }
+    // Wake in-process waiters so they re-race for the released lock.
+    notifyLockReleased(resolvedPath);
 };
 export const write = async (filePath, data) => {
     const handle = await open(filePath, "w");
@@ -242,6 +332,17 @@ export function escapeShellPath(filePath) {
     // Escape double quotes and special shell characters
     return `"${resolvedPath.replace(/(["\\$`])/g, "\\$1")}"`;
 }
+/**
+ * Unique-per-operation staging path: concurrent writers must never share the
+ * `.tmp/<column>` file. The fixed name let sibling operations clobber each
+ * other's in-progress temp and publish a temp that only contained one writer's
+ * content (column files following different winners -> diverged line counts).
+ * A pid + per-process counter suffix keeps every temp private; each pair is
+ * carried through the rename list and the journal, so commit/rollback/recovery
+ * still know exactly which files to move.
+ */
+let tempSeq = 0;
+const tempPathFor = (filePath) => filePath.replace(/([^/]+)\/?$/, `.tmp/$1.${process.pid}-${(tempSeq++).toString(36)}`);
 const _pipeline = async (filePath, rl, writeStream, transform) => {
     if (filePath.endsWith(".gz"))
         await pipeline(rl, transform, createGzip(), writeStream);
@@ -505,7 +606,7 @@ export async function get(filePath, lineNumbers, field, readWholeFile = false) {
  * Note: If the file doesn't exist and replacements is an object, it creates a new file with the specified replacements.
  */
 export const replace = async (filePath, replacements, totalItems) => {
-    const fileTempPath = filePath.replace(/([^/]+)\/?$/, ".tmp/$1");
+    const fileTempPath = tempPathFor(filePath);
     const isReplacementsObject = isObject(replacements);
     const isReplacementsLineNumbered = isReplacementsObject && !Number.isNaN(Number(Object.keys(replacements)[0]));
     if (await isExists(filePath)) {
@@ -581,19 +682,33 @@ export const replace = async (filePath, replacements, totalItems) => {
                 const replacementsKeys = Object.keys(replacements)
                     .map(Number)
                     .toSorted((a, b) => a - b);
-                await write(fileTempPath, `${"\n".repeat(replacementsKeys[0] - 1) +
-                    replacementsKeys
-                        .map((lineNumber, index) => index === 0 ||
-                        lineNumber - replacementsKeys[index - 1] - 1 === 0
-                        ? replacements[lineNumber]
-                        : "\n".repeat(lineNumber - replacementsKeys[index - 1] - 1) +
-                            replacements[lineNumber])
-                        .join("\n")}\n`);
+                await write(fileTempPath, 
+                // First-write for a compressed column: see append() — the
+                // unique temp path hides the ".gz" suffix from write().
+                filePath.endsWith(".gz")
+                    ? await gzip(`${"\n".repeat(replacementsKeys[0] - 1) +
+                        replacementsKeys
+                            .map((lineNumber, index) => index === 0 ||
+                            lineNumber - replacementsKeys[index - 1] - 1 === 0
+                            ? replacements[lineNumber]
+                            : "\n".repeat(lineNumber - replacementsKeys[index - 1] - 1) + replacements[lineNumber])
+                            .join("\n")}\n`)
+                    : `${"\n".repeat(replacementsKeys[0] - 1) +
+                        replacementsKeys
+                            .map((lineNumber, index) => index === 0 ||
+                            lineNumber - replacementsKeys[index - 1] - 1 === 0
+                            ? replacements[lineNumber]
+                            : "\n".repeat(lineNumber - replacementsKeys[index - 1] - 1) + replacements[lineNumber])
+                            .join("\n")}\n`);
             }
             else {
                 if (!totalItems)
                     throw new Error("INVALID_PARAMETERS");
-                await write(fileTempPath, `${`${replacements}\n`.repeat(totalItems)}\n`);
+                await write(fileTempPath, 
+                // First-write for a compressed column: see append().
+                filePath.endsWith(".gz")
+                    ? await gzip(`${`${replacements}\n`.repeat(totalItems)}\n`)
+                    : `${`${replacements}\n`.repeat(totalItems)}\n`);
             }
             return [fileTempPath, filePath];
         }
@@ -612,7 +727,7 @@ export const replace = async (filePath, replacements, totalItems) => {
  *
  */
 export const append = async (filePath, data) => {
-    const fileTempPath = filePath.replace(/([^/]+)\/?$/, ".tmp/$1");
+    const fileTempPath = tempPathFor(filePath);
     try {
         if (await isExists(filePath)) {
             await copyFile(filePath, fileTempPath);
@@ -627,7 +742,13 @@ export const append = async (filePath, data) => {
             }
         }
         else
-            await write(fileTempPath, `${Array.isArray(data) ? data.join("\n") : data}\n`);
+            await write(fileTempPath, 
+            // Unique temp paths no longer end with the original extension
+            // (.tmp/<col>.<pid>-<seq>), so write()'s suffix check can't
+            // gzip a first-write for a compressed column. Do it here.
+            filePath.endsWith(".gz")
+                ? await gzip(`${Array.isArray(data) ? data.join("\n") : data}\n`)
+                : `${Array.isArray(data) ? data.join("\n") : data}\n`);
         return [fileTempPath, filePath];
     }
     catch {
@@ -643,7 +764,7 @@ export const append = async (filePath, data) => {
  *
  */
 export const prepend = async (filePath, data) => {
-    const fileTempPath = filePath.replace(/([^/]+)\/?$/, ".tmp/$1");
+    const fileTempPath = tempPathFor(filePath);
     if (await isExists(filePath)) {
         if (!filePath.endsWith(".gz")) {
             let fileHandle = null;
@@ -673,7 +794,7 @@ export const prepend = async (filePath, data) => {
             }
         }
         else {
-            const fileChildTempPath = filePath.replace(/([^/]+)\/?$/, ".tmp/tmp_$1");
+            const fileChildTempPath = `${tempPathFor(filePath)}.child`;
             try {
                 await write(fileChildTempPath, `${Array.isArray(data) ? data.join("\n") : data}\n`);
                 const escapedFilePath = escapeShellPath(filePath);
@@ -691,7 +812,12 @@ export const prepend = async (filePath, data) => {
     }
     else {
         try {
-            await write(fileTempPath, `${Array.isArray(data) ? data.join("\n") : data}\n`);
+            await write(fileTempPath, 
+            // First-write for a compressed column: see append() — the
+            // unique temp path hides the ".gz" suffix from write().
+            filePath.endsWith(".gz")
+                ? await gzip(`${Array.isArray(data) ? data.join("\n") : data}\n`)
+                : `${Array.isArray(data) ? data.join("\n") : data}\n`);
         }
         catch {
             return [fileTempPath, null];
@@ -714,7 +840,7 @@ export const remove = async (filePath, linesToDelete) => {
         : [Number(linesToDelete)];
     if (linesToDelete.some(Number.isNaN))
         throw new Error("UNVALID_LINE_NUMBERS");
-    const fileTempPath = filePath.replace(/([^/]+)\/?$/, ".tmp/$1");
+    const fileTempPath = tempPathFor(filePath);
     try {
         const escapedFilePath = escapeShellPath(filePath);
         const escapedFileTempPath = escapeShellPath(fileTempPath);

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;
@@ -145,6 +155,7 @@ export default class Inibase {
      * @param {TableConfig} [config]
      */
     createTable(tableName: string, schema?: Schema, config?: TableConfig): Promise<void>;
+    private _createTable;
     private replaceStringInFile;
     /**
      * Update table schema or config
@@ -156,6 +167,7 @@ export default class Inibase {
     updateTable(tableName: string, schema?: Schema, config?: TableConfig & {
         name?: string;
     }): Promise<void>;
+    private _updateTable;
     private updateTableLocked;
     /**
      * Get table schema and config
@@ -183,6 +195,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 +247,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;
     /**
@@ -314,6 +335,7 @@ export default class Inibase {
      * locked on first touch, in first-touch order.
      */
     begin(tables?: string[]): Promise<void>;
+    private _begin;
     /**
      * Publish every staged mutation atomically: per table (sorted), the
      * pagination rename comes first (the atomic publication point readers
@@ -352,6 +374,7 @@ export default class Inibase {
     get<TData extends Record<string, any> & Partial<Data>>(tableName: string, where?: string | number | (string | number)[] | Criteria, options?: Options, onlyOne?: boolean, onlyLinesNumbers?: false, _whereIsLinesNumbers?: boolean): Promise<(Data & TData)[] | null>;
     get<_TData extends Record<string, any> & Partial<Data>>(tableName: string, where: string | number | (string | number)[] | Criteria | undefined, options: Options | undefined, onlyOne: false | undefined, onlyLinesNumbers: true, _whereIsLinesNumbers?: boolean): Promise<number[] | null>;
     get<_TData extends Record<string, any> & Partial<Data>>(tableName: string, where: string | number | (string | number)[] | Criteria | undefined, options: Options | undefined, onlyOne: true, onlyLinesNumbers: true, _whereIsLinesNumbers?: boolean): Promise<number | null>;
+    private _get;
     private getOnce;
     /**
      * Create new item(s) in a table
@@ -366,6 +389,7 @@ export default class Inibase {
     post<TData extends Record<string, any> & Partial<Data>>(tableName: string, data: (Data & TData)[], options?: Options, returnPostedData?: boolean): Promise<string[]>;
     post<TData extends Record<string, any> & Partial<Data>>(tableName: string, data: Data & TData, options: Options | undefined, returnPostedData: true): Promise<(Data & TData) | null>;
     post<TData extends Record<string, any> & Partial<Data>>(tableName: string, data: (Data & TData)[], options: Options | undefined, returnPostedData: true): Promise<(Data & TData)[] | null>;
+    private _post;
     /**
      * Update item(s) in a table
      *
@@ -380,6 +404,7 @@ export default class Inibase {
     put<TData extends Record<string, any> & Partial<Data>>(tableName: string, data: Data & TData, where: number | string | (number | string)[] | Criteria | undefined, options: Options | undefined, returnUpdatedData: true | boolean, _whereIsLinesNumbers?: boolean): Promise<(Data & TData) | null>;
     put<TData extends Record<string, any> & Partial<Data>>(tableName: string, data: (Data & TData)[], where: number | string | (number | string)[] | Criteria | undefined, options: Options | undefined, returnUpdatedData: true | boolean, _whereIsLinesNumbers?: boolean): Promise<(Data & TData)[] | null>;
     put<TData extends Record<string, any> & Partial<Data>>(tableName: string, data: (Data & TData) | (Data & TData)[], where: number | string | (number | string)[] | Criteria | undefined, options: Options | undefined, returnUpdatedData: true | boolean, _whereIsLinesNumbers?: boolean): Promise<(Data & TData) | (Data & TData)[] | null>;
+    private _put;
     /**
      * Delete item(s) in a table
      *
@@ -388,6 +413,7 @@ export default class Inibase {
      * @return {boolean | null}  {(Promise<boolean | null>)}
      */
     delete(tableName: string, where?: number | string | (number | string)[] | Criteria, _whereIsLinesNumbers?: boolean, _cascadeGuard?: Set<string>): Promise<boolean | null>;
+    private _delete;
     /**
      * Cascade delete: remove rows in other tables whose `table`-typed schema
      * fields reference the given rows. Reference columns store the numeric
@@ -405,8 +431,17 @@ export default class Inibase {
      * @param {(number | string | (number | string)[] | Criteria)} [where]
      * @return {*}  {Promise<number | Record<string, number>>}
      */
-    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>>;
+    sum(tableName: string, columns: string, where?: number | string | (number | string)[] | Criteria, options?: AggregateOptions): Promise<number>;
+    sum(tableName: string, columns: string[], where?: number | string | (number | string)[] | Criteria, options?: AggregateOptions): 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
      *