@wxn0brp/db 0.0.1

package/CollectionManager.js

@@ -0,0 +1,119 @@
+class CollectionManager{
+    constructor(db, collection){
+        this.db = db;
+        this.collection = collection;
+    }
+
+    /**
+     * Add data to a database.
+     *
+     * @async
+     * @function
+     * @param {Object} data - The data to add.
+     * @param {boolean} id_gen - Whether to generate an ID for the entry. Default is true.
+     * @returns {Promise<Object>} A Promise that resolves with the added data.
+     */
+    async add(data, id_gen=true){
+        return await this.db.add(this.collection, data, id_gen);
+    }
+
+    /**
+     * Find data in a database.
+     *
+     * @async
+     * @function
+     * @param {function|Object} search - The query. It can be an object or a function.
+     * @param {Object} context - The context object (for functions).
+     * @param {Object} options - The options for the search.
+     * @param {number} options.max - The maximum number of entries to return. Default is -1, meaning no limit.
+     * @param {boolean} options.reverse - Whether to reverse the order of returned entries. Default is false.
+     * @returns {Promise<Array<Object>>} A Promise that resolves with the matching data.
+     */
+    async find(search, context={}, options={}){
+        return await this.db.find(this.collection, search, context, options);
+    }
+
+    /**
+     * Find one data entry in a database.
+     *
+     * @async
+     * @function
+     * @param {function|Object} search - The query. It can be an object or a function.
+     * @param {Object} context - The context object (for functions).
+     * @returns {Promise<Object|null>} A Promise that resolves with the first matching data entry.
+     */
+    async findOne(search, context={}){
+        return await this.db.findOne(this.collection, search, context);
+    }
+
+    /**
+     * Update data in a database.
+     *
+     * @async
+     * @function
+     * @param {function|Object} search - The query. It can be an object or a function.
+     * @param {function|Object} arg - Update arguments.
+     * @param {Object} context - The context object (for functions).
+     * @returns {Promise<boolean>} A Promise that resolves when the data is updated.
+     */
+    async update(search, arg, context={}){
+        return await this.db.update(this.collection, search, arg, context);
+    }
+
+    /**
+     * Update one data entry in a database.
+     *
+     * @async
+     * @function
+     * @param {function|Object} search - The query. It can be an object or a function.
+     * @param {function|Object} arg - The query.
+     * @param {Object} context - The context object (for functions).
+     * @returns {Promise<boolean>} A Promise that resolves when the data entry is updated.
+     */
+    async updateOne(search, arg, context={}){
+        return await this.db.updateOne(this.collection, search, arg, context);
+    }
+
+    /**
+     * Remove data from a database.
+     *
+     * @async
+     * @function
+     * @param {function|Object} search - The query. It can be an object or a function.
+     * @param {Object} context - The context object (for functions).
+     * @returns {Promise<boolean>} A Promise that resolves when the data is removed.
+     */
+
+    async remove(search, context={}){
+        return await this.db.remove(this.collection, search, context);
+    }
+
+    /**
+     * Remove one data entry from a database.
+     *
+     * @async
+     * @function
+     * @param {function|Object} search - The query. It can be an object or a function.
+     * @param {Object} context - The context object (for functions).
+     * @returns {Promise<boolean>} A Promise that resolves when the data entry is removed.
+     */
+    async removeOne(search, context={}){
+        return await this.db.removeOne(this.collection, search, context);
+    }
+
+    /**
+     * Asynchronously updates one entry in a database or adds a new one if it doesn't exist.
+     *
+     * @param {function|Object} search - The query. It can be an object or a function.
+     * @param {function|Object} arg - The search criteria for the update.
+     * @param {function|Object} add_arg - The arguments to be added to the new entry.
+     * @param {Object} context - The context object (for functions).
+     * @param {boolean} id_gen - Whether to generate an ID for the entry. Default is true.
+     * @return {Promise<boolean>} A Promise that resolves to `true` if the entry was updated, or `false` if it was added.
+     */
+    async updateOneOrAdd(search, arg, add_arg={}, context={}, id_gen=true){
+        return await this.db.updateOneOrAdd(this.collection, search, arg, add_arg, context, id_gen);
+    }
+}
+
+export default CollectionManager;

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 wxn0brP
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,194 @@
+# DataBase Class
+
+The `DataBase` class simplifies managing data with a file-based database, providing an easy way to perform CRUD operations, caching, and custom queries.
+
+## Installation
+
+Ensure you have Node.js installed. To install the `DataBase` package, run:
+
+```bash
+npm install @wxn0brp/database
+```
+
+## Usage Example
+
+```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
+
+```javascript
+// Updates the age of all users named 'Alice' to 31
+await db.update('users', { name: 'Alice' }, { age: 31 });
+```
+
+#### 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();
+```
+
+## License
+
+This project is licensed under the [MIT License](https://opensource.org/licenses/MIT). See the [LICENSE](./LICENSE) file for details.

package/action.js

@@ -0,0 +1,250 @@
+import { existsSync, mkdirSync, readdirSync, appendFileSync, rmSync, writeFileSync, statSync } from "fs";
+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
+ */
+class dbActionC{
+    /**
+     * Creates a new instance of dbActionC.
+     * @constructor
+     * @param {string} folder - The folder where database files are stored.
+     * @param {object} options - The options object.
+     */
+    constructor(folder, options){
+        this.folder = folder;
+        // this.cacheManager = new CacheManager(options.cacheThreshold, options.cacheTTL);
+        
+        if(!existsSync(folder)) mkdirSync(folder, { recursive: true });
+    }
+
+    /**
+     * Get a list of available databases in the specified folder.
+     * @returns {string[]} An array of database names.
+     */
+    getCollections(){
+        const collections = readdirSync(this.folder, { recursive: true, withFileTypes: true })
+            .filter(dirent => dirent.isDirectory())
+            .map(dirent => {
+                if(dirent.parentPath === this.folder) return dirent.name;
+                return dirent.parentPath.replace(this.folder + "/", "") + "/" + dirent.name
+            });
+
+        return collections;
+    }
+
+    /**
+     * Check and create the specified collection if it doesn't exist.
+     * @function
+     * @param {string} collection - The collection to check.
+     */
+    checkCollection(collection){
+        const path = this.folder + "/" + collection;
+        if(!existsSync(path)) mkdirSync(path, { recursive: true });
+    }
+
+    /**
+     * Check if a collection exists.
+     * @function
+     * @param {string} collection - The name of the collection.
+     * @returns {boolean} True if the collection exists, false otherwise.
+     */
+    issetCollection(collection){
+        const path = this.folder + "/" + collection;
+        return existsSync(path);
+    }
+
+    /**
+     * Add a new entry to the specified database.
+     * @async
+     * @param {string} collection - The name of the collection.
+     * @param {Object} arg - The data to be added to the database.
+     * @param {boolean} id_gen - Whether to generate an ID for the entry. Default is true.
+     * @returns {Promise<Object>} A Promise that resolves to the added data.
+     */
+    async add(collection, arg, id_gen=true){
+        await this.checkCollection(collection);
+        const file = this.folder + "/" + collection + "/" + getLastFile(this.folder + "/" + collection);
+
+        if(id_gen) arg._id = arg._id || gen();
+        const data = stringify(arg);
+        appendFileSync(file, data+"\n");
+        return arg;
+    }
+
+    /**
+     * Find entries in the specified database based on search criteria.
+     * @async
+     * @param {string} collection - The name of 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 {Object} options - The options for the search.
+     * @param {number} options.max - The maximum number of entries to return. Default is -1, meaning no limit.
+     * @param {boolean} options.reverse - Whether to reverse the order of returned entries. Default is false.
+     * @param {Object} findOpts - Update result object with findOpts options.
+     * @returns {Promise<Object[]>} A Promise that resolves to an array of matching entries.
+     */
+    async find(collection, arg, context={}, options={}, findOpts={}){
+        options.reverse = options.reverse || false;
+        options.max = options.max || -1;
+
+        await this.checkCollection(collection);
+        const files = getSortedFiles(this.folder + "/" + collection).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);
+            if(options.reverse) data.reverse();
+
+            if(options.max !== -1){
+                if(totalEntries + data.length > options.max){
+                    let remainingEntries = options.max - totalEntries;
+                    data = data.slice(0, remainingEntries);
+                    totalEntries = options.max;
+                }else{
+                    totalEntries += data.length;
+                }
+            }
+
+            datas = datas.concat(data);
+
+            if(options.max !== -1 && totalEntries >= options.max) break;
+        }
+        return datas;
+    }
+
+    /**
+     * Find the first matching entry in the specified database based on search criteria.
+     * @async
+     * @param {string} collection - Name of the database 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 {Object} findOpts - Update result object with findOpts options.
+     * @returns {Promise<Object|null>} A Promise that resolves to the first matching entry or null if not found.
+     */
+    async findOne(collection, arg, context={}, findOpts={}){
+        await this.checkCollection(collection);
+        const files = getSortedFiles(this.folder + "/" + collection).map(f => f.f);
+        files.reverse();
+
+        for(let f of files){
+            let data = await _findOne(this.folder + "/" + collection + "/" + f, arg, context, findOpts);
+            if(data){
+                return data;
+            }
+        }
+        return null;
+    }
+
+    /**
+     * Update entries in the specified database based on search criteria and an updater function or object.
+     * @async
+     * @param {string} collection - Name of the database 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).
+     * @returns {Promise<boolean>} A Promise that resolves to `true` if entries were updated, or `false` otherwise.
+     */
+    async update(collection, arg, obj, context={}){
+        await this.checkCollection(collection);
+        return await _update(this.folder, collection, arg, obj, context);
+    }
+
+    /**
+     * Update the first matching entry in the specified database based on search criteria and an updater function or object.
+     * @async
+     * @param {string} collection - Name of the database 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).
+     * @returns {Promise<boolean>} A Promise that resolves to `true` if one entry was updated, or `false` otherwise.
+     */
+    async updateOne(collection, arg, obj, context={}){
+        await this.checkCollection(collection);
+        return await _update(this.folder, collection, arg, obj, context, true);
+    }
+
+    /**
+     * Remove entries from the specified database based on search criteria.
+     * @async
+     * @param {string} collection - Name of the database collection.
+     * @param {function|Object} arg - The search criteria. It can be a function or an object.
+     * @param {Object} context - The context object (for functions).
+     * @returns {Promise<boolean>} A Promise that resolves to `true` if entries were removed, or `false` otherwise.
+     */
+    async remove(collection, arg, context={}){
+        await this.checkCollection(collection);
+        return await _remove(this.folder, collection, arg, context);
+    }
+
+    /**
+     * Remove the first matching entry from the specified database based on search criteria.
+     * @async
+     * @param {string} collection - Name of the database collection.
+     * @param {function|Object} arg - The search criteria. It can be a function or an object.
+     * @param {Object} context - The context object (for functions).
+     * @returns {Promise<boolean>} A Promise that resolves to `true` if one entry was removed, or `false` otherwise.
+     */
+    async removeOne(collection, arg, context={}){
+        await this.checkCollection(collection);
+        return await _remove(this.folder, collection, arg, context, true);
+    }
+
+    /**
+     * Removes a database collection from the file system.
+     *
+     * @param {string} collection - The name of the collection to remove.
+     * @return {void}
+     */
+    removeDb(collection){
+        rmSync(this.folder + "/" + collection, { recursive: true, force: true });
+    }
+}
+
+/**
+ * Get the last file in the specified directory.
+ * @param {string} path - The directory path.
+ * @returns {string} The name of the last file in the directory.
+ */
+function getLastFile(path){
+    if(!existsSync(path)) mkdirSync(path, { recursive: true });
+    const files = getSortedFiles(path);
+
+    if(files.length == 0){
+        writeFileSync(path+"/1.db", "");
+        return "1.db";
+    }
+
+    const last = files[files.length-1];
+    const info = path + "/" + last.f;
+
+    if(statSync(info).size < maxFileSize) return last.f;
+    
+    const num = last.i + 1;
+    writeFileSync(path + "/" + num + ".db", "");
+    return num+".db";
+}
+
+/**
+ * Get all files in a directory sorted by name.
+ * @param {string} path - The path to the directory.
+ * @return {string[]} An array of file names sorted by name.
+ */
+function getSortedFiles(path){
+    let files = readdirSync(path).filter(file => file.endsWith(".db"));
+    if(files.length == 0) return [];
+    files = files.map(file => parseInt(file.replace(".db", "")))
+    files = files.sort();
+    files = files.map(file => { return { i: file, f: file+".db" } });
+    return files;
+}
+
+export default dbActionC;

