Locality IDB

SQL-like query builder for IndexedDB with a type-safe, chainable API.

Official Documentation • Demo Application • Contributing

🚀 Quick Start

1. Installation

Install the package via your preferred package manager:

# npm
npm i locality-idb

# pnpm
pnpm add locality-idb

# yarn
yarn add locality-idb

# bun
bun add locality-idb

# deno
deno add npm:locality-idb

2. Usage

import { Locality, defineSchema, column } from 'locality-idb';

// Define your schema
const mySchema = defineSchema({
  users: {
    id: column.int().pk().auto(),
    name: column.text(),
    email: column.email().unique(),
    createdAt: column.timestamp(),
  },
  posts: {
    id: column.int().pk().auto(),
    userId: column.int().ref('users.id', {
      onDelete: 'cascade',
      onUpdate: 'cascade',
    }).index(),
    title: column.varchar(255),
    content: column.text(),
    createdAt: column.timestamp(),
  },
});

// Initialize database
const db = new Locality({
  dbName: 'my-app-db',
  schema: mySchema,
  version: 1,
});

// Insert data
const user = await db.insert('users').values({ name: 'Alice', email: '[email protected]' }).run();

// Query data
const users = await db.from('users').findAll();
const alice = await db.from('users').where((user) => user.email === '[email protected]').findFirst();

// Update data
await db.update('users').set({ name: 'Alice in Wonderland' }).where('id', 1).run();

// Delete data
await db.delete('users').where('id', 1).run();

For advanced usages and a complete reference, please visit the documentation website:

👉 https://locality-idb.vercel.app

✨ Features

Locality IDB comes packed with features designed to make IndexedDB simple, type-safe, and highly performant:

• 🎯 Type-Safe: Full TypeScript support with automatic type inference.
• 🔍 SQL-like Queries: Familiar query syntax inspired by modern ORMs (especially Drizzle).
• 🔒 Transactions: Execute multiple operations across tables with automatic rollback on failure.
• 🗄️ Foreign Key References: Define relationships between tables with foreign key references.
• 🚀 Modern API: Clean and intuitive interface for IndexedDB operations.
• 📦 Zero Dependencies: Comes with zero runtime dependencies.
• 🔄 Auto-Generation: Automatic UUID and timestamp generation during insertions.
• 🎨 Schema-First: Define your database schema with a simple, declarative API.
• 🛠️ Rich Column Types: Support for various data types including custom types.
• ✅ Built-in Validation: Validation for built-in column types during insert and update operations.
• 🔧 Custom Validators: Define custom validation logic for columns to enforce complex rules.
• 📤 Database Export: Export database data as JSON for backup, migration, or debugging.
• 📥 Database Import: Import exported data with 'merge', 'replace', or 'upsert' modes.

🎮 Live Demo

Check out the demo application in the demo/ directory for selective examples with basic CRUD, transactions, and database export/import and integrity tests.

You can also try the live web demo here:

👉 https://locality-idb-demo.vercel.app

📄 License

MIT © Nazmul Hassan

🔗 Links

• GitHub: nazmul-nhb/locality-idb
• Official Docs: https://locality-idb.vercel.app
• Demo Application: https://locality-idb-demo.vercel.app
• NPM Registry: locality-idb
• Author: Nazmul Hassan

Made with ❤️ by Nazmul Hassan

If you find this package useful, please consider giving it a ⭐ on GitHub!