EasyDB

Multi-backend storage with async/await, async iterables, and modern JavaScript — IndexedDB, SQLite, PostgreSQL, MySQL/MariaDB, Redis, Turso, D1, KV, localStorage.

Inspired by Cloudflare's "We deserve a better streams API" philosophy — applying pull semantics, zero ceremony, and native fast paths to client-side and edge storage.

Why?

IndexedDB was designed in 2011 with DOM events. Reading a single record requires ~18 lines of callback-based code. EasyDB reduces that to one:

const user = await db.users.get(42);

And the same API works across browsers (IndexedDB), Node.js (SQLite, PostgreSQL, MySQL/MariaDB, Redis), edge (D1, KV, Turso), and tests (Memory) — swap the adapter, keep your code.

Features

10 storage adapters — IndexedDB, Memory, SQLite, PostgreSQL, MySQL/MariaDB, Redis, Turso, D1, KV, localStorage
7 framework integrations — React, Vue, Svelte, Angular, Solid.js, Preact, Lit
~400 LOC core, zero dependencies — thin ergonomic wrapper, not a framework
Proxy-based store access — db.users, db.orders without registration
Async iterables — for await (const user of db.users.all()) with true pull-based cursors
Range queries — .gt(), .lt(), .between() using native key ranges
Fluent query builder — .where('role', 'admin').filter(u => u.age > 30).limit(10).toArray()
Transactions — multi-store with auto-rollback on throw
Watch — for await (const change of db.users.watch()) reactive observation
Cross-tab sync — watch events broadcast across browser tabs via BroadcastChannel
Cross-adapter sync — push, pull, or bidirectional replication between any two adapters
Migrations — versioned schema migrations with migrations: { 1: fn, 2: fn }
Fast paths — toArray() uses getAll() when possible; count() uses native count
Batch operations — putMany(), getMany()
TypeScript — full type declarations with generic schema support
~4.4KB gzip (browser bundle)

Installation

npm install @rckflr/easydb

Quick Start

Browser (IndexedDB — default)

import { EasyDB } from '@rckflr/easydb';

const db = await EasyDB.open('myApp', {
  schema(s) {
    s.createStore('users', {
      key: 'id',
      indexes: ['role', 'age', { name: 'email', unique: true }]
    });
    s.createStore('orders', { key: 'orderId', indexes: ['userId'] });
  }
});

// CRUD
await db.users.put({ id: 1, name: 'Alice', role: 'admin', age: 32 });
const user = await db.users.get(1);
await db.users.delete(1);

// Query
const admins = await db.users
  .where('role', 'admin')
  .filter(u => u.age > 30)
  .limit(5)
  .toArray();

// Range queries
const adults = await db.users.where('age').between(18, 65).toArray();

// Async iteration with pull cursor
for await (const user of db.users.all()) {
  console.log(user.name);
  if (user.role === 'admin') break; // cursor closes, no wasted reads
}

Node.js (SQLite)

import { EasyDB } from '@rckflr/easydb';
import { SQLiteAdapter } from '@rckflr/easydb/adapters/sqlite';

const db = await EasyDB.open('app', {
  adapter: new SQLiteAdapter('./my-data.db'),  // or ':memory:' for testing
  schema(s) {
    s.createStore('users', { key: 'id', indexes: ['email'] });
    s.createStore('posts', { key: 'id', autoIncrement: true });
  }
});
// Same API — full ACID transactions via better-sqlite3

Node.js (PostgreSQL)

import { PostgresAdapter } from '@rckflr/easydb/adapters/postgres';
import { Pool } from 'pg';

const pool = new Pool({ connectionString: process.env.DATABASE_URL });
const db = await EasyDB.open('app', {
  adapter: new PostgresAdapter(pool),
  schema(s) {
    s.createStore('users', { key: 'id', indexes: ['role'] });
  }
});

Node.js (MySQL / MariaDB)

import { MySQLAdapter } from '@rckflr/easydb/adapters/mysql';
import mysql from 'mysql2/promise';

const pool = mysql.createPool({ host: 'localhost', user: 'root', database: 'app' });
const db = await EasyDB.open('app', {
  adapter: new MySQLAdapter(pool),
  schema(s) {
    s.createStore('users', { key: 'id', indexes: ['role'] });
  }
});

Node.js (Redis)

import { RedisAdapter } from '@rckflr/easydb/adapters/redis';
import Redis from 'ioredis';

