rengandb 1.0.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Talha
+
+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,35 @@
+# rengandb
+
+A **safe**, **performant**, and **file-locking protected** JSON/YAML database module for Node.js.
+
+## Quick Start
+
+```bash
+npm install rengandb
+```
+
+```javascript
+import Database from 'rengandb';
+
+const db = await Database.init('data.json', { useLodash: true });
+
+// Write data
+await db.set('user.name', 'Rengan');
+
+// Read data
+console.log(db.get('user.name')); // "Rengan"
+
+```
+
+## Why use it?
+
+* **Safe:** Prevents data corruption using `proper-lockfile`, even when multiple processes try to write to the file simultaneously.
+* **Smart:** Automatically refreshes data in RAM using `chokidar` when the file is modified externally.
+* **Lightweight:** Optional `lodash` support; use it only if you need deep access (e.g., `user.settings.theme`).
+
+## License
+
+This project is licensed under the MIT License. 
+See the [LICENSE](LICENSE) file for details.
+
+> **Note:** This is a hobby project. Please use it responsibly in production environments.

package/build/main.d.ts

@@ -0,0 +1,57 @@
+interface IEngine {
+    get<T>(key: string): T | undefined;
+    set<T>(key: string, value: T): void;
+    has(key: string): boolean;
+    delete(key: string): void;
+}
+interface IProvider {
+    stringify(data: any): any;
+    parse(data: any): any;
+}
+interface IFileSys {
+    isExists(path: string): Promise<boolean>;
+    writeFile(path: string, data: any): void;
+    readFile(path: string): Promise<string>;
+    watch(path: string): any;
+    stopWatcher(): Promise<void>;
+}
+interface IDatabaseSettings {
+    useLodash?: boolean;
+    customFileSystem?: IFileSys;
+}
+declare class Database {
+    file: string;
+    fileType: string;
+    initialized: boolean;
+    settings: IDatabaseSettings;
+    engine: IEngine;
+    provider: IProvider;
+    filesystem: IFileSys;
+    watcher: any;
+    data: any;
+    private writeQueue;
+    private isWriting;
+    constructor(file: string, settings?: IDatabaseSettings);
+    static init(...parameters: ConstructorParameters<typeof Database>): Promise<Database>;
+    _lodash(): IEngine;
+    _native(): IEngine;
+    _json(): IProvider;
+    _yaml(): IProvider;
+    _fs(): IFileSys;
+    setup(): Promise<boolean>;
+    startWatcher(): Promise<void>;
+    loadData(): Promise<any>;
+    write(): Promise<void>;
+    error(message: string): Error;
+    set(key: string, value: any): Promise<void>;
+    delete(key: string): Promise<void>;
+    math(key: string, value: any, func: (found: number, value: number) => number): Promise<void>;
+    push(key: string, value: any): Promise<void>;
+    length(key: string): number | undefined;
+    has(key: string): boolean;
+    clear(really: boolean): Promise<void>;
+    fetch(key: string): {} | null;
+    get(key: string): {} | null;
+    fetchAll(): any;
+}
+export default Database;

package/build/main.js

