@wxn0brp/db 0.0.1

package/database.js

@@ -0,0 +1,208 @@
+import dbActionC from "./action.js";
+import executorC from "./executor.js";
+import CollectionManager from "./CollectionManager.js";
+
+/**
+ * Represents a database management class for performing CRUD operations.
+ * @class
+ */
+class DataBase{
+    /**
+     * Create a new database instance.
+     * @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).
+     */
+    constructor(folder, options={}){
+        options = {
+            cacheThreshold: 3,
+            cacheTTL: 300_000,
+            ...options
+        }
+        this.dbAction = new dbActionC(folder, options);
+        this.executor = new executorC();
+    }
+
+    /**
+     * Create a new instance of a CollectionManager class.
+     * @function
+     * @param {string} collection - The name of the collection.
+     * @returns {CollectionManager} A new instance of CollectionManager.
+     */
+    c(collection){
+        return new CollectionManager(this, collection);
+    }
+
+    /**
+     * Get the names of all available databases.
+     *
+     * @function
+     * @returns {string[]} An array of database names.
+     */
+    async getCollections(){
+        return await this.dbAction.getCollections();
+    }
+
+    /**
+     * Check and create the specified collection if it doesn't exist.
+     *
+     * @function
+     * @param {string} collection - The collection to check.
+     */
+    async checkCollection(collection){
+        await this.dbAction.checkCollection(collection);
+    }
+
+    /**
+     * Check if a collection exists.
+     *
+     * @function
+     * @param {string} collection - The name of the collection.
+     * @returns {boolean} True if the collection exists, false otherwise.
+     */
+    async issetCollection(collection){
+        return await this.dbAction.issetCollection(collection);
+    }
+
+    /**
+     * Add data to a database.
+     *
+     * @async
+     * @function
+     * @param {string} collection - The name of the collection.
+     * @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(collection, data, id_gen=true){
+        return await this.executor.addOp(this.dbAction.add.bind(this.dbAction), collection, data, id_gen);
+    }
+
+    /**
+     * Find data in a database.
+     *
+     * @async
+     * @function
+     * @param {string} collection - Name of the database collection.
+     * @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.
+     * @param {Object} findOpts - Update result object with findOpts options.
+     * @returns {Promise<Array<Object>>} A Promise that resolves with the matching data.
+     */
+    async find(collection, search, context={}, options={}, findOpts={}){
+        return await this.executor.addOp(this.dbAction.find.bind(this.dbAction), collection, search, context, options, findOpts);
+    }
+
+    /**
+     * Find one data entry in a database.
+     *
+     * @async
+     * @function
+     * @param {string} collection - Name of the database collection.
+     * @param {function|Object} search - The query. It can be an object or a function.
+     * @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 with the first matching data entry.
+     */
+    async findOne(collection, search, context={}, findOpts={}){
+        return await this.executor.addOp(this.dbAction.findOne.bind(this.dbAction), collection, search, context, findOpts);
+    }
+
+    /**
+     * Update data in a database.
+     *
+     * @async
+     * @function
+     * @param {string} collection - Name of the database collection.
+     * @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(collection, search, arg, context={}){
+        return await this.executor.addOp(this.dbAction.update.bind(this.dbAction), collection, search, arg, context);
+    }
+
+    /**
+     * Update one data entry in a database.
+     *
+     * @async
+     * @function
+     * @param {string} collection - Name of the database collection.
+     * @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(collection, search, arg, context={}){
+        return await this.executor.addOp(this.dbAction.updateOne.bind(this.dbAction), collection, search, arg, context);
+    }
+
+    /**
+     * Remove data from a database.
+     *
+     * @async
+     * @function
+     * @param {string} collection - Name of the database collection.
+     * @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(collection, search, context={}){
+        return await this.executor.addOp(this.dbAction.remove.bind(this.dbAction), collection, search, context);
+    }
+
+    /**
+     * Remove one data entry from a database.
+     *
+     * @async
+     * @function
+     * @param {string} collection - Name of the database collection.
+     * @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(collection, search, context={}){
+        return await this.executor.addOp(this.dbAction.removeOne.bind(this.dbAction), collection, search, context);
+    }
+
+    /**
+     * Asynchronously updates one entry in a database or adds a new one if it doesn't exist.
+     *
+     * @param {string} collection - Name of the database collection.
+     * @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(collection, search, arg, add_arg={}, context={}, id_gen=true){
+        const res = await this.updateOne(collection, search, arg, context);
+        if(!res){
+            const assignData = [];
+            if(typeof search === "object" && !Array.isArray(search)) assignData.push(search);
+            if(typeof arg === "object" && !Array.isArray(arg)) assignData.push(arg);
+            if(typeof add_arg === "object" && !Array.isArray(add_arg)) assignData.push(add_arg);
+            await this.add(collection, Object.assign({}, ...assignData), id_gen);
+        }
+        return res;
+    }
+
+    /**
+     * Removes a database collection from the file system.
+     *
+     * @param {string} collection - The name of the collection to remove.
+     * @return {void}
+     */
+    removeDb(collection){
+         this.dbAction.removeDb(collection);
+    }
+}
+
+export default DataBase;

