inibase 1.8.0 → 2.0.0

package/README.md

@@ -791,6 +791,7 @@ await db.get("user", undefined, { sort: {age: -1, username: "asc"} });
 | DELETE | 118 ms (0.59 mb)    | 113 ms (0.51 mb)   | 103 ms (3.14 mb)   |
 
 > Default testing uses a table with username, email, and password fields, ensuring password encryption is included in the process<br>
+> Results are measured on a default table plus dedicated tables with `prepend`, `compression`, and `decodeID` configs enabled<br>
 > To run benchmarks, install _typescript_ & _[tsx](https://github.com/privatenumber/tsx)_ globally and run `benchmark` by default bulk, for single use `benchmark --single|-s`
 
 ## Roadmap

package/dist/file.d.ts

@@ -30,7 +30,8 @@ export declare const encode: (input: string | number | boolean | null | (string
  */
 export declare const decode: (input: string | null | number, field: Field & {
     databasePath?: string;
-}) => string | number | boolean | null | (string | number | null | boolean)[];
+}) => string | number | boolean | null | undefined | (string | number | null | boolean)[];
+export declare function _groupIntoRanges(arr: number[], action?: "p" | "d"): string | any[];
 /**
  * Asynchronously reads and decodes data from a file at specified line numbers.
  * Decodes each line based on specified field types and an optional secret key.
@@ -45,11 +46,11 @@ export declare const decode: (input: string | null | number, field: Field & {
  */
 export declare function get(filePath: string, lineNumbers?: number | number[], field?: Field & {
     databasePath?: string;
-}, readWholeFile?: false): Promise<Record<number, string | number | boolean | null | (string | number | boolean | (string | number | boolean)[] | null)[]> | null>;
+}, readWholeFile?: false): Promise<Record<number, string | number | boolean | null | undefined | (string | number | boolean | (string | number | boolean)[] | null)[]> | null>;
 export declare function get(filePath: string, lineNumbers: undefined | number | number[], field: undefined | (Field & {
     databasePath?: string;
 }), readWholeFile: true): Promise<[
-    Record<number, string | number | boolean | null | (string | number | boolean | (string | number | boolean)[] | null)[]> | null,
+    Record<number, string | number | boolean | null | undefined | (string | number | boolean | (string | number | boolean)[] | null)[]> | null,
     number
 ]>;
 /**
@@ -62,7 +63,7 @@ export declare function get(filePath: string, lineNumbers: undefined | number |
  *
  * Note: If the file doesn't exist and replacements is an object, it creates a new file with the specified replacements.
  */
-export declare const replace: (filePath: string, replacements: string | number | boolean | null | (string | number | boolean | null)[] | Record<number, string | boolean | number | null | (string | boolean | number | null)[]>, totalItems?: number) => Promise<string[]>;
+export declare const replace: (filePath: string, replacements: string | number | boolean | null | (string | number | boolean | null)[] | Record<number, string | boolean | number | null | (string | boolean | number | null)[]>, totalItems?: number) => Promise<(string | null)[]>;
 /**
  * Asynchronously appends data to the end of a file.
  *
@@ -71,7 +72,7 @@ export declare const replace: (filePath: string, replacements: string | number |
  * @returns Promise<string[]>. Modifies the file by appending data.
  *
  */
-export declare const append: (filePath: string, data: string | number | (string | number)[]) => Promise<string[]>;
+export declare const append: (filePath: string, data: string | number | (string | number)[]) => Promise<(string | null)[]>;
 /**
  * Asynchronously prepends data to the beginning of a file.
  *
@@ -80,7 +81,7 @@ export declare const append: (filePath: string, data: string | number | (string
  * @returns Promise<string[]>. Modifies the file by appending data.
  *
  */
-export declare const prepend: (filePath: string, data: string | number | (string | number)[]) => Promise<string[]>;
+export declare const prepend: (filePath: string, data: string | number | (string | number)[]) => Promise<(string | null)[]>;
 /**
  * Asynchronously removes specified lines from a file.
  *
@@ -90,7 +91,7 @@ export declare const prepend: (filePath: string, data: string | number | (string
  *
  * Note: Creates a temporary file during the process and replaces the original file with it after removing lines.
  */
-export declare const remove: (filePath: string, linesToDelete: number | number[]) => Promise<string[]>;
+export declare const remove: (filePath: string, linesToDelete: number | number[]) => Promise<(string | null)[]>;
 /**
  * Asynchronously searches a file for lines matching specified criteria, using comparison and logical operators.
  *
@@ -110,7 +111,7 @@ export declare const remove: (filePath: string, linesToDelete: number | number[]
  */
 export declare const search: (filePath: string, operator: ComparisonOperator | ComparisonOperator[], comparedAtValue: string | number | boolean | null | (string | number | boolean | null)[], logicalOperator?: "and" | "or", searchIn?: Set<number>, field?: Field & {
     databasePath?: string;
-}, limit?: number, offset?: number, readWholeFile?: boolean) => Promise<[Record<number, string | number | boolean | null | (string | number | boolean | null)[]> | null, number, Set<number> | null]>;
+}, limit?: number, offset?: number, readWholeFile?: boolean) => Promise<[Record<number, string | number | boolean | null | undefined | (string | number | boolean | null)[]> | null, number, Set<number> | null]>;
 export declare const sum: (fp: string, ln?: number | number[]) => Promise<number>;
 export declare const min: (fp: string, ln?: number | number[]) => Promise<number>;
 export declare const max: (fp: string, ln?: number | number[]) => Promise<number>;

package/dist/file.js