package/cacheManager.js

@@ -0,0 +1,83 @@
+/**
+ * A cache manager for storing and managing cached data.
+ * @class
+ */
+class CacheManager{
+    /**
+     * Create a new cache manager instance.
+     * @constructor
+     * @param {number} cacheThreshold - The threshold for caching query results.
+     * @param {number} ttl - The time-to-live (TTL) for cached data in milliseconds.
+     */
+    constructor(cacheThreshold, ttl){
+        this.queryCounterCache = {};
+        this.dataCache = {};
+        this.cacheThreshold = cacheThreshold;
+        this.ttl = ttl;
+    }
+
+    /**
+     * Increment the query counter for a specific cache key.
+     * @private
+     * @param {string} key - The cache key.
+     * @returns {number} The updated query count for the cache key.
+     */
+    _incrementQueryCounter(key){
+        if(!this.queryCounterCache[key]){
+            this.queryCounterCache[key] = 1;
+        }else{
+            this.queryCounterCache[key]++;
+        }
+        return this.queryCounterCache[key];
+    }
+
+    /**
+     * Set data in the cache for a specific cache key.
+     * @private
+     * @param {string} key - The cache key.
+     * @param {*} data - The data to be cached.
+     */
+    _setCache(key, data){
+        this.dataCache[key] = { data, expires: Date.now() + this.ttl };
+    }
+
+    /**
+     * Get data from the cache for a specific cache key if it is not expired.
+     * @param {string} key - The cache key.
+     * @returns {*} The cached data if not expired, otherwise null.
+     */
+    getFromCache(key){
+        const item = this.dataCache[key];
+        if(item && Date.now() < item.expires){
+            return item.data;
+        }
+        delete this.dataCache[key];
+        return null;
+    }
+
+    /**
+     * Add data to the cache if the query count exceeds the cache threshold.
+     * @param {string} key - The cache key.
+     * @param {*} data - The data to be cached.
+     */
+    addToCacheIfNeeded(key, data){
+        const queryCount = this._incrementQueryCounter(key);
+        if(queryCount > this.cacheThreshold){
+            this._setCache(key, data);
+        }
+    }
+
+    /**
+     * Invalidate cache entries matching a specific key pattern.
+     * @param {string} keyPattern - The key pattern to match and invalidate cache entries.
+     */
+    invalidateCache(keyPattern){
+        Object.keys(this.dataCache).forEach(key => {
+            if(key.startsWith(keyPattern)){
+                delete this.dataCache[key];
+            }
+        });
+    }
+}
+
+export default CacheManager;