package/executor.js

@@ -0,0 +1,54 @@
+/**
+ * A simple executor for queuing and executing asynchronous operations sequentially.
+ * @class
+ */
+class executorC{
+    /**
+     * Create a new executor instance.
+     * @constructor
+     */
+    constructor(){
+        this.quote = [];
+        this.isExecuting = false;
+    }
+
+    /**
+     * Add an asynchronous operation to the execution queue.
+     *
+     * @async
+     * @function
+     * @param {Function} func - The asynchronous function to execute.
+     * @param {...*} param - Parameters to pass to the function.
+     * @returns {Promise} A Promise that resolves when the operation is executed.
+     */
+    async addOp(func, ...param){
+        return await new Promise((resolve, reject) => {
+            this.quote.push({
+                func,
+                param,
+                resolve,
+                reject
+            });
+            this.execute();
+        });
+    }
+
+    /**
+     * Execute the queued asynchronous operations sequentially.
+     *
+     * @async
+     * @function
+     */
+    async execute(){
+        if(this.isExecuting) return;
+        this.isExecuting = true;
+        while(this.quote.length > 0){
+            let q = this.quote.shift();
+            let res = await q.func(...q.param);
+            q.resolve(res)
+        }
+        this.isExecuting = false;
+    }
+}
+
+export default executorC;

package/file/find.js

@@ -0,0 +1,88 @@
+import { existsSync, promises } from "fs";
+import { pathRepair, createRL } from "./utils.js";
+import { parse } from "../format.js";
+import { hasFieldsAdvanced, updateFindObject } from "../more.js";
+
+/**
+ * Processes a line of text from a file and checks if it matches the search criteria.
+ * @private
+ * @param {function|Object} arg - The search criteria. It can be a function or an object.
+ * @param {string} line - The line of text from the file.
+ * @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 matching object or null.
+ */
+async function findProcesLine(arg, line, context={}, findOpts={}){
+    const ob = parse(line);
+    let res = false;
+    
+    if(typeof arg === "function"){
+        if(arg(ob, context)) res = true;
+    }else if(typeof arg === "object" && !Array.isArray(arg)){
+        if(hasFieldsAdvanced(ob, arg)) res = true;
+    }
+
+    if(res) return updateFindObject(ob, findOpts);
+    return null;
+}
+
+/**
+ * Asynchronously finds entries in a file based on search criteria.
+ * @function
+ * @param {string} file - The file path to search in.
+ * @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[]>} A Promise that resolves to an array of matching objects.
+ */
+export async function find(file, arg, context={}, findOpts={}){
+    file = pathRepair(file);
+    return await new Promise(async (resolve) => {
+        if(!existsSync(file)){
+            await promises.writeFile(file, "");
+            resolve(false);
+            return;
+        }
+        const rl = createRL(file);
+        const resF = [];
+        for await(const line of rl){
+            if(line == "" || !line) continue;
+
+            const res = await findProcesLine(arg, line, context, findOpts);
+            if(res) resF.push(res); 
+        };
+        resolve(resF);
+        rl.close();
+    })
+}
+
+/**
+ * Asynchronously finds one entry in a file based on search criteria.
+ * @function
+ * @param {string} file - The file path to search in.
+ * @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>} A Promise that resolves to the first matching object found or an empty array.
+ */
+export async function findOne(file, arg, context={}, findOpts={}){
+    file = pathRepair(file);
+    return await new Promise(async (resolve) => {
+        if(!existsSync(file)){
+            await promises.writeFile(file, "");
+            resolve(false);
+            return;
+        }
+        const rl = createRL(file);
+        for await(const line of rl){
+            if(line == "" || !line) continue;
+
+            const res = await findProcesLine(arg, line, context, findOpts);
+            if(res){
+                resolve(res);
+                rl.close();
+            }
+        };
+        resolve(false);
+    });
+}

package/file/index.js

