@waelio/realdb

A local-first, reactive database for JavaScript & TypeScript.
Works in browsers, Node.js, and edge runtimes — no native dependencies.

import { RealDB } from '@waelio/realdb'

interface Task { title: string; done: boolean }

const db = new RealDB({ name: 'myApp' })
await db.open()

const tasks = db.collection<Task>('tasks')

const task = await tasks.insert({ title: 'Build realdb', done: false })
await tasks.update(task.id, { done: true })

tasks.subscribe((event) => {
  console.log(event.type, event.document)
})

Features

• 🔷 Fully typed — generics flow end-to-end, from schema to query results
• ⚡ Reactive — subscribe to collection changes with collection.subscribe()
• 🔌 Pluggable adapters — swap storage without changing your app code
• 🧪 Testable — MemoryAdapter is the default, perfect for unit tests
• 🌐 Universal — runs anywhere that speaks ES2020+

Installation

npm install @waelio/realdb

Quick Start

import { RealDB, LocalStorageAdapter } from '@waelio/realdb'

interface Note { text: string; pinned: boolean }

// Use LocalStorage in the browser
const db = new RealDB({
  name: 'notes-app',
  adapter: new LocalStorageAdapter('notes-app'),
})
await db.open()

const notes = db.collection<Note>('notes')

// Insert
const note = await notes.insert({ text: 'Hello realdb', pinned: false })

// Find with filters
const pinned = await notes.find({
  filter: [{ field: 'pinned', op: 'eq', value: true }],
  sort:   [{ field: 'createdAt', direction: 'desc' }],
  limit:  10,
})

// Update
await notes.update(note.id, { pinned: true })

// Delete
await notes.delete(note.id)

// Subscribe to changes
const sub = notes.subscribe((event) => {
  console.log(`[${event.type}]`, event.document)
})

sub.unsubscribe() // stop listening

Storage Adapters

| Adapter | Import | Persists? | Best For | |---------|--------|-----------|----------| | MemoryAdapter | 'realdb' | ❌ No | Tests, SSR, edge runtimes | | LocalStorageAdapter | 'realdb' | ✅ Yes | Browser apps |

Bring your own by implementing the StorageAdapter interface:

import type { StorageAdapter } from '@waelio/realdb'

class MyAdapter implements StorageAdapter {
  name = 'my-adapter'
  async init(collection: string) { /* ... */ }
  async getAll(collection: string) { /* ... */ }
  async getById(collection: string, id: string) { /* ... */ }
  async put(collection: string, doc: unknown) { /* ... */ }
  async delete(collection: string, id: string) { /* ... */ }
  async clear(collection: string) { /* ... */ }
  async destroy() { /* ... */ }
}

Query API

Filters

await tasks.find({
  filter: [
    { field: 'done',     op: 'eq',       value: false },
    { field: 'priority', op: 'gte',      value: 2 },
    { field: 'title',    op: 'contains', value: 'realdb' },
  ],
})

| Operator | Description | |----------|-------------| | eq / neq | Equal / not equal | | gt / gte / lt / lte | Numeric comparisons | | in / nin | Value in / not in array | | contains | String contains | | startsWith / endsWith | String prefix / suffix |

Sort, Limit, Offset

await tasks.find({
  sort:   [{ field: 'priority', direction: 'desc' }],
  limit:  20,
  offset: 40,
})

Reactive Subscriptions

const sub = tasks.subscribe((event) => {
  // event.type     → 'insert' | 'update' | 'delete'
  // event.document → the new/current document
  // event.previous → the old document (update/delete only)
})

sub.unsubscribe()

API Reference

RealDB

| Method / Property | Description | |---|---| | new RealDB(config) | Create a database instance | | db.open() | Open the database (call once) | | db.close() | Shut down and free resources | | db.collection<T>(name, schema?) | Get or create a collection | | db.collectionNames | Array of registered collection names | | db.isOpen | Whether the DB is open | | db.name | Database name | | db.adapterName | Active adapter's name |

Collection<T>

| Method | Description | |---|---| | insert(data) | Create a new document | | insertMany(items) | Create multiple documents | | findById(id) | Find one by ID | | find(options?) | Find with filter/sort/limit/offset | | findAll() | All documents, newest first | | count(options?) | Count matching documents | | update(id, patch) | Partial update | | replace(id, data) | Full replace | | delete(id) | Delete one | | deleteMany(options?) | Delete matching | | clear() | Wipe collection | | subscribe(callback) | Watch for changes |

License

MIT © Peace Marshal