@@ -0,0 +1,290 @@
+import fsPromises from 'fs/promises';
+import path from 'path';
+import YAML from 'yaml';
+import chokidar from 'chokidar';
+import lockfile from 'proper-lockfile';
+let lodash;
+const supportedFileTypes = [
+    "json",
+    "yaml",
+    "yml"
+];
+class Database {
+    file;
+    fileType;
+    initialized;
+    settings;
+    engine;
+    provider;
+    filesystem;
+    watcher;
+    data;
+    writeQueue;
+    isWriting;
+    constructor(file, settings = {}) {
+        this.initialized = false;
+        this.file = file;
+        this.fileType = path.extname(file).toLowerCase();
+        if (!supportedFileTypes.includes(this.fileType.replace(/^\./, ''))) {
+            this.initialized = false;
+            throw this.error("Unsupported file type!");
+        }
+        this.settings = {
+            useLodash: false,
+            customFileSystem: undefined,
+            ...settings
+        };
+        this.engine = this._native();
+        this.provider = this._json();
+        this.filesystem = this.settings.customFileSystem || this._fs();
+        this.watcher = null;
+        this.writeQueue = Promise.resolve();
+        this.isWriting = false;
+    }
+    static async init(...parameters) {
+        const instance = new Database(...parameters);
+        await instance.setup();
+        instance.initialized = true;
+        instance.data = await instance.loadData();
+        await instance.startWatcher();
+        return instance;
+    }
+    // Engines (is it lodash or not)
+    _lodash() {
+        return {
+            get: (key) => lodash.get(this.data, key),
+            set: (key, value) => lodash.set(this.data, key, value),
+            has: (key) => lodash.has(this.data, key),
+            delete: (key) => lodash.unset(this.data, key)
+        };
+    }
+    _native() {
+        return {
+            get: (key) => this.data[key],
+            set: (key, value) => { this.data[key] = value; },
+            has: (key) => (key in this.data),
+            delete: (key) => { delete this.data[key]; }
+        };
+    }
+    // File Types
+    _json() {
+        return {
+            stringify: (data) => JSON.stringify(data, null, 4),
+            parse: (data) => JSON.parse(data)
+        };
+    }
+    _yaml() {
+        return {
+            stringify: (data) => YAML.stringify(data, null, { indent: 4 }),
+            parse: (data) => YAML.parse(data)
+        };
+    }
+    // File Systems
+    _fs() {
+        return {
+            isExists: async (path) => {
+                try {
+                    await fsPromises.access(path);
+                    return true;
+                }
+                catch {
+                    return false;
+                }
+            },
+            writeFile: (path, data) => fsPromises.writeFile(path, data),
+            readFile: (path) => fsPromises.readFile(path, 'utf8'),
+            watch: (path) => {
+                const watcher = chokidar.watch(path, {
+                    ignoreInitial: true,
+                    awaitWriteFinish: {
+                        stabilityThreshold: 100,
+                        pollInterval: 50
+                    },
+                });
+                watcher
+                    .on('change', (path) => {
+                    if (!this.isWriting) {
+                        this.loadData().then(data => { this.data = data; }).catch(err => { console.error(this.error("Watcher cannot read file")); });
+                    }
+                })
+                    .on('unlink', (path) => {
+                    this.loadData().then(data => { this.data = data; }).catch(err => { console.error(this.error("Watcher cannot read file")); });
+                });
+                return watcher;
+            },
+            stopWatcher: async () => { if (this.watcher) {
+                await this.watcher.close();
+            } }
+        };
+    }
+    async setup() {
+        if (this.settings.useLodash) {
+            try {
+                const [getModule, setModule, hasModule, unsetModule] = await Promise.all([
+                    // @ts-ignore
+                    import('lodash/get.js'),
+                    // @ts-ignore
+                    import('lodash/set.js'),
+                    // @ts-ignore
+                    import('lodash/has.js'),
+                    // @ts-ignore
+                    import('lodash/unset.js')
+                ]);
+                lodash = {
+                    get: getModule.default || getModule,
+                    set: setModule.default || setModule,
+                    has: hasModule.default || hasModule,
+                    unset: unsetModule.default || unsetModule
+                };
+                this.engine = this._lodash();
+            }
+            catch (err) {
+                console.error(this.error(`Lodash cannot be loaded: ${err}`));
+                this.engine = this._native();
+            }
+        }
+        if (this.fileType === '.yaml' || this.fileType === '.yml') {
+            this.provider = this._yaml();
+        }
+        else if (this.fileType === '.json') {
+            this.provider = this._json();
+        }
+        return true;
+    }
+    async startWatcher() {
+        if (this.watcher) {
+            await this.filesystem.stopWatcher();
+        }
+        this.watcher = await this.filesystem.watch(this.file);
+    }
+    async loadData() {
+        if (!this.initialized)
+            throw this.error("Not initialized");
+        try {
+            if (!await this.filesystem.isExists(this.file)) {
+                await this.filesystem.writeFile(this.file, this.provider.stringify({}));
+                return {};
+            }
+            return this.provider.parse(await this.filesystem.readFile(this.file)) || {};
+        }
+        catch {
+            return {};
+        }
+    }
+    async write() {
+        if (!this.initialized)
+            throw this.error("Not initialized");
+        this.writeQueue = this.writeQueue.then(async () => {
+            this.isWriting = true;
+            let releaseLock;
+            try {
+                releaseLock = await lockfile.lock(this.file, {
+                    retries: { retries: 10, minTimeout: 50 },
+                    stale: 5000,
+                });
+                const content = this.provider.stringify(this.data);
+                await this.filesystem.writeFile(this.file, content);
+                await new Promise(resolve => setTimeout(resolve, 150));
+            }
+            catch (err) {
+                throw err;
+            }
+            finally {
+                this.isWriting = false;
+                if (typeof releaseLock === 'function') {
+                    await releaseLock();
+                }
+            }
+        }).catch(err => {
+            this.isWriting = false;
+            throw this.error(`Writing Error: ${err.message}`);
+        });
+        await this.writeQueue;
+    }
+    error(message) {
+        return new Error(`Saver.db error: ${message}`);
+    }
+    async set(key, value) {
+        if (!key)
+            throw this.error(`Undefined key! - ${key}`);
+        if (value === undefined)
+            throw this.error(`Undefined value! - ${value}`);
+        this.engine.set(key, value);
+        await this.write();
+    }
+    async delete(key) {
+        if (!key)
+            throw this.error(`Undefined key! - ${key}`);
+        if (!this.engine.has(key))
+            throw this.error(`${key} not found in database.`);
+        this.engine.delete(key);
+        await this.write();
+    }
+    async math(key, value, func) {
+        if (!key)
+            throw this.error(`Undefined key! - ${key}`);
+        if (value === undefined)
+            throw this.error(`Undefined value! - ${value}`);
+        if (!func)
+            throw this.error(`Undefined func!`);
+        if (!this.engine.has(key))
+            throw this.error(`${key} not found in database.`);
+        const found = this.engine.get(key);
+        const numValue = Number(value);
+        if (Number.isNaN(numValue))
+            throw this.error('Value is not number!');
+        if (isNaN(found))
+            throw this.error('Found data is not number!');
+        this.engine.set(key, func(found, numValue));
+        await this.write();
+    }
+    async push(key, value) {
+        if (!key)
+            throw this.error(`Undefined key! - ${key}`);
+        if (value === undefined)
+            throw this.error(`Undefined value! - ${value}`);
+        let found = this.engine.get(key);
+        if (found === undefined) {
+            found = [];
+        }
+        else if (!Array.isArray(found)) {
+            throw this.error(`Thats not an array! - ${key}`);
+        }
+        found.push(value);
+        this.engine.set(key, found);
+        await this.write();
+    }
+    length(key) {
+        const found = this.engine.get(key);
+        if (found === undefined) {
+            return undefined;
+        }
+        else if (!Array.isArray(found)) {
+            throw this.error('Thats not an array!');
+        }
+        return found.length;
+    }
+    has(key) {
+        if (!key)
+            throw this.error(`Undefined key! - ${key}`);
+        return this.engine.has(key);
+    }
+    async clear(really) {
+        if (really) {
+            this.data = {};
+            await this.write();
+        }
+    }
+    fetch(key) {
+        if (!key)
+            throw this.error(`Undefined key! - ${key}`);
+        return this.engine.get(key) ?? null;
+    }
+    get(key) {
+        return this.fetch(key);
+    }
+    fetchAll() {
+        return this.data;
+    }
+}
+export default Database;

package/package.json

@@ -0,0 +1,35 @@
+{
+    "name": "rengandb",
+    "version": "1.0.2",
+    "description": "RenganDB Database Module",
+    "author": {
+        "name": "RengaN"
+    },
+    "repository": {
+        "type": "git",
+        "url": "https://github.com/RengaN02/rengandb.git"
+    },
+    "type": "module",
+    "main": "build/main.js", 
+    "types": "build/main.d.ts",
+    "files": [
+        "build/",
+        "README.md",
+        "LICENSE"
+    ],
+    "scripts": {
+        "build": "tsc"
+    },
+    "dependencies": {
+        "chokidar": "^4.0.0",
+        "lodash": "^4.17.21",
+        "proper-lockfile": "^4.1.2",
+        "yaml": "^2.3.4"
+    },
+    "devDependencies": {
+        "@types/lodash": "^4.17.24",
+        "@types/node": "^20.0.0",
+        "@types/proper-lockfile": "^4.1.4",
+        "typescript": "^5.0.0"
+    }
+}