@@ -0,0 +1,3 @@
+export { default as update } from "./update.js";
+export { default as remove } from "./remove.js";
+export * from "./find.js";

package/file/remove.js

@@ -0,0 +1,75 @@
+import { existsSync, promises, appendFileSync, readdirSync } from "fs";
+import { pathRepair, createRL } from "./utils.js";
+import { parse } from "../format.js";
+import { hasFieldsAdvanced } from "../more.js";
+
+/**
+ * Removes entries from a file based on search criteria.
+ * @private
+ * @param {string} file - The file path to remove entries from.
+ * @param {function|Object} search - The search criteria. It can be a function or an object.
+ * @param {Object} context - The context object (for functions).
+ * @param {boolean} [one=false] - 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 removeWorker(file, search, context={}, one=false){
+    file = pathRepair(file);
+    if(!existsSync(file)){
+        await promises.writeFile(file, "");
+        return false;
+    }
+    await promises.copyFile(file, file+".tmp");
+    await promises.writeFile(file, "");
+
+    const rl = createRL(file+".tmp");
+  
+    let removed = false;
+    for await(let line of rl){
+        if(one && removed){
+            appendFileSync(file, line+"\n");
+            continue;
+        }
+
+        const data = parse(line);
+
+        if(typeof search === "function"){
+            if(search(data, context)){
+                removed = true;
+                continue;
+            }
+        }else if(typeof search === "object" && !Array.isArray(search)){
+            if(hasFieldsAdvanced(data, search)){
+                removed = true;
+                continue;
+            }
+        }
+        
+        appendFileSync(file, line+"\n");
+    }
+    await promises.writeFile(file+".tmp", "");
+    return removed;
+}
+
+/**
+ * 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 {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));
+    files.reverse();
+    let remove = false;
+    for(const file of files){
+        const removed = await removeWorker(folder + "/" + name + "/" + file, arg, context, one);
+        if(one && removed) break;
+        remove = remove || removed;
+    }
+    return remove;
+}
+
+export default remove;

package/file/update.js

@@ -0,0 +1,83 @@
+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";
+
+/**
+ * Updates a file based on search criteria and an updater function or object.
+ * @private
+ * @param {string} file - The file path to update.
+ * @param {function|Object} search - The search criteria. It can be a function or an object.
+ * @param {function|Object} updater - The updater function or object.
+ * @param {Object} context - The context object (for functions).
+ * @param {boolean} [one=false] - Indicates whether to update only one matching entry (default: false).
+ * @returns {Promise<boolean>} A Promise that resolves to `true` if the file was updated, or `false` otherwise.
+ */
+async function updateWorker(file, search, updater, context={}, one=false){
+    file = pathRepair(file);
+    if(!existsSync(file)){
+        await promises.writeFile(file, "");
+        return false;
+    }
+    await promises.copyFile(file, file+".tmp");
+    await promises.writeFile(file, "");
+
+    const rl = createRL(file+".tmp");
+  
+    let updated = false;
+    for await(let line of rl){
+        if(one && updated){
+            appendFileSync(file, line+"\n");
+            continue;
+        }
+
+        const data = parse(line);
+        let ob = false;
+
+        if(typeof search === "function"){
+            ob = search(data, context) || false;
+        }else if(typeof search === "object" && !Array.isArray(search)){
+            ob = hasFieldsAdvanced(data, search);
+        }
+
+        if(ob){
+            let updateObj;
+            if(typeof updater === "function"){
+                updateObj = updater(data, context);
+            }else if(typeof updater === "object" && !Array.isArray(updater)){
+                updateObj = updateObject(data, updater);
+            }
+            line = await stringify(updateObj);
+            updated = true;
+        }
+        
+        appendFileSync(file, line+"\n");
+    }
+    await promises.writeFile(file+".tmp", "");
+    return updated;
+}
+
+/**
+ * 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 {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));
+    files.reverse();
+    let update = false;
+    for(const file of files){
+        const updated = await updateWorker(folder + "/" + name + "/" + file, arg, obj, context, one);
+        if(one && updated) return true;
+        update = update || updated;
+    }
+    return update;
+}
+
+export default update;

package/file/utils.js

@@ -0,0 +1,27 @@
+import { createReadStream } from "fs";
+import { createInterface } from "readline";
+
+/**
+ * Repairs a file path by replacing double slashes
+ * @private
+ * @param {string} path - The file path to repair.
+ * @returns {string} The repaired file path.
+ */
+export function pathRepair(path){
+    return path.replaceAll("//", "/");
+}
+
+/**
+ * Creates a Readline interface for reading large files with a specified high water mark.
+ * @private
+ * @param {string} file - The file path to create a Readline interface for.
+ * @returns {readline.Interface} The Readline interface.
+ */
+export function createRL(file){
+    const read_stream = createReadStream(file, { highWaterMark: 10 * 1024 * 1024 }); //10MB
+    const rl = createInterface({
+        input: read_stream,
+        crlfDelay: Infinity
+    });
+    return rl;
+}

