inibase 1.0.0-rc.25 → 1.0.0-rc.27

package/dist/file.js

@@ -1,16 +1,51 @@
-import { open, rename, stat, writeFile, appendFile, } from "node:fs/promises";
+import { open, access, writeFile, readFile, constants as fsConstants, } from "node:fs/promises";
 import { createInterface } from "node:readline";
+import { Transform } from "node:stream";
+import { pipeline } from "node:stream/promises";
+import { createGzip, createGunzip, gzip as gzipAsync, gunzip as gunzipAsync, } from "node:zlib";
+import { promisify } from "node:util";
 import { detectFieldType, isArrayOfArrays, isNumber, isObject, } from "./utils.js";
 import { encodeID, comparePassword } from "./utils.server.js";
+import Config from "./config.js";
+const gzip = promisify(gzipAsync);
+const gunzip = promisify(gunzipAsync);
+export const write = async (filePath, data, disableCompression = false) => {
+    await writeFile(filePath, Config.isCompressionEnabled && !disableCompression ? await gzip(data) : data);
+};
+export const read = async (filePath, disableCompression = false) => {
+    return Config.isCompressionEnabled && !disableCompression
+        ? (await gunzip(await readFile(filePath))).toString()
+        : (await readFile(filePath)).toString();
+};
+const _pipeline = async (rl, writeStream, transform) => {
+    if (Config.isCompressionEnabled)
+        await pipeline(rl, transform, createGzip(), writeStream);
+    else
+        await pipeline(rl, transform, writeStream);
+};
+/**
+ * Creates a readline interface for a given file handle.
+ *
+ * @param fileHandle - The file handle from which to create a read stream.
+ * @returns A readline.Interface instance configured with the provided file stream.
+ */
 const readLineInternface = (fileHandle) => {
     return createInterface({
-        input: fileHandle.createReadStream(),
+        input: Config.isCompressionEnabled
+            ? fileHandle.createReadStream().pipe(createGunzip())
+            : fileHandle.createReadStream(),
         crlfDelay: Infinity,
     });
 };
