@wxn0brp/db 0.0.1 → 0.0.4

package/README.md

@@ -1,194 +1,30 @@
-# DataBase Class
+# @wxn0brp/db
 
-The `DataBase` class simplifies managing data with a file-based database, providing an easy way to perform CRUD operations, caching, and custom queries.
+A lightweight file-based database management system that supports CRUD operations, custom queries, and graph structures.
 
 ## Installation
 
-Ensure you have Node.js installed. To install the `DataBase` package, run:
+To install the package, run:
 
 ```bash
-npm install @wxn0brp/database
+npm install @wxn0brp/db
 ```
 
-## Usage Example
+## Usage
 
-```javascript
-import DataBase from '@wxn0brp/database/database.js';
-
-async function main(){
-    // Initialize the database with a folder path and optional cache settings
-    const db = new DataBase('./data');
-
-    // Create or check a collection
-    await db.checkCollection('users');
-
-    // Add a new user to the collection
-    await db.add('users', { name: 'Alice', age: 30 });
-
-    // Find users based on search criteria
-    const users = await db.find('users', { age: 30 });
-    console.log(users);
-
-    // Update a user's data
-    await db.update('users', { name: 'Alice' }, { age: 31 });
-
-    // Remove a user
-    await db.remove('users', { name: 'Alice' });
-}
-
-main().catch(console.error);
-
-```
-
-## Methods Overview
-
-| Method Name | Description | Parameters | Returns |
-| ----------- | ----------- | ---------- | ------- | 
-| `getCollections` | Retrieves the names of all available collections. | None | `string[]` |
-| `checkCollection` | Ensures that a collection exists, creating it if necessary. | `collection` (string): Name of the collection | `Promise<void>` |
-| `issetCollection` | Checks if a collection exists. | `collection` (string): Name of the collection | `Promise<boolean>` |
-| `add` | Adds data to a collection, optionally generating an ID. | `collection` (string), `data` (Object), `id_gen` (boolean) | `Promise<Object>` |
-| `find` | Finds data entries matching a query. | `collection` (string), `search` (function/Object), `context` (Object), `options` (Object) - { max, reverse } | `Promise<Array<Object>>` |
-| `findOne` | Finds the first data entry matching a query. | `collection` (string), `search` (function/Object), `context` (Object) | `Promise<Object\|null>` |
-| `update` | Updates data entries matching a query. | `collection` (string), `search` (function/Object), `arg` (function/Object), `context` (Object) | `Promise<boolean>` |
-| `updateOne` | Updates the first data entry matching a query. | `collection` (string), `search` (function/Object), `arg` (function/Object), `context` (Object) | `Promise<boolean>` |
-| `remove` | Removes data entries matching a query. | `collection` (string), `search` (function/Object), `context` (Object) | `Promise<boolean>` |
-| `removeOne` | Removes the first data entry matching a query. | `collection` (string), `search` (function/Object), `context` (Object) | `Promise<boolean>` |
-| `updateOneOrAdd` | Updates one entry or adds a new one if no match is found. | `collection` (string), `search` (function/Object), `arg` (function/Object), `add_arg` (function/Object), `context` (Object), `id_gen` (boolean) | `Promise<boolean>` |
-| `removeDb` | Removes an entire database collection from the file system. | `collection` (string)  | `void` |
-
----
-
-### Querying Data
-
-The `DataBase` class offers flexibility for querying collections using either an object or a function as the `search` parameter in methods like `find`, `findOne`, `update`, and `remove`.
-
-#### Object-Based Queries
-
-You can use the following operators to build your queries:
-
-- **`$or`**: Matches if at least one condition is true.
-
-  ```javascript
-  const result = await db.find('users', {
-      $or: [{ status: 'active' }, { role: 'admin' }]
-  });
-  ```
-
-- **`$not`**: Matches if the condition is false.
-
-  ```javascript
-  const result = await db.find('users', {
-      $not: { status: 'inactive' }
-  });
-  ```
-
-- **`$and`**: Combines multiple conditions, all of which must be true. Useful for complex queries involving other operators.
-
-  ```javascript
-  const result = await db.find('users', {
-      $and: [
-        { age: 25 },
-        { $or: [{ status: 'active' }, { status: 'away' }] }
-      ]
-  });
-  ```
-
-- **`$set`**: Ensures that specified fields are present in the document.
-
-  ```javascript
-  const result = await db.find('users', {
-      $set: { name: true }
-  });
-  ```
-
-#### Search as a Function
-
-Alternatively, you can use a function for more dynamic queries. The function receives each document as an argument and should return `true` for documents that match the criteria.
-
-```javascript
-const results = await db.find('users', obj => obj.age > 30);
-```
-
-This approach is powerful for cases where the query logic is too complex to be represented as an object.
-
-### Update Argument
-
-When updating data, the `update` argument can also be either an object or a function.
-
-#### Update as an Object
-
-If you pass an object as the `update` argument, it will directly set the new values for the specified fields.
-
-##### Example: Update with Object
+You can import the necessary classes from the package as follows:
 
 ```javascript
-// Updates the age of all users named 'Alice' to 31
-await db.update('users', { name: 'Alice' }, { age: 31 });
+import { DataBase, Graph, DataBaseRemote, GraphRemote, Relation, genId } from "@wxn0brp/db";
 ```
 