package/format.js

@@ -0,0 +1,29 @@
+import json5 from "json5";
+
+/**
+ * Parses given string into a JSON object. If the string does not start with
+ * a {, it is wrapped in one. This allows for a shorthand when
+ * storing/reading data from a file.
+ *
+ * @param {string} data
+ * @returns {Object}
+ */
+export function parse(data){
+    if(!data.startsWith("{")) data = "{" + data + "}";
+    return json5.parse(data);
+}
+/**
+ * Converts given object to a string. If the string is a valid json5, it is
+ * returned as is. If it is a valid json5 wrapped in {}, the curly brackets
+ * are removed. Otherwise the string is wrapped in {}.
+ *
+ * @param {Object} data
+ * @return {String}
+ */
+export function stringify(data){
+    data = json5.stringify(data);
+    if(data.startsWith("{")){
+        data = data.slice(1, -1);
+    }
+    return data;
+}

package/gen.js

@@ -0,0 +1,97 @@
+const usedIdsMap = new Map();
+
+/**
+ * Generates a unique identifier based on specified parts.
+ * @function
+ * @param {number|number[]} parts - The number of parts or an array of parts.
+ * @param {number} [fill=1] - The fill value for each part (default: 1).
+ * @returns {string} The generated unique identifier.
+ */
+export default function genId(parts, fill=1){
+    parts = changeInputToPartsArray(parts, fill);
+    const time = getTime();
+    const id = getUniqueRandom(time, parts);
+    return id;
+}
+
+/**
+ * Generates a unique random identifier based on time and parts.
+ * @private
+ * @param {string} time - The current time in a base36 string format.
+ * @param {number[]} parts - An array of parts to be used for generating the identifier.
+ * @param {number} [s=0] - Recursion counter for handling collision (default: 0).
+ * @returns {string} The unique random identifier.
+ */
+function getUniqueRandom(time, partsA, s=0){
+    const parts = partsA.map(l => getRandom(l));
+    const id = [time, ...parts].join("-");
+    if(usedIdsMap.has(id)){
+        s++;
+        if(s < 25) return getUniqueRandom(time, partsA, s);
+        partsA = addOneToPods(partsA);
+        time = getTime();
+        return getUniqueRandom(time, partsA);
+    }
+    usedIdsMap.set(id, Date.now() + 2000);
+
+    usedIdsMap.forEach((value, key) => {
+        if(value < Date.now()) usedIdsMap.delete(key);
+    });
+
+    return id;
+}
+
+/**
+ * Generates a random string of base36 characters.
+ * @private
+ * @param {string} unix - The Unix timestamp used for generating the random string.
+ * @returns {string} The random string.
+ */
+function getRandom(unix){
+    return (Math.floor(Math.random() * Math.pow(36, unix))).toString(36);
+}
+
+/**
+ * Gets the current time in a base36 string format.
+ * @private
+ * @returns {string} The current time in base36.
+ */
+function getTime(){
+    return Math.floor(new Date().getTime() / 1000).toString(36);
+}
+
+/**
+ * Adds one to each part of the input array.
+ * @private
+ * @param {number[]} array - The input array.
+ * @returns {number[]} An array with one added to each element.
+ */
+function addOneToPods(array){
+    const sum = array.reduce((acc, current) => acc + current, 0);
+    const num = sum + 1;
+    const len = array.length;
+
+    const result = [];
+    const quotient = Math.floor(num / len);
+    const remainder = num % len;
+  
+    for(let i=0; i<len; i++){
+        if(i < remainder) result.push(quotient + 1);
+        else result.push(quotient);
+    }
+  
+    return result;
+}
+
+/**
+ * Converts input to an array of parts.
+ * @private
+ * @param {number|number[]} parts - The number of parts or an array of parts.
+ * @param {number} [fill=1] - The fill value for each part (default: 1).
+ * @returns {number[]} An array of parts.
+ */
+function changeInputToPartsArray(parts, fill=1){
+    if(Array.isArray(parts)) return parts;
+    if(typeof parts == "number") return Array(parts).fill(fill);
+    return [1, 1];
+}