ctrodb and the case for client-side databases using IndexedDB

Client-Side Databases Are Underrated

For the last five years, I've worked on web apps that follow the same pattern: build a backend, set up Postgres, wire up REST endpoints, fetch data on the client, cache it in React state or Redux. Somewhere along the way, I realized a lot of the data I was sending to the server never needed to go there. Form drafts. UI preferences. Search indexes. Cached API responses. Offline queues. All of it lives on the client already — it just takes a detour through the network for no real reason. The latency tax A round-trip to the server costs 200-500ms on a fast connection. On mobile, it's worse. Multiply that by every interaction that needs data, and your app feels sluggish even when the UI is technically fast. The typical fix is caching: store API responses in localStorage, serve stale data while re-fetching, invalidate caches manually. It works, but it's fighting the architecture. You're maintaining two copies of the same data — one in a cache, one in state — and hoping they stay in sync. A client-side database flips the model: data lives where it's used. The server mediates shared state, auth, and writes that need coordination. Everything else stays in the browser. What a client-side database gives you The same primitives you'd expect from a server-side database, running in-process: Schema validation at write time Queries with filtering, sorting, and pagination Indexes for fast lookups Transactions for atomic multi-collection operations Reactivity — subscribe to changes and re-render automatically No network calls. No connection pooling. No serialization overhead. A concrete example I built ctrodb to explore this pattern. It's a client-side database that runs in the browser (IndexedDB) with zero dependencies: import { Database } from "ctrodb" const db = new Database({ name: "app" }) await db.connect() const todos = db.collection("todos") await todos.create({ title: "Try ctrodb", done: false }) const pending = await todos .query() .where("done", false) .sort({ createdAt: "desc" }) .fetch() Every record is a Model with typed field access. Update a record, and any React component using useQuery re-renders automatically. When it makes sense Client-side databases aren't for everything. But they shine for: Offline-first apps — notes, tasks, journaling tools Local-first architecture — data lives in the browser, sync with a server when needed Search-heavy UIs — full-text search indexes can live on the client Form-heavy apps — multi-step forms, draft-saving, autosave Prototypes — skip the backend entirely during early development The architecture shift The mental model is subtle but powerful. Instead of "fetch from API → store in state → render", you think "query local database → render → sync to server". Your UI becomes a view into a local database. No cache invalidation. No loading spinners for data that's already on disk. The database is the store. If you're curious, ctrodb is open source. Check it out on npm at https://www.npmjs.com/package/ctrodb, try the playground at https://ctrodb.vercel.app/playground, or browse the docs at https://ctrodb.vercel.app/docs.

16 hours ago

ctrodb: A Client-Side Database for TypeScript — Zero Dependencies

I've been working on ctrodb — a client-side database for TypeScript that runs in the browser (IndexedDB) and Node.js (in-memory). Zero runtime dependencies. It started as a personal project to stop rewriting IndexedDB wrappers. Every new client-side app needed the same boilerplate: open a connection, create object stores, handle version upgrades, write CRUD helpers. After the sixth time, I wrote it once and got it right. What it does ctrodb gives you MongoDB-like CRUD with schema validation at write time: import { Database } from "ctrodb" const db = new Database({ name: "my-app", schema: { version: 1, collections: { notes: { fields: { title: { type: "string", required: true }, body: { type: "string" }, pinned: { type: "boolean", default: false }, tags: { type: "array", items: { type: "string" } }, createdAt: { type: "string", default: () => new Date().toISOString() }, }, indexes: [{ field: "createdAt" }], }, }, }, }) await db.connect() const notes = db.collection("notes") const note = await notes.create({ title: "Hello", body: "World" }) const results = await notes.query() .where("pinned", true) .sort({ createdAt: "desc" }) .limit(10) .fetch() Every record is a Model — a Proxy wrapper with typed field access. note.title works. note.update() handles writes. Direct property assignment logs a warning telling you to use .update() instead. What's included The core package ships with three plugins: Full-text search — inverted index, stop word removal, auto-indexed on create/update/delete Relations — has_many, belongs_to, has_one with lazy accessors built into every Model and eager loading via .with() Custom validation — extendable rules beyond the built-in validators (email, URL, regex) Plus React hooks (separate import, same package): import { DatabaseProvider, useQuery, useMutation } from "ctrodb/react" Signal-based reactivity. When data changes, useQuery re-fetches and your UI updates. No Redux, no Zustand, no manual subscriptions. Why zero dependencies The library ships as ESM, CJS, and IIFE. Works with any bundler, any framework, or directly in a <script> tag. The entire source is 2,400 lines — readable, debuggable, and easy to contribute to. Try it There's a browser playground at https://ctrodb.vercel.app/playground where you can run all 7 examples without installing anything. npm install ctrodb GitHub: https://github.com/ctrotech-tutor/ctrodb Docs: https://ctrodb.vercel.app/docs NPM: https://www.npmjs.com/package/ctrodb I'd love feedback on the API, the plugin system, or anything else.

1 day ago