pure.db 1.0.0

package/README.md

@@ -0,0 +1,147 @@
+
+# pure.db
+
+A simple, robust, and synchronous JSON-based key-value database for Node.js.
+Perfect for Discord bots and small projects where you need persistent storage without the hassle of setting up a database server.
+
+## Features
+
+- 🚀 **Easy to use**: Simple `set`, `get`, `push`, `pull` API.
+- ⚡ **Fast**: Synchronous operations using native filesystem.
+- 📂 **No Dependencies**: Uses Node.js `fs` module, so no native compilation errors.
+- 💾 **JSON Storage**: Data is stored in a human-readable `database.json` file.
+
+## Installation
+
+```bash
+npm install pure.db
+```
+
+## Usage
+
+```javascript
+const { PureDB } = require('pure.db');
+
+// Initialize the database (creates 'database.json' by default)
+const db = new PureDB();
+
+// Or specify a file path
+// const db = new PureDB('my-db.json');
+
+// --- Basic Operations ---
+
+// Set a value
+db.set('user.name', 'Alice');
+db.set('user.balance', 100);
+
+// Get a value
+console.log(db.get('user.name')); // Output: "Alice"
+console.log(db.get('user.balance')); // Output: 100
+
+// Check availability
+if (db.has('user.balance')) {
+    console.log('User has a balance!');
+}
+
+// Delete a value
+db.delete('user.name');
+
+// --- Math Operations ---
+
+// Add to a number
+db.add('user.balance', 50); // Balance is now 150
+
+// Subtract from a number
+db.subtract('user.balance', 25); // Balance is now 125
+
+// --- Array Operations ---
+
+// Push to an array
+db.push('guild.roles', 'Admin');
+db.push('guild.roles', 'Moderator');
+
+// Pull (remove) from an array
+db.pull('guild.roles', 'Moderator'); // Removes 'Moderator'
+
+// --- varied ---
+
+// Get all data
+console.log(db.all());
+
+// Clear the entire database
+db.clear();
+```
+
+
+## Professional Features 🚀
+
+`pure.db` is now equipped with high-performance features suitable for production environments.
+
+### ⚡ In-Memory Caching
+All data is cached in memory for **instant** read speeds (`O(1)`). Writes are synchronous and atomic to ensure data safety.
+
+### 🔒 Encryption
+Secure your data at rest with AES-256-CBC encryption.
+
+```javascript
+const db = new PureDB({ 
+    filePath: 'secure.db', 
+    encryptionKey: '12345678901234567890123456789012' // Must be 32 chars
+});
+```
+*Note: If you lose the key, data is unrecoverable.*
+
+### 📡 Event System
+Listen to database changes in real-time.
+
+```javascript
+db.on('set', (key, value) => {
+    console.log(`Key "${key}" was set to:`, value);
+});
+
+db.on('delete', (key) => {
+    console.log(`Key "${key}" was deleted.`);
+});
+```
+
+### 🧮 Advanced Math
+Perform complex calculations directly on keys.
+
+```javascript
+// Supported: '+', '-', '*', '/', '%'
+db.math('user.xp', '*', 2); // Double XP!
+db.math('user.health', '/', 2); // Halve health
+```
+
+### 📦 Backups
+Create instant backups of your database.
+
+```javascript
+db.backup('backup_date.json');
+```
+
+## API
+
+### `new PureDB(options?)`
+- `options` (object | string): Configuration object or file path string.
+  - `filePath` (string): Path to JSON file.
+  - `encryptionKey` (string): 32-char key for encryption.
+  - `pretty` (boolean): Indent JSON output (default: true).
+  - `debug` (boolean): meaningful error logs.
+
+### Methods
+- `set(key, value)`
+- `get(key, defaultValue?)`
+- `has(key)`
+- `delete(key)`
+- `math(key, operator, number)`
+- `push(key, ...elements)`
+- `pull(key, elementOrFilter)`
+- `all()`
+- `clear()`
+- `backup(path)`
+
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,96 @@
+import { EventEmitter } from 'events';
+interface PureDBOptions {
+    /**
+     * File path for the database. generic 'database.json' by default.
+     */
+    filePath?: string;
+    /**
+     * Secret key for encryption. If provided, the database will be encrypted.
+     * Must be 32 characters long.
+     */
+    encryptionKey?: string;
+    /**
+     * Format the JSON file with indentation for readability. Default: true.
+     * Set to false for smaller file size.
+     */
+    pretty?: boolean;
+    /**
+     * Enable debug logging.
+     */
+    debug?: boolean;
+}
+export declare class PureDB extends EventEmitter {
+    filePath: string;
+    options: PureDBOptions;
+    private _cache;
+    private _algorithm;
+    private _ivLength;
+    constructor(options?: PureDBOptions | string);
+    /**
+     * Loads the database from disk into memory.
+     */
+    private _load;
+    /**
+     * Saves the current memory cache to disk.
+     */
+    private _save;
+    private _encrypt;
+    private _decrypt;
+    private _setDeep;
+    private _getDeep;
+    private _deleteDeep;
+    /**
+     * Set a value in the database.
+     * @param key The key to set (supports dot notation)
+     * @param value The value to store
+     */
+    set<T = any>(key: string, value: T): T;
+    /**
+     * Get a value from the database.
+     * @param key The key to look for (supports dot notation)
+     * @param defaultValue Optional default value if key not found
+     */
+    get<T = any>(key: string, defaultValue?: T): T | undefined;
+    /**
+     * Check if a key exists in the database.
+     */
+    has(key: string): boolean;
+    /**
+     * Delete a key from the database.
+     */
+    delete(key: string): boolean;
+    /**
+     * Add a number to a key.
+     */
+    add(key: string, count: number): number;
+    /**
+     * Subtract a number from a key.
+     */
+    subtract(key: string, count: number): number;
+    /**
+     * Perform mathematical operations on a key.
+     */
+    math(key: string, operator: '+' | '-' | '*' | '/' | '%', operand: number): number;
+    /**
+     * Push an element to an array.
+     */
+    push<T = any>(key: string, ...elements: T[]): T[];
+    /**
+     * Remove (pull) elements from an array which match the given filter or value.
+     */
+    pull<T = any>(key: string, elementOrFilter: T | ((item: T) => boolean)): T[];
+    /**
+     * Returns the entire database object.
+     */
+    all(): any;
+    /**
+     * Clears the entire database.
+     */
+    clear(): void;
+    /**
+     * Creates a backup of the current database file.
+     * @param destPath Path to save the backup to.
+     */
+    backup(destPath: string): boolean;
+}
+export {};

