inibase 1.0.0-rc.24 → 1.0.0-rc.26

package/dist/file.d.ts

@@ -1,29 +1,159 @@
 /// <reference types="node" resolution-mode="require"/>
 import { ComparisonOperator, FieldType } from "./index.js";
+/**
+ * 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 declare const isExists: (path: string) => Promise<boolean>;
+/**
+ * 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 declare const encode: (input: string | number | boolean | null | (string | number | boolean | null)[], secretKey?: string | Buffer) => string | number | boolean | null;
+/**
+ * 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 declare const decode: (input: string | null | number, fieldType?: FieldType | FieldType[], fieldChildrenType?: FieldType | FieldType[], secretKey?: string | Buffer) => string | number | boolean | null | (string | number | null | boolean)[];
+/**
+ * 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.
+ *
+ * @param filePath - Path of the file to be read.
+ * @param lineNumbers - Optional line number(s) to read from the file. If -1, reads the last line.
+ * @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 Promise resolving to a tuple:
+ *   1. Record of line numbers and their decoded content or null if no lines are read.
+ *   2. Total count of lines processed.
+ */
 export declare const get: (filePath: string, lineNumbers?: number | number[], fieldType?: FieldType | FieldType[], fieldChildrenType?: FieldType | FieldType[], secretKey?: string | Buffer) => Promise<[
     Record<number, string | number | boolean | null | (string | number | boolean | (string | number | boolean)[] | null)[]> | null,
     number
 ]>;
