idb-ts 3.10.0 → 3.12.0

package/README.md

@@ -24,17 +24,22 @@
   </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
+npm i idb-ts     # for pure npm users
+pnpm add idb-ts  # for pnpm users
+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.
@@ -47,10 +52,11 @@ npm i idb-ts
 ## 📖 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 {
@@ -90,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
@@ -146,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;
@@ -155,18 +169,114 @@ 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
 
+### Creation & Update Timestamps
+
+Each entity managed by `idb-ts` automatically gets two internal timestamp fields:
+
+- `__idb_createdAt`: numeric epoch milliseconds set when the record is first created.
+- `__idb_updatedAt`: numeric epoch milliseconds updated on each successful update.
+
+These fields are applied automatically during `create` and `update` operations and can be used for auditing, sorting, or retention policies. They are stored as numbers (milliseconds since Unix epoch).
+
+Example usage (reading timestamps):
+
+```ts
+const item = await db.MyEntity.read('key');
+console.log(item.__idb_createdAt, item.__idb_updatedAt);
+```
+
+### Retention Policy & Cleanup Job
+
+`idb-ts` supports per-entity data retention via the `@RetentionPolicy()` class decorator. It accepts the following options:
+
+- `seconds` (required): number of seconds after which records are considered expired.
+- `enabled` (optional, default `true`): whether cleanup is active for this entity.
+- `field` (optional, default `__idb_createdAt`): the numeric field to use for age calculation (usually creation timestamp).
+
+When one or more entities register retention policies, the library computes a single cleanup interval equal to the greatest common divisor (GCD) of all configured `seconds` values and runs a background cleanup job at that interval. On each tick the job scans the configured entity stores and deletes records whose `field` value is older than the configured retention window.
+
+Example:
+
+```ts
+@RetentionPolicy({ seconds: 60 * 60 * 24 * 30 }) // 30 days
+@DataClass()
+class Session {
+  /* ... */
+}
+
+// Database will run a periodic cleanup that removes sessions older than 30 days
+```
+
+Notes:
+
+- Cleanup runs with readwrite transactions and deletes records one-by-one via cursors. It runs at startup and then periodically. Logs are emitted for inspection when debug logging is enabled.
+- To temporarily disable cleanup for an entity, set `enabled: false` on the decorator.
+
+### Field Validation
+
+You can declare validation rules for individual properties using the `@Validate(predicate, message)` property decorator. Each rule must provide a predicate function that receives the property value and the full item and returns `true` when valid.
+
+Validation is enforced on `create` and `update` operations. If any rule fails, the repository operation throws an error with a concise message describing the failing fields.
+
+Example:
+
+```ts
+@DataClass()
+class User {
+  @KeyPath()
+  id!: string;
+
+  @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')
+  age!: number;
+}
+
+await db.User.create(new User('u1', 'alice@example.com', 30));
+```
+
+The thrown error contains all failing rules in the format `field: message` joined by `; `.
+
+### Bulk Operations
+
+Repositories include convenience bulk helpers for common batch operations:
+
+- `createMany(items: T[])`: creates multiple items (runs validators and generators for each item).
+- `updateMany(items: T[])`: updates multiple items.
+- `deleteMany(keys: Array<string | string[] | number>)`: deletes multiple keys.
+
+These helpers are implemented by iterating the corresponding single-item operations. They are convenient for simple bulk workloads but are not currently implemented as a single atomic transaction across all items. For high-throughput or atomic requirements, consider batching items into a single transaction or performing multiple operations inside a custom `performOperation` call.
+
+Example:
+
+```ts
+await db.User.createMany([alice, bob, charlie]);
+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
@@ -179,6 +289,7 @@ const firstElectronic = await db.Product.findOneByIndex('category', 'Electronics
 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
@@ -196,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 {
@@ -228,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 {
@@ -252,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 {
@@ -272,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;
@@ -296,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()
@@ -325,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']);
@@ -338,7 +462,7 @@ console.log(relationship?.role); // "developer"
 
 // Update relationship
 if (relationship) {
-  relationship.role = "maintainer";
+  relationship.role = 'maintainer';
   await db.UserProject.update(relationship);
 }
 
@@ -350,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
@@ -393,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
@@ -415,20 +636,18 @@ 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
+// 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!** 🚀
-