-#### Update as a Function
-
-If you pass a function, it receives the current object as an argument and should return the updated object. This allows for dynamic updates based on the current state of the object.
-
-##### Example: Update with Function
-
-```javascript
-// Increments the age of all users named 'Alice' by 1
-await db.update('users', { name: 'Alice' }, obj => {
-    obj.age++;
-    return obj;
-});
-```
-
-This method is useful when you need to compute new values based on existing ones.
-
-## Other Features
-
-### Graph.js
-
-The `Graph` class extends the functionality of the `DataBase` class to handle graph-like structures, where relationships (edges) between nodes (vertices) are stored in collections.
-
-#### Methods
-
-- **`add(collection, a, b)`**: Adds an edge between `a` and `b` in the specified collection. The nodes are sorted to ensure consistency in the storage format.
-
-    ```javascript
-    // Adds a friendship between Alice and Bob
-    await graph.add('friends', 'Alice', 'Bob');
-    ```
-
-- **`remove(collection, a, b)`**: Removes the edge between `a` and `b`.
-
-    ```javascript
-    // Removes the friendship between Alice and Bob
-    await graph.remove('friends', 'Alice', 'Bob');
-    ```
-
-- **`find(collection, d)`**: Finds all edges where `d` is one of the nodes.
-
-    ```javascript
-    // Returns all friends of Alice
-    const friends = await graph.find('friends', 'Alice');
-    ```
-
-- **`findOne(collection, d, e)`**: Finds the edge between `d` and `e`.
-
-    ```javascript
-    // Returns the friendship between Alice and Bob, if it exists
-    const relation = await graph.findOne('friends', 'Alice', 'Bob');
-    ```
-
-### Gen.js
-
-The `gen.js` file contains a utility function `genId`, which generates a unique identifier.
-
-#### Example: Generating an ID
-
-```javascript
-const id = genId();
-```
+## Documentation
 
-## License
+For detailed information, refer to the following resources:
 