const redis = new Redis(process.env.REDIS_URL);
const db = await EasyDB.open('app', {
  adapter: new RedisAdapter(redis),
  schema(s) {
    s.createStore('sessions', { key: 'id' });
  }
});

Edge (Turso / libSQL)

import { TursoAdapter } from '@rckflr/easydb/adapters/turso';
import { createClient } from '@libsql/client';

const client = createClient({ url: process.env.TURSO_URL, authToken: process.env.TURSO_TOKEN });
const db = await EasyDB.open('app', {
  adapter: new TursoAdapter(client),
  schema(s) {
    s.createStore('users', { key: 'id', indexes: ['email'] });
  }
});

Cloudflare Workers (D1)

import { EasyDB, D1Adapter } from '@rckflr/easydb';

export default {
  async fetch(request, env) {
    const db = await EasyDB.open('app', {
      adapter: new D1Adapter(env.DB),
      schema(s) {
        s.createStore('users', { key: 'id', indexes: ['role'] });
      }
    });
    const user = await db.users.get(1);
    return Response.json(user);
  }
};

Testing / SSR (Memory)

import { EasyDB, MemoryAdapter } from '@rckflr/easydb';

const db = await EasyDB.open('test', {
  adapter: new MemoryAdapter(),
  schema(s) {
    s.createStore('users', { key: 'id' });
  }
});
// Same API — no browser, no polyfill needed

Framework Integrations

EasyDB provides reactive bindings for 7 UI frameworks. All integrations auto-refresh when data changes via watch().

React

import { useQuery, useRecord, useSyncStatus } from '@rckflr/easydb/react';

function UserList({ db }) {
  const { data, loading, error } = useQuery(db.users);
  if (loading) return <p>Loading...</p>;
  return data.map(u => <p key={u.id}>{u.name}</p>);
}

function UserProfile({ db, userId }) {
  const { data: user } = useRecord(db.users, userId);
  return <h1>{user?.name}</h1>;
}

// Track sync status reactively:
function SyncIndicator({ syncEngine }) {
  const { running, paused, lastEvent, error } = useSyncStatus(syncEngine);
  if (error) return <p>Sync error: {error.err.message}</p>;
  return <p>Sync: {running ? (paused ? 'paused' : 'active') : 'stopped'}</p>;
}

Vue 3

import { useQuery, useRecord, useSyncStatus } from '@rckflr/easydb/vue';

// In <script setup>:
const { data, loading, error } = useQuery(db.users);
const admins = useQuery(db.users.where('role', 'admin'));

// Reactive key (re-fetches when ref changes):
const userId = ref(1);
const { data: user } = useRecord(db.users, userId);

// Track sync status (reactive refs, auto-cleanup via onUnmounted):
const { running, paused, lastEvent, error } = useSyncStatus(syncEngine);

Svelte

import { queryStore, recordStore, syncStatusStore } from '@rckflr/easydb/svelte';

const users = queryStore(db.users);
// {#if $users.loading} ... {:else} {#each $users.data as user} ... {/each} {/if}

// Track sync status:
const status = syncStatusStore(syncEngine);
// {#if $status.running}Syncing...{/if}
// {#if $status.error}Error: {$status.error.err.message}{/if}

Angular 16+

import { createQuery, createRecord, createSyncStatus } from '@rckflr/easydb/angular';

@Component({ template: `@for (user of users.data(); track user.id) { ... }` })
class UserList {
  users = createQuery(db.users);          // Signal-based
  admins = createQuery(() => db.users.where('role', 'admin'));  // Reactive
  sync = createSyncStatus(syncEngine);    // sync.running(), sync.lastEvent()
}

Solid.js

import { createQuery, createRecord, createSyncStatus } from '@rckflr/easydb/solid';

function UserList() {
  const users = createQuery(db.users);
  const sync = createSyncStatus(syncEngine);
  return <>
    <Show when={sync.running()}>Syncing...</Show>
    <For each={users.data()}>{u => <p>{u.name}</p>}</For>
  </>;
}

Preact

import { useQuery, useRecord, useSyncStatus } from '@rckflr/easydb/preact';
// Same API as React — drop-in replacement (includes useSyncStatus)

Lit

import { EasyDBQueryController, EasyDBSyncStatusController } from '@rckflr/easydb/lit';

class UserList extends LitElement {
  _users = new EasyDBQueryController(this, db.users);
  _sync = new EasyDBSyncStatusController(this, syncEngine);
  render() {
    const { data, loading } = this._users;
    return loading ? html`<p>Loading...</p>` : html`<ul>${data.map(u => html`<li>${u.name}</li>`)}</ul>`;
  }
}

