Ruggy

A simple, fast embedded database for Node.js backed by Rust.

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

$3

#### 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

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

---

$3

#### 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