package/dist/index.js

@@ -0,0 +1,303 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PureDB = void 0;
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+const events_1 = require("events");
+const crypto_1 = __importDefault(require("crypto"));
+class PureDB extends events_1.EventEmitter {
+    constructor(options = {}) {
+        super();
+        this._cache = {};
+        this._algorithm = 'aes-256-cbc';
+        this._ivLength = 16;
+        if (typeof options === 'string') {
+            options = { filePath: options };
+        }
+        this.options = {
+            filePath: 'database.json',
+            pretty: true,
+            ...options
+        };
+        this.filePath = path_1.default.resolve(this.options.filePath);
+        // Validate Encryption Key
+        if (this.options.encryptionKey) {
+            if (this.options.encryptionKey.length !== 32) {
+                throw new Error('Encryption key must be exactly 32 characters long.');
+            }
+        }
+        this._load();
+    }
+    /**
+     * Loads the database from disk into memory.
+     */
+    _load() {
+        try {
+            if (!fs_1.default.existsSync(this.filePath)) {
+                this._cache = {};
+                this._save(); // Create file
+                return;
+            }
+            const fileContent = fs_1.default.readFileSync(this.filePath, 'utf-8');
+            if (!fileContent.trim()) {
+                this._cache = {};
+                return;
+            }
+            if (this.options.encryptionKey) {
+                try {
+                    this._cache = JSON.parse(this._decrypt(fileContent));
+                }
+                catch (e) {
+                    // Fallback check: maybe it wasn't encrypted before?
+                    // Or wrong key.
+                    if (this.options.debug)
+                        console.error("Decryption failed. attempting plain text read.", e);
+                    try {
+                        this._cache = JSON.parse(fileContent);
+                    }
+                    catch (e2) {
+                        this._cache = {}; // Corrupt file or wrong key
+                    }
+                }
+            }
+            else {
+                this._cache = JSON.parse(fileContent);
+            }
+        }
+        catch (err) {
+            if (this.options.debug)
+                console.error("Load Error:", err);
+            this._cache = {};
+        }
+        this.emit('ready', this);
+    }
+    /**
+     * Saves the current memory cache to disk.
+     */
+    _save() {
+        try {
+            let dataToWrite;
+            if (this.options.encryptionKey) {
+                dataToWrite = this._encrypt(JSON.stringify(this._cache));
+            }
+            else {
+                dataToWrite = JSON.stringify(this._cache, null, this.options.pretty ? 2 : undefined);
+            }
+            // Write to temp file then rename (atomic write prevention of corruption)
+            const tempPath = `${this.filePath}.tmp`;
+            fs_1.default.writeFileSync(tempPath, dataToWrite);
+            fs_1.default.renameSync(tempPath, this.filePath);
+        }
+        catch (err) {
+            if (this.options.debug)
+                console.error("Write Error:", err);
+            this.emit('error', err);
+        }
+    }
+    // --- Encryption Helpers ---
+    _encrypt(text) {
+        if (!this.options.encryptionKey)
+            return text;
+        const iv = crypto_1.default.randomBytes(this._ivLength);
+        const cipher = crypto_1.default.createCipheriv(this._algorithm, Buffer.from(this.options.encryptionKey), iv);
+        let encrypted = cipher.update(text);
+        encrypted = Buffer.concat([encrypted, cipher.final()]);
+        return iv.toString('hex') + ':' + encrypted.toString('hex');
+    }
+    _decrypt(text) {
+        if (!this.options.encryptionKey)
+            return text;
+        const textParts = text.split(':');
+        const iv = Buffer.from(textParts.shift(), 'hex');
+        const encryptedText = Buffer.from(textParts.join(':'), 'hex');
+        const decipher = crypto_1.default.createDecipheriv(this._algorithm, Buffer.from(this.options.encryptionKey), iv);
+        let decrypted = decipher.update(encryptedText);
+        decrypted = Buffer.concat([decrypted, decipher.final()]);
+        return decrypted.toString();
+    }
+    // --- Deep Object Helpers ---
+    _setDeep(path, value) {
+        const keys = path.split('.');
+        let current = this._cache;
+        for (let i = 0; i < keys.length - 1; i++) {
+            const key = keys[i];
+            if (!(key in current) || typeof current[key] !== 'object') {
+                current[key] = {};
+            }
+            current = current[key];
+        }
+        current[keys[keys.length - 1]] = value;
+    }
+    _getDeep(path) {
+        const keys = path.split('.');
+        let current = this._cache;
+        for (const key of keys) {
+            if (current === undefined || current === null || typeof current !== 'object')
+                return undefined;
+            current = current[key];
+        }
+        return current;
+    }
+    _deleteDeep(path) {
+        const keys = path.split('.');
+        let current = this._cache;
+        for (let i = 0; i < keys.length - 1; i++) {
+            const key = keys[i];
+            if (current === undefined || current === null || typeof current !== 'object')
+                return false;
+            current = current[key];
+        }
+        if (current && typeof current === 'object') {
+            const lastKey = keys[keys.length - 1];
+            if (lastKey in current) {
+                delete current[lastKey];
+                return true;
+            }
+        }
+        return false;
+    }
+    // --- Public API ---
+    /**
+     * Set a value in the database.
+     * @param key The key to set (supports dot notation)
+     * @param value The value to store
+     */
+    set(key, value) {
+        this._setDeep(key, value);
+        this._save();
+        this.emit('set', key, value);
+        return value;
+    }
+    /**
+     * Get a value from the database.
+     * @param key The key to look for (supports dot notation)
+     * @param defaultValue Optional default value if key not found
+     */
+    get(key, defaultValue) {
+        const val = this._getDeep(key);
+        return val === undefined ? defaultValue : val;
+    }
+    /**
+     * Check if a key exists in the database.
+     */
+    has(key) {
+        return this.get(key) !== undefined;
+    }
+    /**
+     * Delete a key from the database.
+     */
+    delete(key) {
+        const deleted = this._deleteDeep(key);
+        if (deleted) {
+            this._save();
+            this.emit('delete', key);
+        }
+        return deleted;
+    }
+    /**
+     * Add a number to a key.
+     */
+    add(key, count) {
+        const current = this.get(key, 0);
+        if (typeof current !== 'number')
+            throw new Error(`Value at key "${key}" is not a number.`);
+        const newVal = current + count;
+        this.set(key, newVal);
+        return newVal;
+    }
+    /**
+     * Subtract a number from a key.
+     */
+    subtract(key, count) {
+        return this.add(key, -count);
+    }
+    /**
+     * Perform mathematical operations on a key.
+     */
+    math(key, operator, operand) {
+        const current = this.get(key, 0);
+        if (typeof current !== 'number')
+            throw new Error(`Value at key "${key}" is not a number.`);
+        let newVal;
+        switch (operator) {
+            case '+':
+                newVal = current + operand;
+                break;
+            case '-':
+                newVal = current - operand;
+                break;
+            case '*':
+                newVal = current * operand;
+                break;
+            case '/':
+                newVal = current / operand;
+                break;
+            case '%':
+                newVal = current % operand;
+                break;
+            default: throw new Error(`Invalid operator: ${operator}`);
+        }
+        this.set(key, newVal);
+        return newVal;
+    }
+    /**
+     * Push an element to an array.
+     */
+    push(key, ...elements) {
+        const current = this.get(key, []);
+        if (!Array.isArray(current))
+            throw new Error(`Value at key "${key}" is not an array.`);
+        current.push(...elements);
+        this.set(key, current);
+        return current;
+    }
+    /**
+     * Remove (pull) elements from an array which match the given filter or value.
+     */
+    pull(key, elementOrFilter) {
+        const current = this.get(key, []);
+        if (!Array.isArray(current))
+            throw new Error(`Value at key "${key}" is not an array.`);
+        let newArr;
+        if (typeof elementOrFilter === 'function') {
+            // @ts-ignore
+            newArr = current.filter(item => !elementOrFilter(item));
+        }
+        else {
+            newArr = current.filter(item => JSON.stringify(item) !== JSON.stringify(elementOrFilter));
+        }
+        this.set(key, newArr);
+        return newArr;
+    }
+    /**
+     * Returns the entire database object.
+     */
+    all() {
+        return this._cache;
+    }
+    /**
+     * Clears the entire database.
+     */
+    clear() {
+        this._cache = {};
+        this._save();
+        this.emit('clear');
+    }
+    /**
+     * Creates a backup of the current database file.
+     * @param destPath Path to save the backup to.
+     */
+    backup(destPath) {
+        try {
+            fs_1.default.copyFileSync(this.filePath, path_1.default.resolve(destPath));
+            return true;
+        }
+        catch (err) {
+            return false;
+        }
+    }
+}
+exports.PureDB = PureDB;

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "pure.db",
+  "version": "1.0.0",
+  "description": "A simple, robust, and synchronous JSON-based key-value database for Node.js.",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "scripts": {
+    "build": "tsc",
+    "test": "ts-node test/comprehensive_test.ts",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "db",
+    "database",
+    "json",
+    "store",
+    "key-value",
+    "quick.db",
+    "snap.db"
+  ],
+  "author": "Thendra",
+  "license": "MIT",
+  "devDependencies": {
+    "@types/node": "^22.13.1",
+    "ts-node": "^10.9.2",
+    "typescript": "^5.7.3"
+  },
+  "directories": {
+    "test": "test"
+  },
+  "dependencies": {
+    "undici-types": "^7.16.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/justthendra/pure.db.git"
+  },
+  "bugs": {
+    "url": "https://github.com/justthendra/pure.db/issues"
+  },
+  "homepage": "https://github.com/justthendra/pure.db#readme",
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/index.ts

