idb-ts 3.11.1 → 3.12.0

package/README.md

@@ -24,12 +24,14 @@
   </a>
 </p>
 
-
 ## 📌 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! ⚡
+
 ```sh
 npm i idb-ts     # for pure npm users
 pnpm add idb-ts  # for pnpm users
@@ -37,6 +39,7 @@ yarn add idb-ts  # for yarn users
 ```
 
 ## ✨ 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.
@@ -49,10 +52,11 @@ yarn add idb-ts  # for yarn users
 ## 📖 Example Usage
 
 ### 🏗️ Declaring Entities
+
 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";
+import { Database, DataClass, KeyPath, Index } from 'idb-ts';
 
 @DataClass()
 class User {
@@ -92,45 +96,47 @@ class Location {
 ```
 
 ### 🔄 CRUD Operations
+
 Perform database operations using the repository API:
 
 ```typescript
-const db = await Database.build("idb-crud", [User, Location]);
+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");
+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);
+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);
+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);
+console.log('📄 Page 1:', page1);
 
-await db.User.delete("u1");
-console.log("❌ User Alice deleted.");
+await db.User.delete('u1');
+console.log('❌ User Alice deleted.');
 
 const remainingUsers = await db.User.list();
-console.log("🔍 Remaining users:", remainingUsers);
+console.log('🔍 Remaining users:', remainingUsers);
 
 const locations = await db.Location.list();
-console.log("🌍 All locations:", locations);
+console.log('🌍 All locations:', locations);
 ```
 
 ### 🔍 Indexing Support
+
 Create indexes on fields for fast querying. Query indexes using the repository API:
 
 ```typescript
@@ -148,7 +154,13 @@ class Product {
   name!: string;
   description!: string;
 
-  constructor(id: string, category: string, 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;
@@ -157,14 +169,18 @@ class Product {
   }
 }
 
-const db = await Database.build("products-db", [Product]);
+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');
+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
 
@@ -199,7 +215,9 @@ Example:
 ```ts
 @RetentionPolicy({ seconds: 60 * 60 * 24 * 30 }) // 30 days
 @DataClass()
-class Session { /* ... */ }
+class Session {
+  /* ... */
+}
 
 // Database will run a periodic cleanup that removes sessions older than 30 days
 ```
@@ -223,7 +241,10 @@ class User {
   @KeyPath()
   id!: string;
 
-  @Validate((v) => typeof v === 'string' && v.includes('@'), 'must be a valid email')
+  @Validate(
+    (v) => typeof v === 'string' && v.includes('@'),
+    'must be a valid email',
+  )
   email!: string;
 
   @Validate((v) => typeof v === 'number' && v >= 0, 'age must be >= 0')
@@ -255,6 +276,7 @@ await db.User.deleteMany(['u1', 'u2']);
 Performance note: `createMany` will trigger validation and key generation per item. If you need large batch inserts frequently, batching these into a single transaction or adding a dedicated bulk API may improve throughput.
 
 #### Error Handling
+
 - If you query a non-existent index, an error is thrown:
   ```typescript
   await db.Product.findByIndex('nonexistent', 'value'); // throws
@@ -267,6 +289,7 @@ Performance note: `createMany` will trigger validation and key generation per it
 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
@@ -284,19 +307,21 @@ class Task {
   }
 }
 
-const db = await Database.build("tasks-db", [Task]);
+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"));
+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 {
@@ -316,13 +341,16 @@ class Document {
   }
 }
 
-const db = await Database.build("docs-db", [Document]);
+const db = await Database.build('docs-db', [Document]);
 
-const doc = await db.Document.create(new Document("tutorial", "Getting Started", "Welcome..."));
+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 {
@@ -340,11 +368,12 @@ class Event {
   }
 }
 
-const event = await db.Event.create(new Event("user_login", { userId: "123" }));
+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 {
@@ -360,17 +389,21 @@ class Session {
   }
 }
 
-const session = await db.Session.create(new Session("user123", new Date()));
+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')}` })
+  @KeyPath({
+    generator: (entity: any) =>
+      `INV-${entity.year}-${String(entity.number).padStart(4, '0')}`,
+  })
   invoiceId!: string;
 
   year!: number;
@@ -384,15 +417,16 @@ class Invoice {
   }
 }
 
-const invoice = await db.Invoice.create(new Invoice(2024, 1, 1500.00));
+const invoice = await db.Invoice.create(new Invoice(2024, 1, 1500.0));
 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";
+import { CompositeKeyPath } from 'idb-ts';
 
 @CompositeKeyPath(['userId', 'projectId'])
 @DataClass()
@@ -413,12 +447,14 @@ class UserProject {
   }
 }
 