Migrations

Use the migrations API for versioned schema changes. Only new migrations run on upgrade.

const db = await EasyDB.open('myApp', {
  migrations: {
    1: (s) => {
      s.createStore('users', { key: 'id', indexes: ['role'] });
    },
    2: (s) => {
      s.createStore('orders', { key: 'orderId', indexes: ['userId'] });
    },
    3: (s) => {
      s.createStore('logs', { key: 'id', autoIncrement: true });
    }
  }
});

// Version is auto-inferred from highest key (3 in this case)
// Re-opening at a higher version only runs migrations > current version

Watch

Observe mutations reactively with async iterables:

// Watch all mutations on a store
for await (const event of db.users.watch()) {
  console.log(event.type, event.key, event.value);
  // type: 'put' | 'delete' | 'clear'
}

// Watch a specific key
for await (const event of db.users.watch({ key: 42 })) {
  console.log('User 42 changed:', event);
}

Cross-tab sync

In browsers with BroadcastChannel support, watch events automatically propagate across tabs:

// Tab 1
for await (const event of db.users.watch()) {
  console.log('Change from any tab:', event);
}

// Tab 2
await db.users.put({ id: 1, name: 'Updated in tab 2' });
// Tab 1's watcher fires with the put event

Sync

Synchronize data between any two EasyDB instances (e.g. browser ↔ server, IndexedDB ↔ PostgreSQL):

import { SyncEngine } from '@rckflr/easydb/sync';

const local  = await EasyDB.open('app', { adapter: idbAdapter, schema });
const remote = await EasyDB.open('app', { adapter: pgAdapter, schema });

const sync = new SyncEngine(local, remote, {
  stores: ['users', 'orders'],
  direction: 'bidirectional',   // 'push' | 'pull' | 'bidirectional'
  conflict: 'last-write-wins',  // 'source-wins' | 'target-wins' | 'last-write-wins' | 'manual'
  timestampField: 'updatedAt',
  onSync(event) { console.log(event.store, event.type, event.key); },
});

// Real-time sync (watch-based for push, polling for pull)
sync.start();

// Pause/resume
sync.pause();                // events queue up
await sync.resume();         // flush queued events

// One-time full sync
await sync.syncAll();        // reconcile all stores
await sync.syncStore('users'); // single store

sync.stop();                 // stop and clean up

Programmatic sync monitoring

Use addListener() to track sync events and lifecycle changes outside of framework hooks:

const unsub = sync.addListener({
  onSync(event) { console.log('synced:', event.store, event.type); },
  onError(err, ctx) { console.error('sync error:', ctx.store, err); },
  onStatusChange({ running, paused }) { console.log({ running, paused }); },
});

// Call unsub() when done. Safe for multiple concurrent listeners.

Custom conflict resolution

const sync = new SyncEngine(local, remote, {
  stores: ['users'],
  conflict: 'manual',
  onConflict(store, key, sourceVal, targetVal) {
    // Merge strategy: keep source name, keep higher score
    return {
      ...sourceVal,
      score: Math.max(sourceVal.score, targetVal.score),
    };
  },
});

Transactions

Multi-store transactions with automatic rollback on error:

await db.transaction(['users', 'orders'], async (tx) => {
  const user = await tx.users.get(1);
  user.orderCount += 1;
  await tx.users.put(user);
  await tx.orders.put({ orderId: 'abc', userId: 1 });
  // throw → everything rolls back
});

API Reference

`EasyDB.open(name, options?)`

Opens or creates a database. Returns Promise<EasyDB>.

Option	Type	Default	Description
`version`	`number`	`1`	Schema version
`schema`	`(builder, oldVersion) => void`	—	Schema definition callback
`migrations`	`Record<number, fn>`	—	Versioned migrations (alternative to `schema`)
`adapter`	`Adapter`	`IDBAdapter`	Storage backend

`EasyDB.destroy(name, options?)`

Deletes a database. Pass { adapter } when using a non-default backend.

Instance properties

Property	Description
`db.stores`	Array of store names
`db.version`	Current database version
`db.store(name)`	Explicit store access (for names that collide with methods)
`db.close()`	Close connection and clean up watchers

Store access (`db.storeName`)

Accessed via Proxy — any property returns a store accessor.