+/**
+ * Checks if a file or directory exists at the specified path.
+ *
+ * @param path - The path to the file or directory.
+ * @returns A Promise that resolves to true if the file/directory exists, false otherwise.
+ */
 export const isExists = async (path) => {
     try {
-        await stat(path);
+        await access(path, fsConstants.R_OK | fsConstants.W_OK);
         return true;
     }
     catch {
@@ -18,28 +53,57 @@ export const isExists = async (path) => {
     }
 };
 const delimiters = [",", "|", "&", "$", "#", "@", "^", ":", "!", ";"];
+/**
+ * Secures input by encoding/escaping characters.
+ *
+ * @param input - String, number, boolean, or null.
+ * @returns Encoded string for true/false, special characters in strings, or original input.
+ */
 const secureString = (input) => {
     if (["true", "false"].includes(String(input)))
         return input ? 1 : 0;
-    return typeof input === "string"
-        ? decodeURIComponent(input.replace(/%(?![0-9][0-9a-fA-F]+)/g, ""))
-            .replaceAll("<", "&lt;")
-            .replaceAll(">", "&gt;")
-            .replaceAll(",", "%2C")
-            .replaceAll("|", "%7C")
-            .replaceAll("&", "%26")
-            .replaceAll("$", "%24")
-            .replaceAll("#", "%23")
-            .replaceAll("@", "%40")
-            .replaceAll("^", "%5E")
-            .replaceAll(":", "%3A")
-            .replaceAll("!", "%21")
-            .replaceAll(";", "%3B")
-            .replaceAll("\n", "\\n")
-            .replaceAll("\r", "\\r")
-        : input;
+    if (typeof input !== "string")
+        return input;
+    let decodedInput = null;
+    try {
+        decodedInput = decodeURIComponent(input);
+    }
+    catch (_error) {
+        decodedInput = decodeURIComponent(input.replace(/%(?![0-9][0-9a-fA-F]+)/g, ""));
+    }
+    const replacements = {
+        "<": "&lt;",
+        ">": "&gt;",
+        ",": "%2C",
+        "|": "%7C",
+        "&": "%26",
+        $: "%24",
+        "#": "%23",
+        "@": "%40",
+        "^": "%5E",
+        ":": "%3A",
+        "!": "%21",
+        ";": "%3B",
+        "\n": "\\n",
+        "\r": "\\r",
+    };
+    // Replace characters using a single regular expression.
+    return decodedInput.replace(/[<>,|&$#@^:!\n\r]/g, (match) => replacements[match]);
 };
+/**
+ * Secures each element in an array or a single value using secureString.
+ *
+ * @param arr_str - An array or a single value of any type.
+ * @returns An array with each element secured, or a single secured value.
+ */
 const secureArray = (arr_str) => Array.isArray(arr_str) ? arr_str.map(secureArray) : secureString(arr_str);
+/**
+ * Joins elements of a multidimensional array into a string.
+ *
+ * @param arr - A multidimensional array or a single level array.
+ * @param delimiter_index - Index for selecting delimiter, defaults to 0.
+ * @returns Joined string of array elements with appropriate delimiters.
+ */
 const joinMultidimensionalArray = (arr, delimiter_index = 0) => {
     delimiter_index++;
     if (isArrayOfArrays(arr))
@@ -47,283 +111,539 @@ const joinMultidimensionalArray = (arr, delimiter_index = 0) => {
     delimiter_index--;
     return arr.join(delimiters[delimiter_index]);
 };
+/**
+ * Encodes the input using 'secureString' and 'joinMultidimensionalArray' functions.
+ * If the input is an array, it is first secured and then joined into a string.
+ * If the input is a single value, it is directly secured.
+ *
+ * @param input - A value or array of values (string, number, boolean, null).
+ * @param secretKey - Optional secret key for encoding, can be a string or Buffer.
+ * @returns The secured and/or joined string.
+ */
 export const encode = (input, secretKey) => {
+    // Use the optimized secureArray and joinMultidimensionalArray functions.
     return Array.isArray(input)
         ? joinMultidimensionalArray(secureArray(input))
         : secureString(input);
 };
-const unSecureString = (input) => input
-    .replaceAll("&lt;", "<")
-    .replaceAll("&gt;", ">")
-    .replaceAll("%2C", ",")
-    .replaceAll("%7C", "|")
-    .replaceAll("%26", "&")
-    .replaceAll("%24", "$")
-    .replaceAll("%23", "#")
-    .replaceAll("%40", "@")
-    .replaceAll("%5E", "^")
-    .replaceAll("%3A", ":")
-    .replaceAll("%21", "!")
-    .replaceAll("%3B", ";")
-    .replaceAll("\\n", "\n")
-    .replaceAll("\\r", "\r") || null;
+/**
+ * Decodes each element in an array or a single value using unSecureString.
+ *
+ * @param arr_str - An array or a single value of any type.
+ * @returns An array with each element decoded, or a single decoded value.
+ */
 const unSecureArray = (arr_str) => Array.isArray(arr_str) ? arr_str.map(unSecureArray) : unSecureString(arr_str);
+/**
+ * Reverses the encoding done by 'secureString'. Replaces encoded characters with their original symbols.
+ *
+ * @param input - Encoded string.
+ * @returns Decoded string or null if input is empty.
+ */
+const unSecureString = (input) => {
+    // Define a mapping of encoded characters to their original symbols.
+    const replacements = {
+        "&lt;": "<",
+        "%2C": ",",
+        "%7C": "|",
+        "%26": "&",
+        "%24": "$",
+        "%23": "#",
+        "%40": "@",
+        "%5E": "^",
+        "%3A": ":",
+        "%21": "!",
+        "%3B": ";",
+        "\\n": "\n",
+        "\\r": "\r",
+    };
+    // Replace encoded characters with their original symbols using the defined mapping.
+    return (input.replace(/%(2C|7C|26|24|23|40|5E|3A|21|3B|\\n|\\r)/g, (match) => replacements[match]) || null);
+};
+/**
+ * Reverses the process of 'joinMultidimensionalArray', splitting a string back into a multidimensional array.
+ * It identifies delimiters used in the joined string and applies them recursively to reconstruct the original array structure.
+ *
+ * @param joinedString - A string, array, or multidimensional array.
+ * @returns Original array structure before joining, or the input if no delimiters are found.
+ */
 const reverseJoinMultidimensionalArray = (joinedString) => {
+    // Helper function for recursive array splitting based on delimiters.
     const reverseJoinMultidimensionalArrayHelper = (arr, delimiter) => Array.isArray(arr)
         ? arr.map((ar) => reverseJoinMultidimensionalArrayHelper(ar, delimiter))
         : arr.split(delimiter);
+    // Identify available delimiters in the input.
     const availableDelimiters = delimiters.filter((delimiter) => joinedString.includes(delimiter));
-    for (const delimiter of availableDelimiters) {
-        joinedString = Array.isArray(joinedString)
-            ? reverseJoinMultidimensionalArrayHelper(joinedString, delimiter)
-            : joinedString.split(delimiter);
-    }
-    return joinedString;
+    // Apply delimiters recursively to reconstruct the original array structure.
+    return availableDelimiters.reduce((acc, delimiter) => reverseJoinMultidimensionalArrayHelper(acc, delimiter), joinedString);
 };
+/**
+ * Decodes a value based on specified field types and optional secret key.
+ * Handles different data types and structures, including nested arrays.
+ *
+ * @param value - The value to be decoded, can be string, number, or array.
+ * @param fieldType - Optional type of the field to guide decoding (e.g., 'number', 'boolean').
+ * @param fieldChildrenType - Optional type for children elements, used for arrays.
+ * @param secretKey - Optional secret key for decoding, can be string or Buffer.
+ * @returns Decoded value, transformed according to the specified field type(s).
+ */
 const decodeHelper = (value, fieldType, fieldChildrenType, secretKey) => {
-    if (Array.isArray(value) && fieldType !== "array")
-        return value.map((v) => decodeHelper(v, fieldType, fieldChildrenType, secretKey));
-    switch (fieldType) {
-        case "table":
-        case "number":
-            return isNumber(value) ? Number(value) : null;
-        case "boolean":
-            return typeof value === "string" ? value === "true" : Boolean(value);
-        case "array":
-            if (!Array.isArray(value))
-                return [value];
-            if (fieldChildrenType)
-                return fieldChildrenType
-                    ? value.map((v) => decode(v, Array.isArray(fieldChildrenType)
-                        ? detectFieldType(v, fieldChildrenType)
-                        : fieldChildrenType, undefined, secretKey))
-                    : value;
-        case "id":
-            return isNumber(value) && secretKey
-                ? encodeID(value, secretKey)
-                : value;
-        default:
-            return value;
+    // Use a stack-based approach for efficient processing without recursion.
+    const stack = [{ value }];
+    while (stack.length > 0) {
+        // Explicitly check if stack.pop() is not undefined.
+        const stackItem = stack.pop();
+        if (!stackItem) {
+            // Skip the rest of the loop if the stack item is undefined.
+            continue;
+        }
+        const { value } = stackItem;
+        if (Array.isArray(value) && fieldType !== "array") {
+            // If the value is an array and the fieldType is not 'array', process each element.
+            stack.push(...value.map((v) => ({ value: v })));
+        }
+        else {
+            switch (fieldType) {
+                // Handle different field types with appropriate decoding logic.
+                case "table":
+                case "number":
+                    return isNumber(value) ? Number(value) : null;
+                case "boolean":
+                    return typeof value === "string" ? value === "true" : Boolean(value);
+                case "array":
+                    if (!Array.isArray(value))
+                        return [value];
+                    if (fieldChildrenType)
+                        // Decode each element in the array based on the specified fieldChildrenType.
+                        return fieldChildrenType
+                            ? value.map((v) => decode(v, Array.isArray(fieldChildrenType)
+                                ? detectFieldType(v, fieldChildrenType)
+                                : fieldChildrenType, undefined, secretKey))
+                            : value;
+                case "id":
+                    return isNumber(value) && secretKey
+                        ? encodeID(value, secretKey)
+                        : value;
+                default:
+                    return value;
+            }
+        }
     }
 };
+/**
+ * Decodes the input based on the specified field type(s) and an optional secret key.
+ * Handles different formats of input, including strings, numbers, and their array representations.
+ *
+ * @param input - The input to be decoded, can be a string, number, or null.
+ * @param fieldType - Optional type of the field to guide decoding (e.g., 'number', 'boolean').
+ * @param fieldChildrenType - Optional type for child elements in array inputs.
+ * @param secretKey - Optional secret key for decoding, can be a string or Buffer.
+ * @returns Decoded value as a string, number, boolean, or array of these, or null if no fieldType or input is null/empty.
+ */
 export const decode = (input, fieldType, fieldChildrenType, secretKey) => {
     if (!fieldType)
         return null;
     if (input === null || input === "")
         return null;
     if (Array.isArray(fieldType))
+        // Detect the fieldType based on the input and the provided array of possible types.
         fieldType = detectFieldType(String(input), fieldType);
+    // Decode the input using the decodeHelper function.
     return decodeHelper(typeof input === "string"
         ? input.includes(",")
             ? unSecureArray(reverseJoinMultidimensionalArray(input))
             : unSecureString(input)
         : input, fieldType, fieldChildrenType, secretKey);
 };
-export const get = async (filePath, lineNumbers, fieldType, fieldChildrenType, secretKey) => {
-    const fileHandle = await open(filePath, "r"), rl = readLineInternface(fileHandle);
-    let lines = new Map(), lineCount = 0;
-    if (!lineNumbers) {
-        for await (const line of rl)
-            lineCount++,
-                lines.set(lineCount, decode(line, fieldType, fieldChildrenType, secretKey));
-    }
-    else if (lineNumbers === -1) {
-        let lastLine = null;
-        for await (const line of rl)
-            lineCount++, (lastLine = line);
-        if (lastLine)
-            lines.set(lineCount, decode(lastLine, fieldType, fieldChildrenType, secretKey));
-    }
-    else {
-        let lineNumbersArray = new Set(Array.isArray(lineNumbers) ? lineNumbers : [lineNumbers]);
-        for await (const line of rl) {
-            lineCount++;
-            if (!lineNumbersArray.has(lineCount))
-                continue;
-            lines.set(lineCount, decode(line, fieldType, fieldChildrenType, secretKey));
-            lineNumbersArray.delete(lineCount);
-            if (!lineNumbersArray.size)
-                break;
+export async function get(filePath, lineNumbers, fieldType, fieldChildrenType, secretKey, readWholeFile) {
+    let fileHandle, rl;
+    try {
+        fileHandle = await open(filePath, "r");
+        rl = readLineInternface(fileHandle);
+        let lines = {}, linesCount = 0;
+        if (!lineNumbers) {
+            for await (const line of rl)
+                linesCount++,
+                    (lines[linesCount] = decode(line, fieldType, fieldChildrenType, secretKey));
         }
-    }
-    await fileHandle.close();
-    return [lines.size ? Object.fromEntries(lines) : null, lineCount];
-};
-export const replace = async (filePath, replacements) => {
-    if (await isExists(filePath)) {
-        let lineCount = 0;
-        const fileHandle = await open(filePath, "r"), fileTempPath = `${filePath.replace(".inib", "")}-${Date.now()}.tmp`, fileTempHandle = await open(fileTempPath, "w"), rl = readLineInternface(fileHandle), writeStream = fileTempHandle.createWriteStream();
-        if (isObject(replacements)) {
-            if (!(replacements instanceof Map))
-                replacements = new Map(Object.entries(replacements));
+        else if (lineNumbers === -1) {
+            let lastLine = null;
+            for await (const line of rl)
+                linesCount++, (lastLine = line);
+            if (lastLine)
+                lines[linesCount] = decode(lastLine, fieldType, fieldChildrenType, secretKey);
+        }
+        else {
+            let lineNumbersArray = new Set(Array.isArray(lineNumbers) ? lineNumbers : [lineNumbers]);
             for await (const line of rl) {
-                lineCount++;
-                writeStream.write((replacements.has(lineCount.toString())
-                    ? replacements.get(lineCount.toString())
-                    : line) + "\n");
-            }
-            const newLinesNumbers = new Set([...replacements.keys()].filter((num) => num > lineCount));
-            if (newLinesNumbers.size) {
-                if (Math.min(...newLinesNumbers) - lineCount - 1 > 1)
-                    writeStream.write("\n".repeat(Math.min(...newLinesNumbers) - lineCount - 1));
-                for await (const newLineNumber of newLinesNumbers)
-                    writeStream.write(replacements.get(newLineNumber.toString()) + "\n");
+                linesCount++;
+                if (!lineNumbersArray.has(linesCount))
+                    continue;
+                lines[linesCount] = decode(line, fieldType, fieldChildrenType, secretKey);
+                lineNumbersArray.delete(linesCount);
+                if (!lineNumbersArray.size && !readWholeFile)
+                    break;
             }
         }
-        else
-            for await (const _line of rl)
-                writeStream.write(replacements + "\n");
-        await fileHandle.close();
-        await fileTempHandle.close();
-        await rename(fileTempPath, filePath);
+        return readWholeFile ? [lines, linesCount] : lines;
     }
-    else if (isObject(replacements)) {
-        if (!(replacements instanceof Map))
-            replacements = new Map(Object.entries(replacements).map(([key, value]) => [Number(key), value]));
-        await writeFile(filePath, (Math.min(...replacements.keys()) - 1 > 1
-            ? "\n".repeat(Math.min(...replacements.keys()) - 1)
-            : "") +
-            Array.from(new Map([...replacements.entries()].sort(([keyA], [keyB]) => keyA - keyB)).values()).join("\n") +
-            "\n");
+    finally {
+        // Ensure that file handles are closed, even if an error occurred
+        rl?.close();
+        await fileHandle?.close();
+    }
+}
+/**
+ * Asynchronously replaces specific lines in a file based on the provided replacements map or string.
+ *
+ * @param filePath - Path of the file to modify.
+ * @param replacements - Map of line numbers to replacement values, or a single replacement value for all lines.
+ *   Can be a string, number, boolean, null, array of these types, or a Record/Map of line numbers to these types.
+ * @returns Promise<string[]>
+ *
+ * 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) => {
+    let fileHandle, fileTempHandle, rl;
+    const fileTempPath = filePath.replace(/([^/]+)\/?$/, `.tmp/${Date.now()}-$1`);
+    try {
+        let linesCount = 0;
+        fileHandle = await open(filePath, "r");
+        fileTempHandle = await open(fileTempPath, "w");
+        rl = readLineInternface(fileHandle);
+        await _pipeline(rl, fileTempHandle.createWriteStream(), new Transform({
+            transform(line, encoding, callback) {
+                linesCount++;
+                const replacement = isObject(replacements)
+                    ? replacements.hasOwnProperty(linesCount)
+                        ? replacements[linesCount]
+                        : line
+                    : replacements;
+                callback(null, replacement + "\n");
+            },
+        }));
+        return [fileTempPath, filePath];
+    }
+    finally {
+        // Ensure that file handles are closed, even if an error occurred
+        rl?.close();
+        await fileHandle?.close();
+        await fileTempHandle?.close();
     }
 };
-export const append = async (filePath, data, startsAt = 1) => {
-    let currentNumberOfLines = 0;
-    const doesFileExists = await isExists(filePath);
-    if (doesFileExists)
-        currentNumberOfLines = await count(filePath);
-    await appendFile(filePath, (currentNumberOfLines > 0
-        ? startsAt - currentNumberOfLines - 1 > 0
-            ? "\n".repeat(startsAt - currentNumberOfLines - 1)
-            : ""
-        : "") +
-        (Array.isArray(data) ? data.join("\n") : data) +
-        "\n");
+/**
+ * Asynchronously appends data to the beginning of a file.
+ *
+ * @param filePath - Path of the file to append to.
+ * @param data - Data to append. Can be a string, number, or an array of strings/numbers.
+ * @returns Promise<string[]>. Modifies the file by appending data.
+ *
+ */
+export const append = async (filePath, data) => {
+    const fileTempPath = filePath.replace(/([^/]+)\/?$/, `.tmp/${Date.now()}-$1`);
+    if (await isExists(filePath)) {
+        let fileHandle, fileTempHandle, rl;
+        try {
+            fileHandle = await open(filePath, "r");
+            fileTempHandle = await open(fileTempPath, "w");
+            rl = readLineInternface(fileHandle);
+            let isAppended = false;
+            await _pipeline(rl, fileTempHandle.createWriteStream(), new Transform({
+                transform(line, encoding, callback) {
+                    if (!isAppended) {
+                        isAppended = true;
+                        callback(null, `${Array.isArray(data) ? data.join("\n") : data}\n${line}\n`);
+                    }
+                    else
+                        callback(null, `${line}\n`);
+                },
+            }));
+        }
+        finally {
+            // Ensure that file handles are closed, even if an error occurred
+            rl?.close();
+            await fileHandle?.close();
+            await fileTempHandle?.close();
+        }
+    }
+    else
+        await write(fileTempPath, `${Array.isArray(data) ? data.join("\n") : data}\n`);
+    return [fileTempPath, filePath];
 };
+/**
+ * Asynchronously removes specified lines from a file.
+ *
+ * @param filePath - Path of the file from which lines are to be removed.
+ * @param linesToDelete - A single line number or an array of line numbers to be deleted.
+ * @returns Promise<string[]>. Modifies the file by removing specified lines.
+ *
+ * Note: Creates a temporary file during the process and replaces the original file with it after removing lines.
+ */
 export const remove = async (filePath, linesToDelete) => {
-    let lineCount = 0;
-    const fileHandle = await open(filePath, "r"), fileTempPath = `${filePath.replace(".inib", "")}-${Date.now()}.tmp`, fileTempHandle = await open(fileTempPath, "w"), linesToDeleteArray = new Set(Array.isArray(linesToDelete)
+    let linesCount = 0;
+    const fileHandle = await open(filePath, "r"), fileTempPath = filePath.replace(/([^/]+)\/?$/, `.tmp/${Date.now()}-$1`), fileTempHandle = await open(fileTempPath, "w"), linesToDeleteArray = new Set(Array.isArray(linesToDelete)
         ? linesToDelete.map(Number)
-        : [Number(linesToDelete)]), rl = readLineInternface(fileHandle), writeStream = fileTempHandle.createWriteStream();
-    for await (const line of rl) {
-        lineCount++;
-        if (!linesToDeleteArray.has(lineCount))
-            writeStream.write(`${line}\n`);
-    }
-    await rename(fileTempPath, filePath);
+        : [Number(linesToDelete)]), rl = readLineInternface(fileHandle);
+    await _pipeline(rl, fileTempHandle.createWriteStream(), new Transform({
+        transform(line, encoding, callback) {
+            linesCount++;
+            if (!linesToDeleteArray.has(linesCount))
+                callback(null, `${line}\n`);
+            callback();
+        },
+    }));
     await fileTempHandle.close();
     await fileHandle.close();
+    return [fileTempPath, filePath];
 };
-export const count = async (filePath) => {
-    // return Number((await exec(`wc -l < ${filePath}`)).stdout.trim());
-    let lineCount = 0;
-    const fileHandle = await open(filePath, "r"), rl = readLineInternface(fileHandle);
-    for await (const line of rl)
-        lineCount++;
-    await fileHandle.close();
-    return lineCount;
-};
+/**
+ * Evaluates a comparison between two values based on a specified operator and field types.
+ *
+ * @param operator - The comparison operator (e.g., '=', '!=', '>', '<', '>=', '<=', '[]', '![]', '*', '!*').
+ * @param originalValue - The value to compare, can be a single value or an array of values.
+ * @param comparedAtValue - The value or values to compare against.
+ * @param fieldType - Optional type of the field to guide comparison (e.g., 'password', 'boolean').
+ * @param fieldChildrenType - Optional type for child elements in array inputs.
+ * @returns boolean - Result of the comparison operation.
+ *
+ * Note: Handles various data types and comparison logic, including special handling for passwords and regex patterns.
+ */
 const handleComparisonOperator = (operator, originalValue, comparedAtValue, fieldType, fieldChildrenType) => {
-    if (Array.isArray(fieldType))
+    // Determine the field type if it's an array of potential types.
+    if (Array.isArray(fieldType)) {
         fieldType = detectFieldType(String(originalValue), fieldType);
-    if (Array.isArray(comparedAtValue) && !["[]", "![]"].includes(operator))
+    }
+    // Handle comparisons involving arrays.
+    if (Array.isArray(comparedAtValue) && !["[]", "![]"].includes(operator)) {
         return comparedAtValue.some((comparedAtValueSingle) => handleComparisonOperator(operator, originalValue, comparedAtValueSingle, fieldType));
-    // check if not array or object // it can't be array or object!
+    }
+    // Switch statement for different comparison operators.
     switch (operator) {
+        // Equal (Case Insensitive for strings, specific handling for passwords and booleans).
         case "=":
-            switch (fieldType) {
-                case "password":
-                    return typeof originalValue === "string" &&
-                        typeof comparedAtValue === "string"
-                        ? comparePassword(originalValue, comparedAtValue)
-                        : false;
-                case "boolean":
-                    return Number(originalValue) - Number(comparedAtValue) === 0;
-                default:
-                    return originalValue === comparedAtValue;
-            }
+            return isEqual(originalValue, comparedAtValue, fieldType);
+        // Not Equal.
         case "!=":
-            return !handleComparisonOperator("=", originalValue, comparedAtValue, fieldType);
+            return !isEqual(originalValue, comparedAtValue, fieldType);
+        // Greater Than.
         case ">":
             return (originalValue !== null &&
                 comparedAtValue !== null &&
                 originalValue > comparedAtValue);
+        // Less Than.
         case "<":
             return (originalValue !== null &&
                 comparedAtValue !== null &&
                 originalValue < comparedAtValue);
+        // Greater Than or Equal.
         case ">=":
             return (originalValue !== null &&
                 comparedAtValue !== null &&
                 originalValue >= comparedAtValue);
+        // Less Than or Equal.
         case "<=":
             return (originalValue !== null &&
                 comparedAtValue !== null &&
                 originalValue <= comparedAtValue);
+        // Array Contains (equality check for arrays).
         case "[]":
-            return ((Array.isArray(originalValue) &&
-                Array.isArray(comparedAtValue) &&
-                originalValue.some(comparedAtValue.includes)) ||
-                (Array.isArray(originalValue) &&
-                    !Array.isArray(comparedAtValue) &&
-                    originalValue.includes(comparedAtValue)) ||
-                (!Array.isArray(originalValue) &&
-                    Array.isArray(comparedAtValue) &&
-                    comparedAtValue.includes(originalValue)));
+            return isArrayEqual(originalValue, comparedAtValue);
+        // Array Does Not Contain.
         case "![]":
-            return !handleComparisonOperator("[]", originalValue, comparedAtValue, fieldType);
+            return !isArrayEqual(originalValue, comparedAtValue);
+        // Wildcard Match (using regex pattern).
         case "*":
-            return new RegExp(`^${(String(comparedAtValue).includes("%")
-                ? String(comparedAtValue)
-                : "%" + String(comparedAtValue) + "%").replace(/%/g, ".*")}$`, "i").test(String(originalValue));
+            return isWildcardMatch(originalValue, comparedAtValue);
+        // Not Wildcard Match.
         case "!*":
-            return !handleComparisonOperator("*", originalValue, comparedAtValue, fieldType);
+            return !isWildcardMatch(originalValue, comparedAtValue);
+        // Unsupported operator.
         default:
-            throw new Error(operator);
+            throw new Error(`Unsupported operator: ${operator}`);
     }
 };
-export const search = async (filePath, operator, comparedAtValue, logicalOperator, fieldType, fieldChildrenType, limit, offset, readWholeFile, secretKey) => {
-    let RETURN = new Map(), lineCount = 0, foundItems = 0;
-    const fileHandle = await open(filePath, "r"), rl = readLineInternface(fileHandle);
-    for await (const line of rl) {
-        lineCount++;
-        const decodedLine = decode(line, fieldType, fieldChildrenType, secretKey);
-        if ((Array.isArray(operator) &&
+/**
+ * Helper function to check equality based on the field type.
+ *
+ * @param originalValue - The original value.
+ * @param comparedAtValue - The value to compare against.
+ * @param fieldType - Type of the field.
+ * @returns boolean - Result of the equality check.
+ */
+const isEqual = (originalValue, comparedAtValue, fieldType) => {
+    // Switch based on the field type for specific handling.
+    switch (fieldType) {
+        // Password comparison.
+        case "password":
+            return typeof originalValue === "string" &&
+                typeof comparedAtValue === "string"
+                ? comparePassword(originalValue, comparedAtValue)
+                : false;
+        // Boolean comparison.
+        case "boolean":
+            return Number(originalValue) === Number(comparedAtValue);
+        // Default comparison.
+        default:
+            return originalValue === comparedAtValue;
+    }
+};
+/**
+ * Helper function to check array equality.
+ *
+ * @param originalValue - The original value.
+ * @param comparedAtValue - The value to compare against.
+ * @returns boolean - Result of the array equality check.
+ */
+const isArrayEqual = (originalValue, comparedAtValue) => {
+    return ((Array.isArray(originalValue) &&
+        Array.isArray(comparedAtValue) &&
+        originalValue.some((v) => comparedAtValue.includes(v))) ||
+        (Array.isArray(originalValue) &&
+            !Array.isArray(comparedAtValue) &&
+            originalValue.includes(comparedAtValue)) ||
+        (!Array.isArray(originalValue) &&
             Array.isArray(comparedAtValue) &&
-            ((logicalOperator &&
-                logicalOperator === "or" &&
-                operator.some((single_operator, index) => handleComparisonOperator(single_operator, decodedLine, comparedAtValue[index], fieldType))) ||
-                operator.every((single_operator, index) => handleComparisonOperator(single_operator, decodedLine, comparedAtValue[index], fieldType)))) ||
-            (!Array.isArray(operator) &&
-                handleComparisonOperator(operator, decodedLine, comparedAtValue, fieldType))) {
-            foundItems++;
-            if (offset && foundItems < offset)
-                continue;
-            if (limit && foundItems > limit)
-                if (readWholeFile)
+            comparedAtValue.includes(originalValue)) ||
+        (!Array.isArray(originalValue) &&
+            !Array.isArray(comparedAtValue) &&
+            comparedAtValue === originalValue));
+};
+/**
+ * Helper function to check wildcard pattern matching using regex.
+ *
+ * @param originalValue - The original value.
+ * @param comparedAtValue - The value with wildcard pattern.
+ * @returns boolean - Result of the wildcard pattern matching.
+ */
+const isWildcardMatch = (originalValue, comparedAtValue) => {
+    const wildcardPattern = `^${(String(comparedAtValue).includes("%")
+        ? String(comparedAtValue)
+        : "%" + String(comparedAtValue) + "%").replace(/%/g, ".*")}$`;
+    return new RegExp(wildcardPattern, "i").test(String(originalValue));
+};
+/**
+ * Asynchronously searches a file for lines matching specified criteria, using comparison and logical operators.
+ *
+ * @param filePath - Path of the file to search.
+ * @param operator - Comparison operator(s) for evaluation (e.g., '=', '!=', '>', '<').
+ * @param comparedAtValue - Value(s) to compare each line against.
+ * @param logicalOperator - Optional logical operator ('and' or 'or') for combining multiple comparisons.
+ * @param fieldType - Optional type of the field to guide comparison.
+ * @param fieldChildrenType - Optional type for child elements in array inputs.
+ * @param limit - Optional limit on the number of results to return.
+ * @param offset - Optional offset to start returning results from.
+ * @param readWholeFile - Flag to indicate whether to continue reading the file after reaching the limit.
+ * @param secretKey - Optional secret key for decoding, can be a string or Buffer.
+ * @returns Promise resolving to a tuple:
+ *   1. Record of line numbers and their content that match the criteria or null if none.
+ *   2. The count of found items or processed items based on the 'readWholeFile' flag.
+ *
+ * Note: Decodes each line for comparison and can handle complex queries with multiple conditions.
+ */
+export const search = async (filePath, operator, comparedAtValue, logicalOperator, fieldType, fieldChildrenType, limit, offset, readWholeFile, secretKey) => {
+    // Initialize a Map to store the matching lines with their line numbers.
+    const matchingLines = {};
+    // Initialize counters for line number, found items, and processed items.
+    let linesCount = 0, foundItems = 0, linesNumbers = new Set();
+    let fileHandle, rl;
+    try {
+        // Open the file for reading.
+        fileHandle = await open(filePath, "r");
+        // Create a Readline interface to read the file line by line.
+        rl = readLineInternface(fileHandle);
+        // Iterate through each line in the file.
+        for await (const line of rl) {
+            // Increment the line count for each line.
+            linesCount++;
+            // Decode the line for comparison.
+            const decodedLine = decode(line, fieldType, fieldChildrenType, secretKey);
+            // Check if the line meets the specified conditions based on comparison and logical operators.
+            const meetsConditions = (Array.isArray(operator) &&
+                Array.isArray(comparedAtValue) &&
+                ((logicalOperator === "or" &&
+                    operator.some((single_operator, index) => handleComparisonOperator(single_operator, decodedLine, comparedAtValue[index], fieldType))) ||
+                    operator.every((single_operator, index) => handleComparisonOperator(single_operator, decodedLine, comparedAtValue[index], fieldType)))) ||
+                (!Array.isArray(operator) &&
+                    handleComparisonOperator(operator, decodedLine, comparedAtValue, fieldType));
+            // If the line meets the conditions, process it.
+            if (meetsConditions) {
+                // Increment the found items counter.
+                foundItems++;
+                linesNumbers.add(linesCount);
+                // Check if the line should be skipped based on the offset.
+                if (offset && foundItems < offset)
                     continue;
-                else
-                    break;
-            RETURN.set(lineCount, decodedLine);
+                // Check if the limit has been reached.
+                if (limit && foundItems > limit)
+                    if (readWholeFile)
+                        continue;
+                    else
+                        break;
+                // Store the decoded line in the result object.
+                matchingLines[linesCount] = decodedLine;
+            }
         }
+        // Convert the Map to an object using Object.fromEntries and return the result.
+        return foundItems
+            ? [
+                matchingLines,
+                readWholeFile ? foundItems : foundItems - 1,
+                linesNumbers.size ? linesNumbers : null,
+            ]
+            : [null, 0, null];
+    }
+    finally {
+        // Close the file handle in the finally block to ensure it is closed even if an error occurs.
+        rl?.close();
+        await fileHandle?.close();
     }
-    await fileHandle.close();
-    return foundItems
-        ? [Object.fromEntries(RETURN), readWholeFile ? foundItems : foundItems - 1]
-        : [null, 0];
 };
+/**
+ * Asynchronously counts the number of lines in a file.
+ *
+ * @param filePath - Path of the file to count lines in.
+ * @returns Promise<number>. The number of lines in the file.
+ *
+ * Note: Reads through the file line by line to count the total number of lines.
+ */
+export const count = async (filePath) => {
+    // return Number((await exec(`wc -l < ${filePath}`)).stdout.trim());
+    let linesCount = 0;
+    if (await isExists(filePath)) {
+        let fileHandle, rl;
+        try {
+            (fileHandle = await open(filePath, "r")),
+                (rl = readLineInternface(fileHandle));
+            for await (const line of rl)
+                linesCount++;
+        }
+        finally {
+            rl?.close();
+            await fileHandle?.close();
+        }
+    }
+    return linesCount;
+};
+/**
+ * Asynchronously calculates the sum of numerical values from specified lines in a file.
+ *
+ * @param filePath - Path of the file to read.
+ * @param lineNumbers - Optional specific line number(s) to include in the sum. If not provided, sums all lines.
+ * @returns Promise<number>. The sum of numerical values from the specified lines.
+ *
+ * Note: Decodes each line as a number using the 'decode' function. Non-numeric lines contribute 0 to the sum.
+ */
 export const sum = async (filePath, lineNumbers) => {
     let sum = 0;
     const fileHandle = await open(filePath, "r"), rl = readLineInternface(fileHandle);
     if (lineNumbers) {
-        let lineCount = 0;
+        let linesCount = 0;
         let lineNumbersArray = new Set(Array.isArray(lineNumbers) ? lineNumbers : [lineNumbers]);
         for await (const line of rl) {
-            lineCount++;
-            if (!lineNumbersArray.has(lineCount))
+            linesCount++;
+            if (!lineNumbersArray.has(linesCount))
                 continue;
             sum += +(decode(line, "number") ?? 0);
-            lineNumbersArray.delete(lineCount);
+            lineNumbersArray.delete(linesCount);
             if (!lineNumbersArray.size)
                 break;
         }
@@ -334,20 +654,29 @@ export const sum = async (filePath, lineNumbers) => {
     await fileHandle.close();
     return sum;
 };
+/**
+ * Asynchronously finds the maximum numerical value from specified lines in a file.
+ *
+ * @param filePath - Path of the file to read.
+ * @param lineNumbers - Optional specific line number(s) to consider for finding the maximum value. If not provided, considers all lines.
+ * @returns Promise<number>. The maximum numerical value found in the specified lines.
+ *
+ * Note: Decodes each line as a number using the 'decode' function. Considers only numerical values for determining the maximum.
+ */
 export const max = async (filePath, lineNumbers) => {
     let max = 0;
     const fileHandle = await open(filePath, "r"), rl = readLineInternface(fileHandle);
     if (lineNumbers) {
-        let lineCount = 0;
+        let linesCount = 0;
         let lineNumbersArray = new Set(Array.isArray(lineNumbers) ? lineNumbers : [lineNumbers]);
         for await (const line of rl) {
-            lineCount++;
-            if (!lineNumbersArray.has(lineCount))
+            linesCount++;
+            if (!lineNumbersArray.has(linesCount))
                 continue;
             const lineContentNum = +(decode(line, "number") ?? 0);
             if (lineContentNum > max)
                 max = lineContentNum;
-            lineNumbersArray.delete(lineCount);
+            lineNumbersArray.delete(linesCount);
             if (!lineNumbersArray.size)
                 break;
         }
@@ -361,20 +690,29 @@ export const max = async (filePath, lineNumbers) => {
     await fileHandle.close();
     return max;
 };
+/**
+ * Asynchronously finds the minimum numerical value from specified lines in a file.
+ *
+ * @param filePath - Path of the file to read.
+ * @param lineNumbers - Optional specific line number(s) to consider for finding the minimum value. If not provided, considers all lines.
+ * @returns Promise<number>. The minimum numerical value found in the specified lines.
+ *
+ * Note: Decodes each line as a number using the 'decode' function. Considers only numerical values for determining the minimum.
+ */
 export const min = async (filePath, lineNumbers) => {
     let min = 0;
     const fileHandle = await open(filePath, "r"), rl = readLineInternface(fileHandle);
     if (lineNumbers) {
-        let lineCount = 0;
+        let linesCount = 0;
         let lineNumbersArray = new Set(Array.isArray(lineNumbers) ? lineNumbers : [lineNumbers]);
         for await (const line of rl) {
-            lineCount++;
-            if (!lineNumbersArray.has(lineCount))
+            linesCount++;
+            if (!lineNumbersArray.has(linesCount))
                 continue;
             const lineContentNum = +(decode(line, "number") ?? 0);
             if (lineContentNum < min)
                 min = lineContentNum;
-            lineNumbersArray.delete(lineCount);
+            lineNumbersArray.delete(linesCount);
             if (!lineNumbersArray.size)
                 break;
         }
@@ -388,13 +726,23 @@ export const min = async (filePath, lineNumbers) => {
     await fileHandle.close();
     return min;
 };
+/**
+ * Asynchronously sorts the lines in a file in the specified direction.
+ *
+ * @param filePath - Path of the file to be sorted.
+ * @param sortDirection - Direction for sorting: 1 or 'asc' for ascending, -1 or 'desc' for descending.
+ * @param lineNumbers - Optional specific line numbers to sort. If not provided, sorts all lines.
+ * @param _lineNumbersPerChunk - Optional parameter for handling large files, specifying the number of lines per chunk.
+ * @returns Promise<void>. Modifies the file by sorting specified lines.
+ *
+ * Note: The sorting is applied either to the entire file or to the specified lines. Large files are handled in chunks.
+ */
 export const sort = async (filePath, sortDirection, lineNumbers, _lineNumbersPerChunk = 100000) => { };
 export default class File {
     static get = get;
     static remove = remove;
     static search = search;
     static replace = replace;
-    static count = count;
     static encode = encode;
     static decode = decode;
     static isExists = isExists;
@@ -402,4 +750,7 @@ export default class File {
     static min = min;
     static max = max;
     static append = append;
+    static count = count;
+    static write = write;
+    static read = read;
 }