-This project is licensed under the [MIT License](https://opensource.org/licenses/MIT). See the [LICENSE](./LICENSE) file for details.
+- [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)
+- [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

@@ -0,0 +1,140 @@
+# DataBase Class Documentation
+
+This documentation provides a detailed overview of the `DataBase` class, designed for performing CRUD operations on database collections. The class uses the `dbActionC` module for file-based operations and `executorC` for managing execution tasks.
+
+## Class: `DataBase`
+
+### Constructor: `DataBase(folder, options={})`
+Creates a new instance of the `DataBase` class.
+
+- **Parameters:**
+  - `folder` (`string`): The folder path where the database files are stored.
+  - `options` (`object`): Optional configuration options.
+    - `cacheThreshold` (`number`, default: 3): The threshold for caching entries.
+    - `cacheTTL` (`number`, default: 300000): Time-to-live for cache entries in milliseconds (default: 5 minutes).
+
+### Method: `c(collection)`
+Creates a new instance of the `CollectionManager` class for the specified collection.
+
+- **Parameters:**
+  - `collection` (`string`): The name of the collection.
+- **Returns:**
+  - `CollectionManager`: A new instance of `CollectionManager`.
+
+### Method: `async getCollections()`
+Gets the names of all available collections in the database.
+
+- **Returns:**
+  - `Promise<string[]>`: A promise that resolves with an array of collection names.
+
+### Method: `async checkCollection(collection)`
+Checks and creates the specified collection if it doesn't exist.
+
+- **Parameters:**
+  - `collection` (`string`): The name of the collection to check.
+
+### Method: `async issetCollection(collection)`
+Checks if a collection exists.
+
+- **Parameters:**
+  - `collection` (`string`): The name of the collection.
+- **Returns:**
+  - `Promise<boolean>`: A promise that resolves to `true` if the collection exists, otherwise `false`.
+
+### Method: `async add(collection, data, id_gen=true)`
+Adds data to a specified collection.
+
+- **Parameters:**
+  - `collection` (`string`): The name of the collection.
+  - `data` (`Object`): The data to add.
+  - `id_gen` (`boolean`, default: true): Whether to generate an ID for the entry.
+- **Returns:**
+  - `Promise<Object>`: A promise that resolves with the added data.
+
+### Method: `async find(collection, search, context={}, options={}, findOpts={})`
+Finds data in a collection based on a query.
+
+- **Parameters:**
+  - `collection` (`string`): The name of the collection.
+  - `search` (`function|Object`): The search query.
+  - `context` (`Object`): The context object (for functions).
+  - `options` (`Object`): Search options.
+    - `max` (`number`, default: -1): Maximum number of entries to return.
+    - `reverse` (`boolean`, default: false): Whether to reverse the search results.
+  - `findOpts` (`Object`): Options for updating the search result.
+- **Returns:**
+  - `Promise<Array<Object>>`: A promise that resolves with the matching data.
+
+### Method: `async findOne(collection, search, context={}, findOpts={})`
+Finds one matching entry in a collection.
+
+- **Parameters:**
+  - `collection` (`string`): The name of the collection.
+  - `search` (`function|Object`): The search query.
+  - `context` (`Object`): The context object (for functions).
+  - `findOpts` (`Object`): Options for updating the search result.
+- **Returns:**
+  - `Promise<Object|null>`: A promise that resolves with the found entry, or `null` if no match is found.
+
+### Method: `async update(collection, search, arg, context={})`
+Updates data in a collection.
+
+- **Parameters:**
+  - `collection` (`string`): The name of the collection.
+  - `search` (`function|Object`): The search query.
+  - `arg` (`function|Object`): Update arguments.
+  - `context` (`Object`): The context object (for functions).
+- **Returns:**
+  - `Promise<boolean>`: A promise that resolves when the data is updated.
+
+### Method: `async updateOne(collection, search, arg, context={})`
+Updates one entry in a collection.
+
+- **Parameters:**
+  - `collection` (`string`): The name of the collection.
+  - `search` (`function|Object`): The search query.
+  - `arg` (`function|Object`): Update arguments.
+  - `context` (`Object`): The context object (for functions).
+- **Returns:**
+  - `Promise<boolean>`: A promise that resolves when the data is updated.
+
+### Method: `async updateOneOrAdd(collection, search, arg, add_arg={}, context={}, id_gen=true)`
+Updates one entry or adds a new one if it doesn't exist.
+
+- **Parameters:**
+  - `collection` (`string`): The name of the collection.
+  - `search` (`function|Object`): The search query.
+  - `arg` (`function|Object`): Update arguments.
+  - `add_arg` (`function|Object`): Data to add if no match is found.
+  - `context` (`Object`): The context object (for functions).
+  - `id_gen` (`boolean`, default: true): Whether to generate an ID for the new entry.
+- **Returns:**
+  - `Promise<boolean>`: A promise that resolves to `true` if the entry was updated, otherwise `false`.
+
+### Method: `async remove(collection, search, context={})`
+Removes data from a collection.
+
+- **Parameters:**
+  - `collection` (`string`): The name of the collection.
+  - `search` (`function|Object`): The search query.
+  - `context` (`Object`): The context object (for functions).
+- **Returns:**
+  - `Promise<boolean>`: A promise that resolves when the data is removed.
+
+### Method: `async removeOne(collection, search, context={})`
+Removes one entry from a collection.
+
+- **Parameters:**
+  - `collection` (`string`): The name of the collection.
+  - `search` (`function|Object`): The search query.
+  - `context` (`Object`): The context object (for functions).
+- **Returns:**
+  - `Promise<boolean>`: A promise that resolves when the entry is removed.
+
+### 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/graph.md

@@ -0,0 +1,86 @@
+# Graph Database Documentation
+
+This documentation provides an overview of the `Graph` class, which represents a graph database built on top of a custom `DataBase` module. The `Graph` class allows for managing graph structures by adding, removing, and querying edges between nodes in the database.
+
+## Class: `Graph`
+
+### Constructor: `Graph(databaseFolder)`
+Initializes the graph database.
+
+- **Parameters:**
+  - `databaseFolder` (`string`): The folder where the database is stored.
+
+### Method: `async add(collection, nodeA, nodeB)`
+Adds an edge between two nodes in the specified collection.
+
+- **Parameters:**
+  - `collection` (`string`): The name of the collection.
+  - `nodeA` (`string`): The first node.
+  - `nodeB` (`string`): The second node.
+- **Returns:**
+  - `Promise<Object>`: A promise that resolves with the added edge.
+
+### Method: `async remove(collection, nodeA, nodeB)`
+Removes an edge between two nodes in the specified collection.
+
+- **Parameters:**
+  - `collection` (`string`): The name of the collection.
+  - `nodeA` (`string`): The first node.
+  - `nodeB` (`string`): The second node.
+- **Returns:**
+  - `Promise<boolean>`: A promise that resolves to `true` if the edge is removed, otherwise `false`.
+
+### Method: `async find(collection, node)`
+Finds all edges with either node equal to the specified `node`.
+
+- **Parameters:**
+  - `collection` (`string`): The name of the collection.
+  - `node` (`string`): The node to search for.
+- **Returns:**
+  - `Promise<Object[]>`: A promise that resolves with an array of edges.
+
+### Method: `async findOne(collection, nodeA, nodeB)`
+Finds one edge with either `nodeA` or `nodeB` as nodes.
+
+- **Parameters:**
+  - `collection` (`string`): The name of the collection.
+  - `nodeA` (`string`): The first node.
+  - `nodeB` (`string`): The second node.
+- **Returns:**
+  - `Promise<Object|null>`: A promise that resolves with the found edge or `null` if no edge is found.
+
+### Method: `async getAll(collection)`
+Gets all edges in the specified collection.
+
+- **Parameters:**
+  - `collection` (`string`): The name of the collection.
+- **Returns:**
+  - `Promise<Object[]>`: A promise that resolves with all edges in the collection.
+
+### Method: `async getCollections()`
+Returns the names of all available collections in the database.
+
+- **Returns:**
+  - `Promise<string[]>`: A promise that resolves with an array of collection names.
+
+### Method: `async checkCollection(collection)`
+Checks and creates the specified collection if it doesn't exist.
+
+- **Parameters:**
+  - `collection` (`string`): The name of the collection.
+
+### Method: `async issetCollection(collection)`
+Checks if the specified collection exists.
+
+- **Parameters:**
+  - `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`