@@ -129,8 +129,10 @@ export const encode = (input) => Array.isArray(input)
 const unSecureString = (input) => {
     if (isNumber(input))
         return String(input).at(0) === "0" ? input : Number(input);
+    // Fast path: the common case has no `\n` escape sequence, so avoid
+    // allocating a replacement string (and a fresh RegExp) per cell.
     if (typeof input === "string")
-        return input.replace(/\\n/g, "\n") || null;
+        return input.includes("\\n") ? input.replaceAll("\\n", "\n") || null : input;
     return null;
 };
 /**
@@ -156,7 +158,8 @@ const decodeHelper = (value, field) => {
                 return value.map((v) => decode(v, {
                     ...field,
                     type: Array.isArray(field.children)
-                        ? detectFieldType(v, field.children)
+                        ? (detectFieldType(v, field.children) ??
+                            field.children[0])
                         : field.children,
                 }));
             break;
@@ -186,15 +189,33 @@ export const decode = (input, field) => {
         return undefined;
     // Detect the fieldType based on the input and the provided array of possible types.
     // Decode the input using the decodeHelper function.
-    return decodeHelper(typeof input === "string"
-        ? isStringified(input)
-            ? Inison.unstringify(input)
-            : unSecureString(input)
-        : input, Array.isArray(field.type)
-        ? { ...field, type: detectFieldType(String(input), field.type) }
+    let value = input;
+    if (typeof input === "string") {
+        if (isStringified(input)) {
+            try {
+                value = Inison.unstringify(input);
+            }
+            catch {
+                // The stored string merely *starts with* `{` or `[`
+                // (e.g. a template binding like `{{item.username}}`
+                // or a literal like `{hello world`) but is not valid
+                // Inison. Treat it as a plain string so a single row
+                // never breaks reads of the whole file/table.
+                value = unSecureString(input);
+            }
+        }
+        else
+            value = unSecureString(input);
+    }
+    return decodeHelper(value, Array.isArray(field.type)
+        ? {
+            ...field,
+            type: detectFieldType(String(input), field.type) ??
+                field.type[0],
+        }
         : field);
 };
-function _groupIntoRanges(arr, action = "p") {
+export function _groupIntoRanges(arr, action = "p") {
     if (arr.length === 0)
         return [];
     arr.sort((a, b) => a - b); // Ensure the array is sorted
@@ -224,10 +245,14 @@ export async function get(filePath, lineNumbers, field, readWholeFile = false) {
         const rl = createReadLineInternface(filePath, fileHandle);
         const lines = {};
         let linesCount = 0;
+        const config = field ?? {
+            key: "BLABLA",
+            type: "string",
+        };
         if (!lineNumbers) {
             for await (const line of rl) {
                 linesCount++;
-                lines[linesCount] = decode(line, field);
+                lines[linesCount] = decode(line, config);
             }
         }
         else if (lineNumbers === -1) {
@@ -237,7 +262,7 @@ export async function get(filePath, lineNumbers, field, readWholeFile = false) {
                 : `sed -n '$p' ${escapedFilePath}`;
             const foundedLine = (await exec(command)).stdout.trimEnd();
             if (foundedLine)
-                lines[linesCount] = decode(foundedLine, field);
+                lines[linesCount] = decode(foundedLine, config);
         }
         else {
             lineNumbers = Array.isArray(lineNumbers) ? lineNumbers : [lineNumbers];
@@ -249,7 +274,7 @@ export async function get(filePath, lineNumbers, field, readWholeFile = false) {
                     linesCount++;
                     if (!lineNumbersArray.has(linesCount))
                         continue;
-                    lines[linesCount] = decode(line, field);
+                    lines[linesCount] = decode(line, config);
                     lineNumbersArray.delete(linesCount);
                 }
                 return [lines, linesCount];
@@ -261,7 +286,7 @@ export async function get(filePath, lineNumbers, field, readWholeFile = false) {
             const foundedLines = (await exec(command)).stdout.trimEnd().split("\n");
             let index = 0;
             for (const line of foundedLines) {
-                lines[lineNumbers[index]] = decode(line, field);
+                lines[lineNumbers[index]] = decode(line, config);
                 index++;
             }
         }
@@ -561,7 +586,7 @@ function buildEqualsPatterns(comparedAtValue, field) {
             for (const form of [...new Set(forms)]) {
                 let valid = false;
                 try {
-                    valid = compare("=", decode(form, field), value, type);
+                    valid = compare("=", decode(form, field) ?? null, value, type);
                 }
                 catch {
                     valid = false;
@@ -578,7 +603,7 @@ function buildEqualsPatterns(comparedAtValue, field) {
             const form = String(Number(value));
             let valid = false;
             try {
-                valid = compare("=", decode(form, field), value, type);
+                valid = compare("=", decode(form, field) ?? null, value, type);
             }
             catch {
                 valid = false;
@@ -607,7 +632,7 @@ function buildEqualsPatterns(comparedAtValue, field) {
             const form = String(encoded);
             let valid = false;
             try {
-                valid = compare("=", decode(form, field), value, type);
+                valid = compare("=", decode(form, field) ?? null, value, type);
             }
             catch {
                 valid = false;
@@ -642,7 +667,7 @@ async function searchEqualsNative(filePath, patterns, field, searchIn, comparedA
     // (decode() eagerly unstringifies them), so a native whole-line grep could
     // silently miss matches that live inside those containers. Detect such lines
     // up front; when any are present, fall back to the JS reader.
-    let probe;
+    let probe = "";
     try {
         ({ stdout: probe } = await exec(`LC_ALL=C ${source} | LC_ALL=C grep -a -m 1 -E '^[[{]'`, { maxBuffer: 1024 * 1024 * 4 }));
     }
@@ -696,8 +721,8 @@ async function searchEqualsNative(filePath, patterns, field, searchIn, comparedA
         // Defensive verification: the raw line must decode to one of the compared
         // values (guaranteed by construction, kept as a safety net).
         const verifies = Array.isArray(comparedAtValue)
-            ? comparedAtValue.some((value) => compare("=", decodedLine, value, field.type))
-            : compare("=", decodedLine, comparedAtValue, field.type);
+            ? comparedAtValue.some((value) => compare("=", decodedLine ?? null, value, field.type))
+            : compare("=", decodedLine ?? null, comparedAtValue, field.type);
         if (!verifies)
             return null;
         matchingLines[lineNumber] = decodedLine;
@@ -724,14 +749,13 @@ async function searchEqualsNative(filePath, patterns, field, searchIn, comparedA
  */
 export const search = async (filePath, operator, comparedAtValue, logicalOperator, searchIn, field, limit, offset, readWholeFile) => {
     // Native fast path for exact-equality searches (whole-line `grep -x -F`).
-    const fieldType = field?.type;
     if (operator === "=" &&
         !Array.isArray(operator) &&
         !logicalOperator &&
         comparedAtValue !== null &&
         comparedAtValue !== undefined &&
-        typeof fieldType === "string" &&
-        EQUALS_FAST_TYPES.has(fieldType)) {
+        typeof field?.type === "string" &&
+        EQUALS_FAST_TYPES.has(field.type)) {
         const patterns = buildEqualsPatterns(comparedAtValue, field);
         if (patterns) {
             const fastResult = await searchEqualsNative(filePath, patterns, field, searchIn, comparedAtValue, limit, offset, readWholeFile);
@@ -745,13 +769,17 @@ export const search = async (filePath, operator, comparedAtValue, logicalOperato
     let linesCount = 0;
     const linesNumbers = new Set();
     let fileHandle = null;
+    const config = field ?? {
+        key: "BLABLA",
+        type: "string",
+    };
     const meetsConditions = (value) => (Array.isArray(operator) &&
         Array.isArray(comparedAtValue) &&
         ((logicalOperator === "or" &&
-            operator.some((single_operator, index) => compare(single_operator, value, comparedAtValue[index], field.type))) ||
-            operator.every((single_operator, index) => compare(single_operator, value, comparedAtValue[index], field.type)))) ||
+            operator.some((single_operator, index) => compare(single_operator, value, comparedAtValue[index], config.type))) ||
+            operator.every((single_operator, index) => compare(single_operator, value, comparedAtValue[index], config.type)))) ||
         (!Array.isArray(operator) &&
-            compare(operator, value, comparedAtValue, field.type));
+            compare(operator, value, comparedAtValue, config.type));
     try {
         // Open the file for reading.
         fileHandle = await open(filePath, "r");
@@ -766,7 +794,7 @@ export const search = async (filePath, operator, comparedAtValue, logicalOperato
                 (!searchIn.has(linesCount) || searchIn.has(-linesCount)))
                 continue;
             // Decode the line for comparison.
-            const decodedLine = decode(line, field);
+            const decodedLine = decode(line, config);
             // Check if the line meets the specified conditions based on comparison and logical operators.
             const doesMeetCondition = (Array.isArray(decodedLine) &&
                 operator !== "=" &&

package/dist/index.d.ts

@@ -73,6 +73,11 @@ export default class Inibase {
     language: ErrorLang;
     fileExtension: string;
     totalItems: Map<string, number>;
+    /** Tracks whether a decodeID table's stored ids are the dense sequence
+     *  1..rowCount (no rows ever deleted). When true, `get`/`put`/`delete` can
+     *  resolve numeric ids to line numbers arithmetically instead of scanning
+     *  the id file. Set false by any partial row deletion. */
+    private idDensity;
     private databasePath;
     private uniqueMap;
     private schemaFileExtension;
@@ -134,6 +139,14 @@ export default class Inibase {
     private processSchemaData;
     private isSimpleField;
     private processSimpleField;
+    /**
+     * Batched read for top-level simple columns: a single `paste | sed` child
+     * process returns every requested line of every column at once instead of
+     * spawning one `sed`/`gunzip|sed` child process per column. Returning null
+     * (e.g. when any column file is missing, or the shell command fails) makes
+     * the caller fall back to the existing per-column reads.
+     */
+    private processSimpleFieldsBatch;
     private isArrayField;
     private processArrayField;
     private isObjectField;
@@ -198,7 +211,16 @@ export default class Inibase {
      * @param {(number | string | (number | string)[] | Criteria)} [where]
      * @return {boolean | null}  {(Promise<boolean | null>)}
      */
-    delete(tableName: string, where?: number | string | (number | string)[] | Criteria, _whereIsLinesNumbers?: boolean): Promise<boolean | null>;
+    delete(tableName: string, where?: number | string | (number | string)[] | Criteria, _whereIsLinesNumbers?: boolean, _cascadeGuard?: Set<string>): Promise<boolean | null>;
+    /**
+     * Cascade delete: remove rows in other tables whose `table`-typed schema
+     * fields reference the given rows. Reference columns store the numeric
+     * (line-number) id of the referenced row, so deleted ids are matched
+     * against them directly. Recursion into child tables happens through
+     * `delete` itself (which calls this method again); the `guard` set keeps
+     * deep/cyclic reference chains from re-processing the same (table, line).
+     */
+    private cascadeDelete;
     /**
      * Generate sum of column(s) in a table
      *

package/dist/index.js

@@ -40,6 +40,11 @@ export default class Inibase {
     language;
     fileExtension = ".txt";
     totalItems;
+    /** Tracks whether a decodeID table's stored ids are the dense sequence
+     *  1..rowCount (no rows ever deleted). When true, `get`/`put`/`delete` can
+     *  resolve numeric ids to line numbers arithmetically instead of scanning
+     *  the id file. Set false by any partial row deletion. */
+    idDensity = new Map();
     databasePath;
     uniqueMap;
     schemaFileExtension = process.env.INIBASE_SCHEMA_EXTENSION ?? "json";
@@ -145,6 +150,8 @@ export default class Inibase {
                 await writeFile(join(tablePath, ".cache.config"), "");
             if (config.prepend)
                 await writeFile(join(tablePath, ".prepend.config"), "");
+            if (config.decodeID)
+                await writeFile(join(tablePath, ".decodeID.config"), "");
         }
         if (schema) {
             const lastSchemaID = { value: 0 };
@@ -156,6 +163,7 @@ export default class Inibase {
         else
             await writeFile(join(tablePath, "0.schema"), "");
         await writeFile(join(tablePath, "0-0.pagination"), "");
+        this.idDensity.set(tableName, true);
     }
     // Function to replace the string in one schema file
     async replaceStringInFile(filePath, targetString, replaceString) {
@@ -213,6 +221,23 @@ export default class Inibase {
                 await rename(schemaIdFilePath, join(tablePath, `${lastSchemaID.value}.schema`));
             else
                 await writeFile(join(tablePath, `${lastSchemaID.value}.schema`), "");
+            // Fields added by this migration have no backing file yet. If the
+            // first post after the migration writes such a file from scratch it
+            // starts at line 1 and every existing row becomes misaligned (the
+            // new value lands on the wrong record). Materialize missing column
+            // 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)))
+                    await File.write(filePath, "\n".repeat(totalLines));
+            }));
         }
         if (config) {
             if (config.compression !== undefined &&
@@ -442,9 +467,11 @@ export default class Inibase {
         }
     }
     async validateTableData(tableName, data, skipRequiredField = false) {
-        const clonedData = structuredClone(data);
+        // `data` is always a private clone owned by the caller (post/put already
+        // cloned it once), so validate in place instead of re-cloning — otherwise
+        // every bulk write holds several full copies of the payload in memory.
         // Skip ID and (created|updated)At
-        this.validateData(clonedData, globalConfig[this.databasePath].tables
+        this.validateData(data, globalConfig[this.databasePath].tables
             ?.get(tableName)
             ?.schema?.slice(1, -2) ?? [], skipRequiredField);
         await this.checkUnique(tableName);
@@ -579,7 +606,11 @@ export default class Inibase {
         this.uniqueMap = new Map();
     }
     formatData(data, schema, formatOnlyAvailiableKeys) {
-        const clonedData = structuredClone(data);
+        // formatData only reads its input (all transformations produce new
+        // values), so no defensive clone is needed. Callers pass data they no
+        // longer need, and skipping the copy halves the payload footprint of
+        // every bulk post/put.
+        const clonedData = data;
         if (Utils.isArrayOfObjects(clonedData))
             return clonedData.map((singleData) => this.formatData(singleData, schema, formatOnlyAvailiableKeys));
         if (Utils.isObject(clonedData)) {
@@ -717,7 +748,26 @@ export default class Inibase {
     }
     async processSchemaData(tableName, schema, linesNumber, options, prefix) {
         const RETURN = {};
+        // Fast path: read every top-level simple column in one `paste | sed`
+        // child process instead of spawning one child process per column.
+        // Nested (prefixed) schemas keep the per-column path.
+        let batchedKeys = null;
+        if (!prefix && linesNumber?.length) {
+            const simpleFields = schema.filter((field) => this.isSimpleField(field.type));
+            const batched = await this.processSimpleFieldsBatch(tableName, simpleFields, linesNumber);
+            if (batched) {
+                batchedKeys = new Set(simpleFields.map((field) => field.key));
+                for (const [line, row] of Object.entries(batched)) {
+                    if (!RETURN[line])
+                        RETURN[line] = {};
+                    Object.assign(RETURN[line], row);
+                }
+            }
+        }
         for (const field of schema) {
+            // Batch-read fields were already merged into RETURN.
+            if (batchedKeys?.has(field.key))
+                continue;
             // If the field is of simple type (non-recursive), process it directly
             if (this.isSimpleField(field.type)) {
                 await this.processSimpleField(tableName, field, RETURN, linesNumber, prefix);
@@ -768,6 +818,80 @@ export default class Inibase {
             }
         }
     }
+    /**
+     * Batched read for top-level simple columns: a single `paste | sed` child
+     * process returns every requested line of every column at once instead of
+     * spawning one `sed`/`gunzip|sed` child process per column. Returning null
+     * (e.g. when any column file is missing, or the shell command fails) makes
+     * the caller fall back to the existing per-column reads.
+     */
+    async processSimpleFieldsBatch(tableName, fields, linesNumber) {
+        if (!fields.length || !linesNumber.length)
+            return null;
+        const decodeID = globalConfig[this.databasePath].tables?.get(tableName)?.config
+            .decodeID === true;
+        // Decode configs are computed once per column (the per-column read path
+        // builds one config per file too), not once per cell.
+        const cols = [];
+        for (const field of fields) {
+            const path = join(this.databasePath, tableName, `${field.key}${this.getFileExtension(tableName)}`);
+            if (!(await File.isExists(path)))
+                return null;
+            cols.push({
+                path,
+                key: field.key,
+                config: {
+                    ...field,
+                    type: field.key === "id" && decodeID
+                        ? "number"
+                        : field.type,
+                    databasePath: this.databasePath,
+                },
+            });
+        }
+        const sortedLines = [...linesNumber].sort((a, b) => a - b);
+        const range = File._groupIntoRanges(sortedLines);
+        const files = cols.map(({ path }) => File.escapeShellPath(path)).join(" ");
+        const isGz = this.getFileExtension(tableName).endsWith(".gz");
+        // Each compressed column needs its own process substitution so the
+        // streams stay aligned column-by-column inside `paste`.
+        const pasteInputs = isGz
+            ? cols
+                .map(({ path }) => `<(gunzip -c ${File.escapeShellPath(path)})`)
+                .join(" ")
+            : files;
+        const command = isGz
+            ? `bash -c 'paste -d "\\t" ${pasteInputs} | sed -n "${range}"'`
+            : `paste -d'\\t' ${files} | sed -n '${range}'`;
+        let output;
+        try {
+            output = (await UtilsServer.exec(command)).stdout;
+        }
+        catch {
+            return null;
+        }
+        const outLines = output.trimEnd().split("\n");
+        const RETURN = {};
+        for (let i = 0; i < outLines.length && i < sortedLines.length; i++) {
+            const lineNo = sortedLines[i];
+            const cells = outLines[i].split("\t");
+            const row = {};
+            let added = false;
+            for (let c = 0; c < cols.length; c++) {
+                const raw = cells[c];
+                if (raw === undefined)
+                    continue;
+                const value = File.decode(raw, cols[c].config);
+                if (value !== undefined) {
+                    row[cols[c].key] = value;
+                    added = true;
+                }
+            }
+            if (added)
+                RETURN[lineNo] = row;
+        }
+        return Object.keys(RETURN).length ? RETURN : null;
+    }
     // Helper function to check if the field type is array
     isArrayField(fieldType) {
         return ((Array.isArray(fieldType) &&
@@ -809,7 +933,8 @@ export default class Inibase {
                             RETURN[index] = {};
                         if (Utils.isObject(item)) {
                             const itemEntries = Object.entries(item);
-                            const itemValues = itemEntries.map(([_key, value]) => value);
+                            // Values without a second per-row tuple array.
+                            const itemValues = Object.values(item);
                             if (!Utils.isArrayOfNulls(itemValues)) {
                                 if (RETURN[index][field.key])
                                     for (let _index = 0; _index < itemEntries.length; _index++) {
@@ -1054,11 +1179,19 @@ export default class Inibase {
                         return null;
                     continue;
                 }
-                const formatedSearchResult = Object.fromEntries(Object.entries(searchResult).map(([id, value]) => {
+                // Merge matched lines into RETURN. The old code round-tripped through
+                // Object.entries(...).map(...) + Object.fromEntries, allocating two
+                // tuple arrays + a map array per matched row; building the nested
+                // result object directly keeps the exact same semantics with less
+                // garbage. Note: in `allTrue` mode RETURN is *replaced* per key
+                // (searchIn narrowing is what enforces the AND), so the assignment
+                // below intentionally mirrors the original replace/merge behavior.
+                const formatedSearchResult = {};
+                for (const id of Object.keys(searchResult)) {
                     const nestedObj = {};
-                    this._setNestedKey(nestedObj, key, value);
-                    return [id, nestedObj];
-                }));
+                    this._setNestedKey(nestedObj, key, searchResult[id]);
+                    formatedSearchResult[id] = nestedObj;
+                }
                 RETURN = allTrue
                     ? formatedSearchResult
                     : Utils.deepMerge(RETURN, formatedSearchResult);
@@ -1080,10 +1213,17 @@ export default class Inibase {
             const searchResult = await this.applyCriteria(tableName, options, criteriaOR, false, searchIn);
             if (searchResult) {
                 RETURN = Utils.deepMerge(RETURN, searchResult);
-                if (!Object.keys(RETURN).length)
-                    RETURN = {};
-                RETURN = Object.fromEntries(Object.entries(RETURN).filter(([_index, item]) => Object.keys(item).filter((key) => Object.keys(criteriaOR).includes(key) ||
-                    Object.keys(criteriaOR).some((criteriaKey) => criteriaKey.startsWith(`${key}.`))).length));
+                // Filter RETURN in place instead of rebuilding it through
+                // Object.entries/fromEntries on every OR iteration. The key list of
+                // criteriaOR is hoisted out of the per-row check as well.
+                const orKeys = Object.keys(criteriaOR);
+                for (const id of Object.keys(RETURN)) {
+                    const item = RETURN[id];
+                    const matches = Object.keys(item).some((key) => orKeys.includes(key) ||
+                        orKeys.some((criteriaKey) => criteriaKey.startsWith(`${key}.`)));
+                    if (!matches)
+                        delete RETURN[id];
+                }
                 if (!Object.keys(RETURN).length)
                     RETURN = {};
             }
@@ -1187,11 +1327,19 @@ export default class Inibase {
                 awkCommand = `awk '${itemsIDs.map((id) => `$1 == ${id}`).join(" || ")}'`;
             }
             else
-                awkCommand = `awk '${Array.from({ length: options.perPage }, (_, index) => (options.page - 1) * options.perPage +
-                    index +
-                    1)
-                    .map((lineNumber) => `NR==${lineNumber}`)
-                    .join(" || ")}'`;
+                // perPage < 0 means "no limit": select every line instead of
+                // generating an empty awk window (with perPage -1 the old code
+                // produced `awk ''`, which prints nothing and the empty stdout
+                // decoded into a single hollow row).
+                awkCommand =
+                    options.perPage < 0
+                        ? "awk '1'"
+                        : `awk '${Array.from({ length: options.perPage }, (_, index) => (options.page - 1) *
+                            options.perPage +
+                            index +
+                            1)
+                            .map((lineNumber) => `NR==${lineNumber}`)
+                            .join(" || ")}'`;
             const filesPathes = (sortArray.find(([key]) => key === "id")
                 ? sortArray
                 : [["id", true], ...sortArray]).map((column) => join(tablePath, `${column[0]}${this.getFileExtension(tableName)}`));
@@ -1200,14 +1348,14 @@ export default class Inibase {
                     return null;
             // Construct the paste command to merge files and filter lines by IDs
             const pasteCommand = `paste '${filesPathes.join("' '")}'`;
-            // Construct the sort command dynamically based on the number of files for sorting
-            const index = 1;
+            const _idPrepended = !sortArray.find(([key]) => key === "id");
             const sortColumns = sortArray
                 .map(([key, ascending], i) => {
                 const field = Utils.getField(key, schema);
-                if (field)
-                    return `-k${i + index},${i + index}${Utils.isFieldType(field, ["id", "number", "date"]) ? "n" : ""}${!ascending ? "r" : ""}`;
-                return "";
+                if (!field)
+                    return "";
+                const colIndex = _idPrepended ? i + 2 : i + 1;
+                return `-k${colIndex},${colIndex}${Utils.isFieldType(field, ["id", "number", "date"]) ? "n" : ""}${!ascending ? "r" : ""}`;
             })
                 .join(" ");
             const sortCommand = `sort ${sortColumns} -T='${join(tablePath, ".tmp")}'`;
@@ -1299,7 +1447,48 @@ export default class Inibase {
             let Ids = where;
             if (!Array.isArray(Ids))
                 Ids = [Ids];
-            const [lineNumbers, countItems] = await File.search(join(tablePath, `id${this.getFileExtension(tableName)}`), "[]", Ids.map((id) => Utils.isNumber(id) ? Number(id) : UtilsServer.decodeID(id)), undefined, undefined, { key: "BLABLA", type: "number" }, Ids.length, 0, !this.totalItems.has(`${tableName}-id`));
+            // Fast path for decodeID tables whose ids are the dense sequence
+            // 1..N: when the requested numeric ids form a duplicate-free
+            // consecutive range [min..max] with max within the row count, the
+            // line numbers ARE the ids — no id-file scan required.
+            let lineNumbers = null;
+            let countItems = 0;
+            const isDecodeID = globalConfig[this.databasePath].tables?.get(tableName)?.config
+                .decodeID === true &&
+                !globalConfig[this.databasePath].tables?.get(tableName)?.config
+                    .prepend;
+            if (isDecodeID &&
+                this.idDensity.get(tableName) &&
+                Ids.every(Utils.isNumber)) {
+                const seen = new Set();
+                let min = Number.POSITIVE_INFINITY;
+                let max = Number.NEGATIVE_INFINITY;
+                let distinct = true;
+                for (const raw of Ids) {
+                    const n = Number(raw);
+                    if (seen.has(n)) {
+                        distinct = false;
+                        break;
+                    }
+                    seen.add(n);
+                    if (n < min)
+                        min = n;
+                    if (n > max)
+                        max = n;
+                }
+                if (distinct &&
+                    min >= 1 &&
+                    max <= pagination[1] &&
+                    max - min + 1 === Ids.length) {
+                    lineNumbers = {};
+                    for (let line = min; line <= max; line++)
+                        lineNumbers[line] = line;
+                    countItems = Ids.length;
+                }
+            }
+            if (!lineNumbers) {
+                [lineNumbers, countItems] = await File.search(join(tablePath, `id${this.getFileExtension(tableName)}`), "[]", Ids.map((id) => Utils.isNumber(id) ? Number(id) : UtilsServer.decodeID(id)), undefined, undefined, { key: "BLABLA", type: "number" }, Ids.length, 0, !this.totalItems.has(`${tableName}-id`));
+            }
             if (!lineNumbers)
                 return null;
             this.totalItems.set(`${tableName}-id`, countItems);
@@ -1425,7 +1614,7 @@ export default class Inibase {
                 ? await File.prepend(path, content)
                 : await File.append(path, content))));
             await Promise.allSettled(renameList
-                .filter(([_, filePath]) => filePath)
+                .filter((pair) => Boolean(pair[1]))
                 .map(async ([tempPath, filePath]) => rename(tempPath, filePath)));
             if (globalConfig[this.databasePath].tables?.get(tableName)?.config.cache)
                 await this.clearCache(tableName);
@@ -1453,7 +1642,7 @@ export default class Inibase {
         finally {
             if (renameList.length)
                 await Promise.allSettled(renameList
-                    .filter(([_, filePath]) => filePath)
+                    .filter((pair) => Boolean(pair[1]))
                     .map(async ([tempPath, _]) => unlink(tempPath)));
             await File.unlock(join(tablePath, ".tmp"), keys);
         }
@@ -1498,7 +1687,7 @@ export default class Inibase {
                     this.totalItems.set(`${tableName}-*`, parse(paginationFileName).name.split("-").map(Number)[1]);
                 await Promise.allSettled(Object.entries(pathesContents).map(async ([path, content]) => renameList.push(await File.replace(path, content, this.totalItems.get(`${tableName}-*`)))));
                 await Promise.allSettled(renameList
-                    .filter(([_, filePath]) => filePath)
+                    .filter((pair) => Boolean(pair[1]))
                     .map(async ([tempPath, filePath]) => rename(tempPath, filePath)));
                 if (globalConfig[this.databasePath].tables?.get(tableName)?.config.cache)
                     await this.clearCache(join(tablePath, ".cache"));
@@ -1508,7 +1697,7 @@ export default class Inibase {
             finally {
                 if (renameList.length)
                     await Promise.allSettled(renameList
-                        .filter(([_, filePath]) => filePath)
+                        .filter((pair) => Boolean(pair[1]))
                         .map(async ([tempPath, _]) => unlink(tempPath)));
                 await File.unlock(join(tablePath, ".tmp"));
             }
@@ -1540,7 +1729,7 @@ export default class Inibase {
                 await File.lock(join(tablePath, ".tmp"), keys);
                 await Promise.allSettled(Object.entries(pathesContents).map(async ([path, content]) => renameList.push(await File.replace(path, content))));
                 await Promise.allSettled(renameList
-                    .filter(([_, filePath]) => filePath)
+                    .filter((pair) => Boolean(pair[1]))
                     .map(async ([tempPath, filePath]) => rename(tempPath, filePath)));
                 if (globalConfig[this.databasePath].tables?.get(tableName)?.config.cache)
                     await this.clearCache(tableName);
@@ -1550,7 +1739,7 @@ export default class Inibase {
             finally {
                 if (renameList.length)
                     await Promise.allSettled(renameList
-                        .filter(([_, filePath]) => filePath)
+                        .filter((pair) => Boolean(pair[1]))
                         .map(async ([tempPath, _]) => unlink(tempPath)));
                 await File.unlock(join(tablePath, ".tmp"), keys);
             }
@@ -1564,7 +1753,14 @@ export default class Inibase {
             Utils.isValidID(where)) {
             const lineNumbers = await this.get(tableName, where, undefined, undefined, true);
             if (lineNumbers)
-                return this.put(tableName, clonedData, lineNumbers, options, returnUpdatedData, true);
+                return this.put(tableName, clonedData, 
+                // get() with onlyLinesNumbers always returns an array; a
+                // single-id update must keep the scalar so the recursive
+                // line-numbers branch returns a single row (matching the
+                // shape of get(singleId)) instead of a one-element array.
+                !Array.isArray(where) && Array.isArray(lineNumbers)
+                    ? lineNumbers[0]
+                    : lineNumbers, options, returnUpdatedData, true);
         }
         else if (Utils.isObject(where)) {
             const lineNumbers = await this.get(tableName, where, undefined, undefined, true);
@@ -1581,7 +1777,7 @@ export default class Inibase {
      * @param {(number | string | (number | string)[] | Criteria)} [where]
      * @return {boolean | null}  {(Promise<boolean | null>)}
      */
-    async delete(tableName, where, _whereIsLinesNumbers) {
+    async delete(tableName, where, _whereIsLinesNumbers, _cascadeGuard) {
         this.validateName(tableName);
         const tablePath = join(this.databasePath, tableName);
         await this.throwErrorIfTableEmpty(tableName);
@@ -1604,6 +1800,12 @@ export default class Inibase {
                 if (globalConfig[this.databasePath].tables?.get(tableName)?.config.cache)
                     await this.clearCache(tableName);
                 await rename(paginationFilePath, join(tablePath, `${pagination[0]}-0.pagination`));
+                this.idDensity.set(tableName, true);
+                // Deleting every row must also delete rows that reference them.
+                if (pagination[1]) {
+                    const allLines = Array.from({ length: pagination[1] }, (_, i) => i + 1);
+                    await this.cascadeDelete(tableName, allLines, new Set());
+                }
                 return true;
             }
             finally {
@@ -1633,24 +1835,30 @@ export default class Inibase {
                     }
                     if (pagination[1] &&
                         pagination[1] - (Array.isArray(where) ? where.length : 1) > 0) {
+                        this.idDensity.set(tableName, false);
                         await Promise.allSettled(files.map(async (file) => renameList.push(await File.remove(join(tablePath, file), where))));
                         await Promise.allSettled(renameList
-                            .filter(([_, filePath]) => filePath)
+                            .filter((pair) => Boolean(pair[1]))
                             .map(async ([tempPath, filePath]) => rename(tempPath, filePath)));
                     }
-                    else
+                    else {
+                        this.idDensity.set(tableName, true);
                         await Promise.allSettled((await readdir(tablePath))
                             ?.filter((fileName) => fileName.endsWith(this.getFileExtension(tableName)))
                             .map(async (file) => unlink(join(tablePath, file))));
+                    }
                     if (globalConfig[this.databasePath].tables?.get(tableName)?.config.cache)
                         await this.clearCache(tableName);
                     await rename(paginationFilePath, join(tablePath, `${pagination[0]}-${pagination[1] - (Array.isArray(where) ? where.length : 1)}.pagination`));
+                    // Cascade: rows in other tables referencing the deleted rows
+                    // (via `table`-typed fields) are removed too.
+                    await this.cascadeDelete(tableName, Array.isArray(where) ? where : [where], _cascadeGuard ?? new Set());
                     return true;
                 }
                 finally {
                     if (renameList.length)
                         await Promise.allSettled(renameList
-                            .filter(([_, filePath]) => filePath)
+                            .filter((pair) => Boolean(pair[1]))
                             .map(async ([tempPath, _]) => unlink(tempPath)));
                     await File.unlock(join(tablePath, ".tmp"));
                 }
@@ -1664,17 +1872,86 @@ export default class Inibase {
             (Array.isArray(where) && where.every(Utils.isValidID)) ||
             Utils.isValidID(where)) {
             const lineNumbers = await this.get(tableName, where, undefined, undefined, true);
-            return this.delete(tableName, lineNumbers, true);
+            // Deleting a non-existent id must not fall through to the
+            // "delete all rows" branch (this.delete(_, null, _) would truncate
+            // the whole table), so resolve the id to line numbers first and
+            // only delegate when something actually matched.
+            if (lineNumbers)
+                return this.delete(tableName, lineNumbers, true, _cascadeGuard ?? new Set());
+            return false;
         }
         if (Utils.isObject(where)) {
             const lineNumbers = await this.get(tableName, where, undefined, undefined, true);
             if (lineNumbers)
-                return this.delete(tableName, lineNumbers, true);
+                return this.delete(tableName, lineNumbers, true, _cascadeGuard ?? new Set());
         }
         else
             throw this.createError("INVALID_PARAMETERS");
         return false;
     }
+    /**
+     * Cascade delete: remove rows in other tables whose `table`-typed schema
+     * fields reference the given rows. Reference columns store the numeric
+     * (line-number) id of the referenced row, so deleted ids are matched
+     * against them directly. Recursion into child tables happens through
+     * `delete` itself (which calls this method again); the `guard` set keeps
+     * deep/cyclic reference chains from re-processing the same (table, line).
+     */
+    async cascadeDelete(tableName, deletedLines, guard) {
+        if (!deletedLines.length)
+            return;
+        for (const line of deletedLines)
+            guard.add(`${tableName}:${line}`);
+        const tables = globalConfig[this.databasePath]?.tables;
+        if (!tables)
+            return;
+        for (const [candidateName, tableData] of tables) {
+            if (candidateName === tableName || !tableData?.schema)
+                continue;
+            // Only direct `table`-typed columns hold one stored id per row;
+            // arrays/objects of table refs serialize differently and are
+            // intentionally out of scope for the cascade.
+            const refFields = Utils.flattenSchema(tableData.schema, true).filter((field) => field.table === tableName && field.type === "table");
+            if (!refFields.length)
+                continue;
+            for (const field of refFields) {
+                const refPath = join(this.databasePath, candidateName, `${field.key}${this.getFileExtension(candidateName)}`);
+                if (!(await File.isExists(refPath)))
+                    continue;
+                const matching = new Set();
+                for (const line of deletedLines) {
+                    try {
+                        const [, , found] = await File.search(refPath, "=", line, undefined, undefined, {
+                            key: field.key,
+                            type: "number",
+                            databasePath: this.databasePath,
+                        }, undefined, undefined, false);
+                        if (found)
+                            for (const l of found)
+                                matching.add(l);
+                    }
+                    catch {
+                        // Unreadable/unsupported column -> skip this reference.
+                    }
+                }
+                const toDelete = [...matching].filter((line) => {
+                    const key = `${candidateName}:${line}`;
+                    if (guard.has(key))
+                        return false;
+                    guard.add(key);
+                    return true;
+                });
+                if (!toDelete.length)
+                    continue;
+                try {
+                    await this.delete(candidateName, toDelete, true, guard);
+                }
+                catch {
+                    // Cascade is best-effort: never break the parent delete.
+                }
+            }
+        }
+    }
     async sum(tableName, columns, where) {
         this.validateName(tableName);
         if (!Array.isArray(columns))

package/dist/utils.server.d.ts

@@ -1,9 +1,9 @@
 import "dotenv/config";
-import { execFile as execFileSync, exec as execSync } from "node:child_process";
+import { execFile as execFileSync, exec as rawExec } from "node:child_process";
 import { gunzip as gunzipSync, gzip as gzipSync } from "node:zlib";
 import RE2 from "re2";
 import type { ComparisonOperator, FieldType } from "./index.js";
-export declare const exec: typeof execSync.__promisify__;
+export declare const exec: typeof rawExec.__promisify__;
 export declare const execFile: typeof execFileSync.__promisify__;
 export declare const gzip: typeof gzipSync.__promisify__;
 export declare const gunzip: typeof gunzipSync.__promisify__;

package/dist/utils.server.js

@@ -1,5 +1,5 @@
 import "dotenv/config";
-import { execFile as execFileSync, exec as execSync } from "node:child_process";
+import { execFile as execFileSync, exec as rawExec } from "node:child_process";
 import { createCipheriv, createDecipheriv, createHash, randomBytes, scryptSync, } from "node:crypto";
 import { promisify } from "node:util";
 import { gunzip as gunzipSync, gzip as gzipSync } from "node:zlib";
@@ -7,7 +7,7 @@ import Inison from "inison";
 import RE2 from "re2";
 import { globalConfig } from "./index.js";
 import { detectFieldType, isNumber, isPassword } from "./utils.js";
-export const exec = promisify(execSync);
+export const exec = promisify(rawExec);
 export const execFile = promisify(execFileSync);
 export const gzip = promisify(gzipSync);
 export const gunzip = promisify(gunzipSync);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "inibase",
-  "version": "1.8.0",
+  "version": "2.0.0",
   "type": "module",
   "author": {
     "name": "Karim Amahtil",
@@ -87,6 +87,7 @@
     "build": "tsc",
     "benchmark": "./benchmark/run.js",
     "test": "tsx ./tests/inibase.test.ts",
-    "test:utils": "tsx ./tests/utils.test.ts"
+    "test:utils": "tsx ./tests/utils.test.ts",
+    "test:advanced": "tsx ./tests/inibase.advanced.test.ts"
   }
 }