-const db = await Database.build("collaboration-db", [UserProject]);
+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"));
+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']);
@@ -426,7 +462,7 @@ console.log(relationship?.role); // "developer"
 
 // Update relationship
 if (relationship) {
-  relationship.role = "maintainer";
+  relationship.role = 'maintainer';
   await db.UserProject.update(relationship);
 }
 
@@ -438,16 +474,113 @@ 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";
+import { KeyGenerators } from 'idb-ts';
 
-const uuid = KeyGenerators.uuid();        // Generate UUID
+const uuid = KeyGenerators.uuid(); // Generate UUID
 const timestamp = KeyGenerators.timestamp(); // Current timestamp
-const random = KeyGenerators.random();    // Random string
+const random = KeyGenerators.random(); // Random string
+```
+
+### Transaction API
+
+idb-ts provides a simple, atomic Transaction API that lets you group multiple repository operations into a single native IndexedDB transaction. Operations performed inside a transaction are committed together or discarded together on failure.
+
+Usage — callback form (automatic commit/rollback):
+
+```ts
+await db.transaction(async (tx) => {
+  await tx.User.create(user);
+  await tx.Order.create(order);
+  await tx.OrderItem.create(item);
+  // If the callback returns successfully, the transaction is committed.
+  // If an exception is thrown, the transaction is aborted and all writes are rolled back.
+});
 ```
 
+Usage — explicit control:
+
+```ts
+const tx = await db.beginTransaction(['User', 'Order'], 'readwrite');
+try {
+  await tx.User.create(user);
+  await tx.Order.create(order);
+  await tx.commit(); // explicitly commit, but optional
+} catch (e) {
+  await tx.rollback(); // abort and rollback
+}
+```
+
+Key notes and behavior:
+
+- Atomicity: all repository writes that use the transaction handle (`tx.Entity.*`) share the same native `IDBTransaction` and are atomic — either all succeed (commit) or none persist (abort/rollback).
+- Scope: `beginTransaction` accepts an array of entity names (e.g., `['User','Order']`) and opens a native transaction over those object stores. The callback form uses a transaction covering all registered entities.
+- Querying inside transactions: use `tx.Entity.query()` or other `tx.Entity.*` repository methods to ensure those reads/writes are performed on the same underlying transaction.
+- Modes: transactions support standard IndexedDB modes (`'readonly'` or `'readwrite'`). The default for `beginTransaction` and the callback wrapper is `'readwrite'`.
+- Commit/abort semantics: modern browsers may perform implicit commit when the transaction's event loop completes; `commit()` is called when available. `rollback()` triggers `transaction.abort()`.
+- Error handling: if an error is thrown in the callback form the library will call `rollback()` and rethrow the error to the caller.
+- Limitations: composite operations that span many stores still must list all involved entity names when using `beginTransaction`. Long-running synchronous work inside a transaction can increase the risk of versionchange or blocked events — keep transaction work asynchronous and short.
+
+Example patterns:
+
+- Batch inserts in one transaction for performance and atomic safety.
+- Run a read-modify-write sequence in a single transaction to avoid lost updates.
+
+The Transaction API is covered by the test suite in `__tests__/transaction.test.ts` which demonstrates both the callback and explicit modes.
+
+### Advanced Querying
+
+`idb-ts` includes a typed query builder for field-level filtering, logical grouping, and basic aggregations. The available operators are constrained by the field type, so string-only and array-only operations are only exposed where they make sense.
+
+```ts
+const users = await db.User.query()
+  .where('name').startsWith('John')
+  .and('email').endsWith('@gmail.com')
+  .and('description').contains('important')
+  .execute();
+
+const activeOrTrial = await db.User.query()
+  .where('age').gte(18)
+  .or()
+  .where('hasParentalConsent').equals(true)
+  .execute();
+
+const premiumUsers = await db.User.query()
+  .where((qb) =>
+    qb.where('type').equals('premium').and('status').equals('active'),
+  )
+  .or()
+  .where('isTrial').equals(true)
+  .execute();
+```
+
+Supported operators include:
+
+- String operations: `startsWith`, `endsWith`, `contains`, `matches`
+- Range operations: `between`, `notBetween`
+- Collection operations: `contains`, `containsAny`, `containsAll`, `in`, `notIn`
+- Logical chaining: `and()`, `or()`, and grouped predicates via `where((qb) => ...)`
+
+Aggregations are available directly on the query builder:
+
+```ts
+await db.Order.query().sum('amount');
+await db.Order.query().avg('price');
+await db.Order.query().min('date');
+await db.Order.query().max('date');
+await db.Order.query().groupBy('status').count();
+```
+
+Notes:
+
+- `sum()` and `avg()` are numeric-only.
+- `min()` and `max()` are available for comparable scalar fields.
+- `groupBy(...).count()` returns grouped counts by the selected field.
+- TypeScript will reject unsupported operator/field combinations at compile time.
+
 ---
 
 ## 🔄 Schema Versioning
@@ -481,7 +614,7 @@ class Comment {
 }
 
 // Database version will be 3 (highest entity version)
-const db = await Database.build("blog", [User, Post, Comment]);
+const db = await Database.build('blog', [User, Post, Comment]);
 
 console.log(db.getDatabaseVersion()); // 3
 console.log(db.getEntityVersions()); // Map with entity versions
@@ -504,17 +637,17 @@ const userVersion = db.getEntityVersion('User');
 
 // Version upgrade flow:
 // v1.0: User(v1) -> Database v1
-// v1.1: User(v1), Post(v2) -> Database v2  
+// v1.1: User(v1), Post(v2) -> Database v2
 // v1.2: User(v1), Post(v2), Comment(v3) -> Database v3
 ```
 
 ---
 
 ## 🔗 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,9 +1,52 @@
 import 'reflect-metadata';
 type QueryDirection = 'asc' | 'desc';
