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

package/README.md

@@ -4,17 +4,20 @@
 
 [![npmjs](https://img.shields.io/npm/dm/inibase.svg?style=flat)](https://www.npmjs.org/package/inibase) [![License](https://img.shields.io/github/license/inicontent/inibase.svg?style=flat&colorA=18181B&colorB=28CF8D)](./LICENSE) [![Activity](https://img.shields.io/github/commit-activity/m/inicontent/inibase)](https://github.com/inicontent/inibase/pulse) [![GitHub stars](https://img.shields.io/github/stars/inicontent/inibase?style=social)](https://github.com/inicontent/inibase)
 
-> File-based relational database, simple to use and can handle large data :fire:
+> A file-based & memory-efficient, serverless relational database management system :fire:
 
 ## Features
 
 - **Lightweight** 🪶
-- **Minimalist** :white_circle:
+- **Minimalist** :white_circle: (but powerful)
 - **TypeScript** :large_blue_diamond:
-- **Super-Fast** :zap:
-- **Form-validation** included :sunglasses:
-- **Suitable for large data** :page_with_curl:
-- **Safe** :lock:
+- **Super-Fast** :zap: (built-in caching system)
+- **Built-in form-validation** included :sunglasses:
+- **Suitable for large data** :page_with_curl: (tested with 200K row)
+- **Support Compression** :eight_spoked_asterisk: (using built-in nodejs zlib)
+- **Support Table Joins** :link:
+- **Low memory-usage** :chart_with_downwards_trend: (3-5mb)
+- **Safe** :lock: (no sql or javascript injections)
 - **Easy to use** :bread:
 - **...** and much more :rocket:
 
@@ -35,8 +38,8 @@ const users = await db.get("user", undefined, {
   columns: ["username", "address.street", "hobbies.name"],
 });
 
-// Get items from "user" table where "favoriteFoods" does not includes "Pizza"
-const users = await db.get("user", { favoriteFoods: "![]Pizza" });
+// Get items from "user" table where "favoriteFoods" does not includes "Pizza" or "Burger"
+const users = await db.get("user", { favoriteFoods: "![]Pizza,Burger" });
 ```
 
 If you like Inibase, please sponsor: [GitHub Sponsors](https://github.com/sponsors/inicontent) || [Paypal](https://paypal.me/KarimAmahtil).
@@ -49,7 +52,7 @@ If you like Inibase, please sponsor: [GitHub Sponsors](https://github.com/sponso
 
 ## How it works?
 
-To simplify the idea, each database has tables, each table has columns, each column will be stored in a seperated file. When POSTing new data, it will be appended to the end of each file as new line. When GETing data, the file will be readed line-by-line so it can handle large data (without consuming a lot of resources), when PUTing(updating) in a specific column, only one file will be opened and updated
+To simplify the idea, each database has tables, each table has columns, each column will be stored in a seperated file. When **POST**ing new data, it will be appended to the _head_ of each file as new line. When **GET**ing data, the file will be readed line-by-line so it can handle large data (without consuming a lot of resources), when **PUT**ing(updating) in a specific column, only one file will be opened and updated
 
 ## Benchmark
 
@@ -71,6 +74,45 @@ To simplify the idea, each database has tables, each table has columns, each col
 | PUT    | 33 ms (10.29 mb)  | 312 ms (11.06 mb)  | 3539 ms (14.87 mb) |
 | DELETE | 134 ms (13.50 mb) | 1224 ms (16.57 mb) | 7339 ms (11.46 mb) |
 
+
+## Roadmap
+
+- [x] Actions:
+  - [x] GET:
+    - [x] Pagination
+    - [x] Criteria
+    - [x] Columns
+    - [ ] Order By
+  - [x] POST
+  - [x] PUT
+  - [x] DELETE
+  - [x] SUM
+  - [x] MAX
+  - [x] MIN
+- [ ] Schema supported types:
+  - [x] String
+  - [x] Number
+  - [x] Boolean
+  - [x] Date
+  - [x] Email
+  - [x] Url
+  - [x] Table
+  - [x] Object
+  - [x] Array
+  - [x] Password
+  - [x] IP
+  - [x] HTML
+  - [x] Id
+- [ ] TO-DO:
+  - [x] Improve caching
+  - [x] Commenting the code
+- [ ] Features:
+  - [ ] Encryption
+  - [x] Data Compression
+  - [x] Caching System
+  - [ ] Suggest [new feature +](https://github.com/inicontent/inibase/discussions/new?category=ideas)
+
+
 ## Examples
 
 <details>
@@ -447,40 +489,17 @@ await db.min("user", ["age", ...], { isActive: false });
 
 </details>
 
+## Config
 
+The `.env` file supports the following parameters (make sure to run command with flag --env-file=.env)
 
-## Roadmap
+```ini
+# Auto generated secret key, will be using for encrypting the IDs
+INIBASE_SECRET=
 
-- [x] Actions:
-  - [x] GET:
-    - [x] Pagination
-    - [x] Criteria
-    - [x] Columns
-    - [ ] Order By
-  - [x] POST
-  - [x] PUT
-  - [x] DELETE
-- [ ] Schema supported types:
-  - [x] String
-  - [x] Number
-  - [x] Boolean
-  - [x] Date
-  - [x] Email
-  - [x] Url
-  - [x] Table
-  - [x] Object
-  - [x] Array
-  - [x] Password
-  - [x] IP
-  - [x] HTML
-  - [x] Id
-- [ ] TO-DO:
-  - [ ] Improve caching
-  - [ ] Commenting the code
-- [ ] Features:
-  - [ ] Encryption
-  - [ ] Compress data
-  - [ ] Suggest [new feature +](https://github.com/inicontent/inibase/discussions/new?category=ideas)
+INIBASE_COMPRESSION=true
+INIBASE_CACHE=true
+```
 
 ## License
 

package/dist/config.d.ts

@@ -0,0 +1,4 @@
+export default class Config {
+    static isCompressionEnabled: boolean;
+    static isCacheEnabled: boolean;
+}

package/dist/config.js

@@ -0,0 +1,4 @@
+export default class Config {
+    static isCompressionEnabled = process.env.INIBASE_COMPRESSION === "true";
+    static isCacheEnabled = process.env.INIBASE_CACHE === "true";
+}

package/dist/file.d.ts

@@ -1,35 +1,171 @@
 /// <reference types="node" resolution-mode="require"/>
 import { ComparisonOperator, FieldType } from "./index.js";
+export declare const write: (filePath: string, data: any, disableCompression?: boolean) => Promise<void>;
+export declare const read: (filePath: string, disableCompression?: boolean) => Promise<string>;
+/**
+ * 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)[];
-export declare const get: (filePath: string, lineNumbers?: number | number[], fieldType?: FieldType | FieldType[], fieldChildrenType?: FieldType | FieldType[], secretKey?: string | Buffer) => Promise<[
+/**
+ * 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 function 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>;
+export declare function get(filePath: string, lineNumbers: undefined | number | number[], fieldType: undefined | FieldType | FieldType[], fieldChildrenType: undefined | FieldType | FieldType[], secretKey: undefined | string | Buffer, readWholeFile: true): 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>;
-export declare const count: (filePath: string) => Promise<number>;
+/**
+ * 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 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 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 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
+    Record<number, string | number | boolean | null | (string | number | boolean | null)[]> | null,
+    number,
+    Set<number> | null
 ]>;
+/**
+ * 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 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 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 count: (filePath: string) => Promise<number>;
+    static get: typeof get;
+    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, Set<number> | null]>;
+    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 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;
     static isExists: (path: string) => Promise<boolean>;
     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[]>;
+    static count: (filePath: string) => Promise<number>;
+    static write: (filePath: string, data: any, disableCompression?: boolean) => Promise<void>;
+    static read: (filePath: string, disableCompression?: boolean) => Promise<string>;
 }