@wxn0brp/db 0.0.2 → 0.0.4

package/README.md

@@ -15,7 +15,7 @@ npm install @wxn0brp/db
 You can import the necessary classes from the package as follows:
 
 ```javascript
-import { DataBase, Graph, DataBaseRemote, GraphRemote } from "@wxn0brp/db";
+import { DataBase, Graph, DataBaseRemote, GraphRemote, Relation, genId } from "@wxn0brp/db";
 ```
 
 ## Documentation
@@ -25,4 +25,6 @@ For detailed information, refer to the following resources:
 - [DataBase Documentation](./docs/database.md)
 - [Graph Documentation](./docs/graph.md)
 - [Remote Database and Graph Client Documentation](./docs/remote.md)
-- [Remote Server Documentation](./docs/remote_server.md)
+- [Remote Server Documentation](./docs/remote_server.md)
+- [Search Options Documentation](./docs/search_opts.md)
+- [Relation Documentation](./docs/relation.md)

package/action.js

@@ -3,8 +3,6 @@ import gen from "./gen.js";
 import { stringify } from "./format.js";
 import { find as _find, findOne as _findOne, update as _update, remove as _remove } from "./file/index.js";
 
-const maxFileSize = 2 * 1024 * 1024; //2 MB
-
 /**
  * A class representing database actions on files.
  * @class
@@ -18,11 +16,18 @@ class dbActionC{
      */
     constructor(folder, options){
         this.folder = folder;
-        // this.cacheManager = new CacheManager(options.cacheThreshold, options.cacheTTL);
+        this.options = {
+            maxFileSize: 2 * 1024 * 1024, //2 MB
+            ...options,
+        };
         
         if(!existsSync(folder)) mkdirSync(folder, { recursive: true });
     }
 
