ruggy 0.1.0

package/package.json

@@ -0,0 +1,42 @@
+{
+    "name": "ruggy",
+    "version": "0.1.0",
+    "description": "A simple, fast embedded database for Node.js backed by Rust",
+    "main": "src/index.js",
+    "types": "index.d.ts",
+    "keywords": [
+        "database",
+        "embedded",
+        "rust",
+        "ffi",
+        "nosql",
+        "document-store"
+    ],
+    "files": [
+        "src/",
+        "lib/",
+        "assets/",
+        "index.d.ts",
+        "README.md",
+        "LICENSE",
+        "CHANGELOG.md"
+    ],
+    "engines": {
+        "node": ">=14.0.0"
+    },
+    "scripts": {
+        "test": "node test/run-all.js",
+        "bench": "node benchmark/run.js"
+    },
+    "dependencies": {
+        "koffi": "^2.8.0",
+        "js-yaml": "^4.1.0"
+    },
+    "devDependencies": {},
+    "repository": {
+        "type": "git",
+        "url": "https://github.com/Mub1522/ruggy"
+    },
+    "author": "Andres Diaz",
+    "license": "MIT"
+}

package/src/Collection.js

@@ -0,0 +1,176 @@
+const {
+    ruggy_insert,
+    ruggy_find_all,
+    ruggy_find,
+    ruggy_col_free,
+    ruggy_str_free
+} = require('./bindings');
+const { readCString, toCString, isValidPointer } = require('./utils');
+
+/**
+ * Represents a collection in the Ruggy database
+ */
+class RuggyCollection {
+    /**
+     * @private
+     * @type {*} Native pointer to the Rust Collection
+     */
+    #colPtr = null;
+
+    /**
+     * @private
+     * @type {string} Collection name
+     */
+    #name = null;
+
+    /**
+     * @private
+     * @param {*} colPtr - Native pointer from Rust
+     * @param {string} name - Collection name
+     */
+    constructor(colPtr, name) {
+        if (!isValidPointer(colPtr)) {
+            throw new Error(`Invalid collection pointer for '${name}'`);
+        }
+        this.#colPtr = colPtr;
+        this.#name = name;
+    }
+
+    /**
+     * Gets the collection name
+     * @returns {string}
+     */
+    get name() {
+        return this.#name;
+    }
+
+    /**
+     * Checks if the collection is open
+     * @returns {boolean}
+     */
+    get isOpen() {
+        return this.#colPtr !== null;
+    }
+
+    /**
+     * Inserts a document into the collection
+     * @param {Object} data - Document to insert
+     * @returns {string|null} - Generated document ID or null on error
+     * @throws {Error} If collection is closed or data is invalid
+     */
+    insert(data) {
+        this.#ensureOpen();
+
+        if (typeof data !== 'object' || data === null) {
+            throw new Error('Data must be a non-null object');
+        }
+
+        const json = JSON.stringify(data);
+        const buf = toCString(json);
+
+        const resPtr = ruggy_insert(this.#colPtr, buf);
+
+        if (!isValidPointer(resPtr)) {
+            return null;
+        }
+
+        const id = readCString(resPtr);
+        ruggy_str_free(resPtr);
+        return id;
+    }
+
+    /**
+     * Finds all documents in the collection
+     * @returns {Array<Object>} - Array of documents
+     * @throws {Error} If collection is closed
+     */
+    findAll() {
+        this.#ensureOpen();
+
+        const resPtr = ruggy_find_all(this.#colPtr);
+        if (!isValidPointer(resPtr)) {
+            return [];
+        }
+
+        const json = readCString(resPtr);
+        ruggy_str_free(resPtr);
+
+        try {
+            return JSON.parse(json);
+        } catch (error) {
+            console.error('Failed to parse JSON from Rust:', error);
+            return [];
+        }
+    }
+
+    /**
+     * Finds documents matching a field-value pair
+     * @param {string} field - Field name to search
+     * @param {*} value - Value to match (converted to string)
+     * @returns {Array<Object>} - Array of matching documents
+     * @throws {Error} If collection is closed
+     */
+    find(field, value) {
+        this.#ensureOpen();
+
+        if (typeof field !== 'string' || !field) {
+            throw new Error('Field must be a non-empty string');
+        }
+
+        const fieldBuf = toCString(field);
+        const valueBuf = toCString(String(value));
+
+        const resPtr = ruggy_find(this.#colPtr, fieldBuf, valueBuf);
+        if (!isValidPointer(resPtr)) {
+            return [];
+        }
+
+        const json = readCString(resPtr);
+        ruggy_str_free(resPtr);
+
+        try {
+            return JSON.parse(json);
+        } catch (error) {
+            console.error('Failed to parse JSON from Rust:', error);
+            return [];
+        }
+    }
+
+    /**
+     * Closes the collection and frees native resources
+     * Safe to call multiple times
+     */
+    close() {
+        if (this.#colPtr) {
+            ruggy_col_free(this.#colPtr);
+            this.#colPtr = null;
+        }
+    }
+
+    /**
+     * @private
+     * Ensures the collection is open
+     * @throws {Error} If collection is closed
+     */
+    #ensureOpen() {
+        if (!this.#colPtr) {
+            throw new Error(`Collection '${this.#name}' is closed`);
+        }
+    }
+
+    /**
+     * Symbol.dispose implementation for "using" syntax (Node.js 20+)
+     */
+    [Symbol.dispose]() {
+        this.close();
+    }
+
+    /**
+     * Symbol.asyncDispose implementation for "await using" syntax
+     */
+    async [Symbol.asyncDispose]() {
+        this.close();
+    }
+}
+
+module.exports = RuggyCollection;

package/src/Database.js

@@ -0,0 +1,217 @@
+const {
+    ruggy_open,
+    ruggy_get_collection,
+    ruggy_db_free
+} = require('./bindings');
+const { toCString, isValidPointer } = require('./utils');
+const RuggyCollection = require('./Collection');
+
+/**
+ * Ruggy Database - A simple, fast embedded database
+ */
+class RuggyDatabase {
+    /**
+     * @private
+     * @type {*} Native pointer to the Rust Database
+     */
+    #dbPtr = null;
+
+    /**
+     * @private
+     * @type {string} Database path
+     */
+    #path = null;
+
+    /**
+     * @private
+     * @type {Map<string, RuggyCollection>} Cache of open collections
+     */
+    #collectionCache = new Map();
+
+    /**
+     * Creates a new database connection
+     * @param {string} dbPath - Path to the database directory
+     * @throws {Error} If the database cannot be opened
+     */
+    constructor(dbPath) {
+        if (typeof dbPath !== 'string' || !dbPath) {
+            throw new Error('Database path must be a non-empty string');
+        }
+
+        const buf = toCString(dbPath);
+        this.#dbPtr = ruggy_open(buf);
+
+        if (!isValidPointer(this.#dbPtr)) {
+            throw new Error(
+                `Failed to open database at '${dbPath}'. ` +
+                `Possible causes: invalid path, insufficient permissions, or disk full.`
+            );
+        }
+
+        this.#path = dbPath;
+    }
+
+    /**
+     * Gets the database path
+     * @returns {string}
+     */
+    get path() {
+        return this.#path;
+    }
+
+    /**
+     * Checks if the database is open
+     * @returns {boolean}
+     */
+    get isOpen() {
+        return this.#dbPtr !== null;
+    }
+
+    /**
+     * Gets a collection (creates if doesn't exist)
+     * @param {string} name - Collection name
+     * @returns {RuggyCollection}
+     * @throws {Error} If database is closed or collection cannot be opened
+     */
+    collection(name) {
+        this.#ensureOpen();
+
+        if (typeof name !== 'string' || !name) {
+            throw new Error('Collection name must be a non-empty string');
+        }
+
+        // Return cached collection if available
+        if (this.#collectionCache.has(name)) {
+            const col = this.#collectionCache.get(name);
+            if (col.isOpen) {
+                return col;
+            }
+            // Remove stale reference
+            this.#collectionCache.delete(name);
+        }
+
+        // Get or create collection from Rust
+        const buf = toCString(name);
+        const colPtr = ruggy_get_collection(this.#dbPtr, buf);
+
+        if (!isValidPointer(colPtr)) {
+            throw new Error(`Failed to get collection '${name}'`);
+        }
+
+        const collection = new RuggyCollection(colPtr, name);
+        this.#collectionCache.set(name, collection);
+        return collection;
+    }
+
+    /**
+     * Alias for collection() for semantic clarity
+     * @param {string} name - Collection name
+     * @returns {RuggyCollection}
+     */
+    createCollection(name) {
+        return this.collection(name);
+    }
+
+    /**
+     * Closes all cached collections
+     * @private
+     */
+    #closeAllCollections() {
+        for (const col of this.#collectionCache.values()) {
+            col.close();
+        }
+        this.#collectionCache.clear();
+    }
+
+    /**
+     * Closes the database and frees native resources
+     * Also closes all open collections
+     * Safe to call multiple times
+     */
+    close() {
+        if (this.#dbPtr) {
+            this.#closeAllCollections();
+            ruggy_db_free(this.#dbPtr);
+            this.#dbPtr = null;
+        }
+    }
+
+    /**
+     * Helper: Automatically manages collection lifecycle
+     * @param {string} name - Collection name
+     * @param {Function} callback - Async function that receives the collection
+     * @returns {Promise<*>} - Result of callback
+     * @throws {Error} If database is closed
+     */
+    async withCollection(name, callback) {
+        const col = this.collection(name);
+        try {
+            return await callback(col);
+        } finally {
+            col.close();
+            this.#collectionCache.delete(name);
+        }
+    }
+
+    /**
+     * Static helper: Automatically manages database lifecycle
+     * @param {string} path - Database path
+     * @param {Function} callback - Async function that receives the database
+     * @returns {Promise<*>} - Result of callback
+     */
+    static async withDatabase(path, callback) {
+        const db = new RuggyDatabase(path);
+        try {
+            return await callback(db);
+        } finally {
+            db.close();
+        }
+    }
+
+    /**
+     * Static factory: Creates a database instance using ruggy.yaml configuration
+     * Searches for ruggy.yaml from current directory up to root
+     * @param {Object} options - Configuration options
+     * @param {boolean} options.reload - Force reload configuration (bypass cache)
+     * @param {string} options.searchFrom - Directory to start searching from
+     * @returns {RuggyDatabase} - Database instance configured from YAML
+     * @throws {Error} If database cannot be opened with configured path
+     * @example
+     * // With ruggy.yaml in project root containing: dataPath: ./my-data
+     * const db = RuggyDatabase.fromConfig();
+     * const col = db.collection('users');
+     */
+    static fromConfig(options = {}) {
+        const { loadConfig } = require('./config');
+        const config = loadConfig(options);
+        return new RuggyDatabase(config.dataPath);
+    }
+
+
+    /**
+     * @private
+     * Ensures the database is open
+     * @throws {Error} If database is closed
+     */
+    #ensureOpen() {
+        if (!this.#dbPtr) {
+            throw new Error(`Database at '${this.#path}' is closed`);
+        }
+    }
+
+    /**
+     * Symbol.dispose implementation for "using" syntax (Node.js 20+)
+     */
+    [Symbol.dispose]() {
+        this.close();
+    }
+
+    /**
+     * Symbol.asyncDispose implementation for "await using" syntax
+     */
+    async [Symbol.asyncDispose]() {
+        this.close();
+    }
+}
+
+module.exports = RuggyDatabase;

package/src/Pool.js

@@ -0,0 +1,251 @@
+const RuggyDatabase = require('./Database');
+
+/**
+ * Connection pool for Ruggy database
+ * Reuses a single database connection across multiple operations
+ * Ideal for long-running applications (servers, background jobs)
+ */
+class RuggyPool {
+    /**
+     * @private
+     * @type {RuggyDatabase|null} Pooled database instance
+     */
+    #db = null;
+
+    /**
+     * @private
+     * @type {string} Database path
+     */
+    #path = null;
+
+    /**
+     * @private
+     * @type {boolean} Whether the pool is closed
+     */
+    #closed = false;
+
+    /**
+     * @private
+     * @type {number} Number of active operations
+     */
+    #activeOperations = 0;
+
+    /**
+     * @private
+     * @type {number} Total operations performed
+     */
+    #totalOperations = 0;
+
+    /**
+     * Creates a new connection pool
+     * @param {string} path - Database path
+     * @param {Object} options - Pool options
+     * @param {boolean} options.lazyConnect - If true, don't open DB until first use (default: true)
+     */
+    constructor(path, options = {}) {
+        if (typeof path !== 'string' || !path) {
+            throw new Error('Database path must be a non-empty string');
+        }
+
+        this.#path = path;
+
+        // Eager connection if requested
+        if (options.lazyConnect === false) {
+            this.#ensureConnection();
+        }
+    }
+
+    /**
+     * Static factory: Creates a pool instance using ruggy.yaml configuration
+     * Searches for ruggy.yaml from current directory up to root
+     * @param {Object} options - Combined configuration and pool options
+     * @param {boolean} options.reload - Force reload configuration (bypass cache)
+     * @param {string} options.searchFrom - Directory to start searching from
+     * @param {boolean} options.lazyConnect - If true, don't open DB until first use (default: true)
+     * @returns {RuggyPool} - Pool instance configured from YAML
+     * @throws {Error} If database cannot be opened with configured path
+     * @example
+     * // With ruggy.yaml in project root containing: dataPath: ./my-data
+     * const pool = RuggyPool.fromConfig();
+     * await pool.withCollection('users', async (col) => { ... });
+     */
+    static fromConfig(options = {}) {
+        const { loadConfig } = require('./config');
+        const { reload, searchFrom, ...poolOptions } = options;
+        const config = loadConfig({ reload, searchFrom });
+        return new RuggyPool(config.dataPath, poolOptions);
+    }
+
+
+    /**
+     * Gets the database path
+     * @returns {string}
+     */
+    get path() {
+        return this.#path;
+    }
+
+    /**
+     * Checks if the pool is closed
+     * @returns {boolean}
+     */
+    get isClosed() {
+        return this.#closed;
+    }
+
+    /**
+     * Checks if there's an active connection
+     * @returns {boolean}
+     */
+    get isConnected() {
+        return this.#db !== null && this.#db.isOpen;
+    }
+
+    /**
+     * Gets the number of active operations
+     * @returns {number}
+     */
+    get activeOperations() {
+        return this.#activeOperations;
+    }
+
+    /**
+     * Gets the total number of operations performed
+     * @returns {number}
+     */
+    get totalOperations() {
+        return this.#totalOperations;
+    }
+
+    /**
+     * Gets pool statistics
+     * @returns {Object}
+     */
+    getStats() {
+        return {
+            path: this.#path,
+            connected: this.isConnected,
+            closed: this.#closed,
+            activeOperations: this.#activeOperations,
+            totalOperations: this.#totalOperations
+        };
+    }
+
+    /**
+     * @private
+     * Ensures a connection exists, creating one if needed
+     * @throws {Error} If pool is closed
+     */
+    #ensureConnection() {
+        if (this.#closed) {
+            throw new Error('Pool is closed');
+        }
+
+        if (!this.#db || !this.#db.isOpen) {
+            this.#db = new RuggyDatabase(this.#path);
+        }
+    }
+
+    /**
+     * Executes a callback with a database connection
+     * The connection is reused across calls (not closed after each operation)
+     * @param {Function} callback - Async function that receives the database
+     * @returns {Promise<*>} - Result of callback
+     * @throws {Error} If pool is closed or callback fails
+     */
+    async withDatabase(callback) {
+        if (typeof callback !== 'function') {
+            throw new Error('Callback must be a function');
+        }
+
+        this.#ensureConnection();
+        this.#activeOperations++;
+        this.#totalOperations++;
+
+        try {
+            return await callback(this.#db);
+        } catch (error) {
+            // Log error but don't close connection (it might be a user error)
+            throw error;
+        } finally {
+            this.#activeOperations--;
+        }
+    }
+
+    /**
+     * Alias for withDatabase for convenience
+     * @param {Function} callback - Async function that receives the database
+     * @returns {Promise<*>}
+     */
+    async withDB(callback) {
+        return this.withDatabase(callback);
+    }
+
+    /**
+     * Helper: Executes a callback with a collection from the pooled database
+     * @param {string} collectionName - Collection name
+     * @param {Function} callback - Async function that receives the collection
+     * @returns {Promise<*>} - Result of callback
+     */
+    async withCollection(collectionName, callback) {
+        return this.withDatabase(async (db) => {
+            return db.withCollection(collectionName, callback);
+        });
+    }
+
+    /**
+     * Closes the pooled connection and releases resources
+     * All active operations should complete before calling this
+     * Safe to call multiple times
+     */
+    close() {
+        if (this.#closed) {
+            return;
+        }
+
+        this.#closed = true;
+
+        if (this.#db) {
+            this.#db.close();
+            this.#db = null;
+        }
+    }
+
+    /**
+     * Waits for all active operations to complete, then closes the pool
+     * @param {number} timeoutMs - Maximum time to wait in milliseconds (default: 5000)
+     * @returns {Promise<void>}
+     * @throws {Error} If timeout is reached
+     */
+    async closeGracefully(timeoutMs = 5000) {
+        const startTime = Date.now();
+
+        while (this.#activeOperations > 0) {
+            if (Date.now() - startTime > timeoutMs) {
+                throw new Error(
+                    `Graceful shutdown timeout: ${this.#activeOperations} operations still active`
+                );
+            }
+            await new Promise(resolve => setTimeout(resolve, 10));
+        }
+
+        this.close();
+    }
+
+    /**
+     * Symbol.dispose implementation for "using" syntax (Node.js 20+)
+     */
+    [Symbol.dispose]() {
+        this.close();
+    }
+
+    /**
+     * Symbol.asyncDispose implementation for "await using" syntax
+     * Uses graceful shutdown
+     */
+    async [Symbol.asyncDispose]() {
+        await this.closeGracefully();
+    }
+}
+
+module.exports = RuggyPool;