Method	Description
`.get(key)`	Get single record
`.getAll()`	Get all records
`.getMany(keys)`	Batch get
`.put(value)`	Insert or update (returns key)
`.putMany(items)`	Batch insert/update (returns count)
`.delete(key)`	Delete by key
`.clear()`	Delete all records
`.count()`	Count records
`.all()`	Returns `QueryBuilder` for all records
`.where(index, value?)`	Returns `QueryBuilder` with index filter
`.watch(opts?)`	Returns async iterable of mutation events

`QueryBuilder`

Chainable, immutable query builder. Implements Symbol.asyncIterator.

Method	Description
`.gt(value)`	Greater than
`.gte(value)`	Greater than or equal
`.lt(value)`	Less than
`.lte(value)`	Less than or equal
`.between(lo, hi)`	Inclusive range
`.filter(fn)`	JS-side predicate (composable — multiple are ANDed)
`.limit(n)`	Max results
`.skip(n)`	Skip first N results
`.page(num, size)`	Pagination (1-indexed)
`.desc()`	Reverse order
`.asc()`	Forward order (default)
`.toArray()`	Collect all results
`.first()`	Get first result
`.count()`	Count matching results

Adapters

EasyDB uses a pluggable adapter architecture. All adapters implement the same interface, so your application code stays identical.

Adapter	Import	Runtime	Persistence
`IDBAdapter`	`@rckflr/easydb`	Browser	IndexedDB
`MemoryAdapter`	`@rckflr/easydb`	Anywhere	In-memory
`SQLiteAdapter`	`@rckflr/easydb/adapters/sqlite`	Node.js	File / in-memory
`PostgresAdapter`	`@rckflr/easydb/adapters/postgres`	Node.js	PostgreSQL
`MySQLAdapter`	`@rckflr/easydb/adapters/mysql`	Node.js	MySQL / MariaDB
`RedisAdapter`	`@rckflr/easydb/adapters/redis`	Node.js	Redis
`TursoAdapter`	`@rckflr/easydb/adapters/turso`	Node.js / Edge	Turso / libSQL
`D1Adapter`	`@rckflr/easydb`	Cloudflare Workers	D1 (SQLite)
`KVAdapter`	`@rckflr/easydb`	Cloudflare Workers	KV
`LocalStorageAdapter`	`@rckflr/easydb/adapters/localstorage`	Browser	localStorage

Writing a custom adapter

Implement the Adapter interface:

class MyAdapter {
  async open(name, options) {
    // Return an object implementing AdapterConnection:
    // name, version, storeNames, hasStore(), getKeyPath(), close(),
    // get(), getAll(), count(), getMany(),
    // put(), delete(), clear(), putMany(),
    // cursor() (async generator), transaction()
  }
  async destroy(name) { /* delete the database */ }
}

See src/adapters/memory.js for a complete reference implementation.

Architecture

Your code (async/await)
        |
   EasyDB API (Proxy + AsyncIterable)
        |
   ┌────┼────────────────────┐
   |    |                    |
Tx Mgr   QueryBuilder    Watch Engine
(auto      (pull cursor     (cross-tab
rollback)   + range          BroadcastChannel)
             + filter)
   |    |                    |
   └────┼────────────────────┘
        |
   Adapter Interface
        |
   ┌──────┬──────┬──────┬──────┬──────┬──────┬──────┬──────┬──────┬──────┐
  IDB  Memory  SQLite  PG   MySQL Redis Turso  D1    KV  localStorage

Bundle Size

CDN Bundle	Raw	Gzip
`easydb.mjs.js` (ESM)	13.9 KB	4.4 KB
`easydb.iife.js`	14.4 KB	4.6 KB
`easydb.umd.js`	14.7 KB	4.8 KB

Framework integrations: ~0.6–0.7 KB gzip each.

Build CDN bundles: npm run build

TypeScript

EasyDB ships with full type declarations. Use generic schemas for type-safe store access:

interface MySchema {
  users: { id: number; name: string; role: string };
  orders: { orderId: string; total: number };
}

const db = await EasyDB.open<MySchema>('app', { ... });
const user = await db.users.get(1);        // MySchema['users'] | undefined
const admins = await db.users.where('role', 'admin').toArray();  // MySchema['users'][]

Known Limitations

IndexedDB adapter

Transactions auto-commit when there are no pending IDB requests in the event loop. Avoid await fetch() inside a transaction.
No compound indexes — use .filter() for JS-side compound predicates.

