idb-ts 3.3.0 → 3.7.0

package/README.md

@@ -39,37 +39,47 @@ npm i idb-ts
 - ⚡ **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 with automatic schema management.
+Use decorators to define your data models. Each class must have exactly one `@KeyPath()` and be decorated with `@DataClass()`.
 
 ```typescript
+import { Database, DataClass, KeyPath, Index } from "idb-ts";
+
 @DataClass()
 class User {
   @KeyPath()
-  name: string;
-  age: number;
-  cell?: string;
-  address: string;
+  id!: string;
+
+  @Index()
+  email!: string;
 
-  constructor(name: string, age: number, address: string, cell?: string) {
+  name!: string;
+  age!: number;
+
+  constructor(id: string, name: string, age: number, email?: string) {
+    this.id = id;
     this.name = name;
     this.age = age;
-    this.address = address;
-    this.cell = cell;
+    this.email = email || `${name.toLowerCase()}@example.com`;
   }
 }
 
 @DataClass()
 class Location {
   @KeyPath()
-  id: string;
-  city: string;
-  country: string;
+  id!: string;
+
+  @Index()
+  city!: string;
+
+  country!: string;
 
   constructor(id: string, city: string, country: string) {
     this.id = id;
@@ -80,42 +90,345 @@ class Location {
 ```
 
 ### 🔄 CRUD Operations
-Perform database operations in an intuitive way:
+Perform database operations using the repository API:
 
 ```typescript
 const db = await Database.build("idb-crud", [User, Location]);
 
-const alice = new User("Alice", 25, "123 Main St");
+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.create(User, alice);
-await db.create(Location, nyc);
+await db.User.create(alice);
+await db.User.create(bob);
+await db.Location.create(nyc);
+await db.Location.create(sf);
 
-const readAlice = await db.read(User, "Alice");
+const readAlice = await db.User.read("u1");
 console.log("👤 Read user:", readAlice);
 
 alice.age = 26;
-alice.address = "789 Maple St";
-await db.update(User, alice);
+await db.User.update(alice);
 
-const users = await db.list(User);
+const users = await db.User.list();
 console.log("📋 All users:", users);
 
-await db.delete(User, "Alice");
+// 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.list(User);
+const remainingUsers = await db.User.list();
 console.log("🔍 Remaining users:", remainingUsers);
 
-const locations = await db.list(Location);
+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:
+
+```typescript
+@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:
+  ```typescript
+  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:
+
+```typescript
+@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
+```typescript
+@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
+```typescript
+@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
+```typescript
+@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:
+
+```typescript
+@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:
+
+```typescript
+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:
+
+```typescript
+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
+
+```typescript
+@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
+
+```typescript
+// 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](./SCHEMA_VERSIONING.md)** - Detailed documentation with examples and best practices.
+
 ---
 
 ## 🔗 Useful Links
 - 📂 **GitHub**: [maifeeulasad/idb-ts](https://github.com/maifeeulasad/idb-ts)
 - 📦 **NPM**: [idb-ts](https://www.npmjs.com/package/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!** 🚀
 

package/lib/index.d.ts

@@ -1,31 +1,84 @@
 import 'reflect-metadata';
-declare function KeyPath(): PropertyDecorator;
-declare function DataClass(): ClassDecorator;
+type QueryDirection = 'asc' | 'desc';
+declare class QueryBuilder<T> {
+    private db;
+    private storeName;
+    private conditions;
+    private orderField?;
+    private orderDirection;
+    private limitCount?;
+    private offsetCount?;
+    private indexName?;
+    private rangeStart?;
+    private rangeEnd?;
+    private currentField?;
+    constructor(db: IDBDatabase, storeName: string);
+    where(field: string): this;
+    and(field: string): this;
+    equals(value: any): this;
+    gt(value: any): this;
+    gte(value: any): this;
+    lt(value: any): this;
+    lte(value: any): this;
+    orderBy(field: string, direction?: QueryDirection): this;
+    limit(n: number): this;
+    offset(n: number): this;
+    useIndex(indexName: string): this;
+    range(start: any, end: any): this;
+    execute(): Promise<T[]>;
+}
+interface KeyPathOptions {
+    autoIncrement?: boolean;
+    generator?: 'uuid' | 'timestamp' | 'random' | ((item?: any) => string | number);
+}
+interface KeyPathMetadata {
+    fields: string | string[];
+    options?: KeyPathOptions;
+}
+declare class KeyGenerators {
+    static uuid(): string;
+    static timestamp(): number;
+    static random(): string;
+}
+declare function KeyPath(options?: KeyPathOptions): PropertyDecorator;
+declare function CompositeKeyPath(fields: string[], options?: KeyPathOptions): ClassDecorator;
+declare function Index(): PropertyDecorator;
+interface DataClassOptions {
+    version?: number;
+}
+declare function DataClass(options?: DataClassOptions): ClassDecorator;
+interface EntityRepository<T> {
+    create(item: T): Promise<void>;
+    read(key: string | string[] | number): Promise<T | undefined>;
+    update(item: T): Promise<void>;
+    delete(key: string | string[] | number): Promise<void>;
+    list(): Promise<T[]>;
+    listPaginated(page: number, pageSize: number): Promise<T[]>;
+    findByIndex(indexName: string, value: any): Promise<T[]>;
+    findOneByIndex(indexName: string, value: any): Promise<T | undefined>;
+    count(): Promise<number>;
+    exists(key: string): Promise<boolean>;
+    clear(): Promise<void>;
+    query(): QueryBuilder<T>;
+}
+type DatabaseWithRepositories<T extends Record<string, any>> = Database & T;
 declare class Database {
     private dbName;
     private classes;
     private db;
+    private entityRepositories;
+    private dbVersion;
     private constructor();
-    static build(dbName: string, classes: Function[]): Promise<Database>;
+    private calculateDatabaseVersion;
+    static build<T extends Record<string, EntityRepository<any>>>(dbName: string, classes: Function[]): Promise<DatabaseWithRepositories<T>>;
     private initDB;
-    private getObjectStore;
-    create<T>(cls: {
-        new (...args: any[]): T;
-    }, item: T): Promise<void>;
-    read<T>(cls: {
-        new (...args: any[]): T;
-    }, key: string): Promise<T | undefined>;
-    update<T>(cls: {
-        new (...args: any[]): T;
-    }, item: T): Promise<void>;
-    delete<T>(cls: {
-        new (...args: any[]): T;
-    }, key: string): Promise<void>;
-    list<T>(cls: {
-        new (...args: any[]): T;
-    }): Promise<T[]>;
-    listPaginated<T>(cls: {
-        new (...args: any[]): T;
-    }, page: number, pageSize: number): Promise<T[]>;
+    private generateEntityRepositories;
+    private createEntityRepository;
+    private performOperation;
+    getAvailableEntities(): string[];
+    getDatabaseVersion(): number;
+    getEntityVersions(): Map<string, number>;
+    getEntityVersion(entityName: string): number | undefined;
 }
-export { Database, KeyPath, DataClass };
+export { Database, KeyPath, CompositeKeyPath, DataClass, Index, EntityRepository, KeyGenerators };
+export type { DatabaseWithRepositories, DataClassOptions, KeyPathOptions, KeyPathMetadata };