@@ -0,0 +1,330 @@
+
+import fs from 'fs';
+import path from 'path';
+import { EventEmitter } from 'events';
+import crypto, { BinaryLike, CipherKey } from 'crypto';
+
+interface PureDBOptions {
+    /**
+     * File path for the database. generic 'database.json' by default.
+     */
+    filePath?: string;
+    /**
+     * Secret key for encryption. If provided, the database will be encrypted.
+     * Must be 32 characters long.
+     */
+    encryptionKey?: string;
+    /**
+     * Format the JSON file with indentation for readability. Default: true.
+     * Set to false for smaller file size.
+     */
+    pretty?: boolean;
+    /**
+     * Enable debug logging.
+     */
+    debug?: boolean;
+}
+
+export class PureDB extends EventEmitter {
+    public filePath: string;
+    public options: PureDBOptions;
+    private _cache: any = {};
+    private _algorithm = 'aes-256-cbc';
+    private _ivLength = 16;
+
+    constructor(options: PureDBOptions | string = {}) {
+        super();
+        
+        if (typeof options === 'string') {
+            options = { filePath: options };
+        }
+
+        this.options = { 
+            filePath: 'database.json', 
+            pretty: true, 
+            ...options 
+        };
+
+        this.filePath = path.resolve(this.options.filePath!);
+
+        // Validate Encryption Key
+        if (this.options.encryptionKey) {
+            if (this.options.encryptionKey.length !== 32) {
+                throw new Error('Encryption key must be exactly 32 characters long.');
+            }
+        }
+
+        this._load();
+    }
+
+    /**
+     * Loads the database from disk into memory.
+     */
+    private _load(): void {
+        try {
+            if (!fs.existsSync(this.filePath)) {
+                this._cache = {};
+                this._save(); // Create file
+                return;
+            }
+
+            const fileContent = fs.readFileSync(this.filePath, 'utf-8');
+            
+            if (!fileContent.trim()) {
+                this._cache = {};
+                return;
+            }
+
+            if (this.options.encryptionKey) {
+                 try {
+                    this._cache = JSON.parse(this._decrypt(fileContent));
+                 } catch (e) {
+                     // Fallback check: maybe it wasn't encrypted before?
+                     // Or wrong key.
+                     if (this.options.debug) console.error("Decryption failed. attempting plain text read.", e);
+                     try {
+                        this._cache = JSON.parse(fileContent);
+                     } catch (e2) {
+                        this._cache = {}; // Corrupt file or wrong key
+                     }
+                 }
+            } else {
+                this._cache = JSON.parse(fileContent);
+            }
+
+        } catch (err) {
+            if (this.options.debug) console.error("Load Error:", err);
+            this._cache = {};
+        }
+        this.emit('ready', this);
+    }
+
+    /**
+     * Saves the current memory cache to disk.
+     */
+    private _save(): void {
+        try {
+            let dataToWrite: string;
+            
+            if (this.options.encryptionKey) {
+                dataToWrite = this._encrypt(JSON.stringify(this._cache));
+            } else {
+                dataToWrite = JSON.stringify(this._cache, null, this.options.pretty ? 2 : undefined);
+            }
+
+            // Write to temp file then rename (atomic write prevention of corruption)
+            const tempPath = `${this.filePath}.tmp`;
+            fs.writeFileSync(tempPath, dataToWrite);
+            fs.renameSync(tempPath, this.filePath);
+
+        } catch (err) {
+            if (this.options.debug) console.error("Write Error:", err);
+            this.emit('error', err);
+        }
+    }
+
+    // --- Encryption Helpers ---
+    private _encrypt(text: string): string {
+        if (!this.options.encryptionKey) return text;
+        const iv = crypto.randomBytes(this._ivLength);
+        const cipher = crypto.createCipheriv(this._algorithm, Buffer.from(this.options.encryptionKey), iv);
+        let encrypted = cipher.update(text);
+        encrypted = Buffer.concat([encrypted, cipher.final()]);
+        return iv.toString('hex') + ':' + encrypted.toString('hex');
+    }
+
+    private _decrypt(text: string): string {
+        if (!this.options.encryptionKey) return text;
+        const textParts = text.split(':');
+        const iv = Buffer.from(textParts.shift()!, 'hex');
+        const encryptedText = Buffer.from(textParts.join(':'), 'hex');
+        const decipher = crypto.createDecipheriv(this._algorithm, Buffer.from(this.options.encryptionKey), iv);
+        let decrypted = decipher.update(encryptedText);
+        decrypted = Buffer.concat([decrypted, decipher.final()]);
+        return decrypted.toString();
+    }
+
+    // --- Deep Object Helpers ---
+    private _setDeep(path: string, value: any): void {
+        const keys = path.split('.');
+        let current = this._cache;
+        for (let i = 0; i < keys.length - 1; i++) {
+            const key = keys[i];
+            if (!(key in current) || typeof current[key] !== 'object') {
+                current[key] = {};
+            }
+            current = current[key];
+        }
+        current[keys[keys.length - 1]] = value;
+    }
+
+    private _getDeep(path: string): any {
+        const keys = path.split('.');
+        let current = this._cache;
+        for (const key of keys) {
+            if (current === undefined || current === null || typeof current !== 'object') return undefined;
+            current = current[key];
+        }
+        return current;
+    }
+
+    private _deleteDeep(path: string): boolean {
+        const keys = path.split('.');
+        let current = this._cache;
+        for (let i = 0; i < keys.length - 1; i++) {
+             const key = keys[i];
+             if (current === undefined || current === null || typeof current !== 'object') return false;
+             current = current[key];
+        }
+        if (current && typeof current === 'object') {
+            const lastKey = keys[keys.length - 1];
+            if (lastKey in current) {
+                delete current[lastKey];
+                return true;
+            }
+        }
+        return false;
+    }
+
+    // --- Public API ---
+
+    /**
+     * Set a value in the database.
+     * @param key The key to set (supports dot notation)
+     * @param value The value to store
+     */
+    public set<T = any>(key: string, value: T): T {
+        this._setDeep(key, value);
+        this._save();
+        this.emit('set', key, value);
+        return value;
+    }
+
+    /**
+     * Get a value from the database.
+     * @param key The key to look for (supports dot notation)
+     * @param defaultValue Optional default value if key not found
+     */
+    public get<T = any>(key: string, defaultValue?: T): T | undefined {
+        const val = this._getDeep(key);
+        return val === undefined ? defaultValue : val;
+    }
+
+    /**
+     * Check if a key exists in the database.
+     */
+    public has(key: string): boolean {
+        return this.get(key) !== undefined;
+    }
+
+    /**
+     * Delete a key from the database.
+     */
+    public delete(key: string): boolean {
+        const deleted = this._deleteDeep(key);
+        if (deleted) {
+            this._save();
+            this.emit('delete', key);
+        }
+        return deleted;
+    }
+
+    /**
+     * Add a number to a key.
+     */
+    public add(key: string, count: number): number {
+        const current = this.get<number>(key, 0);
+        if (typeof current !== 'number') throw new Error(`Value at key "${key}" is not a number.`);
+        const newVal = current + count;
+        this.set(key, newVal);
+        return newVal;
+    }
+
+    /**
+     * Subtract a number from a key.
+     */
+    public subtract(key: string, count: number): number {
+        return this.add(key, -count);
+    }
+    
+    /**
+     * Perform mathematical operations on a key.
+     */
+    public math(key: string, operator: '+' | '-' | '*' | '/' | '%', operand: number): number {
+        const current = this.get<number>(key, 0);
+         if (typeof current !== 'number') throw new Error(`Value at key "${key}" is not a number.`);
+        
+        let newVal: number;
+        switch(operator) {
+            case '+': newVal = current + operand; break;
+            case '-': newVal = current - operand; break;
+            case '*': newVal = current * operand; break;
+            case '/': newVal = current / operand; break;
+            case '%': newVal = current % operand; break;
+            default: throw new Error(`Invalid operator: ${operator}`);
+        }
+        
+        this.set(key, newVal);
+        return newVal;
+    }
+
+    /**
+     * Push an element to an array.
+     */
+    public push<T = any>(key: string, ...elements: T[]): T[] {
+        const current = this.get<T[]>(key, []);
+        if (!Array.isArray(current)) throw new Error(`Value at key "${key}" is not an array.`);
+        
+        current.push(...elements);
+        this.set(key, current);
+        return current;
+    }
+
+    /**
+     * Remove (pull) elements from an array which match the given filter or value.
+     */
+    public pull<T = any>(key: string, elementOrFilter: T | ((item: T) => boolean)): T[] {
+         const current = this.get<T[]>(key, []);
+         if (!Array.isArray(current)) throw new Error(`Value at key "${key}" is not an array.`);
+
+         let newArr: T[];
+         if (typeof elementOrFilter === 'function') {
+             // @ts-ignore
+             newArr = current.filter(item => !elementOrFilter(item));
+         } else {
+             newArr = current.filter(item => JSON.stringify(item) !== JSON.stringify(elementOrFilter));
+         }
+         
+         this.set(key, newArr);
+         return newArr;
+    }
+
+    /**
+     * Returns the entire database object.
+     */
+    public all(): any {
+        return this._cache;
+    }
+
+    /**
+     * Clears the entire database.
+     */
+    public clear(): void {
+        this._cache = {};
+        this._save();
+        this.emit('clear');
+    }
+    
+    /**
+     * Creates a backup of the current database file.
+     * @param destPath Path to save the backup to.
+     */
+    public backup(destPath: string): boolean {
+        try {
+            fs.copyFileSync(this.filePath, path.resolve(destPath));
+            return true;
+        } catch (err) {
+            return false;
+        }
+    }
+}

