Name	Name	Last commit message	Last commit date
Latest commit History 227 Commits
.github/workflows	.github/workflows
__tests__	__tests__
examples	examples
.gitignore	.gitignore
.npmignore	.npmignore
LICENSE	LICENSE
README.md	README.md
index.ts	index.ts
jest.config.mjs	jest.config.mjs
jest.setup.ts	jest.setup.ts
package-lock.json	package-lock.json
package.json	package.json
rollup.config.js	rollup.config.js
tsconfig.json	tsconfig.json

🚀 idb-ts

GitHub stars GitHub watchers Commits after release

📌 Introduction

idb-ts is a lightweight, declarative, and type-safe way to work with IndexedDB using TypeScript. Effortlessly perform CRUD operations on your database with clean, structured code! 🔥

📦 Installation

Install via npm and start using IndexedDB like a pro! ⚡

npm i idb-ts

✨ Features

✅ Declarative & Type-Safe - Define your data models with decorators.
⚡ Easy CRUD Operations - Perform create, read, update, and delete seamlessly.
🚀 Fully Typed API - Benefit from TypeScript’s powerful type system.
🏎️ Performance Optimized - Minimal overhead with IndexedDB's native capabilities.
🔄 Schema Versioning - Manage database schema evolution with automatic migration support.
🔑 Advanced Key Management - Auto-increment, UUID, timestamp, custom generators, and composite keys.

📖 Example Usage

🏗️ Declaring Entities

Use decorators to define your data models. Each class must have exactly one @KeyPath() and be decorated with @DataClass().

import { Database, DataClass, KeyPath, Index } from "idb-ts";
@DataClass()
class User {
 @KeyPath()
 id!: string;
 @Index()
 email!: string;
 name!: string;
 age!: number;
 constructor(id: string, name: string, age: number, email?: string) {
 this.id = id;
 this.name = name;
 this.age = age;
 this.email = email || `${name.toLowerCase()}@example.com`;
 }
}
@DataClass()
class Location {
 @KeyPath()
 id!: string;
 @Index()
 city!: string;
 country!: string;
 constructor(id: string, city: string, country: string) {
 this.id = id;
 this.city = city;
 this.country = country;
 }
}

🔄 CRUD Operations

Perform database operations using the repository API:

const db = await Database.build("idb-crud", [User, Location]);
const alice = new User("u1", "Alice", 25);
const bob = new User("u2", "Bob", 30);
const nyc = new Location("1", "New York", "USA");
const sf = new Location("2", "San Francisco", "USA");
await db.User.create(alice);
await db.User.create(bob);
await db.Location.create(nyc);
await db.Location.create(sf);
const readAlice = await db.User.read("u1");
console.log("👤 Read user:", readAlice);
alice.age = 26;
await db.User.update(alice);
const users = await db.User.list();
console.log("📋 All users:", users);
// Pagination
const page1 = await db.User.listPaginated(1, 2); // page 1, 2 users per page
console.log("📄 Page 1:", page1);
await db.User.delete("u1");
console.log("❌ User Alice deleted.");
const remainingUsers = await db.User.list();
console.log("🔍 Remaining users:", remainingUsers);
const locations = await db.Location.list();
console.log("🌍 All locations:", locations);

🔍 Indexing Support

Create indexes on fields for fast querying. Query indexes using the repository API:

@DataClass()
class Product {
 @KeyPath()
 id!: string;
 @Index()
 category!: string;
 @Index()
 price!: number;
 name!: string;
 description!: string;
 constructor(id: string, category: string, price: number, name: string, description: string) {
 this.id = id;
 this.category = category;
 this.price = price;
 this.name = name;
 this.description = description;
 }
}
const db = await Database.build("products-db", [Product]);
const electronics = await db.Product.findByIndex('category', 'Electronics');
const expensiveItems = await db.Product.findByIndex('price', 999.99);
const firstElectronic = await db.Product.findOneByIndex('category', 'Electronics');

Index Methods:

findByIndex(indexName, value): Promise<T[]> - Find all records matching the index value
findOneByIndex(indexName, value): Promise<T | undefined> - Find the first record matching the index value

Error Handling

If you query a non-existent index, an error is thrown:

await db.Product.findByIndex('nonexistent', 'value'); // throws

🔑 Multi-Field & Composite Key Support

idb-ts provides flexible key management options including auto-increment keys, key generators, and composite keys for complex data relationships.

Auto-Increment Keys

Perfect for entities where you want the database to automatically generate sequential IDs:

@DataClass()
class Task {
 @KeyPath({ autoIncrement: true })
 id!: number;
 title!: string;
 completed!: boolean;
 constructor(title: string, completed = false) {
 this.title = title;
 this.completed = completed;
 }
}
const db = await Database.build("tasks-db", [Task]);
// IDs are automatically generated: 1, 2, 3, etc.
const task1 = await db.Task.create(new Task("Learn TypeScript"));
const task2 = await db.Task.create(new Task("Build amazing apps"));
console.log(task1.id); // 1
console.log(task2.id); // 2

Key Generators

Generate keys automatically using built-in generators:

UUID Keys

