ruggy 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,65 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.1.0] - 2026-01-04
+
+### Added
+- Initial release of Ruggy embedded database
+- Basic CRUD operations (insert, findAll, find)
+- Connection pooling with `RuggyPool`
+- YAML configuration support via `ruggy.yaml`
+- Configuration loader with automatic file discovery
+- `Database.fromConfig()` and `Pool.fromConfig()` factory methods
+- Full TypeScript type definitions
+- Comprehensive README with examples
+- Support for Node.js 14+
+- Windows x64 pre-built binaries
+
+### Features
+- Native Rust backend with FFI bindings
+- Embedded database (no external server required)
+- Simple and intuitive API
+- Persistent storage with append-only files
+- Flexible YAML configuration
+- TypeScript support with complete definitions
+
+### Platform Support
+- Windows x64 - Pre-built binaries included
+- Linux - Not supported at this time
+- macOS - Not supported at this time
+
+### Known Limitations
+- Single-platform binary distribution (Windows only)
+- No query operators (only exact match)
+- No indexes (linear scan)
+- No transactions
+- No schema validation
+
+### Dependencies
+- koffi ^2.8.0 - FFI bindings
+- js-yaml ^4.1.0 - YAML configuration parsing
+
+---
+
+## [Unreleased]
+
+### Planned for 0.2.0
+- Linux and macOS pre-built binaries
+- Configurable limits (maxCollectionSize, maxDocumentSize)
+- Logging configuration
+- Performance tuning options
+
+### Future Enhancements
+- Backup automation
+- Compression support
+- Query operators (range, comparison)
+- Basic indexing
+- Encryption at rest
+
+---
+
+[0.1.0]: https://github.com/Mub1522/ruggy/releases/tag/v0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Andres Diaz
+
+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,315 @@
+<div align="center">
+  <img src="https://raw.githubusercontent.com/Mub1522/ruggy/main/assets/icon.jpeg" alt="Ruggy Logo" width="200"/>
+</div>
+
+<h1 style="text-align: center;">Ruggy</h1>
+
+<p style="text-align: center;">A simple, fast embedded database for Node.js backed by Rust.</p>
+
+## Features
+
+- **Fast** - Native Rust backend with FFI bindings
+- **Embedded** - No separate database server required
+- **Simple** - Clean, intuitive API
+- **Persistent** - Data stored in append-only files
+- **Type-Safe** - Full TypeScript support
+- **Configurable** - YAML configuration for flexible deployment
+
+## Installation
+
+```bash
+npm install ruggy
+```
+
+## Quick Start
+
+```javascript
+const { RuggyDatabase } = require('ruggy');
+
+// Create/open database
+const db = new RuggyDatabase('./data');
+
+// Get a collection
+const users = db.collection('users');
+
+// Insert documents
+const id = users.insert({ name: 'Alice', email: 'alice@example.com' });
+
+// Find all documents
+const allUsers = users.findAll();
+
+// Find by field
+const results = users.find('email', 'alice@example.com');
+
+// Close when done
+db.close();
+```
+
+## Platform Support
+
+| Platform | Status | Pre-built Binaries |
+|----------|--------|-------------------|
+| **Windows x64** | ✅ Fully Supported | ✅ Included |
+| **Linux x64** | Not supported | Not included |
+| **macOS (Intel)** | Not supported | Not included |
+| **macOS (ARM)** | Not supported | Not included |
+
+> **Note:** Version 0.1.0 includes pre-built binaries for Windows only. Linux and macOS users will need Rust installed to build from source. Multi-platform binaries are planned for v0.2.0.
+
+## Configuration
+
+Create a `ruggy.yaml` file in your project root to configure the database path:
+
+```yaml
+dataPath: ./my-database
+# or use absolute path
+# dataPath: /var/data/ruggy
+```
+
+Then use the configuration-based factory:
+
+```javascript
+const { RuggyDatabase } = require('ruggy');
+
+// Automatically uses path from ruggy.yaml
+const db = RuggyDatabase.fromConfig();
+```
+
+If no `ruggy.yaml` is found, Ruggy defaults to `./data`.
+
+## API Reference
+
+### RuggyDatabase
+
+#### Constructor
+
+```javascript
+new RuggyDatabase(path: string)
+```
+
+Creates a new database at the specified path.
+
+#### Static Methods
+
+**`RuggyDatabase.fromConfig(options?)`**
+
+Creates a database instance using `ruggy.yaml` configuration.
+
+- **options.reload** `boolean` - Force reload configuration (bypass cache)
+- **options.searchFrom** `string` - Directory to start searching for `ruggy.yaml`
+
+**`RuggyDatabase.withDatabase(path, callback)`**
+
+Automatically manages database lifecycle.
+
+```javascript
+await RuggyDatabase.withDatabase('./data', async (db) => {
+  const users = db.collection('users');
+  users.insert({ name: 'Bob' });
+  // Database automatically closed after callback
+});
+```
+
+#### Instance Methods
+
+**`collection(name: string): RuggyCollection`**
+
+Gets or creates a collection.
+
+**`withCollection(name, callback): Promise<any>`**
+
+Executes callback with a collection, automatically closing it after.
+
+```javascript
+await db.withCollection('users', async (users) => {
+  const id = users.insert({ name: 'Charlie' });
+  return id;
+});
+```
+
+**`close(): void`**
+
+Closes the database and releases resources.
+
+**Properties:**
+- `path: string` - Database path
+- `isOpen: boolean` - Whether database is open
+
+---
+
+### RuggyCollection
+
+#### Instance Methods
+
+**`insert(data: Object): string | null`**
+
+Inserts a document and returns generated ID.
+
+```javascript
+const id = collection.insert({ name: 'Alice', age: 30 });
+```
+
+**`findAll(): Array<Object>`**
+
+Returns all documents in the collection.
+
+**`find(field: string, value: any): Array<Object>`**
+
+Finds documents where field matches value.
+
+```javascript
+const adults = collection.find('age', '30');
+```
+
+**`close(): void`**
+
+Closes the collection and releases resources.
+
+**Properties:**
+- `name: string` - Collection name
+- `isOpen: boolean` - Whether collection is open
+
+---
+
+### RuggyPool
+
+Connection pool for long-running applications.
+
+#### Constructor
+
+```javascript
+new RuggyPool(path: string, options?)
+```
+
+**Options:**
+- `lazyConnect: boolean` - Don't open DB until first use (default: `true`)
+
+#### Static Methods
+
+**`RuggyPool.fromConfig(options?)`**
+
+Creates a pool instance using `ruggy.yaml` configuration.
+
+```javascript
+const pool = RuggyPool.fromConfig();
+```
+
+#### Instance Methods
+
+**`withDatabase(callback): Promise<any>`**
+
+Executes callback with the pooled database connection.
+
+**`withCollection(name, callback): Promise<any>`**
+
+Executes callback with a collection from the pool.
+
+```javascript
+const pool = new RuggyPool('./data');
+
+await pool.withCollection('users', async (users) => {
+  users.insert({ name: 'Dave' });
+});
+
+await pool.closeGracefully();
+```
+
+**`close(): void`**
+
+Immediately closes the pool.
+
+**`closeGracefully(timeoutMs?): Promise<void>`**
+
+Waits for active operations to complete before closing.
+
+**`getStats(): Object`**
+
+Returns pool statistics (connected, activeOperations, totalOperations).
+
+**Properties:**
+- `path: string` - Database path
+- `isConnected: boolean` - Whether pool has active connection
+- `isClosed: boolean` - Whether pool is closed
+- `activeOperations: number` - Current active operations
+- `totalOperations: number` - Total operations performed
+
+## Examples
+
+### Basic CRUD Operations
+
+```javascript
+const { RuggyDatabase } = require('ruggy');
+const db = new RuggyDatabase('./data');
+
+const products = db.collection('products');
+
+// Create
+const id = products.insert({
+  name: 'Laptop',
+  price: 999,
+  category: 'electronics'
+});
+
+// Read
+const all = products.findAll();
+const electronics = products.find('category', 'electronics');
+
+// Close
+db.close();
+```
+
+### Using Connection Pool
+
+```javascript
+const { RuggyPool } = require('ruggy');
+const pool = RuggyPool.fromConfig(); // Uses ruggy.yaml
+
+// Multiple concurrent operations
+await Promise.all([
+  pool.withCollection('users', async (col) => {
+    col.insert({ name: 'User 1' });
+  }),
+  pool.withCollection('logs', async (col) => {
+    col.insert({ event: 'startup' });
+  })
+]);
+
+await pool.closeGracefully();
+```
+
+### Using Modern Syntax (Node.js 20+)
+
+```javascript
+{
+  using db = new RuggyDatabase('./data');
+  const users = db.collection('users');
+  users.insert({ name: 'Eve' });
+  // Automatically closed when leaving scope
+}
+```
+
+
+
+## Performance
+
+Ruggy is optimized for embedded use cases with thousands of documents. For large-scale applications, consider a full database server.
+
+**Benchmarks** (approximate):
+- Insert: ~10,000 ops/sec
+- FindAll: ~50,000 ops/sec
+- Find by field: ~20,000 ops/sec
+
+## License
+
+MIT
+
+## Contributing
+
+Contributions welcome! Please open an issue or submit a pull request.
+
+## Acknowledgments
+
+Built with:
+- [Koffi](https://github.com/Koromix/koffi) - FFI bindings
+- [js-yaml](https://github.com/nodeca/js-yaml) - YAML parsing
+- [Rust](https://www.rust-lang.org/) - Native backend

package/index.d.ts

@@ -0,0 +1,288 @@
+// Type definitions for Ruggy
+// Project: Ruggy
+// Definitions by: Andres Diaz
+
+/// <reference types="node" />
+
+/**
+ * Configuration options for loading ruggy.yaml
+ */
+export interface ConfigOptions {
+    /** Force reload configuration (bypass cache) */
+    reload?: boolean;
+    /** Directory to start searching for ruggy.yaml */
+    searchFrom?: string;
+}
+
+/**
+ * Pool creation options
+ */
+export interface PoolOptions {
+    /** If true, don't open DB until first use (default: true) */
+    lazyConnect?: boolean;
+}
+
+/**
+ * Combined configuration and pool options
+ */
+export interface PoolConfigOptions extends ConfigOptions, PoolOptions { }
+
+/**
+ * Pool statistics
+ */
+export interface PoolStats {
+    /** Database path */
+    path: string;
+    /** Whether pool has active connection */
+    connected: boolean;
+    /** Whether pool is closed */
+    closed: boolean;
+    /** Current active operations */
+    activeOperations: number;
+    /** Total operations performed */
+    totalOperations: number;
+}
+
+/**
+ * Ruggy Collection - Represents a collection in the database
+ */
+export class RuggyCollection {
+    /**
+     * Collection name
+     */
+    readonly name: string;
+
+    /**
+     * Whether the collection is open
+     */
+    readonly isOpen: boolean;
+
+    /**
+     * Inserts a document into the collection
+     * @param data - Document to insert
+     * @returns Generated document ID or null on error
+     */
+    insert(data: Record<string, any>): string | null;
+
+    /**
+     * Finds all documents in the collection
+     * @returns Array of documents
+     */
+    findAll(): Array<Record<string, any>>;
+
+    /**
+     * Finds documents matching a field-value pair
+     * @param field - Field name to search
+     * @param value - Value to match
+     * @returns Array of matching documents
+     */
+    find(field: string, value: any): Array<Record<string, any>>;
+
+    /**
+     * Closes the collection and frees native resources
+     */
+    close(): void;
+
+    /**
+     * Symbol.dispose implementation for "using" syntax (Node.js 20+)
+     */
+    [Symbol.dispose](): void;
+
+    /**
+     * Symbol.asyncDispose implementation for "await using" syntax
+     */
+    [Symbol.asyncDispose](): Promise<void>;
+}
+
+/**
+ * Ruggy Database - A simple, fast embedded database
+ */
+export class RuggyDatabase {
+    /**
+     * Creates a new database connection
+     * @param dbPath - Path to the database directory
+     */
+    constructor(dbPath: string);
+
+    /**
+     * Database path
+     */
+    readonly path: string;
+
+    /**
+     * Whether the database is open
+     */
+    readonly isOpen: boolean;
+
+    /**
+     * Gets a collection (creates if doesn't exist)
+     * @param name - Collection name
+     * @returns Collection instance
+     */
+    collection(name: string): RuggyCollection;
+
+    /**
+     * Alias for collection() for semantic clarity
+     * @param name - Collection name
+     * @returns Collection instance
+     */
+    createCollection(name: string): RuggyCollection;
+
+    /**
+     * Helper: Automatically manages collection lifecycle
+     * @param name - Collection name
+     * @param callback - Async function that receives the collection
+     * @returns Result of callback
+     */
+    withCollection<T>(name: string, callback: (collection: RuggyCollection) => Promise<T>): Promise<T>;
+
+    /**
+     * Closes the database and frees native resources
+     */
+    close(): void;
+
+    /**
+     * Static helper: Automatically manages database lifecycle
+     * @param path - Database path
+     * @param callback - Async function that receives the database
+     * @returns Result of callback
+     */
+    static withDatabase<T>(path: string, callback: (db: RuggyDatabase) => Promise<T>): Promise<T>;
+
+    /**
+     * Static factory: Creates a database instance using ruggy.yaml configuration
+     * @param options - Configuration options
+     * @returns Database instance configured from YAML
+     */
+    static fromConfig(options?: ConfigOptions): RuggyDatabase;
+
+    /**
+     * Symbol.dispose implementation for "using" syntax (Node.js 20+)
+     */
+    [Symbol.dispose](): void;
+
+    /**
+     * Symbol.asyncDispose implementation for "await using" syntax
+     */
+    [Symbol.asyncDispose](): Promise<void>;
+}
+
+/**
+ * Ruggy Pool - Connection pool for long-running applications
+ */
+export class RuggyPool {
+    /**
+     * Creates a new connection pool
+     * @param path - Database path
+     * @param options - Pool options
+     */
+    constructor(path: string, options?: PoolOptions);
+
+    /**
+     * Database path
+     */
+    readonly path: string;
+
+    /**
+     * Whether the pool is closed
+     */
+    readonly isClosed: boolean;
+
+    /**
+     * Whether there's an active connection
+     */
+    readonly isConnected: boolean;
+
+    /**
+     * Number of active operations
+     */
+    readonly activeOperations: number;
+
+    /**
+     * Total number of operations performed
+     */
+    readonly totalOperations: number;
+
+    /**
+     * Gets pool statistics
+     * @returns Pool statistics object
+     */
+    getStats(): PoolStats;
+
+    /**
+     * Executes a callback with a database connection
+     * @param callback - Async function that receives the database
+     * @returns Result of callback
+     */
+    withDatabase<T>(callback: (db: RuggyDatabase) => Promise<T>): Promise<T>;
+
+    /**
+     * Alias for withDatabase
+     * @param callback - Async function that receives the database
+     * @returns Result of callback
+     */
+    withDB<T>(callback: (db: RuggyDatabase) => Promise<T>): Promise<T>;
+
+    /**
+     * Helper: Executes a callback with a collection from the pooled database
+     * @param collectionName - Collection name
+     * @param callback - Async function that receives the collection
+     * @returns Result of callback
+     */
+    withCollection<T>(collectionName: string, callback: (collection: RuggyCollection) => Promise<T>): Promise<T>;
+
+    /**
+     * Closes the pooled connection and releases resources
+     */
+    close(): void;
+
+    /**
+     * Waits for all active operations to complete, then closes the pool
+     * @param timeoutMs - Maximum time to wait in milliseconds (default: 5000)
+     */
+    closeGracefully(timeoutMs?: number): Promise<void>;
+
+    /**
+     * Static factory: Creates a pool instance using ruggy.yaml configuration
+     * @param options - Combined configuration and pool options
+     * @returns Pool instance configured from YAML
+     */
+    static fromConfig(options?: PoolConfigOptions): RuggyPool;
+
+    /**
+     * Symbol.dispose implementation for "using" syntax (Node.js 20+)
+     */
+    [Symbol.dispose](): void;
+
+    /**
+     * Symbol.asyncDispose implementation for "await using" syntax
+     */
+    [Symbol.asyncDispose](): Promise<void>;
+}
+
+/**
+ * Configuration loader
+ */
+export interface Config {
+    /** Database data path */
+    dataPath: string;
+}
+
+/**
+ * Loads Ruggy configuration from ruggy.yaml or returns defaults
+ * @param options - Configuration options
+ * @returns Configuration object
+ */
+export function loadConfig(options?: ConfigOptions): Config;
+
+/**
+ * Clears the cached configuration
+ */
+export function clearCache(): void;
+
+/**
+ * Default configuration values
+ */
+export const DEFAULT_CONFIG: Config;
+
+export { RuggyDatabase, RuggyCollection, RuggyPool };