SQL adapters (D1, SQLite, PostgreSQL, MySQL/MariaDB, Turso)

Transactions are emulated with SAVEPOINT/BEGIN/snapshot depending on adapter.
.filter() runs JS-side after the SQL query.

Redis adapter

All queries fetch records and filter in JS (no native range queries).
Transactions are best-effort with rollback on error.

General

No JOINs, GROUP BY, or SQL — use raw drivers for complex analytical queries.

Comparison with Alternatives

Feature	EasyDB	Dexie.js	idb	SQLite WASM
Size	~400 LOC core	~15k LOC	~2KB	~800KB WASM
Multi-backend	10 adapters	IndexedDB only	IndexedDB only	SQLite only
Framework bindings	7 frameworks	React	No	No
Async iterables	Pull cursor	Callback-based	No	No
Range queries	Native	Native	Manual	SQL
Watch/reactive	Cross-tab	Advanced LiveQuery	No	No
Transactions	Auto-rollback	Robust	Yes	Yes
Migrations	Versioned map	Version-based	Manual	SQL migrations
TypeScript	Generic schemas	Included	Included	Varies
Dependencies	0	0	0	WASM binary

Documentation

Browser Compatibility — supported browsers, runtimes, and CDN usage
Migration Guide — migrating from raw IndexedDB or Dexie.js
Adapter Comparison — choosing the right adapter for your use case
Contributing — how to contribute to EasyDB

Development

git clone https://github.com/MauricioPerera/easydb.git
cd easydb
npm install
npm test            # Run all 730 tests
npm run build       # Generate CDN bundles (dist/)
npm run bench       # Run benchmarks
npm run metrics     # Show LOC and gzip sizes

Context

This project emerged from a discussion about Cloudflare's blog post "We deserve a better streams API for JavaScript" by James M Snell, which argues that Web Streams carry design decisions from 2014 that don't align with modern JavaScript.

We asked: what other JS APIs deserve the same treatment? IndexedDB was the obvious candidate — an API from 2011 that predates async/await, async iterables, and Proxy, all of which are now standard JavaScript.

EasyDB started as a proof of concept and evolved into a multi-backend storage library with 10 adapters and 7 framework integrations — demonstrating that modern JavaScript primitives can provide a clean, unified storage API across environments.

License

MIT

Author

Mauricio Perera — Automators.work

Name		Name	Last commit message	Last commit date
Latest commit History 64 Commits
.github		.github
benchmarks		benchmarks
demo		demo
docs		docs
examples		examples
scripts		scripts
src		src
tests		tests
.gitignore		.gitignore
CHANGELOG.md		CHANGELOG.md
CONTRIBUTING.md		CONTRIBUTING.md
DESIGN.md		DESIGN.md
LICENSE		LICENSE
README.md		README.md
ROADMAP.md		ROADMAP.md
SECURITY.md		SECURITY.md
docker-compose.yml		docker-compose.yml
package-lock.json		package-lock.json
package.json		package.json
vitest.config.frameworks.js		vitest.config.frameworks.js
vitest.config.integration.js		vitest.config.integration.js
vitest.config.js		vitest.config.js

Folders and files

Latest commit

History

Repository files navigation

EasyDB

Why?

Features

Installation

Quick Start

Browser (IndexedDB — default)

Node.js (SQLite)

Node.js (PostgreSQL)

Node.js (MySQL / MariaDB)

Node.js (Redis)

Edge (Turso / libSQL)

Cloudflare Workers (D1)

Testing / SSR (Memory)

Framework Integrations

React

Vue 3

Svelte

Angular 16+

Solid.js

Preact

Lit

Migrations

Watch

Cross-tab sync

Sync

Programmatic sync monitoring

Custom conflict resolution

Transactions

API Reference

EasyDB.open(name, options?)

EasyDB.destroy(name, options?)

Instance properties

Store access (db.storeName)

QueryBuilder

Adapters

Writing a custom adapter

Architecture

Bundle Size

TypeScript

Known Limitations

IndexedDB adapter

SQL adapters (D1, SQLite, PostgreSQL, MySQL/MariaDB, Turso)

Redis adapter

General

Comparison with Alternatives

Documentation

Development

Context

License

Author

About

Topics

Resources

License

Contributing

Security policy

Uh oh!

Stars

Watchers

Forks

Releases 1

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

`EasyDB.open(name, options?)`

`EasyDB.destroy(name, options?)`

Store access (`db.storeName`)

`QueryBuilder`

Packages