-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)[]> | Map<number, string | number | boolean | (string | number | boolean)[]>) => Promise<void>;
-export declare const append: (filePath: string, data: string | number | (string | number)[], startsAt?: number) => Promise<void>;
-export declare const remove: (filePath: string, linesToDelete: number | number[]) => Promise<void>;
+/**
+ * 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 declare const replace: (filePath: string, replacements: string | number | boolean | null | (string | number | boolean | null)[] | Record<number, string | boolean | number | null | (string | boolean | number | null)[]>) => Promise<string[]>;
+/**
+ * Asynchronously appends data to 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 declare const append: (filePath: string, data: string | number | (string | number)[]) => Promise<string[]>;
+/**
+ * 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 declare const remove: (filePath: string, linesToDelete: number | number[]) => Promise<string[]>;
+/**
+ * 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 declare const count: (filePath: string) => Promise<number>;
+/**
+ * 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 declare const search: (filePath: string, operator: ComparisonOperator | ComparisonOperator[], comparedAtValue: string | number | boolean | null | (string | number | boolean | null)[], logicalOperator?: "and" | "or", fieldType?: FieldType | FieldType[], fieldChildrenType?: FieldType | FieldType[], limit?: number, offset?: number, readWholeFile?: boolean, secretKey?: string | Buffer) => Promise<[
     Record<number, string | number | boolean | (string | number | boolean | null)[] | null> | null,
     number
 ]>;
+/**
+ * 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 declare const sum: (filePath: string, lineNumbers?: number | number[]) => Promise<number>;
+/**
+ * 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 declare const max: (filePath: string, lineNumbers?: number | number[]) => Promise<number>;
+/**
+ * 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 declare const min: (filePath: string, lineNumbers?: number | number[]) => Promise<number>;
+/**
+ * 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 declare const sort: (filePath: string, sortDirection: 1 | -1 | "asc" | "desc", lineNumbers?: number | number[], _lineNumbersPerChunk?: number) => Promise<void>;
 export default class File {
     static get: (filePath: string, lineNumbers?: number | number[] | undefined, fieldType?: FieldType | FieldType[] | undefined, fieldChildrenType?: FieldType | FieldType[] | undefined, secretKey?: string | Buffer | undefined) => Promise<[Record<number, string | number | boolean | (string | number | boolean | (string | number | boolean)[] | null)[] | null> | null, number]>;
-    static remove: (filePath: string, linesToDelete: number | number[]) => Promise<void>;
+    static remove: (filePath: string, linesToDelete: number | number[]) => Promise<string[]>;
     static search: (filePath: string, operator: ComparisonOperator | ComparisonOperator[], comparedAtValue: string | number | boolean | (string | number | boolean | null)[] | null, logicalOperator?: "and" | "or" | undefined, fieldType?: FieldType | FieldType[] | undefined, fieldChildrenType?: FieldType | FieldType[] | undefined, limit?: number | undefined, offset?: number | undefined, readWholeFile?: boolean | undefined, secretKey?: string | Buffer | undefined) => Promise<[Record<number, string | number | boolean | (string | number | boolean | null)[] | null> | null, number]>;
-    static replace: (filePath: string, replacements: string | number | boolean | (string | number | boolean | null)[] | Record<number, string | number | boolean | (string | number | boolean | null)[] | null> | Map<number, string | number | boolean | (string | number | boolean)[]> | null) => Promise<void>;
+    static replace: (filePath: string, replacements: string | number | boolean | (string | number | boolean | null)[] | Record<number, string | number | boolean | (string | number | boolean | null)[] | null> | null) => Promise<string[]>;
     static count: (filePath: string) => Promise<number>;
     static encode: (input: string | number | boolean | (string | number | boolean | null)[] | null, secretKey?: string | Buffer | undefined) => string | number | boolean | null;
     static decode: (input: string | number | null, fieldType?: FieldType | FieldType[] | undefined, fieldChildrenType?: FieldType | FieldType[] | undefined, secretKey?: string | Buffer | undefined) => string | number | boolean | (string | number | boolean | null)[] | null;
@@ -31,5 +161,5 @@ export default class File {
     static sum: (filePath: string, lineNumbers?: number | number[] | undefined) => Promise<number>;
     static min: (filePath: string, lineNumbers?: number | number[] | undefined) => Promise<number>;
     static max: (filePath: string, lineNumbers?: number | number[] | undefined) => Promise<number>;
-    static append: (filePath: string, data: string | number | (string | number)[], startsAt?: number) => Promise<void>;
+    static append: (filePath: string, data: string | number | (string | number)[]) => Promise<string[]>;
 }

package/dist/file.js

@@ -1,23 +1,46 @@
-import { open, rename, stat, writeFile, appendFile, } from "node:fs/promises";
+import { open, access, constants, writeFile, } from "node:fs/promises";
 import { createInterface } from "node:readline";
+import { Transform } from "node:stream";
+import { pipeline } from "node:stream/promises";
 import { detectFieldType, isArrayOfArrays, isNumber, isObject, } from "./utils.js";
 import { encodeID, comparePassword } from "./utils.server.js";
+/**
+ * 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(),
-        crlfDelay: Infinity,
-    });
+    const [major, minor, patch] = process.versions.node.split(".").map(Number);
+    return major > 18 || (major === 18 && minor >= 11)
+        ? fileHandle.readLines()
+        : createInterface({
+            input: fileHandle.createReadStream(), // .pipe(createInflate())
+            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, constants.R_OK | constants.W_OK);
         return true;
     }
     catch {
         return false;
     }
 };
-const delimiters = [",", "|", "&", "$", "#", "@", "^", "%", ":", "!", ";"];
+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;
@@ -32,7 +55,6 @@ const secureString = (input) => {
             .replaceAll("#", "%23")
             .replaceAll("@", "%40")
             .replaceAll("^", "%5E")
-            .replaceAll("%", "%25")
             .replaceAll(":", "%3A")
             .replaceAll("!", "%21")
             .replaceAll(";", "%3B")
@@ -40,7 +62,20 @@ const secureString = (input) => {
             .replaceAll("\r", "\\r")
         : input;
 };
+/**
+ * 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))
@@ -48,11 +83,26 @@ 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) => {
     return Array.isArray(input)
         ? joinMultidimensionalArray(secureArray(input))
         : secureString(input);
 };
+/**
+ * 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) => input
     .replaceAll("&lt;", "<")
     .replaceAll("&gt;", ">")
@@ -63,13 +113,25 @@ const unSecureString = (input) => input
     .replaceAll("%23", "#")
     .replaceAll("%40", "@")
     .replaceAll("%5E", "^")
-    .replaceAll("%25", "%")
     .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 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) => {
     const reverseJoinMultidimensionalArrayHelper = (arr, delimiter) => Array.isArray(arr)
         ? arr.map((ar) => reverseJoinMultidimensionalArrayHelper(ar, delimiter))
@@ -82,6 +144,16 @@ const reverseJoinMultidimensionalArray = (joinedString) => {
     }
     return 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));
@@ -108,6 +180,16 @@ const decodeHelper = (value, fieldType, fieldChildrenType, secretKey) => {
             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;
@@ -121,6 +203,19 @@ export const decode = (input, fieldType, fieldChildrenType, secretKey) => {
             : unSecureString(input)
         : input, fieldType, fieldChildrenType, secretKey);
 };
+/**
+ * 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.
+ *
+ * @param filePath - Path of the file to be read.
+ * @param lineNumbers - Optional line number(s) to read from the file. If -1, reads the last line.
+ * @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 Promise resolving to a tuple:
+ *   1. Record of line numbers and their decoded content or null if no lines are read.
+ *   2. Total count of lines processed.
+ */
 export const get = async (filePath, lineNumbers, fieldType, fieldChildrenType, secretKey) => {
     const fileHandle = await open(filePath, "r"), rl = readLineInternface(fileHandle);
     let lines = new Map(), lineCount = 0;
@@ -151,71 +246,122 @@ export const get = async (filePath, lineNumbers, fieldType, fieldChildrenType, s
     await fileHandle.close();
     return [lines.size ? Object.fromEntries(lines) : null, lineCount];
 };
+/**
+ * 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) => {
-    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));
-            for await (const line of rl) {
+    let lineCount = 0;
+    const fileHandle = await open(filePath, "r"), fileTempPath = filePath.replace(/([^/]+)\/?$/, `.tmp/${Date.now()}-$1`), fileTempHandle = await open(fileTempPath, "w"), rl = readLineInternface(fileHandle);
+    if (isObject(replacements))
+        await pipeline(rl, new Transform({
+            transform(line, encoding, callback) {
                 lineCount++;
-                writeStream.write((replacements.has(lineCount.toString())
-                    ? replacements.get(lineCount.toString())
+                callback(null, (replacements.hasOwnProperty(lineCount)
+                    ? replacements[lineCount]
                     : 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");
-            }
-        }
-        else
-            for await (const _line of rl)
-                writeStream.write(replacements + "\n");
+            },
+            final(callback) {
+                const newLinesNumbers = Object.entries(replacements)
+                    .map(([key, value]) => Number(key))
+                    .filter((num) => num > lineCount);
+                if (newLinesNumbers.length) {
+                    if (Math.min(...newLinesNumbers) - lineCount - 1 > 1)
+                        this.push("\n".repeat(Math.min(...newLinesNumbers) - lineCount - 1));
+                    this.push(newLinesNumbers
+                        .map((newLineNumber) => replacements[newLineNumber])
+                        .join("\n") + "\n");
+                }
+                callback();
+            },
+        }), 
+        // createDeflate(),
+        fileTempHandle.createWriteStream());
+    else
+        await pipeline(rl, new Transform({
+            transform(line, encoding, callback) {
+                lineCount++;
+                callback(null, replacements + "\n");
+            },
+        }), 
+        // createDeflate(),
+        fileTempHandle.createWriteStream());
+    await fileHandle.close();
+    await fileTempHandle.close();
+    return [fileTempPath, filePath];
+};
+/**
+ * Asynchronously appends data to 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)) {
+        const fileHandle = await open(filePath, "r"), fileTempHandle = await open(fileTempPath, "w"), rl = readLineInternface(fileHandle);
+        await pipeline(rl, new Transform({
+            transform(line, encoding, callback) {
+                callback(null, `${line}\n`);
+            },
+            final(callback) {
+                this.push((Array.isArray(data) ? data.join("\n") : data) + "\n");
+                callback();
+            },
+        }), 
+        // createDeflate(),
+        fileTempHandle.createWriteStream());
         await fileHandle.close();
         await fileTempHandle.close();
-        await rename(fileTempPath, filePath);
-    }
-    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");
     }
+    else
+        await writeFile(fileTempPath, `${Array.isArray(data) ? data.join("\n") : data}\n`);
+    return [fileTempPath, filePath];
 };
-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 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)
+    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, new Transform({
+        transform(line, encoding, callback) {
+            lineCount++;
+            if (!linesToDeleteArray.has(lineCount))
+                callback(null, `${line}\n`);
+            callback();
+        },
+    }), 
+    // createDeflate(),
+    fileTempHandle.createWriteStream());
     await fileTempHandle.close();
     await fileHandle.close();
+    return [fileTempPath, filePath];
 };
+/**
+ * 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 lineCount = 0;
@@ -225,6 +371,18 @@ export const count = async (filePath) => {
     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))
         fieldType = detectFieldType(String(originalValue), fieldType);
@@ -284,6 +442,25 @@ const handleComparisonOperator = (operator, originalValue, comparedAtValue, fiel
             throw new Error(operator);
     }
 };
+/**
+ * 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) => {
     let RETURN = new Map(), lineCount = 0, foundItems = 0;
     const fileHandle = await open(filePath, "r"), rl = readLineInternface(fileHandle);
@@ -314,6 +491,15 @@ export const search = async (filePath, operator, comparedAtValue, logicalOperato
         ? [Object.fromEntries(RETURN), readWholeFile ? foundItems : foundItems - 1]
         : [null, 0];
 };
+/**
+ * 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);
@@ -336,6 +522,15 @@ 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);
@@ -363,6 +558,15 @@ 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);
@@ -390,6 +594,17 @@ 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;

package/dist/index.js

@@ -1,6 +1,7 @@
 import { unlink, rename, readFile, writeFile, mkdir, readdir, } from "node:fs/promises";
 import { existsSync, appendFileSync } from "node:fs";
 import { join } from "node:path";
+// import { cpus } from "node:os";
 import { scryptSync, randomBytes } from "node:crypto";
 import File from "./file.js";
 import Utils from "./utils.js";
@@ -67,6 +68,8 @@ export default class Inibase {
         const TablePath = join(this.folder, this.database, tableName), TableSchemaPath = join(TablePath, "schema.json");
         if (!(await File.isExists(TablePath)))
             await mkdir(TablePath, { recursive: true });
+        if (!(await File.isExists(join(TablePath, ".tmp"))))
+            await mkdir(join(TablePath, ".tmp"));
         if (await File.isExists(TableSchemaPath)) {
             // update columns files names based on field id
             const schemaToIdsPath = (schema, prefix = "") => {
@@ -721,20 +724,21 @@ export default class Inibase {
         let RETURN;
         if (!schema)
             throw this.throwError("NO_SCHEMA", tableName);
-        const idFilePath = join(this.folder, this.database, tableName, "id.inib");
-        let [last_line_number, last_id] = (await File.isExists(idFilePath))
-            ? Object.entries((await File.get(idFilePath, -1, "number", undefined, this.salt))[0] ??
-                {})[0].map(Number) ?? [0, 0]
-            : [0, 0];
+        const idFilePath = join(this.folder, this.database, tableName, "id.inib"), idCacheFilePath = join(this.folder, this.database, tableName, ".tmp", "lastId.inib");
+        let lastId = (await File.isExists(idFilePath))
+            ? Number((await File.isExists(idCacheFilePath))
+                ? (await readFile(idCacheFilePath)).toString()
+                : Object.entries((await File.get(idFilePath, -1, "number", undefined, this.salt))[0] ?? {})[0][1] ?? 0)
+            : 0;
         if (Utils.isArrayOfObjects(data))
             RETURN = data.map(({ id, updatedAt, createdAt, ...rest }) => ({
-                id: ++last_id,
+                id: ++lastId,
                 ...rest,
                 createdAt: Date.now(),
             }));
         else
             RETURN = (({ id, updatedAt, createdAt, ...rest }) => ({
-                id: ++last_id,
+                id: ++lastId,
                 ...rest,
                 createdAt: Date.now(),
             }))(data);
@@ -742,16 +746,11 @@ export default class Inibase {
             throw this.throwError("NO_DATA");
         RETURN = this.formatData(RETURN, schema);
         const pathesContents = this.joinPathesContents(join(this.folder, this.database, tableName), RETURN);
-        last_line_number += 1;
+        const renameList = [];
         for await (const [path, content] of Object.entries(pathesContents))
-            await File.append(path, 
-            // Array.isArray(content)
-            //   ? content.reduce((obj, value, index) => {
-            //       obj[last_line_number + index] = value;
-            //       return obj;
-            //     }, {})
-            //   : { [last_line_number]: content }
-            content, last_line_number);
+            renameList.push(await File.append(path, content));
+        await Promise.all(renameList.map(([tempPath, filePath]) => rename(tempPath, filePath)));
+        await writeFile(idCacheFilePath, lastId.toString());
         if (returnPostedData)
             return this.get(tableName, Utils.isArrayOfObjects(RETURN)
                 ? RETURN.map((data) => Number(data.id))
@@ -822,8 +821,10 @@ export default class Inibase {
                         [lineNum]: Array.isArray(content) ? content[index] : content,
                     }), {}),
                 ]));
+                const renameList = [];
                 for await (const [path, content] of Object.entries(pathesContents))
-                    await File.replace(path, content);
+                    renameList.push(await File.replace(path, content));
+                await Promise.all(renameList.map(([tempPath, filePath]) => rename(tempPath, filePath)));
                 if (returnPostedData)
                     return this.get(tableName, where, options, !Array.isArray(where));
             }
@@ -847,8 +848,7 @@ export default class Inibase {
         if (!where) {
             const files = (await readdir(join(this.folder, this.database, tableName)))?.filter((fileName) => fileName.endsWith(".inib"));
             if (files.length)
-                for await (const file of files)
-                    await unlink(join(this.folder, this.database, tableName, file));
+                await Promise.all(files.map((file) => unlink(join(this.folder, this.database, tableName, file))));
             return "*";
         }
         else if ((Array.isArray(where) &&
@@ -871,8 +871,10 @@ export default class Inibase {
                         _id = Object.entries((await File.get(join(this.folder, this.database, tableName, "id.inib"), where, "number", undefined, this.salt))[0] ?? {}).map(([_key, id]) => UtilsServer.encodeID(Number(id), this.salt));
                     if (!_id.length)
                         throw this.throwError("NO_ITEMS", tableName);
+                    const renameList = [];
                     for await (const file of files)
-                        await File.remove(join(this.folder, this.database, tableName, file), where);
+                        renameList.push(await File.remove(join(this.folder, this.database, tableName, file), where));
+                    await Promise.all(renameList.map(([tempPath, filePath]) => rename(tempPath, filePath)));
                     return Array.isArray(_id) && _id.length === 1 ? _id[0] : _id;
                 }
             }

package/dist/utils.d.ts

@@ -1,23 +1,178 @@
 import { type FieldType } from "./index.js";
+/**
+ * Type guard function to check if the input is an array of objects.
+ *
+ * @param input - The value to be checked.
+ * @returns boolean - True if the input is an array of objects, false otherwise.
+ *
+ * Note: Considers empty arrays and arrays where every element is an object.
+ */
 export declare const isArrayOfObjects: (input: any) => input is Record<any, any>[];
+/**
+ * Type guard function to check if the input is an array of arrays.
+ *
+ * @param input - The value to be checked.
+ * @returns boolean - True if the input is an array of arrays, false otherwise.
+ *
+ * Note: Considers empty arrays and arrays where every element is also an array.
+ */
 export declare const isArrayOfArrays: (input: any) => input is any[][];
+/**
+ * Type guard function to check if the input is an array of nulls or an array of arrays of nulls.
+ *
+ * @param input - The value to be checked.
+ * @returns boolean - True if the input is an array consisting entirely of nulls or arrays of nulls, false otherwise.
+ *
+ * Note: Recursively checks each element, allowing for nested arrays of nulls.
+ */
 export declare const isArrayOfNulls: (input: any) => input is null[] | null[][];
+/**
+ * Type guard function to check if the input is an object.
+ *
+ * @param obj - The value to be checked.
+ * @returns boolean - True if the input is an object (excluding arrays), false otherwise.
+ *
+ * Note: Checks if the input is non-null and either has 'Object' as its constructor name or is of type 'object' without being an array.
+ */
 export declare const isObject: (obj: any) => obj is Record<any, any>;
+/**
+ * Recursively merges properties from a source object into a target object. If a property exists in both, the source's value overwrites the target's.
+ *
+ * @param target - The target object to merge properties into.
+ * @param source - The source object from which properties are merged.
+ * @returns any - The modified target object with merged properties.
+ *
+ * Note: Performs a deep merge for nested objects. Non-object properties are directly overwritten.
+ */
 export declare const deepMerge: (target: any, source: any) => any;
+/**
+ * Combines an array of objects into a single object. If the same key exists in multiple objects, the values are merged.
+ *
+ * @param arr - Array of objects to be combined.
+ * @returns Record<string, any> - A single object with combined keys and values.
+ *
+ * Note: Handles nested objects by recursively combining them. Non-object values with the same key are merged into arrays.
+ */
 export declare const combineObjects: (arr: Record<string, any>[]) => Record<string, any>;
+/**
+ * Type guard function to check if the input is a number.
+ *
+ * @param input - The value to be checked.
+ * @returns boolean - True if the input is a number, false otherwise.
+ *
+ * Note: Validates that the input can be parsed as a float and that subtracting zero results in a number, ensuring it's a numeric value.
+ */
 export declare const isNumber: (input: any) => input is number;
+/**
+ * Checks if the input is a valid email format.
+ *
+ * @param input - The value to be checked.
+ * @returns boolean - True if the input matches the email format, false otherwise.
+ *
+ * Note: Uses a regular expression to validate the email format, ensuring it has parts separated by '@' and contains a domain with a period.
+ */
 export declare const isEmail: (input: any) => boolean;
+/**
+ * Checks if the input is a valid URL format.
+ *
+ * @param input - The value to be checked.
+ * @returns boolean - True if the input matches the URL format, false otherwise.
+ *
+ * Note: Validates URLs including protocols (http/https), domain names, IP addresses, ports, paths, query strings, and fragments.
+ *       Also recognizes 'tel:' and 'mailto:' as valid URL formats, as well as strings starting with '#' without spaces.
+ */
 export declare const isURL: (input: any) => boolean;
+/**
+ * Checks if the input contains HTML tags or entities.
+ *
+ * @param input - The value to be checked.
+ * @returns boolean - True if the input contains HTML tags or entities, false otherwise.
+ *
+ * Note: Uses a regular expression to detect HTML tags (like <tag>) and entities (like &entity;).
+ *       Recognizes both opening and closing tags, as well as self-closing tags.
+ */
 export declare const isHTML: (input: any) => boolean;
+/**
+ * Type guard function to check if the input is a string, excluding strings that match specific formats (number, boolean, email, URL, IP).
+ *
+ * @param input - The value to be checked.
+ * @returns boolean - True if the input is a string that doesn't match the specific formats, false otherwise.
+ *
+ * Note: Validates the input against being a number, boolean, email, URL, or IP address to ensure it's a general string.
+ */
 export declare const isString: (input: any) => input is string;
+/**
+ * Checks if the input is a valid IP address format.
+ *
+ * @param input - The value to be checked.
+ * @returns boolean - True if the input matches the IP address format, false otherwise.
+ *
+ * Note: Uses a regular expression to validate IP addresses, ensuring they consist of four octets, each ranging from 0 to 255.
+ */
 export declare const isIP: (input: any) => boolean;
+/**
+ * Type guard function to check if the input is a boolean or a string representation of a boolean.
+ *
+ * @param input - The value to be checked.
+ * @returns boolean - True if the input is a boolean value or 'true'/'false' strings, false otherwise.
+ *
+ * Note: Recognizes both boolean literals (true, false) and their string representations ("true", "false").
+ */
 export declare const isBoolean: (input: any) => input is boolean;
+/**
+ * Type guard function to check if the input is a password based on a specific length criterion.
+ *
+ * @param input - The value to be checked.
+ * @returns boolean - True if the input is a string with a length of 161 characters, false otherwise.
+ *
+ * Note: Specifically checks for string length to determine if it matches the defined password length criterion.
+ */
 export declare const isPassword: (input: any) => input is string;
+/**
+ * Checks if the input can be converted to a valid date.
+ *
+ * @param input - The input to be checked, can be of any type.
+ * @returns A boolean indicating whether the input is a valid date.
+ */
 export declare const isDate: (input: any) => boolean;
+/**
+ * Checks if the input is a valid ID.
+ *
+ * @param input - The input to be checked, can be of any type.
+ * @returns A boolean indicating whether the input is a string representing a valid ID of length 32.
+ */
 export declare const isValidID: (input: any) => input is string;
+/**
+ * Identifies and returns properties that have changed between two objects.
+ *
+ * @param obj1 - The first object for comparison, with string keys and values.
+ * @param obj2 - The second object for comparison, with string keys and values.
+ * @returns A record of changed properties with original values from obj1 and new values from obj2, or null if no changes are found.
+ */
 export declare const findChangedProperties: (obj1: Record<string, string>, obj2: Record<string, string>) => Record<string, string> | null;
+/**
+ * Detects the field type of an input based on available types.
+ *
+ * @param input - The input whose field type is to be detected.
+ * @param availableTypes - An array of potential field types to consider.
+ * @returns The detected field type as a string, or undefined if no matching type is found.
+ */
 export declare const detectFieldType: (input: any, availableTypes: FieldType[]) => FieldType | undefined;
+/**
+ * Validates if the given value matches the specified field type(s).
+ *
+ * @param value - The value to be validated.
+ * @param fieldType - The expected field type or an array of possible field types.
+ * @param fieldChildrenType - Optional; the expected type(s) of children elements, used if the field type is an array.
+ * @returns A boolean indicating whether the value matches the specified field type(s).
+ */
 export declare const validateFieldType: (value: any, fieldType: FieldType | FieldType[], fieldChildrenType?: FieldType | FieldType[]) => boolean;
+/**
+ * Converts a nested object to dot notation, flattening the object's structure.
+ *
+ * @param input - The input object to be converted.
+ * @returns A flattened object using dot notation for keys.
+ */
 export declare const objectToDotNotation: (input: Record<string, any>) => Record<string, string | number | (string | number)[]>;
 export default class Utils {
     static isNumber: (input: any) => input is number;

package/dist/utils.js

@@ -1,9 +1,50 @@
+/**
+ * Type guard function to check if the input is an array of objects.
+ *
+ * @param input - The value to be checked.
+ * @returns boolean - True if the input is an array of objects, false otherwise.
+ *
+ * Note: Considers empty arrays and arrays where every element is an object.
+ */
 export const isArrayOfObjects = (input) => Array.isArray(input) && (input.length === 0 || input.every(isObject));
+/**
+ * Type guard function to check if the input is an array of arrays.
+ *
+ * @param input - The value to be checked.
+ * @returns boolean - True if the input is an array of arrays, false otherwise.
+ *
+ * Note: Considers empty arrays and arrays where every element is also an array.
+ */
 export const isArrayOfArrays = (input) => Array.isArray(input) && (input.length === 0 || input.every(Array.isArray));
+/**
+ * Type guard function to check if the input is an array of nulls or an array of arrays of nulls.
+ *
+ * @param input - The value to be checked.
+ * @returns boolean - True if the input is an array consisting entirely of nulls or arrays of nulls, false otherwise.
+ *
+ * Note: Recursively checks each element, allowing for nested arrays of nulls.
+ */
 export const isArrayOfNulls = (input) => input.every((_input) => Array.isArray(_input) ? isArrayOfNulls(_input) : _input === null);
+/**
+ * Type guard function to check if the input is an object.
+ *
+ * @param obj - The value to be checked.
+ * @returns boolean - True if the input is an object (excluding arrays), false otherwise.
+ *
+ * Note: Checks if the input is non-null and either has 'Object' as its constructor name or is of type 'object' without being an array.
+ */
 export const isObject = (obj) => obj != null &&
     (obj.constructor.name === "Object" ||
         (typeof obj === "object" && !Array.isArray(obj)));
+/**
+ * Recursively merges properties from a source object into a target object. If a property exists in both, the source's value overwrites the target's.
+ *
+ * @param target - The target object to merge properties into.
+ * @param source - The source object from which properties are merged.
+ * @returns any - The modified target object with merged properties.
+ *
+ * Note: Performs a deep merge for nested objects. Non-object properties are directly overwritten.
+ */
 export const deepMerge = (target, source) => {
     for (const key in source) {
         if (source.hasOwnProperty(key)) {
@@ -15,6 +56,14 @@ export const deepMerge = (target, source) => {
     }
     return target;
 };
+/**
+ * Combines an array of objects into a single object. If the same key exists in multiple objects, the values are merged.
+ *
+ * @param arr - Array of objects to be combined.
+ * @returns Record<string, any> - A single object with combined keys and values.
+ *
+ * Note: Handles nested objects by recursively combining them. Non-object values with the same key are merged into arrays.
+ */
 export const combineObjects = (arr) => {
     const result = {};
     for (const obj of arr) {
@@ -49,8 +98,33 @@ export const combineObjects = (arr) => {
     }
     return result;
 };
+/**
+ * Type guard function to check if the input is a number.
+ *
+ * @param input - The value to be checked.
+ * @returns boolean - True if the input is a number, false otherwise.
+ *
+ * Note: Validates that the input can be parsed as a float and that subtracting zero results in a number, ensuring it's a numeric value.
+ */
 export const isNumber = (input) => !isNaN(parseFloat(input)) && !isNaN(input - 0);
+/**
+ * Checks if the input is a valid email format.
+ *
+ * @param input - The value to be checked.
+ * @returns boolean - True if the input matches the email format, false otherwise.
+ *
+ * Note: Uses a regular expression to validate the email format, ensuring it has parts separated by '@' and contains a domain with a period.
+ */
 export const isEmail = (input) => /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(String(input));
+/**
+ * Checks if the input is a valid URL format.
+ *
+ * @param input - The value to be checked.
+ * @returns boolean - True if the input matches the URL format, false otherwise.
+ *
+ * Note: Validates URLs including protocols (http/https), domain names, IP addresses, ports, paths, query strings, and fragments.
+ *       Also recognizes 'tel:' and 'mailto:' as valid URL formats, as well as strings starting with '#' without spaces.
+ */
 export const isURL = (input) => {
     if (typeof input !== "string")
         return false;
@@ -68,20 +142,80 @@ export const isURL = (input) => {
         return !!pattern.test(input);
     }
 };
+/**
+ * Checks if the input contains HTML tags or entities.
+ *
+ * @param input - The value to be checked.
+ * @returns boolean - True if the input contains HTML tags or entities, false otherwise.
+ *
+ * Note: Uses a regular expression to detect HTML tags (like <tag>) and entities (like &entity;).
+ *       Recognizes both opening and closing tags, as well as self-closing tags.
+ */
 export const isHTML = (input) => /<\/?\s*[a-z-][^>]*\s*>|(\&(?:[\w\d]+|#\d+|#x[a-f\d]+);)/g.test(input);
+/**
+ * Type guard function to check if the input is a string, excluding strings that match specific formats (number, boolean, email, URL, IP).
+ *
+ * @param input - The value to be checked.
+ * @returns boolean - True if the input is a string that doesn't match the specific formats, false otherwise.
+ *
+ * Note: Validates the input against being a number, boolean, email, URL, or IP address to ensure it's a general string.
+ */
 export const isString = (input) => Object.prototype.toString.call(input) === "[object String]" &&
     [isNumber, isBoolean, isEmail, isURL, isIP].every((fn) => !fn(input));
+/**
+ * Checks if the input is a valid IP address format.
+ *
+ * @param input - The value to be checked.
+ * @returns boolean - True if the input matches the IP address format, false otherwise.
+ *
+ * Note: Uses a regular expression to validate IP addresses, ensuring they consist of four octets, each ranging from 0 to 255.
+ */
 export const isIP = (input) => /^(?:(?:^|\.)(?:2(?:5[0-5]|[0-4]\d)|1?\d?\d)){4}$/.test(input);
+/**
+ * Type guard function to check if the input is a boolean or a string representation of a boolean.
+ *
+ * @param input - The value to be checked.
+ * @returns boolean - True if the input is a boolean value or 'true'/'false' strings, false otherwise.
+ *
+ * Note: Recognizes both boolean literals (true, false) and their string representations ("true", "false").
+ */
 export const isBoolean = (input) => typeof input === "boolean" ||
     input === "true" ||
     input === "false" ||
     input === true ||
     input === false;
+/**
+ * Type guard function to check if the input is a password based on a specific length criterion.
+ *
+ * @param input - The value to be checked.
+ * @returns boolean - True if the input is a string with a length of 161 characters, false otherwise.
+ *
+ * Note: Specifically checks for string length to determine if it matches the defined password length criterion.
+ */
 export const isPassword = (input) => input.length === 161;
+/**
+ * Checks if the input can be converted to a valid date.
+ *
+ * @param input - The input to be checked, can be of any type.
+ * @returns A boolean indicating whether the input is a valid date.
+ */
 export const isDate = (input) => !isNaN(new Date(input).getTime()) || !isNaN(Date.parse(input));
+/**
+ * Checks if the input is a valid ID.
+ *
+ * @param input - The input to be checked, can be of any type.
+ * @returns A boolean indicating whether the input is a string representing a valid ID of length 32.
+ */
 export const isValidID = (input) => {
     return typeof input === "string" && input.length === 32;
 };
+/**
+ * Identifies and returns properties that have changed between two objects.
+ *
+ * @param obj1 - The first object for comparison, with string keys and values.
+ * @param obj2 - The second object for comparison, with string keys and values.
+ * @returns A record of changed properties with original values from obj1 and new values from obj2, or null if no changes are found.
+ */
 export const findChangedProperties = (obj1, obj2) => {
     const result = {};
     for (const key1 in obj1)
@@ -89,6 +223,13 @@ export const findChangedProperties = (obj1, obj2) => {
             result[obj1[key1]] = obj2[key1];
     return Object.keys(result).length ? result : null;
 };
+/**
+ * Detects the field type of an input based on available types.
+ *
+ * @param input - The input whose field type is to be detected.
+ * @param availableTypes - An array of potential field types to consider.
+ * @returns The detected field type as a string, or undefined if no matching type is found.
+ */
 export const detectFieldType = (input, availableTypes) => {
     if (!Array.isArray(input)) {
         if ((input === "0" ||
@@ -126,6 +267,14 @@ export const detectFieldType = (input, availableTypes) => {
         return "array";
     return undefined;
 };
+/**
+ * Validates if the given value matches the specified field type(s).
+ *
+ * @param value - The value to be validated.
+ * @param fieldType - The expected field type or an array of possible field types.
+ * @param fieldChildrenType - Optional; the expected type(s) of children elements, used if the field type is an array.
+ * @returns A boolean indicating whether the value matches the specified field type(s).
+ */
 export const validateFieldType = (value, fieldType, fieldChildrenType) => {
     if (value === null)
         return true;
@@ -177,6 +326,12 @@ export const validateFieldType = (value, fieldType, fieldChildrenType) => {
             return false;
     }
 };
+/**
+ * Converts a nested object to dot notation, flattening the object's structure.
+ *
+ * @param input - The input object to be converted.
+ * @returns A flattened object using dot notation for keys.
+ */
 export const objectToDotNotation = (input) => {
     const result = {};
     const stack = [

package/dist/utils.server.d.ts

@@ -1,10 +1,52 @@
 /// <reference types="node" resolution-mode="require"/>
 import { type Schema } from "./index.js";
+/**
+ * Generates a hashed password using SHA-256.
+ *
+ * @param password - The plain text password to hash.
+ * @returns A string containing the salt and the hashed password, separated by a colon.
+ */
 export declare const hashPassword: (password: string) => string;
+/**
+ * Compares a hashed password with an input password to verify a match.
+ *
+ * @param hashedPassword - The hashed password, containing both the salt and the hash, separated by a colon.
+ * @param inputPassword - The plain text input password to compare against the hashed password.
+ * @returns A boolean indicating whether the input password matches the hashed password.
+ */
 export declare const comparePassword: (hashedPassword: string, inputPassword: string) => boolean;
+/**
+ * Encodes an ID using AES-256-CBC encryption.
+ *
+ * @param id - The ID to encode, either a number or a string.
+ * @param secretKeyOrSalt - The secret key or salt for encryption, can be a string, number, or Buffer.
+ * @returns The encoded ID as a hexadecimal string.
+ */
 export declare const encodeID: (id: number | string, secretKeyOrSalt: string | number | Buffer) => string;
+/**
+ * Decodes an encrypted ID using AES-256-CBC decryption.
+ *
+ * @param input - The encrypted ID as a hexadecimal string.
+ * @param secretKeyOrSalt - The secret key or salt used for decryption, can be a string, number, or Buffer.
+ * @returns The decoded ID as a number.
+ */
 export declare const decodeID: (input: string, secretKeyOrSalt: string | number | Buffer) => number;
+/**
+ * Finds the last ID number in a schema, potentially decoding it if encrypted.
+ *
+ * @param schema - The schema to search, defined as an array of schema objects.
+ * @param secretKeyOrSalt - The secret key or salt for decoding an encrypted ID, can be a string, number, or Buffer.
+ * @returns The last ID number in the schema, decoded if necessary.
+ */
 export declare const findLastIdNumber: (schema: Schema, secretKeyOrSalt: string | number | Buffer) => number;
+/**
+ * Adds or updates IDs in a schema, encoding them using a provided secret key or salt.
+ *
+ * @param schema - The schema to update, defined as an array of schema objects.
+ * @param oldIndex - The starting index for generating new IDs, defaults to 0.
+ * @param secretKeyOrSalt - The secret key or salt for encoding IDs, can be a string, number, or Buffer.
+ * @returns The updated schema with encoded IDs.
+ */
 export declare const addIdToSchema: (schema: Schema, oldIndex: number | undefined, secretKeyOrSalt: string | number | Buffer) => import("./index.js").Field[];
 export default class UtilsServer {
     static encodeID: (id: string | number, secretKeyOrSalt: string | number | Buffer) => string;

package/dist/utils.server.js

@@ -1,5 +1,11 @@
 import { createCipheriv, createDecipheriv, randomBytes, scryptSync, createHash, } from "node:crypto";
 import { isArrayOfObjects, isNumber, isValidID } from "./utils.js";
+/**
+ * Generates a hashed password using SHA-256.
+ *
+ * @param password - The plain text password to hash.
+ * @returns A string containing the salt and the hashed password, separated by a colon.
+ */
 export const hashPassword = (password) => {
     const salt = randomBytes(16).toString("hex");
     const hash = createHash("sha256")
@@ -7,6 +13,13 @@ export const hashPassword = (password) => {
         .digest("hex");
     return `${salt}:${hash}`;
 };
+/**
+ * Compares a hashed password with an input password to verify a match.
+ *
+ * @param hashedPassword - The hashed password, containing both the salt and the hash, separated by a colon.
+ * @param inputPassword - The plain text input password to compare against the hashed password.
+ * @returns A boolean indicating whether the input password matches the hashed password.
+ */
 export const comparePassword = (hashedPassword, inputPassword) => {
     const [salt, originalHash] = hashedPassword.split(":");
     const inputHash = createHash("sha256")
@@ -14,6 +27,13 @@ export const comparePassword = (hashedPassword, inputPassword) => {
         .digest("hex");
     return inputHash === originalHash;
 };
+/**
+ * Encodes an ID using AES-256-CBC encryption.
+ *
+ * @param id - The ID to encode, either a number or a string.
+ * @param secretKeyOrSalt - The secret key or salt for encryption, can be a string, number, or Buffer.
+ * @returns The encoded ID as a hexadecimal string.
+ */
 export const encodeID = (id, secretKeyOrSalt) => {
     let cipher;
     if (Buffer.isBuffer(secretKeyOrSalt))
@@ -24,6 +44,13 @@ export const encodeID = (id, secretKeyOrSalt) => {
     }
     return cipher.update(id.toString(), "utf8", "hex") + cipher.final("hex");
 };
+/**
+ * Decodes an encrypted ID using AES-256-CBC decryption.
+ *
+ * @param input - The encrypted ID as a hexadecimal string.
+ * @param secretKeyOrSalt - The secret key or salt used for decryption, can be a string, number, or Buffer.
+ * @returns The decoded ID as a number.
+ */
 export const decodeID = (input, secretKeyOrSalt) => {
     let decipher;
     if (Buffer.isBuffer(secretKeyOrSalt))
@@ -34,6 +61,13 @@ export const decodeID = (input, secretKeyOrSalt) => {
     }
     return Number(decipher.update(input, "hex", "utf8") + decipher.final("utf8"));
 };
+/**
+ * Finds the last ID number in a schema, potentially decoding it if encrypted.
+ *
+ * @param schema - The schema to search, defined as an array of schema objects.
+ * @param secretKeyOrSalt - The secret key or salt for decoding an encrypted ID, can be a string, number, or Buffer.
+ * @returns The last ID number in the schema, decoded if necessary.
+ */
 export const findLastIdNumber = (schema, secretKeyOrSalt) => {
     const lastField = schema[schema.length - 1];
     if (lastField) {
@@ -47,6 +81,14 @@ export const findLastIdNumber = (schema, secretKeyOrSalt) => {
     }
     return 0;
 };
+/**
+ * Adds or updates IDs in a schema, encoding them using a provided secret key or salt.
+ *
+ * @param schema - The schema to update, defined as an array of schema objects.
+ * @param oldIndex - The starting index for generating new IDs, defaults to 0.
+ * @param secretKeyOrSalt - The secret key or salt for encoding IDs, can be a string, number, or Buffer.
+ * @returns The updated schema with encoded IDs.
+ */
 export const addIdToSchema = (schema, oldIndex = 0, secretKeyOrSalt) => schema.map((field) => {
     if (!field.id) {
         oldIndex++;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "inibase",
-  "version": "1.0.0-rc.24",
+  "version": "1.0.0-rc.26",
   "author": {
     "name": "Karim Amahtil",
     "email": "karim.amahtil@gmail.com"