@DataClass()
class Document {
 @KeyPath({ generator: 'uuid' })
 uuid!: string;
 @Index()
 category!: string;
 title!: string;
 content!: string;
 constructor(category: string, title: string, content: string) {
 this.category = category;
 this.title = title;
 this.content = content;
 }
}
const db = await Database.build("docs-db", [Document]);
const doc = await db.Document.create(new Document("tutorial", "Getting Started", "Welcome..."));
console.log(doc.uuid); // e.g., "a1b2c3d4-e5f6-7890-abcd-ef1234567890"

Timestamp Keys

@DataClass()
class Event {
 @KeyPath({ generator: 'timestamp' })
 timestamp!: number;
 @Index()
 type!: string;
 data!: any;
 constructor(type: string, data: any) {
 this.type = type;
 this.data = data;
 }
}
const event = await db.Event.create(new Event("user_login", { userId: "123" }));
console.log(event.timestamp); // e.g., 1696118400000

Random Keys

@DataClass()
class Session {
 @KeyPath({ generator: 'random' })
 sessionId!: string;
 userId!: string;
 expiresAt!: Date;
 constructor(userId: string, expiresAt: Date) {
 this.userId = userId;
 this.expiresAt = expiresAt;
 }
}
const session = await db.Session.create(new Session("user123", new Date()));
console.log(session.sessionId); // e.g., "xyz789abc123"

Custom Key Generators

Create your own key generation logic:

@DataClass()
class Invoice {
 @KeyPath({ generator: (entity: any) => `INV-${entity.year}-${String(entity.number).padStart(4, '0')}` })
 invoiceId!: string;
 year!: number;
 number!: number;
 amount!: number;
 constructor(year: number, number: number, amount: number) {
 this.year = year;
 this.number = number;
 this.amount = amount;
 }
}
const invoice = await db.Invoice.create(new Invoice(2024, 1, 1500.00));
console.log(invoice.invoiceId); // "INV-2024-0001"

Composite Keys

Handle many-to-many relationships with composite keys using the @CompositeKeyPath decorator:

import { CompositeKeyPath } from "idb-ts";
@CompositeKeyPath(['userId', 'projectId'])
@DataClass()
class UserProject {
 userId!: string;
 projectId!: string;
 @Index()
 role!: string;
 joinedAt!: Date;
 constructor(userId: string, projectId: string, role: string) {
 this.userId = userId;
 this.projectId = projectId;
 this.role = role;
 this.joinedAt = new Date();
 }
}
const db = await Database.build("collaboration-db", [UserProject]);
// Create relationships
await db.UserProject.create(new UserProject("user123", "project456", "developer"));
await db.UserProject.create(new UserProject("user123", "project789", "admin"));
await db.UserProject.create(new UserProject("user456", "project456", "viewer"));
// Read with composite key
const relationship = await db.UserProject.read(['user123', 'project456']);
console.log(relationship?.role); // "developer"
// Update relationship
if (relationship) {
 relationship.role = "maintainer";
 await db.UserProject.update(relationship);
}
// Delete with composite key
await db.UserProject.delete(['user123', 'project789']);
// Query by role index
const developers = await db.UserProject.findByIndex('role', 'developer');

Key Generation Utilities

Access key generators directly for your custom logic:

import { KeyGenerators } from "idb-ts";
const uuid = KeyGenerators.uuid(); // Generate UUID
const timestamp = KeyGenerators.timestamp(); // Current timestamp
const random = KeyGenerators.random(); // Random string

🔄 Schema Versioning

idb-ts supports schema versioning to manage database evolution over time. Version your entities and let the library handle automatic migration!

Basic Usage

@DataClass({ version: 1 })
class User {
 @KeyPath() id!: string;
 @Index() email!: string;
 name!: string;
}
@DataClass({ version: 2 })
class Post {
 @KeyPath() id!: string;
 @Index() authorId!: string;
 title!: string;
 content!: string;
}
@DataClass({ version: 3 })
class Comment {
 @KeyPath() id!: string;
 @Index() postId!: string;
 @Index() authorId!: string;
 text!: string;
}
// Database version will be 3 (highest entity version)
const db = await Database.build("blog", [User, Post, Comment]);
console.log(db.getDatabaseVersion()); // 3
console.log(db.getEntityVersions()); // Map with entity versions

Key Features

Automatic Version Calculation: Database version = highest entity version
Seamless Migration: Only new/updated entities are processed during upgrades
Backward Compatibility: Entities without version default to version 1
Index Evolution: New indexes are automatically created during migration

Version Management

// Check versions
const dbVersion = db.getDatabaseVersion();
const entityVersions = db.getEntityVersions();
const userVersion = db.getEntityVersion('User');
// Version upgrade flow:
// v1.0: User(v1) → Database v1
// v1.1: User(v1), Post(v2) → Database v2 
// v1.2: User(v1), Post(v2), Comment(v3) → Database v3

📖 Complete Schema Versioning Guide - Detailed documentation with examples and best practices.

🔗 Useful Links

📂 GitHub: maifeeulasad/idb-ts
📦 NPM: idb-ts
Demo: https://maifeeulasad.github.io/idb-ts/
Code Coverage report: https://maifeeulasad.github.io/idb-ts/coverage/lcov-report/

🎉 Enjoy seamless IndexedDB integration with TypeScript! Happy coding! 🚀

License

maifeeulasad/idb-ts

Folders and files

Latest commit

History

Repository files navigation