+    _getCollectionPath(collection){
+        return this.folder + "/" + collection + "/";
+    }
+
     /**
      * Get a list of available databases in the specified folder.
      * @returns {string[]} An array of database names.
@@ -44,8 +49,8 @@ class dbActionC{
      * @param {string} collection - The collection to check.
      */
     checkCollection(collection){
-        const path = this.folder + "/" + collection;
-        if(!existsSync(path)) mkdirSync(path, { recursive: true });
+        const cpath = this._getCollectionPath(collection);
+        if(!existsSync(cpath)) mkdirSync(cpath, { recursive: true });
     }
 
     /**
@@ -69,7 +74,8 @@ class dbActionC{
      */
     async add(collection, arg, id_gen=true){
         await this.checkCollection(collection);
-        const file = this.folder + "/" + collection + "/" + getLastFile(this.folder + "/" + collection);
+        const cpath = this._getCollectionPath(collection);
+        const file = cpath + getLastFile(cpath, this.options.maxFileSize);
 
         if(id_gen) arg._id = arg._id || gen();
         const data = stringify(arg);
@@ -94,14 +100,15 @@ class dbActionC{
         options.max = options.max || -1;
 
         await this.checkCollection(collection);
-        const files = getSortedFiles(this.folder + "/" + collection).map(f => f.f);
+        const cpath = this._getCollectionPath(collection);
+        const files = getSortedFiles(cpath).map(f => f.f);
         if(options.reverse) files.reverse();
         let datas = [];
 
         let totalEntries = 0;
 
         for(let f of files){
-            let data = await _find(this.folder + "/" + collection + "/" + f, arg, context, findOpts);
+            let data = await _find(cpath + f, arg, context, findOpts);
             if(options.reverse) data.reverse();
 
             if(options.max !== -1){
@@ -132,11 +139,11 @@ class dbActionC{
      */
     async findOne(collection, arg, context={}, findOpts={}){
         await this.checkCollection(collection);
-        const files = getSortedFiles(this.folder + "/" + collection).map(f => f.f);
-        files.reverse();
+        const cpath = this._getCollectionPath(collection);
+        const files = getSortedFiles(cpath).map(f => f.f);
 
         for(let f of files){
-            let data = await _findOne(this.folder + "/" + collection + "/" + f, arg, context, findOpts);
+            let data = await _findOne(cpath + f, arg, context, findOpts);
             if(data){
                 return data;
             }
@@ -155,7 +162,7 @@ class dbActionC{
      */
     async update(collection, arg, obj, context={}){
         await this.checkCollection(collection);
-        return await _update(this.folder, collection, arg, obj, context);
+        return await _update(this._getCollectionPath(collection), arg, obj, context);
     }
 
     /**
@@ -169,7 +176,7 @@ class dbActionC{
      */
     async updateOne(collection, arg, obj, context={}){
         await this.checkCollection(collection);
-        return await _update(this.folder, collection, arg, obj, context, true);
+        return await _update(this._getCollectionPath(collection), arg, obj, context, true);
     }
 
     /**
@@ -182,7 +189,7 @@ class dbActionC{
      */
     async remove(collection, arg, context={}){
         await this.checkCollection(collection);
-        return await _remove(this.folder, collection, arg, context);
+        return await _remove(this._getCollectionPath(collection), arg, context);
     }
 
     /**
@@ -195,7 +202,7 @@ class dbActionC{
      */
     async removeOne(collection, arg, context={}){
         await this.checkCollection(collection);
-        return await _remove(this.folder, collection, arg, context, true);
+        return await _remove(this._getCollectionPath(collection), arg, context, true);
     }
 
     /**
@@ -204,7 +211,7 @@ class dbActionC{
      * @param {string} collection - The name of the collection to remove.
      * @return {void}
      */
-    removeDb(collection){
+    removeCollection(collection){
         rmSync(this.folder + "/" + collection, { recursive: true, force: true });
     }
 }
@@ -212,9 +219,10 @@ class dbActionC{
 /**
  * Get the last file in the specified directory.
  * @param {string} path - The directory path.
+ * @param {number} maxFileSize - The maximum file size in bytes. Default is 1 MB.
  * @returns {string} The name of the last file in the directory.
  */
-function getLastFile(path){
+function getLastFile(path, maxFileSize=1024*1024){
     if(!existsSync(path)) mkdirSync(path, { recursive: true });
     const files = getSortedFiles(path);
 

package/database.d.ts

@@ -0,0 +1,44 @@
+import dbActionC from "./action.js";
+import executorC from "./executor.js";
+import CollectionManager from "./CollectionManager.js";
+
+declare class DataBase {
+    constructor(folder: string, options?: {
+        cacheThreshold?: number,
+        cacheTTL?: number
+    });
+
+    dbAction: dbActionC;
+    executor: executorC;
+
+    c(collection: string): CollectionManager;
+
+    getCollections(): Promise<string[]>;
+
+    checkCollection(collection: string): Promise<void>;
+
+    issetCollection(collection: string): Promise<boolean>;
+
+    add(collection: string, data: object, id_gen?: boolean): Promise<object>;
+
+    find(collection: string, search: object | Function, context?: object, options?: {
+        max?: number,
+        reverse?: boolean
+    }, findOpts?: object): Promise<object[]>;
+
+    findOne(collection: string, search: object | Function, context?: object, findOpts?: object): Promise<object | null>;
+
+    update(collection: string, search: object | Function, arg: object | Function, context?: object): Promise<boolean>;
+
+    updateOne(collection: string, search: object | Function, arg: object | Function, context?: object): Promise<boolean>;
+
+    remove(collection: string, search: object | Function, context?: object): Promise<boolean>;
+
+    removeOne(collection: string, search: object | Function, context?: object): Promise<boolean>;
+
+    updateOneOrAdd(collection: string, search: object | Function, arg: object | Function, add_arg?: object, context?: object, id_gen?: boolean): Promise<boolean>;
+
+    removeCollection(collection: string): void;
+}
+
+export default DataBase;

package/database.js

@@ -12,15 +12,10 @@ class DataBase{
      * @constructor
      * @param {string} folder - The folder path where the database files are stored.
      * @param {object} [options] - The options object.
-     * @param {number} [options.cacheThreshold=3] - The cache threshold for database entries (default: 3).
-     * @param {number} [options.cacheTTL=300000] - The time-to-live (TTL) for cached entries in milliseconds (default: 300,000 milliseconds or 5 minutes).
+     * @param {number} [options.maxFileSize=2*1024*1024] - The maximum size of a file in bytes. Default is 2 MB.
+     * @param {number} 
      */
     constructor(folder, options={}){
-        options = {
-            cacheThreshold: 3,
-            cacheTTL: 300_000,
-            ...options
-        }
         this.dbAction = new dbActionC(folder, options);
         this.executor = new executorC();
     }
@@ -200,8 +195,8 @@ class DataBase{
      * @param {string} collection - The name of the collection to remove.
      * @return {void}
      */
-    removeDb(collection){
-         this.dbAction.removeDb(collection);
+    removeCollection(collection){
+         this.dbAction.removeCollection(collection);
     }
 }
 

package/docs/database.md

@@ -131,7 +131,7 @@ Removes one entry from a collection.
 - **Returns:**
   - `Promise<boolean>`: A promise that resolves when the entry is removed.
 
-### Method: `removeDb(collection)`
+### Method: `removeCollection(collection)`
 Removes the specified collection from the database file system.
 
 - **Parameters:**

package/docs/graph.md

@@ -76,3 +76,11 @@ Checks if the specified collection exists.
   - `collection` (`string`): The name of the collection.
 - **Returns:**
   - `Promise<boolean>`: A promise that resolves to `true` if the collection exists, otherwise `false`.
+
+### Method: `removeCollection(collection)`
+Removes the specified collection from the database file system.
+
+- **Parameters:**
+  - `collection` (`string`): The name of the collection to remove.
+- **Returns:**
+  - `void`

package/docs/relation.md

@@ -0,0 +1,51 @@
+# Relation Class Documentation
+
+This documentation provides an overview of the `Relation` class, which is designed to manage and resolve relations between database collections.
+
+## Class: `Relation`
+
+### Constructor: `Relation(databases)`
+Creates a new instance of the `Relation` class.
+
+- **Parameters:**
+  - `databases` (`Record<string, Database>`): An object containing database instances, where keys are database names.
+
+### Method: `async find(path: string, search: object | Function, relations?: Record<string, any>, options?: object)`
+Finds items with relations based on the provided path and search criteria.
+
+- **Parameters:**
+  - `path` (`string`): Path in format 'dbName.collectionName'.
+  - `search` (`object | Function`): The search query or function to execute.
+  - `relations` (`Record<string, any>`, optional): Relations configuration for resolving related data.
+  - `options` (`object`, optional): Additional search options.
+- **Returns:**
+  - `Promise<Array<object>>`: A promise that resolves with an array of items, each containing resolved relations.
+
+### Method: `async findOne(path: string, search: object | Function, relations?: Record<string, any>)`
+Finds one item with relations based on the provided path and search criteria.
+
+- **Parameters:**
+  - `path` (`string`): Path in format 'dbName.collectionName'.
+  - `search` (`object | Function`): The search query or function to execute.
+  - `relations` (`Record<string, any>`, optional): Relations configuration for resolving related data.
+- **Returns:**
+  - `Promise<object | null>`: A promise that resolves with the found item containing resolved relations or `null` if no match is found.
+
+### Method: `private _processItemRelations(item: object, relations: Record<string, any>)`
+Processes relations for a single item.
+
+- **Parameters:**
+  - `item` (`object`): The item to process relations for.
+  - `relations` (`Record<string, any>`): Relations configuration.
+- **Returns:**
+  - `Promise<object>`: A promise that resolves with the processed item containing resolved relations.
+
+### Private Method: `_resolvePath(path: string)`
+Resolves the relation path in the format 'dbName.collectionName'.
+
+- **Parameters:**
+  - `path` (`string`): The path to resolve, supporting escaped dots (`\.`).
+- **Returns:**
+  - `{ db: Database; collection: string }`: An object containing the resolved database and collection names.
+- **Throws:**
+  - `Error`: If the database does not exist or if the path format is invalid.

package/docs/search_opts.md

@@ -0,0 +1,227 @@
+# Predefined Search Options Quick Reference
+
+## Operators
+
+### Logical Operators
+
+#### $and
+Checks if all conditions in an array are true.
+```javascript
+{
+  $and: [
+    { $gt: { age: 20 } },
+    { $exists: { name: true } }
+  ]
+}
+```
+
+#### $or
+Checks if at least one condition in an array is true.
+```javascript
+{
+  $or: [
+    { $lt: { age: 20 } },
+    { $gt: { age: 60 } }
+  ]
+}
+```
+
+#### $not
+Negates a condition.
+```javascript
+{
+  $not: { $type: { age: "string" } }
+}
+```
+
+### Comparison Operators
+
+#### $gt
+Greater than comparison.
+```javascript
+{ $gt: { age: 18 } }
+```
+
+#### $lt
+Less than comparison.
+```javascript
+{ $lt: { score: 100 } }
+```
+
+#### $gte
+Greater than or equal comparison.
+```javascript
+{ $gte: { price: 9.99 } }
+```
+
+#### $lte
+Less than or equal comparison.
+```javascript
+{ $lte: { quantity: 50 } }
+```
+
+#### $in
+Checks if value is in an array.
+```javascript
+{ $in: { status: ["active", "pending"] } }
+```
+
+#### $nin
+Checks if value is not in an array.
+```javascript
+{ $nin: { category: ["archived", "deleted"] } }
+```
+
+#### $between
+Checks if a number is between two values (inclusive).
+```javascript
+{ $between: { age: [18, 65] } }
+```
+
+### Type and Existence Operators
+
+#### $exists
+Checks if a field exists (or doesn't exist).
+```javascript
+{ $exists: { email: true, deletedAt: false } }
+```
+
+#### $type
+Checks the type of a field.
+```javascript
+{ $type: { age: "number", name: "string" } }
+```
+
+### Array Operators
+
+#### $arrinc
+Checks if an array includes at least one of the specified values.
+```javascript
+{ $arrinc: { tags: ["developer", "designer"] } }
+```
+
+#### $arrincall
+Checks if an array includes all of the specified values.
+```javascript
+{ $arrincall: { permissions: ["read", "write"] } }
+```
+
+#### $size
+Checks the length of an array or string.
+```javascript
+{ $size: { tags: 3 } }
+```
+
+### String Operators
+
+#### $regex
+Tests a string against a regular expression.
+```javascript
+{ $regex: { email: /^[^@]+@[^@]+\.[^@]+$/ } }
+```
+
+#### $startsWith
+Checks if a string starts with a specified value.
+```javascript
+{ $startsWith: { name: "Dr." } }
+```
+
+#### $endsWith
+Checks if a string ends with a specified value.
+```javascript
+{ $endsWith: { email: "@example.com" } }
+```
+
+### Other Operators
+
+#### $subset
+Allows for skipping advanced validation for specific fields, applying only basic validation. This is useful when validation data may conflict with predefined functions (starting with $), while user data might also contain similar keys. Use this operator as a compromise.
+```javascript
+{ $subset: { $lt: "John Doe" } } // chcek if "$lt" is "John Doe"
+```
+
+## Examples
+
+### Complex Validation
+
+```javascript
+const criteria = {
+  $and: [
+    {
+      $or: [
+        { $gt: { age: 18 } },
+        { $exists: { guardianConsent: true } }
+      ]
+    },
+    {
+      $type: { email: "string" },
+      $regex: { email: /^[^@]+@[^@]+\.[^@]+$/ }
+    },
+    {
+      $arrincall: { roles: ["user"] },
+      $not: { $in: { status: ["banned", "suspended"] } }
+    }
+  ]
+};
+
+const user = {
+  age: 16,
+  guardianConsent: true,
+  email: "john@example.com",
+  roles: ["user", "premium"],
+  status: "active"
+};
+
+const isValid = hasFieldsAdvanced(user, criteria); // true
+```
+
+### Nested Conditions
+
+```javascript
+const criteria = {
+  $and: [
+    {
+      $exists: { address: true },
+      $type: { address: "object" }
+    },
+    {
+      $or: [
+        { $exists: { "address.zipCode": true } },
+        {
+          $and: [
+            { $exists: { "address.city": true } },
+            { $exists: { "address.country": true } }
+          ]
+        }
+      ]
+    }
+  ]
+};
+
+const user = {
+  address: {
+    city: "New York",
+    country: "USA"
+  }
+};
+
+const isValid = hasFieldsAdvanced(user, criteria); // true
+```
+
+## Error Handling
+
+The function will throw an error if:
+- The `fields` parameter is not an object
+- The `fields` parameter is null
+
+Always wrap the function call in a try-catch block when using with untrusted input:
+
+```javascript
+try {
+  const isValid = hasFieldsAdvanced(obj, criteria);
+  // Handle result
+} catch (error) {
+  // Handle error
+  console.error('Validation error:', error.message);
+}
+```

package/file/find.js

@@ -1,7 +1,8 @@
 import { existsSync, promises } from "fs";
 import { pathRepair, createRL } from "./utils.js";
 import { parse } from "../format.js";
-import { hasFieldsAdvanced, updateFindObject } from "../more.js";
+import hasFieldsAdvanced from "../utils/hasFieldsAdvanced.js";
+import updateFindObject from "../utils/updateFindObject.js";
 
 /**
  * Processes a line of text from a file and checks if it matches the search criteria.

package/file/remove.js

@@ -1,7 +1,7 @@
-import { existsSync, promises, appendFileSync, readdirSync } from "fs";
+import { existsSync, promises, appendFileSync, readdirSync, cp } from "fs";
 import { pathRepair, createRL } from "./utils.js";
 import { parse } from "../format.js";
-import { hasFieldsAdvanced } from "../more.js";
+import hasFieldsAdvanced from "../utils/hasFieldsAdvanced.js";
 
 /**
  * Removes entries from a file based on search criteria.
@@ -53,19 +53,18 @@ async function removeWorker(file, search, context={}, one=false){
 /**
  * Asynchronously removes entries from a file based on search criteria.
  * @function
- * @param {string} folder - The folder containing the file.
- * @param {string} name - The name of the file to remove entries from.
+ * @param {string} cpath - Path to the collection.
  * @param {function|Object} arg - The search criteria. It can be a function or an object.
  * @param {Object} context - The context object (for functions).
  * @param {boolean} one - Indicates whether to remove only one matching entry (default: false).
  * @returns {Promise<boolean>} A Promise that resolves to `true` if entries were removed, or `false` otherwise.
  */
-async function remove(folder, name, arg, context={}, one){
-    let files = readdirSync(folder + "/" + name).filter(file => !/\.tmp$/.test(file));
+async function remove(cpath, arg, context={}, one){
+    let files = readdirSync(cpath).filter(file => !/\.tmp$/.test(file));
     files.reverse();
     let remove = false;
     for(const file of files){
-        const removed = await removeWorker(folder + "/" + name + "/" + file, arg, context, one);
+        const removed = await removeWorker(cpath + file, arg, context, one);
         if(one && removed) break;
         remove = remove || removed;
     }

package/file/update.js

@@ -1,7 +1,8 @@
 import { existsSync, promises, appendFileSync, readdirSync } from "fs";
 import { pathRepair, createRL } from "./utils.js";
 import { parse, stringify } from "../format.js";
-import { hasFieldsAdvanced, updateObject } from "../more.js";
+import hasFieldsAdvanced from "../utils/hasFieldsAdvanced.js";
+import updateObject from "../utils/updateObject.js";
 
 /**
  * Updates a file based on search criteria and an updater function or object.
@@ -60,20 +61,19 @@ async function updateWorker(file, search, updater, context={}, one=false){
 /**
  * Asynchronously updates entries in a file based on search criteria and an updater function or object.
  * @function
- * @param {string} folder - The folder containing the file.
- * @param {string} name - The name of the file to update.
+ * @param {string} cpath - Path to the collection.
  * @param {function|Object} arg - The search criteria. It can be a function or an object.
  * @param {function|Object} obj - The updater function or object.
  * @param {Object} context - The context object (for functions).
  * @param {boolean} one - Indicates whether to update only one matching entry (default: false).
  * @returns {Promise<boolean>} A Promise that resolves to `true` if entries were updated, or `false` otherwise.
  */
-async function update(folder, name, arg, obj, context={}, one){
-    let files = readdirSync(folder + "/" + name).filter(file => !/\.tmp$/.test(file));
+async function update(cpath, arg, obj, context={}, one){
+    let files = readdirSync(cpath).filter(file => !/\.tmp$/.test(file));
     files.reverse();
     let update = false;
     for(const file of files){
-        const updated = await updateWorker(folder + "/" + name + "/" + file, arg, obj, context, one);
+        const updated = await updateWorker(cpath + file, arg, obj, context, one);
         if(one && updated) return true;
         update = update || updated;
     }

package/gen.d.ts

@@ -0,0 +1 @@
+export default function genId(parts: number | number[], fill?: number): string;

package/graph.d.ts

@@ -0,0 +1,27 @@
+import DataBase from "./database.js";
+
+declare class Graph {
+    db: DataBase;
+
+    constructor(databaseFolder: string);
+
+    add(collection: string, nodeA: string, nodeB: string): Promise<object>;
+
+    remove(collection: string, nodeA: string, nodeB: string): Promise<boolean>;
+
+    find(collection: string, node: string): Promise<object[]>;
+
+    findOne(collection: string, nodeA: string, nodeB: string): Promise<object | null>;
+
+    getAll(collection: string): Promise<object[]>;
+
+    getCollections(): Promise<string[]>;
+
+    checkCollection(collection: string): Promise<void>;
+
+    issetCollection(collection: string): Promise<boolean>;
+
+    removeCollection(collection: string): void;
+}
+
+export default Graph;

package/graph.js

@@ -112,7 +112,7 @@ class Graph{
      * @param {string} collection - The collection to check.
      */
     async checkCollection(collection){
-        await this.dbAction.checkCollection(collection);
+        await this.db.checkCollection(collection);
     }
 
     /**
@@ -123,7 +123,17 @@ class Graph{
      * @returns {boolean} True if the collection exists, false otherwise.
      */
     async issetCollection(collection){
-        return await this.dbAction.issetCollection(collection);
+        return await this.db.issetCollection(collection);
+    }
+
+    /**
+     * Removes a database collection from the file system.
+     *
+     * @param {string} collection - The name of the collection to remove.
+     * @return {void}
+     */
+    removeCollection(collection){
+         this.db.removeCollection(collection);
     }
 }
 

package/index.d.ts

@@ -0,0 +1,7 @@
+import DataBase from "./database.js";
+import Graph from "./graph.js";
+import DataBaseRemote from "./remote/client/database.js";
+import GraphRemote from "./remote/client/graph.js";
+import genId from "./gen.js";
+
+export { DataBase, Graph, DataBaseRemote, GraphRemote, genId };