localdb

A lightweight browser-based localStorage database with real-time multi-tab sync and a clean proxy-based API — inspired by Appwrite.

Features

• 🗄️ localStorage — কোনো server ছাড়াই persistent storage
• ⚡ Real-time multi-tab sync — BroadcastChannel দিয়ে সব tab instantly update
• 🎯 Proxy-based API — db.users.create() এর মতো সহজ syntax
• 🔷 Full TypeScript — type-safe generics সহ
• 🪶 Zero dependencies — মাত্র ~2KB gzipped
• 🔔 Event system — .on() এবং .subscribe() দুটোই

Installation

# npm
npm install localdb

# bun
bun add localdb

# yarn
yarn add localdb

Quick Start

import Database from "localdb";

const db = new Database();

// Create
const user = await db.users.create({ name: "Abdullah", role: "admin" });

// List all
const users = await db.users.list();

// Filter
const admins = await db.users.list({ role: "admin" });

// Get one
const user = await db.users.get("some-id");

// Update
await db.users.update("some-id", { name: "Al Saif" });

// Delete
await db.users.delete("some-id");

TypeScript Generics

interface User {
  name: string;
  role: "admin" | "user";
  age: number;
}

// Type-safe collection
const user = await db.users.create<User>({ name: "Abdullah", role: "admin", age: 25 });
// user.$id, user.name, user.createdAt — সব typed

Real-time Events

.on() — নির্দিষ্ট event শোনো

// unsubscribe function return করে
const unsub = db.users.on("create", ({ event, payload }) => {
  console.log("নতুন user:", payload.name);
});

// cleanup
unsub();

.subscribe() — সব event (create, update, delete)

const unsub = db.users.subscribe(({ event, payload }) => {
  console.log(`[${event}]`, payload);
});

// cleanup
unsub();

Multi-tab Sync

Tab A-তে data পরিবর্তন করলে Tab B-তে subscriber instantly fire হবে:

// Tab A
await db.products.create({ title: "Keyboard", price: 1200 });

// Tab B — automatically triggered!
db.products.on("create", ({ payload }) => {
  console.log("নতুন product এলো:", payload.title);
});

API Reference

Collection Methods

| Method | Signature | Description | |--------|-----------|-------------| | list | (query?) => Promise<Doc[]> | সব document বা filtered list | | create | (data, id?) => Promise<Doc> | নতুন document তৈরি | | get | (id) => Promise<Doc> | একটি document | | update | (id, data) => Promise<Doc[]> | document update | | delete | (id) => Promise<Doc[]> | document delete | | on | (event, cb) => unsubFn | নির্দিষ্ট event শোনো | | subscribe | (cb) => unsubFn | সব event শোনো | | off | (event, cb) => void | listener সরাও | | unsubscribe | (cb) => void | সব listener সরাও |

Database Methods

db.clear("users");  // একটি collection মুছো
db.clear();         // সব collection মুছো
db.destroy();       // BroadcastChannel বন্ধ করো (cleanup)

Document Structure

প্রতিটি document-এ automatically যোগ হয়:

{
  $id: string;        // UUID (auto-generated বা custom)
  createdAt: string;  // UTC string
  updatedAt: string;  // UTC string
  ...yourData
}

React Example

import { useEffect, useState } from "react";
import Database, { Document } from "localdb";

const db = new Database();

interface Todo { text: string; done: boolean; }

function TodoApp() {
  const [todos, setTodos] = useState<Document<Todo>[]>([]);

  useEffect(() => {
    // initial load
    db.todos.list<Todo>().then(setTodos);

    // real-time sync (এই tab + অন্য সব tab)
    const unsub = db.todos.subscribe(() => {
      db.todos.list<Todo>().then(setTodos);
    });

    return unsub;
  }, []);

  const addTodo = async (text: string) => {
    await db.todos.create<Todo>({ text, done: false });
  };

  return (
    <div>
      {todos.map(todo => <div key={todo.$id}>{todo.text}</div>)}
      <button onClick={() => addTodo("নতুন কাজ")}>Add</button>
    </div>
  );
}

Browser Support

BroadcastChannel এবং localStorage সব modern browser সমর্থন করে।

| Chrome | Firefox | Safari | Edge | |--------|---------|--------|------| | ✅ 54+ | ✅ 38+ | ✅ 15.4+ | ✅ 79+ |

License

MIT © Abdullah Al Saif