+type QueryFieldKey<T> = Extract<keyof T, string>;
+type ComparableValue = string | number | bigint | Date;
+type ComparableFieldKey<T> = {
+    [K in QueryFieldKey<T>]-?: T[K] extends ComparableValue ? K : never;
+}[QueryFieldKey<T>];
+type NumericFieldKey<T> = {
+    [K in QueryFieldKey<T>]-?: T[K] extends number ? K : never;
+}[QueryFieldKey<T>];
+type StringFieldKey<T> = {
+    [K in QueryFieldKey<T>]-?: T[K] extends string ? K : never;
+}[QueryFieldKey<T>];
+type ArrayFieldKey<T> = {
+    [K in QueryFieldKey<T>]-?: T[K] extends readonly any[] ? K : never;
+}[QueryFieldKey<T>];
+type ArrayElement<T> = T extends readonly (infer U)[] ? U : never;
+type ContainsValue<T> = T extends string ? string : T extends readonly (infer U)[] ? U : never;
+type QueryOperator = 'equals' | 'gt' | 'gte' | 'lt' | 'lte' | 'startsWith' | 'endsWith' | 'contains' | 'matches' | 'between' | 'notBetween' | 'in' | 'notIn' | 'containsAny' | 'containsAll';
+type GroupCountResult<T, K extends Extract<keyof T, string>> = Array<Record<K, T[K]> & {
+    count: number;
+}>;
+declare class FieldQueryBuilder<T, K extends QueryFieldKey<T>> {
+    private parent;
+    private field;
+    constructor(parent: QueryBuilder<T>, field: K);
+    equals(value: T[K]): QueryBuilder<T>;
+    gt(value: T[K] extends ComparableValue ? T[K] : never): QueryBuilder<T>;
+    gte(value: T[K] extends ComparableValue ? T[K] : never): QueryBuilder<T>;
+    lt(value: T[K] extends ComparableValue ? T[K] : never): QueryBuilder<T>;
+    lte(value: T[K] extends ComparableValue ? T[K] : never): QueryBuilder<T>;
+    startsWith(this: FieldQueryBuilder<T, StringFieldKey<T>>, value: string): QueryBuilder<T>;
+    endsWith(this: FieldQueryBuilder<T, StringFieldKey<T>>, value: string): QueryBuilder<T>;
+    contains(this: FieldQueryBuilder<T, StringFieldKey<T>> | FieldQueryBuilder<T, ArrayFieldKey<T>>, value: ContainsValue<T[K]>): QueryBuilder<T>;
+    matches(this: FieldQueryBuilder<T, StringFieldKey<T>>, value: RegExp | string): QueryBuilder<T>;
+    between(start: T[K] extends ComparableValue ? T[K] : never, end: T[K] extends ComparableValue ? T[K] : never): QueryBuilder<T>;
+    notBetween(start: T[K] extends ComparableValue ? T[K] : never, end: T[K] extends ComparableValue ? T[K] : never): QueryBuilder<T>;
+    in(values: Array<T[K]>): QueryBuilder<T>;
+    notIn(values: Array<T[K]>): QueryBuilder<T>;
+    containsAny(this: FieldQueryBuilder<T, ArrayFieldKey<T>>, values: Array<ArrayElement<T[K]>>): QueryBuilder<T>;
+    containsAll(this: FieldQueryBuilder<T, ArrayFieldKey<T>>, values: Array<ArrayElement<T[K]>>): QueryBuilder<T>;
+    and<K2 extends QueryFieldKey<T>>(field: K2): FieldQueryBuilder<T, K2>;
+    or(): QueryBuilder<T>;
+}
 declare class QueryBuilder<T> {
     private db;
     private storeName;
-    private conditions;
+    private transaction?;
+    private clauses;
     private orderField?;
     private orderDirection;
     private limitCount?;
@@ -12,20 +55,58 @@ declare class QueryBuilder<T> {
     private rangeStart?;
     private rangeEnd?;
     private currentField?;
-    constructor(db: IDBDatabase, storeName: string);
-    where(field: Extract<keyof T, string>): this;
-    and(field: Extract<keyof T, string>): this;
+    private groupField?;
+    private pendingConnector;
+    constructor(db: IDBDatabase, storeName: string, transaction?: IDBTransaction);
+    where<K extends QueryFieldKey<T>>(field: K): FieldQueryBuilder<T, K>;
+    where(builder: (query: QueryBuilder<T>) => QueryBuilder<T> | void): this;
+    and<K extends QueryFieldKey<T>>(field: K): FieldQueryBuilder<T, K>;
+    and(builder: (query: QueryBuilder<T>) => QueryBuilder<T> | void): this;
+    or(): this;
+    private addNestedGroup;
+    clearCurrentField(): void;
+    appendCondition(field: string, op: QueryOperator, value: any): void;
+    private appendClause;
+    private requireCurrentField;
+    private addCondition;
     equals(value: any): this;
     gt(value: any): this;
     gte(value: any): this;
     lt(value: any): this;
     lte(value: any): this;
+    startsWith(value: string): this;
+    endsWith(value: string): this;
+    contains(value: any): this;
+    matches(value: RegExp | string): this;
+    between(start: any, end: any): this;
+    notBetween(start: any, end: any): this;
+    ['in'](values: any[]): this;
+    notIn(values: any[]): this;
+    containsAny(values: any[]): this;
+    containsAll(values: any[]): this;
     orderBy(field: Extract<keyof T, string>, direction?: QueryDirection): this;
     limit(n: number): this;
     offset(n: number): this;
     useIndex(indexName: string): this;
     range(start: any, end: any): this;
+    groupBy<K extends QueryFieldKey<T>>(field: K): QueryBuilder<T> & {
+        count(): Promise<GroupCountResult<T, K>>;
+    };
+    private loadCandidates;
+    private createReadRequest;
+    private matchesClause;
+    private evaluateClauses;
+    private collectMatches;
+    private sortResults;
+    private applyPagination;
+    private aggregateValues;
+    private aggregateGroupedCount;
     execute(): Promise<T[]>;
+    count(): Promise<number | GroupCountResult<T, Extract<keyof T, string>>>;
+    sum(field: NumericFieldKey<T>): Promise<number>;
+    avg(field: NumericFieldKey<T>): Promise<number>;
+    min(field: ComparableFieldKey<T>): Promise<T[typeof field] | null>;
+    max(field: ComparableFieldKey<T>): Promise<T[typeof field] | null>;
 }
 interface KeyPathOptions {
     autoIncrement?: boolean;
@@ -77,6 +158,11 @@ interface EntityRepository<T> {
     clear(): Promise<void>;
     query(): QueryBuilder<T>;
 }
+interface TransactionController {
+    commit(): Promise<void>;
+    rollback(): Promise<void>;
+}
+type TransactionalDatabase<T extends Record<string, EntityRepository<any>>> = T & TransactionController;
 type DatabaseWithRepositories<T extends Record<string, any>> = Database & T;
 declare class Database {
     private dbName;
@@ -98,11 +184,14 @@ declare class Database {
     private cleanupExpiredRecords;
     private createEntityRepository;
     private performOperation;
+    private createTransactionHandle;
+    beginTransaction(entityNames: string[], mode?: IDBTransactionMode): Promise<TransactionalDatabase<Record<string, EntityRepository<any>>>>;
+    transaction<T>(callback: (tx: TransactionalDatabase<Record<string, EntityRepository<any>>>) => Promise<T> | T): Promise<T>;
     close(): void;
     getAvailableEntities(): string[];
     getDatabaseVersion(): number;
     getEntityVersions(): Map<string, number>;
     getEntityVersion(entityName: string): number | undefined;
 }
-export { Database, KeyPath, CompositeKeyPath, DataClass, Index, Validate, RetentionPolicy, EntityRepository, KeyGenerators };
-export type { DatabaseWithRepositories, DataClassOptions, KeyPathOptions, KeyPathMetadata, RetentionPolicyOptions, RetentionPolicyMetadata };
+export { Database, KeyPath, CompositeKeyPath, DataClass, Index, Validate, RetentionPolicy, EntityRepository, KeyGenerators, };
+export type { DatabaseWithRepositories, DataClassOptions, KeyPathOptions, KeyPathMetadata, RetentionPolicyOptions, RetentionPolicyMetadata, };