package/test/advanced_test.ts

@@ -0,0 +1,63 @@
+
+import { PureDB } from '../src/index';
+import fs from 'fs';
+import assert from 'assert';
+
+const FILE_PLAIN = 'test_plain.json';
+const FILE_ENC = 'test_enc.json';
+
+// Cleanup
+if (fs.existsSync(FILE_PLAIN)) fs.unlinkSync(FILE_PLAIN);
+if (fs.existsSync(FILE_ENC)) fs.unlinkSync(FILE_ENC);
+
+async function runTests() {
+    console.log('--- Advanced Features Test ---');
+
+    console.log('1. Testing Events...');
+    const db = new PureDB({ filePath: FILE_PLAIN });
+    
+    let eventTriggered = false;
+    db.on('set', (key, value) => {
+        console.log(`Event 'set' received: ${key} = ${value}`);
+        eventTriggered = true;
+    });
+
+    db.set('foo', 'bar');
+    assert.strictEqual(eventTriggered, true, "Event was not triggered");
+    console.log('✅ Events Passed');
+
+
+    console.log('2. Testing In-Memory Caching...');
+    // Mechanically, if I manually edit the file, the DB should NOT see it until reload
+    // because it reads from cache.
+    const originalValue = db.get('foo');
+    fs.writeFileSync(FILE_PLAIN, JSON.stringify({ foo: "hacked" }));
+    const cachedValue = db.get('foo');
+    assert.strictEqual(cachedValue, 'bar', "Cache bypassed! Should have returned memory value.");
+    console.log('✅ Caching Passed');
+
+
+    console.log('3. Testing Encryption...');
+    const secret = '12345678901234567890123456789012'; // 32 chars
+    const dbEnc = new PureDB({ filePath: FILE_ENC, encryptionKey: secret });
+    
+    dbEnc.set('secretDetails', { plan: 'world_domination' });
+    
+    // Check file content - should be unreadable
+    const rawContent = fs.readFileSync(FILE_ENC, 'utf-8');
+    console.log('Encrypted File Content Start:', rawContent.substring(0, 20) + '...');
+    assert.doesNotMatch(rawContent, /world_domination/, "File is not encrypted!");
+
+    // Check read
+    const readVal = dbEnc.get('secretDetails');
+    assert.deepStrictEqual(readVal, { plan: 'world_domination' }, "Decryption failed!");
+    console.log('✅ Encryption Passed');
+
+    // Cleanup
+    if (fs.existsSync(FILE_PLAIN)) fs.unlinkSync(FILE_PLAIN);
+    if (fs.existsSync(FILE_ENC)) fs.unlinkSync(FILE_ENC);
+    
+    console.log('--- All Advanced Tests Passed ---');
+}
+
+runTests().catch(console.error);

package/tsconfig.json

@@ -0,0 +1,16 @@
+
+{
+  "compilerOptions": {
+    "target": "ES2020",
+    "module": "commonjs",
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "declaration": true
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "**/*.test.ts"]
+}