inibase 1.0.0-rc.5 → 1.0.0-rc.50

package/README.md

@@ -4,17 +4,21 @@
 
 [![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, ACID compliant, relational database management system :fire:
 
 ## Features
 
-- **Lightweight** 🪶 (~60kb)
-- **Minimalist** :white_circle:
+- **Lightweight** 🪶
+- **Minimalist** :white_circle: (but powerful)
 - **TypeScript** :large_blue_diamond:
-- **Super-Fast** :turtle:
-- **Suitable for large data** :page_with_curl:
-- **Safe** :lock:
-- **Easy to use** :hourglass:
+- **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:
 
 ## Usage
@@ -31,35 +35,89 @@ const users = await db.get("user", undefined, { page: 2, per_page: 15 });
 
 // Get only required columns to improve speed
 const users = await db.get("user", undefined, {
-  columns: ["username", "address.street", "hobbies.*.name"],
+  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).
 
-## Sponsors
-
-<br>
-<br>
-
-Become a sponsor and have your company logo here 👉 [GitHub Sponsors](https://github.com/sponsors/inicontent) || [paypal](https://paypal.me/KarimAmahtil).
-
 ## Install
 
 ```js
-// npm
-npm install inibase
-
-// pnpm
-pnpm add inibase
+<npm|pnpm|yarn> install inibase
 ```
 
 ## How it works?
 
-To semplify 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 each columns 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)
+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
+
+### Bulk
+
+|        | 10              | 100             | 1000            |
+|--------|-----------------|-----------------|-----------------|
+| POST   | 11 ms (0.65 mb) | 19 ms (1.00 mb) | 85 ms (4.58 mb) |
+| GET    | 14 ms (2.77 mb) | 12 ms (3.16 mb) | 34 ms (1.38 mb) |
+| PUT    | 6 ms (1.11 mb)  | 5 ms (1.37 mb)  | 10 ms (1.12 mb) |
+| DELETE | 17 ms (1.68 mb) | 14 ms (5.45 mb) | 25 ms (5.94 mb) |
+
+### Single
+
+|        | 10                | 100                | 1000               |
+|--------|-------------------|--------------------|--------------------|
+| POST   | 43 ms (4.70 mb)   | 387 ms (6.36 mb)   | 5341 ms (24.73 mb) |
+| GET    | 99 ms (12.51 mb)  | 846 ms (30.68 mb)  | 7103 ms (30.86 mb) |
+| 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) |
+
+Ps: Testing by default with `user` table, with username, email, password fields _so results include password encryption process_
+
+
+## Roadmap
+
+- [x] Actions:
+  - [x] GET:
+    - [x] Pagination
+    - [x] Criteria
+    - [x] Columns
+    - [x] Order By (using UNIX commands)
+  - [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
+  - [x] JSON
+- [ ] TO-DO:
+  - [x] Improve caching
+  - [ ] Commenting the code
+  - [ ] Add property "unique" for schema fields
+  - [ ] Add Backup feature (generate a tar.gz)
+  - [ ] Add Custom field validation property to schema (using RegEx?)
+- [ ] Features:
+  - [ ] Encryption
+  - [x] Data Compression
+  - [x] Caching System
+  - [ ] Suggest [new feature +](https://github.com/inicontent/inibase/discussions/new?category=ideas)
+
 
 ## Examples
 
@@ -226,8 +284,9 @@ const product_schema = [
     type: "number",
   },
   {
-    key: "user",
+    key: "createdBy",
     type: "table",
+    table: "user",
     required: true,
   },
 ];
@@ -236,12 +295,12 @@ const product_data = [
   {
     title: "Product 1",
     price: 16,
-    user: "1d88385d4b1581f8fb059334dec30f4c",
+    createdBy: "1d88385d4b1581f8fb059334dec30f4c",
   },
   {
     title: "Product 2",
     price: 10,
-    user: "5011c230aa44481bf7e8dcfe0710474f",
+    createdBy: "5011c230aa44481bf7e8dcfe0710474f",
   },
 ];
 
@@ -251,7 +310,7 @@ const product = await db.post("product", product_data);
 //     "id": "1d88385d4b1581f8fb059334dec30f4c",
 //     "title": "Product 1",
 //     "price": 16,
-//     "user": {
+//     "createdBy": {
 //       "id": "1d88385d4b1581f8fb059334dec30f4c",
 //       "username": "user1",
 //       "email": "user1@example.com",
@@ -262,7 +321,7 @@ const product = await db.post("product", product_data);
 //     "id": "5011c230aa44481bf7e8dcfe0710474f",
 //     "title": "Product 2",
 //     "price": 10,
-//     "user": {
+//     "createdBy": {
 //       "id": "5011c230aa44481bf7e8dcfe0710474f",
 //       "username": "user2",
 //       ...
@@ -389,92 +448,95 @@ await db.put("user", { isActive: false });
 
 </details>
 
-## Typescript
+<details>
+<summary>SUM</summary>
+
+```js
+import Inibase from "inibase";
+const db = new Inibase("/database_name");
+
+// get the sum of column "age" in "user" table
+await db.sum("user", "age");
+
+// get the sum of column "age" by criteria (where "isActive" is equal to "false") in "user" table
+await db.sum("user", ["age", ...], { isActive: false });
+```
+
+</details>
+
+<details>
+<summary>MAX</summary>
+
+```js
+import Inibase from "inibase";
+const db = new Inibase("/database_name");
+
+// get the biggest number of column "age" in "user" table
+await db.max("user", "age");
+
+// get the biggest number of column "age" by criteria (where "isActive" is equal to "false") in "user" table
+await db.max("user", ["age", ...], { isActive: false });
+```
+
+</details>
 
 <details>
-<summary>Schema</summary>
+<summary>MIN</summary>
 
 ```js
-type Schema = Field[];
-type Field = {
-  id?: string | number | null | undefined,
-  key: string,
-  required?: boolean,
-} & (
-  | {
-      type: Exclude<FieldType, "array" | "object">,
-      required?: boolean,
-    }
-  | {
-      type: "array",
-      children: FieldType | FieldType[] | Schema,
-    }
-  | {
-      type: "object",
-      children: Schema,
-    }
-);
-type FieldType =
-  | "string"
-  | "number"
-  | "boolean"
-  | "date"
-  | "email"
-  | "url"
-  | "table"
-  | "object"
-  | "array"
-  | "password";
+import Inibase from "inibase";
+const db = new Inibase("/database_name");
+
+// get the smallest number of column "age" in "user" table
+await db.min("user", "age");
+
+// get the smallest number of column "age" by criteria (where "isActive" is equal to "false") in "user" table
+await db.min("user", ["age", ...], { isActive: false });
 ```
 
 </details>
 
 <details>
-<summary>Data</summary>
+<summary>createWorker</summary>
 
 ```js
-type Data = {
-  id?: number | string,
-  [key: string]: any,
-  created_at?: Date,
-  updated_at?: Date,
-};
+import Inibase from "inibase";
+const db = new Inibase("/database_name");
+
+// POST 10,000 USER
+await Promise.all(
+  [...Array(10)]
+    .map((x, i) => i)
+    .map(
+      (_index) =>
+        db.createWorker("post", [
+          "user",
+          [...Array(1000)].map((_, i) => ({
+            username: `username_${i + 1}`,
+            email: `email_${i + 1}@test.com`,
+            password: `password_${i + 1}`,
+          })),
+        ])
+    )
+)
 ```
 
 </details>
 
-## Roadmap
+## Config (.env)
 
-- [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
-  - [ ] IP
-  - [ ] HTML
-  - [ ] Markdown
-- [ ] TO-DO:
-  - [ ] Improve caching
-  - [ ] Commenting the code
-- [ ] Features:
-  - [ ] Encryption
-  - [ ] Compress data
-  - [ ] Suggest [new feature +](https://github.com/inicontent/inibase/discussions/new?category=ideas)
+The `.env` file supports the following parameters (make sure to run commands with flag --env-file=.env)
+
+```ini
+# Auto generated secret key, will be using for encrypting the IDs
+INIBASE_SECRET=
+
+INIBASE_COMPRESSION=true
+INIBASE_CACHE=true
+
+# Prepend new items to the beginning of file 
+INIBASE_REVERSE=true
+```
 
 ## License
 

package/dist/config.d.ts

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

package/dist/config.js

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

package/dist/file.d.ts

@@ -0,0 +1,176 @@
+/// <reference types="node" resolution-mode="require"/>
+import { ComparisonOperator, FieldType, Schema } from "./index.js";
+export declare const lock: (folderPath: string, prefix?: string) => Promise<void>;
+export declare const unlock: (folderPath: string, prefix?: string) => Promise<void>;
+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 'Inison.stringify' 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).
+ * @returns The secured and/or joined string.
+ */
+export declare const encode: (input: string | number | boolean | null | (string | number | boolean | null)[]) => 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[] | Schema, 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 function get(filePath: string, lineNumbers?: number | number[], fieldType?: FieldType | FieldType[], fieldChildrenType?: FieldType | FieldType[] | Schema, secretKey?: string | Buffer, readWholeFile?: false): 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
+]>;
+/**
+ * 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[] | Schema, limit?: number, offset?: number, readWholeFile?: boolean, secretKey?: string | Buffer) => Promise<[
+    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>;
+export declare function createWorker(functionName: "get" | "remove" | "search" | "replace" | "sum" | "min" | "max" | "append" | "count", arg: any[]): Promise<any>;
+/**
+ * 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: 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[] | Schema | 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) => string | number | boolean | null;
+    static decode: (input: string | number | null, fieldType?: FieldType | FieldType[] | undefined, fieldChildrenType?: FieldType | FieldType[] | Schema | 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)[]) => 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>;
+    static lock: (folderPath: string, prefix?: string | undefined) => Promise<void>;
+    static unlock: (folderPath: string, prefix?: string | undefined) => Promise<void>;
+    static createWorker: typeof createWorker;
+}