idb-ts 3.14.0 → 3.15.0

package/README.md

@@ -55,18 +55,18 @@ yarn add idb-ts
 
 ## Feature Overview
 
-| Feature | Description |
-|---|---|
-| **Declarative entity definition** | Define stores, keys, and indexes with class decorators |
-| **Full CRUD API** | Create, read, update, delete, list, paginate, and count |
-| **Typed query builder** | Chainable, type-checked filter, sort, and aggregation DSL |
-| **Key generation** | Auto-increment, UUID v4, timestamp, random, or custom function |
-| **Composite keys** | Multi-field primary keys for relational associations |
-| **Field validation** | Per-property predicate rules enforced on write |
-| **Schema versioning** | Automatic `onupgradeneeded` migration based on entity versions |
-| **Transaction API** | Callback-based and explicit commit/rollback patterns |
-| **Data retention** | Periodic background cleanup of expired records |
-| **Automatic timestamps** | `__idb_createdAt` / `__idb_updatedAt` injected on every write |
+| Feature                           | Description                                                    |
+| --------------------------------- | -------------------------------------------------------------- |
+| **Declarative entity definition** | Define stores, keys, and indexes with class decorators         |
+| **Full CRUD API**                 | Create, read, update, delete, list, paginate, and count        |
+| **Typed query builder**           | Chainable, type-checked filter, sort, and aggregation DSL      |
+| **Key generation**                | Auto-increment, UUID v4, timestamp, random, or custom function |
+| **Composite keys**                | Multi-field primary keys for relational associations           |
+| **Field validation**              | Per-property predicate rules enforced on write                 |
+| **Schema versioning**             | Automatic `onupgradeneeded` migration based on entity versions |
+| **Transaction API**               | Callback-based and explicit commit/rollback patterns           |
+| **Data retention**                | Periodic background cleanup of expired records                 |
+| **Automatic timestamps**          | `__idb_createdAt` / `__idb_updatedAt` injected on every write  |
 
 ---
 
@@ -88,9 +88,16 @@ class User {
   age!: number;
 }
 
-const db = await Database.build<{ User: EntityRepository<User> }>('mydb', [User]);
+const db = await Database.build<{ User: EntityRepository<User> }>('mydb', [
+  User,
+]);
 
-await db.User.create({ id: '', name: 'Alice', age: 30, email: 'alice@example.com' });
+await db.User.create({
+  id: '',
+  name: 'Alice',
+  age: 30,
+  email: 'alice@example.com',
+});
 const alice = await db.User.findOneByIndex('email', 'alice@example.com');
 ```
 
@@ -109,7 +116,10 @@ class User {
   id!: string;
 
   @Index({ unique: true })
-  @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 non-negative')
@@ -125,18 +135,18 @@ class User {
 
 Marks a class as a managed entity. Must be applied exactly once per class, after all other idb-ts decorators.
 
-| Option | Type | Default | Description |
-|---|---|---|---|
-| `version` | `number` | `1` | Schema version. Increment when the entity's store or indexes change. |
+| Option    | Type     | Default | Description                                                          |
+| --------- | -------- | ------- | -------------------------------------------------------------------- |
+| `version` | `number` | `1`     | Schema version. Increment when the entity's store or indexes change. |
 
 #### `@KeyPath(options?)`
 
 Designates the decorated property as the primary key of the object store. Exactly one property per class may carry this decorator. For multi-field keys, use `@CompositeKeyPath` at the class level instead.
 
-| Option | Type | Default | Description |
-|---|---|---|---|
-| `autoIncrement` | `boolean` | `false` | Delegate key assignment to IndexedDB's auto-increment mechanism. |
-| `generator` | `'uuid'` \| `'timestamp'` \| `'random'` \| `(item) => string \| number` | - | Automatic key generator invoked when the key field is absent or empty on `create`. |
+| Option          | Type                                                                    | Default | Description                                                                        |
+| --------------- | ----------------------------------------------------------------------- | ------- | ---------------------------------------------------------------------------------- |
+| `autoIncrement` | `boolean`                                                               | `false` | Delegate key assignment to IndexedDB's auto-increment mechanism.                   |
+| `generator`     | `'uuid'` \| `'timestamp'` \| `'random'` \| `(item) => string \| number` | -       | Automatic key generator invoked when the key field is absent or empty on `create`. |
 
 #### `@CompositeKeyPath(fields, options?)`
 
@@ -156,8 +166,8 @@ class UserProject {
 
 Creates an IDB index on the decorated field, enabling efficient lookups via `findByIndex` and `findOneByIndex`.
 
-| Option | Type | Description |
-|---|---|---|
+| Option   | Type      | Description                              |
+| -------- | --------- | ---------------------------------------- |
 | `unique` | `boolean` | Enforce uniqueness on the indexed field. |
 
 #### `@Validate(predicate, message)`
@@ -174,7 +184,7 @@ Class-level decorator that configures automatic expiry and deletion of records.
 
 ```typescript
 const db = await Database.build<{
-  User:  EntityRepository<User>;
+  User: EntityRepository<User>;
   Order: EntityRepository<Order>;
 }>('shop', [User, Order]);
 ```
@@ -186,10 +196,10 @@ The effective database version is the highest `version` value declared across al
 ### Inspecting database metadata
 
 ```typescript
-db.getDatabaseVersion();         // number - current IDB version
-db.getEntityVersions();          // Map<string, number>
-db.getEntityVersion('User');     // number | undefined
-db.getAvailableEntities();       // string[]
+db.getDatabaseVersion(); // number - current IDB version
+db.getEntityVersions(); // Map<string, number>
+db.getEntityVersion('User'); // number | undefined
+db.getAvailableEntities(); // string[]
 ```
 
 ### Closing the connection
@@ -210,9 +220,9 @@ await db.User.create(user);
 await db.User.createMany([alice, bob, charlie]);
 
 // Read
-const user = await db.User.read('u1');           // by primary key
+const user = await db.User.read('u1'); // by primary key
 const page = await db.User.listPaginated(1, 20); // 1-based pagination
-const all  = await db.User.list();
+const all = await db.User.list();
 
 // Update
 await db.User.update(updatedUser);
@@ -224,7 +234,7 @@ await db.User.deleteMany(['u1', 'u2']);
 await db.User.deleteWhere((q) => q.where('age').lt(18));
 
 // Utilities
-const count  = await db.User.count();
+const count = await db.User.count();
 const exists = await db.User.exists('u1');
 await db.User.clear();
 ```
@@ -232,7 +242,7 @@ await db.User.clear();
 ### Index lookups
 
 ```typescript
-const allAdmins  = await db.User.findByIndex('role', 'admin');
+const allAdmins = await db.User.findByIndex('role', 'admin');
 const firstAdmin = await db.User.findOneByIndex('role', 'admin');
 ```
 
@@ -244,9 +254,9 @@ Querying a non-existent index throws immediately.
 
 Every record written through a repository automatically receives two internal fields:
 
-| Field | Type | Set on |
-|---|---|---|
-| `__idb_createdAt` | `number` (ms since epoch) | `create` only |
+| Field             | Type                      | Set on                |
+| ----------------- | ------------------------- | --------------------- |
+| `__idb_createdAt` | `number` (ms since epoch) | `create` only         |
 | `__idb_updatedAt` | `number` (ms since epoch) | `create` and `update` |
 
 `__idb_createdAt` is preserved across updates; `__idb_updatedAt` is refreshed on every write.
@@ -266,25 +276,27 @@ console.log(item.__idb_createdAt, item.__idb_updatedAt);
 
 ```typescript
 const results = await db.User.query()
-  .where('age').gte(18)
-  .and('status').equals('active')
+  .where('age')
+  .gte(18)
+  .and('status')
+  .equals('active')
   .execute();
 ```
 
 #### Available operators
 
-| Operator | Field types | Description |
-|---|---|---|
-| `equals` | any | Strict equality (`===`) |
-| `gt` / `gte` / `lt` / `lte` | `ComparableValue` | Comparison |
-| `between(start, end)` | `ComparableValue` | Inclusive range |
-| `notBetween(start, end)` | `ComparableValue` | Outside range |
-| `startsWith` / `endsWith` | `string` | Prefix / suffix match |
-| `contains` | `string` \| array | Substring or element membership |
-| `matches` | `string` | Regular expression test |
-| `in(values)` / `notIn(values)` | any | Membership test |
-| `containsAny(values)` | array | At least one element matches |
-| `containsAll(values)` | array | All elements present |
+| Operator                       | Field types       | Description                     |
+| ------------------------------ | ----------------- | ------------------------------- |
+| `equals`                       | any               | Strict equality (`===`)         |
+| `gt` / `gte` / `lt` / `lte`    | `ComparableValue` | Comparison                      |
+| `between(start, end)`          | `ComparableValue` | Inclusive range                 |
+| `notBetween(start, end)`       | `ComparableValue` | Outside range                   |
+| `startsWith` / `endsWith`      | `string`          | Prefix / suffix match           |
+| `contains`                     | `string` \| array | Substring or element membership |
+| `matches`                      | `string`          | Regular expression test         |
+| `in(values)` / `notIn(values)` | any               | Membership test                 |
+| `containsAny(values)`          | array             | At least one element matches    |
+| `containsAll(values)`          | array             | All elements present            |
 
 TypeScript enforces operator/type compatibility at compile time - string-only operators are not exposed on numeric fields, and so on.
 
@@ -293,9 +305,11 @@ TypeScript enforces operator/type compatibility at compile time - string-only op
 ```typescript
 // OR connector
 const results = await db.User.query()
-  .where('age').gte(18)
+  .where('age')
+  .gte(18)
   .or()
-  .where('hasParentalConsent').equals(true)
+  .where('hasParentalConsent')
+  .equals(true)
   .execute();
 
 // Grouped sub-expression
@@ -304,7 +318,8 @@ const premiumOrTrial = await db.User.query()
     qb.where('type').equals('premium').and('status').equals('active'),
   )
   .or()
-  .where('isTrial').equals(true)
+  .where('isTrial')
+  .equals(true)
   .execute();
 ```
 
@@ -312,7 +327,8 @@ const premiumOrTrial = await db.User.query()
 
 ```typescript
 await db.User.query()
-  .where('status').equals('active')
+  .where('status')
+  .equals('active')
   .orderBy('createdAt', 'desc')
   .offset(20)
   .limit(10)
@@ -324,10 +340,7 @@ await db.User.query()
 When a field is indexed, you can constrain the initial IDB candidate set at the storage layer before in-memory filtering begins:
 
 ```typescript
-await db.Product.query()
-  .useIndex('price')
-  .range(10, 100)
-  .execute();
+await db.Product.query().useIndex('price').range(10, 100).execute();
 ```
 
 ### Aggregations
@@ -356,7 +369,7 @@ const byStatus = await db.Order.query().groupBy('status').count();
 @DataClass()
 class Task {
   @KeyPath({ autoIncrement: true })
-  id!: number;   // Assigned by IndexedDB: 1, 2, 3, …
+  id!: number; // Assigned by IndexedDB: 1, 2, 3, …
 
   title!: string;
 }
@@ -367,7 +380,7 @@ class Task {
 ```typescript
 @DataClass()
 class Document {
-  @KeyPath({ generator: 'uuid' })      // RFC 4122 v4
+  @KeyPath({ generator: 'uuid' }) // RFC 4122 v4
   id!: string;
 }
 
@@ -379,7 +392,7 @@ class Event {
 
 @DataClass()
 class Session {
-  @KeyPath({ generator: 'random' })    // Base-36 random string
+  @KeyPath({ generator: 'random' }) // Base-36 random string
   id!: string;
 }
 ```
@@ -406,9 +419,9 @@ class Invoice {
 ```typescript
 import { KeyGenerators } from 'idb-ts';
 
-KeyGenerators.uuid();      // "a1b2c3d4-..."
+KeyGenerators.uuid(); // "a1b2c3d4-..."
 KeyGenerators.timestamp(); // 1696118400000
-KeyGenerators.random();    // "xyz789abc"
+KeyGenerators.random(); // "xyz789abc"
 ```
 
 ### Composite keys
@@ -452,7 +465,10 @@ class User {
   )
   email!: string;
 
-  @Validate((v) => Number.isInteger(v) && v >= 0, 'must be a non-negative integer')
+  @Validate(
+    (v) => Number.isInteger(v) && v >= 0,
+    'must be a non-negative integer',
+  )
   age!: number;
 }
 ```
@@ -514,11 +530,11 @@ class Session {
 }
 ```
 
-| Option | Type | Default | Description |
-|---|---|---|---|
-| `seconds` | `number` | - | **(Required)** Retention window in seconds. Must be a positive integer. |
-| `enabled` | `boolean` | `true` | Set to `false` to suspend cleanup without removing the policy. |
-| `field` | `string` | `'__idb_createdAt'` | Numeric timestamp field used to compute record age. |
+| Option    | Type      | Default             | Description                                                             |
+| --------- | --------- | ------------------- | ----------------------------------------------------------------------- |
+| `seconds` | `number`  | -                   | **(Required)** Retention window in seconds. Must be a positive integer. |
+| `enabled` | `boolean` | `true`              | Set to `false` to suspend cleanup without removing the policy.          |
+| `field`   | `string`  | `'__idb_createdAt'` | Numeric timestamp field used to compute record age.                     |
 
 When multiple entities define retention policies, the cleanup interval is set to the GCD of all configured `seconds` values in milliseconds, so a single timer satisfies every policy efficiently. The job runs immediately on database open and then on each interval tick, using cursor-based `readwrite` transactions.
 
@@ -529,9 +545,18 @@ When multiple entities define retention policies, the cleanup interval is set to
 Increment an entity's `version` to trigger `onupgradeneeded` and update its object store on the user's next visit. The effective database version is the maximum across all registered entities, so adding a new high-version entity is sufficient to initiate a migration.
 
 ```typescript
-@DataClass({ version: 1 }) class User   { /* ... */ }
-@DataClass({ version: 2 }) class Post   { /* ... */ }
-@DataClass({ version: 3 }) class Comment { /* ... */ }
+@DataClass({ version: 1 })
+class User {
+  /* ... */
+}
+@DataClass({ version: 2 })
+class Post {
+  /* ... */
+}
+@DataClass({ version: 3 })
+class Comment {
+  /* ... */
+}
 
 // Database opens at version 3.
 // If a user was on version 1, only Post (v2) and Comment (v3) stores are
@@ -555,13 +580,112 @@ await db.User.deleteMany(['u1', 'u2', 'u3']);
 
 ---
 
+## Performance
+
+<!-- performance start -->
+
+Already up to date
+Done in 443ms using pnpm v11.5.1
+
+### Suite 1: CRUD Operations
+
+| Operation | Ops | Total ms | Ops/s | Avg ms | P50 | P95 | P99 | Min | Max |
+|-----------|-----:|---------:|------:|-------:|----:|----:|----:|----:|----:|
+| create (single) | 200 | 15.46 | 12,936.753 | 0.077 | 0.058 | 0.137 | 0.162 | 0.052 | 1.01 |
+| read (by PK) | 200 | 10.987 | 18,203.475 | 0.054 | 0.047 | 0.089 | 0.163 | 0.04 | 0.175 |
+| update (single) | 200 | 121.183 | 1,650.4 | 0.605 | 0.535 | 0.991 | 1.739 | 0.459 | 2.227 |
+| findByIndex (email) | 200 | 11.218 | 17,828.706 | 0.056 | 0.052 | 0.083 | 0.111 | 0.044 | 0.143 |
+| findOneByIndex (email) | 200 | 13.331 | 15,002.256 | 0.066 | 0.057 | 0.081 | 0.103 | 0.048 | 1.11 |
+| count | 200 | 10.209 | 19,589.884 | 0.051 | 0.049 | 0.064 | 0.088 | 0.044 | 0.101 |
+| exists | 200 | 16.586 | 12,058.587 | 0.083 | 0.064 | 0.097 | 0.18 | 0.057 | 2.444 |
+| list (all) | 50 | 97.836 | 511.058 | 1.956 | 1.724 | 4.683 | 7.585 | 1.481 | 7.585 |
+| listPaginated (1, 20) | 200 | 374.357 | 534.25 | 1.871 | 1.692 | 2.005 | 9.138 | 1.447 | 12.441 |
+| query().where().gte().execute() | 100 | 182.997 | 546.458 | 1.829 | 1.542 | 1.975 | 2.457 | 1.485 | 14.388 |
+| delete (single) | 200 | 138.608 | 1,442.92 | 0.693 | 0.658 | 0.764 | 0.857 | 0.556 | 5.689 |
+
+
+### Suite 2: Batched CRUD (by batch size)
+
+| Operation | Ops | Total ms | Ops/s | Avg ms | P50 | P95 | P99 | Min | Max |
+|-----------|-----:|---------:|------:|-------:|----:|----:|----:|----:|----:|
+| createMany (10) | 3 | 1.482 | 2,023.901 | 0.493 | 0.531 | 0.534 | 0.534 | 0.415 | 0.534 |
+| read batch (10 keys) | 3 | 0.522 | 5,741.792 | 0.174 | 0.169 | 0.191 | 0.191 | 0.161 | 0.191 |
+| updateMany (10) | 3 | 5.066 | 592.172 | 1.688 | 1.488 | 2.093 | 2.093 | 1.482 | 2.093 |
+| deleteMany (10) | 3 | 3.06 | 980.235 | 1.02 | 1.031 | 1.099 | 1.099 | 0.929 | 1.099 |
+| deleteWhere (10+ match) | 3 | 0.984 | 3,048.328 | 0.327 | 0.302 | 0.401 | 0.401 | 0.279 | 0.401 |
+| createMany (50) | 3 | 5.753 | 521.463 | 1.917 | 1.933 | 2.106 | 2.106 | 1.712 | 2.106 |
+| read batch (50 keys) | 3 | 4.12 | 728.179 | 1.372 | 1.386 | 1.468 | 1.468 | 1.263 | 1.468 |
+| updateMany (50) | 3 | 78.35 | 38.29 | 26.116 | 25.63 | 28.291 | 28.291 | 24.426 | 28.291 |
+| deleteMany (50) | 3 | 76.547 | 39.191 | 25.514 | 24.517 | 27.751 | 27.751 | 24.276 | 27.751 |
+| deleteWhere (50+ match) | 3 | 3.43 | 874.636 | 1.143 | 1.069 | 1.294 | 1.294 | 1.065 | 1.294 |
+| createMany (100) | 3 | 11.795 | 254.341 | 3.931 | 4.058 | 4.244 | 4.244 | 3.491 | 4.244 |
+| read batch (100 keys) | 3 | 29.324 | 102.305 | 9.773 | 8.39 | 14.867 | 14.867 | 6.062 | 14.867 |
+| updateMany (100) | 3 | 272.998 | 10.989 | 90.997 | 89.999 | 95.133 | 95.133 | 87.86 | 95.133 |
+| deleteMany (100) | 3 | 270.164 | 11.104 | 90.048 | 88.568 | 98.799 | 98.799 | 82.777 | 98.799 |
+| deleteWhere (100+ match) | 3 | 6.852 | 437.839 | 2.283 | 2.136 | 2.591 | 2.591 | 2.123 | 2.591 |
+| createMany (500) | 3 | 89.252 | 33.613 | 29.749 | 31.124 | 34.061 | 34.061 | 24.062 | 34.061 |
+| read batch (500 keys) | 3 | 163.408 | 18.359 | 54.467 | 59.069 | 60.496 | 60.496 | 43.837 | 60.496 |
+| updateMany (500) | 3 | 7,195.857 | 0.417 | 2,398.617 | 2,397.101 | 2,406.21 | 2,406.21 | 2,392.539 | 2,406.21 |
+| deleteMany (500) | 3 | 7,951.45 | 0.377 | 2,650.481 | 2,603.507 | 2,912.156 | 2,912.156 | 2,435.78 | 2,912.156 |
+| deleteWhere (500+ match) | 3 | 36.772 | 81.584 | 12.256 | 11.967 | 12.995 | 12.995 | 11.806 | 12.995 |
+
+
+### Suite 3: Mixed CRUD Operations
+
+| Operation | Ops | Total ms | Ops/s | Avg ms | P50 | P95 | P99 | Min | Max |
+|-----------|-----:|---------:|------:|-------:|----:|----:|----:|----:|----:|
+| Read-heavy mix (70R/15U/10C/5D) | 200 | 29.799 | 6,711.698 | 0.149 | 0.029 | 0.606 | 0.619 | 0.016 | 0.652 |
+| Write-heavy mix (20R/15U/50C/15D) | 200 | 41.659 | 4,800.892 | 0.208 | 0.042 | 0.582 | 0.608 | 0.022 | 3.973 |
+| Mixed CRUD + queries | 200 | 118.964 | 1,681.186 | 0.594 | 0.051 | 2.065 | 7.636 | 0.013 | 10.791 |
+| Cross-entity mix (User.read + Order.create) | 200 | 7.316 | 27,336.962 | 0.036 | 0.03 | 0.069 | 0.081 | 0.021 | 0.091 |
+
+
+### Suite 4: Mixed Batched CRUD
+
+| Operation | Ops | Total ms | Ops/s | Avg ms | P50 | P95 | P99 | Min | Max |
+|-----------|-----:|---------:|------:|-------:|----:|----:|----:|----:|----:|
+| Cycle: createMany -> readAll -> updateMany -> deleteMany (50) | 5 | 66.384 | 75.319 | 13.276 | 13.426 | 17.594 | 17.594 | 10.02 | 17.594 |
+| createMany  ->  query filter  ->  deleteMany (50) | 5 | 36.888 | 135.546 | 7.377 | 6.693 | 9.052 | 9.052 | 6.469 | 9.052 |
+| 5 waves × createMany(50) + deleteMany(50) | 3 | 249.923 | 12.004 | 83.307 | 85.413 | 85.568 | 85.568 | 78.939 | 85.568 |
+| Cross-entity batch: createMany(User) + createMany(Order) + deleteMany (×50) | 3 | 140.09 | 21.415 | 46.696 | 47.77 | 51.181 | 51.181 | 41.137 | 51.181 |
+
+
+### Suite 5: Transaction Operations
+
+| Operation | Ops | Total ms | Ops/s | Avg ms | P50 | P95 | P99 | Min | Max |
+|-----------|-----:|---------:|------:|-------:|----:|----:|----:|----:|----:|
+| tx: single create | 100 | 8.886 | 11,253.788 | 0.089 | 0.073 | 0.178 | 0.228 | 0.07 | 0.253 |
+| tx: create 10 users | 100 | 25.153 | 3,975.637 | 0.251 | 0.238 | 0.288 | 0.489 | 0.223 | 0.517 |
+| tx: read + update | 100 | 159.349 | 627.553 | 1.593 | 1.525 | 1.63 | 2.939 | 1.499 | 5.745 |
+| tx: multi-entity create (User+Order+Session) | 100 | 9.628 | 10,386.133 | 0.096 | 0.087 | 0.128 | 0.189 | 0.081 | 0.23 |
+| tx: 10 reads | 100 | 20.01 | 4,997.52 | 0.2 | 0.169 | 0.343 | 0.399 | 0.153 | 0.441 |
+| tx: batch create 50 users | 20 | 24.816 | 805.936 | 1.24 | 1.019 | 1.284 | 4.769 | 0.976 | 4.769 |
+| tx: query().where().gte() | 100 | 933.212 | 107.157 | 9.331 | 8.393 | 19.189 | 19.988 | 7.73 | 19.998 |
+| tx (explicit): begin -> create -> commit | 100 | 6.974 | 14,337.972 | 0.07 | 0.065 | 0.091 | 0.108 | 0.061 | 0.162 |
+
+
+### Suite 6: Mixed Transactions
+
+| Operation | Ops | Total ms | Ops/s | Avg ms | P50 | P95 | P99 | Min | Max |
+|-----------|-----:|---------:|------:|-------:|----:|----:|----:|----:|----:|
+| tx mixed: read User  ->  create Order  ->  update User | 100 | 51.695 | 1,934.439 | 0.517 | 0.41 | 0.485 | 0.724 | 0.38 | 10.259 |
+| tx mixed: query User + read Order + create Session | 100 | 113.605 | 880.244 | 1.136 | 1.037 | 1.134 | 1.274 | 1.018 | 9.734 |
+| tx multi-entity: create User+Order+Session | 100 | 11.079 | 9,025.916 | 0.111 | 0.106 | 0.138 | 0.143 | 0.1 | 0.166 |
+| tx batched: create 20 Users + 40 Orders + 20 Sessions | 10 | 22.237 | 449.703 | 2.223 | 1.238 | 11.051 | 11.051 | 1.164 | 11.051 |
+| tx mixed: delete old orders  ->  create new orders | 100 | 104.138 | 960.266 | 1.041 | 0.971 | 1.09 | 1.189 | 0.829 | 8.342 |
+| tx mixed: count Orders  ->  conditional create | 100 | 9.371 | 10,671.27 | 0.093 | 0.088 | 0.121 | 0.141 | 0.081 | 0.166 |
+| tx complex: read User+Orders  ->  aggregate  ->  create Session | 100 | 18.87 | 5,299.428 | 0.188 | 0.15 | 0.223 | 0.288 | 0.135 | 3.002 |
+
+<!-- performance end -->
+
 ## 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/
+- **Demos**: https://maifeeulasad.github.io/idb-ts/
+- **Live Editor**: https://maifeeulasad.github.io/idb-ts/typescript/
 - **Code Coverage report**: https://maifeeulasad.github.io/idb-ts/coverage/lcov-report/
 
 🎉 **Enjoy seamless IndexedDB integration with TypeScript! Happy coding!** 🚀
 
-Made by [Maifee Ulasad](https://github.com/maifeeulasad) with :heart: and :tea:. Licensed under [MIT](./LICENSE). 
+Made by [Maifee Ulasad](https://github.com/maifeeulasad) with :heart: and :tea:. Licensed under [MIT](./LICENSE).

package/lib/index.cjs

@@ -519,12 +519,23 @@ function DataClass(options = {}) {
     };
 }
 class Database {
-    constructor(dbName, classes) {
+    constructor(dbName, classes, printEnabled = false) {
         this.db = null;
         this.entityRepositories = new Map();
         this.retentionTimer = null;
         this.retentionCleanupRunning = false;
+        this.printDebug = (...data) => {
+            if (!this.printEnabled)
+                return;
+            console.debug('[idb-ts]:DEBUG:', ...data);
+        };
+        this.printError = (...error) => {
+            if (!this.printEnabled)
+                return;
+            console.error('[idb-ts]:ERROR:', ...error);
+        };
         this.dbName = dbName;
+        this.printEnabled = printEnabled;
         if (!classes.every((cls) => Reflect.getMetadata('dataclass', cls))) {
             throw new Error('All classes should be decorated with @DataClass.');
         }
@@ -564,7 +575,7 @@ class Database {
                     const db = request.result;
                     const oldVersion = event.oldVersion;
                     const newVersion = event.newVersion || this.dbVersion;
-                    console.debug(`Database upgrade from version ${oldVersion} to ${newVersion}`);
+                    this.printDebug(`Database upgrade from version ${oldVersion} to ${newVersion}`);
                     this.classes.forEach((cls) => {
                         var _a;
                         const keyPathMetadata = Reflect.getMetadata('keypath', cls);
@@ -573,7 +584,7 @@ class Database {
                         const storeName = cls.name.toLowerCase();
                         if (classVersion > oldVersion) {
                             if (!db.objectStoreNames.contains(storeName)) {
-                                console.debug(`Creating object store: ${storeName} (version ${classVersion})`);
+                                this.printDebug(`Creating object store: ${storeName} (version ${classVersion})`);
                                 const storeOptions = {};
                                 if (keyPathMetadata) {
                                     storeOptions.keyPath = keyPathMetadata.fields;
@@ -596,7 +607,7 @@ class Database {
                                 });
                             }
                             else {
-                                console.debug(`Updating object store: ${storeName} (version ${classVersion})`);
+                                this.printDebug(`Updating object store: ${storeName} (version ${classVersion})`);
                                 const transaction = request.transaction;
                                 if (transaction) {
                                     const store = transaction.objectStore(storeName);
@@ -609,7 +620,7 @@ class Database {
                                             ? { unique: false }
                                             : ((_a = indexField.options) !== null && _a !== void 0 ? _a : { unique: false });
                                         if (!store.indexNames.contains(indexName)) {
-                                            console.debug(`Adding index: ${indexName} to ${storeName}`);
+                                            this.printDebug(`Adding index: ${indexName} to ${storeName}`);
                                             store.createIndex(indexName, indexName, indexOptions);
                                         }
                                     });
@@ -620,12 +631,12 @@ class Database {
                 };
                 request.onsuccess = () => {
                     this.db = request.result;
-                    console.debug(`Database initialized (version ${this.dbVersion}) with object stores for: ${this.classes.map((cls) => `${cls.name}(v${Reflect.getMetadata('version', cls) || 1})`).join(', ')}`);
+                    this.printDebug(`Database initialized (version ${this.dbVersion}) with object stores for: ${this.classes.map((cls) => `${cls.name}(v${Reflect.getMetadata('version', cls) || 1})`).join(', ')}`);
                     this.startRetentionCleanup();
                     resolve();
                 };
                 request.onerror = () => {
-                    console.error('Error initializing database:', request.error);
+                    this.printError('Error initializing database:', request.error);
                     reject(request.error);
                 };
             });
@@ -666,7 +677,7 @@ class Database {
         if (!cleanupIntervalMs || !this.db || this.retentionTimer) {
             return;
         }
-        console.debug(`Retention cleanup enabled for ${this.retentionPolicies.length} entities every ${cleanupIntervalMs}ms`);
+        this.printDebug(`Retention cleanup enabled for ${this.retentionPolicies.length} entities every ${cleanupIntervalMs}ms`);
         void this.runRetentionCleanup();
         this.retentionTimer = setInterval(() => {
             void this.runRetentionCleanup();
@@ -681,11 +692,11 @@ class Database {
             }
             this.retentionCleanupRunning = true;
             try {
-                console.debug('Retention cleanup tick started');
+                this.printDebug('Retention cleanup tick started');
                 for (const { storeName, className, policy } of this.retentionPolicies) {
                     yield this.cleanupExpiredRecords(storeName, className, policy);
                 }
-                console.debug('Retention cleanup tick finished');
+                this.printDebug('Retention cleanup tick finished');
             }
             finally {
                 this.retentionCleanupRunning = false;
@@ -709,11 +720,11 @@ class Database {
                     }
                     const value = cursor.value;
                     const timestamp = value === null || value === void 0 ? void 0 : value[policy.field];
-                    console.debug(`Retention cleanup inspecting ${className}.${policy.field}:`, timestamp, 'cutoff:', cutoff);
+                    this.printDebug(`Retention cleanup inspecting ${className}.${policy.field}:`, timestamp, 'cutoff:', cutoff);
                     if (typeof timestamp === 'number' && timestamp <= cutoff) {
                         const deleteRequest = cursor.delete();
                         deleteRequest.onsuccess = () => {
-                            console.debug(`Retention cleanup removed expired record from ${className}`);
+                            this.printDebug(`Retention cleanup removed expired record from ${className}`);
                             cursor.continue();
                         };
                         deleteRequest.onerror = () => {
@@ -874,7 +885,7 @@ class Database {
                 applyTimestampFields(item);
                 return this.performOperation(cls.name, 'readwrite', (store) => {
                     return createStoredItem(store, item).then(() => {
-                        console.debug(`Item added to ${cls.name}:`, item);
+                        this.printDebug(`Item added to ${cls.name}:`, item);
                     });
                 }, transaction);
             }),
@@ -889,7 +900,7 @@ class Database {
                     const request = store.get(key);
                     return new Promise((resolve, reject) => {
                         request.onsuccess = () => {
-                            console.debug(`Item read from ${cls.name}:`, request.result);
+                            this.printDebug(`Item read from ${cls.name}:`, request.result);
                             resolve(request.result);
                         };
                         request.onerror = () => reject(request.error);
@@ -900,7 +911,7 @@ class Database {
                 validateItem(item);
                 return this.performOperation(cls.name, 'readwrite', (store) => {
                     return updateStoredItem(store, item).then(() => {
-                        console.debug(`Item updated in ${cls.name}:`, item);
+                        this.printDebug(`Item updated in ${cls.name}:`, item);
                     });
                 }, transaction);
             }),
@@ -913,7 +924,7 @@ class Database {
             delete: (key) => tslib.__awaiter(this, void 0, void 0, function* () {
                 return this.performOperation(cls.name, 'readwrite', (store) => {
                     return deleteStoredItem(store, key).then(() => {
-                        console.debug(`Item deleted from ${cls.name}:`, key);
+                        this.printDebug(`Item deleted from ${cls.name}:`, key);
                     });
                 }, transaction);
             }),
@@ -939,7 +950,7 @@ class Database {
                     const request = store.getAll();
                     return new Promise((resolve, reject) => {
                         request.onsuccess = () => {
-                            console.debug(`All items from ${cls.name}:`, request.result);
+                            this.printDebug(`All items from ${cls.name}:`, request.result);
                             resolve(request.result);
                         };
                         request.onerror = () => reject(request.error);
@@ -953,7 +964,7 @@ class Database {
                         request.onsuccess = () => {
                             const items = request.result;
                             const paginatedItems = items.slice((page - 1) * pageSize, page * pageSize);
-                            console.debug(`Paginated items from ${cls.name}:`, paginatedItems);
+                            this.printDebug(`Paginated items from ${cls.name}:`, paginatedItems);
                             resolve(paginatedItems);
                         };
                         request.onerror = () => reject(request.error);
@@ -969,7 +980,7 @@ class Database {
                     const request = index.getAll(value);
                     return new Promise((resolve, reject) => {
                         request.onsuccess = () => {
-                            console.debug(`Items found by index ${indexName} with value ${value}:`, request.result);
+                            this.printDebug(`Items found by index ${indexName} with value ${value}:`, request.result);
                             resolve(request.result);
                         };
                         request.onerror = () => reject(request.error);
@@ -985,7 +996,7 @@ class Database {
                     const request = index.get(value);
                     return new Promise((resolve, reject) => {
                         request.onsuccess = () => {
-                            console.debug(`Item found by index ${indexName} with value ${value}:`, request.result);
+                            this.printDebug(`Item found by index ${indexName} with value ${value}:`, request.result);
                             resolve(request.result);
                         };
                         request.onerror = () => reject(request.error);
@@ -997,7 +1008,7 @@ class Database {
                     const request = store.count();
                     return new Promise((resolve, reject) => {
                         request.onsuccess = () => {
-                            console.debug(`Count for ${cls.name}:`, request.result);
+                            this.printDebug(`Count for ${cls.name}:`, request.result);
                             resolve(request.result);
                         };
                         request.onerror = () => reject(request.error);
@@ -1010,7 +1021,7 @@ class Database {
                     return new Promise((resolve, reject) => {
                         request.onsuccess = () => {
                             const exists = request.result > 0;
-                            console.debug(`Exists check for ${cls.name} with key ${key}:`, exists);
+                            this.printDebug(`Exists check for ${cls.name} with key ${key}:`, exists);
                             resolve(exists);
                         };
                         request.onerror = () => reject(request.error);
@@ -1022,7 +1033,7 @@ class Database {
                     const request = store.clear();
                     return new Promise((resolve, reject) => {
                         request.onsuccess = () => {
-                            console.debug(`Cleared all items from ${cls.name}`);
+                            this.printDebug(`Cleared all items from ${cls.name}`);
                             resolve();
                         };
                         request.onerror = () => reject(request.error);

package/lib/index.d.ts

@@ -173,6 +173,9 @@ declare class Database {
     private retentionTimer;
     private retentionCleanupRunning;
     private retentionPolicies;
+    private printEnabled;
+    private printDebug;
+    private printError;
     private constructor();
     private calculateDatabaseVersion;
     static build<T extends Record<string, EntityRepository<any>>>(dbName: string, classes: Function[]): Promise<DatabaseWithRepositories<T>>;

package/lib/index.esm.js

@@ -517,12 +517,23 @@ function DataClass(options = {}) {
     };
 }
 class Database {
-    constructor(dbName, classes) {
+    constructor(dbName, classes, printEnabled = false) {
         this.db = null;
         this.entityRepositories = new Map();
         this.retentionTimer = null;
         this.retentionCleanupRunning = false;
+        this.printDebug = (...data) => {
+            if (!this.printEnabled)
+                return;
+            console.debug('[idb-ts]:DEBUG:', ...data);
+        };
+        this.printError = (...error) => {
+            if (!this.printEnabled)
+                return;
+            console.error('[idb-ts]:ERROR:', ...error);
+        };
         this.dbName = dbName;
+        this.printEnabled = printEnabled;
         if (!classes.every((cls) => Reflect.getMetadata('dataclass', cls))) {
             throw new Error('All classes should be decorated with @DataClass.');
         }
@@ -562,7 +573,7 @@ class Database {
                     const db = request.result;
                     const oldVersion = event.oldVersion;
                     const newVersion = event.newVersion || this.dbVersion;
-                    console.debug(`Database upgrade from version ${oldVersion} to ${newVersion}`);
+                    this.printDebug(`Database upgrade from version ${oldVersion} to ${newVersion}`);
                     this.classes.forEach((cls) => {
                         var _a;
                         const keyPathMetadata = Reflect.getMetadata('keypath', cls);
@@ -571,7 +582,7 @@ class Database {
                         const storeName = cls.name.toLowerCase();
                         if (classVersion > oldVersion) {
                             if (!db.objectStoreNames.contains(storeName)) {
-                                console.debug(`Creating object store: ${storeName} (version ${classVersion})`);
+                                this.printDebug(`Creating object store: ${storeName} (version ${classVersion})`);
                                 const storeOptions = {};
                                 if (keyPathMetadata) {
                                     storeOptions.keyPath = keyPathMetadata.fields;
@@ -594,7 +605,7 @@ class Database {
                                 });
                             }
                             else {
-                                console.debug(`Updating object store: ${storeName} (version ${classVersion})`);
+                                this.printDebug(`Updating object store: ${storeName} (version ${classVersion})`);
                                 const transaction = request.transaction;
                                 if (transaction) {
                                     const store = transaction.objectStore(storeName);
@@ -607,7 +618,7 @@ class Database {
                                             ? { unique: false }
                                             : ((_a = indexField.options) !== null && _a !== void 0 ? _a : { unique: false });
                                         if (!store.indexNames.contains(indexName)) {
-                                            console.debug(`Adding index: ${indexName} to ${storeName}`);
+                                            this.printDebug(`Adding index: ${indexName} to ${storeName}`);
                                             store.createIndex(indexName, indexName, indexOptions);
                                         }
                                     });
@@ -618,12 +629,12 @@ class Database {
                 };
                 request.onsuccess = () => {
                     this.db = request.result;
-                    console.debug(`Database initialized (version ${this.dbVersion}) with object stores for: ${this.classes.map((cls) => `${cls.name}(v${Reflect.getMetadata('version', cls) || 1})`).join(', ')}`);
+                    this.printDebug(`Database initialized (version ${this.dbVersion}) with object stores for: ${this.classes.map((cls) => `${cls.name}(v${Reflect.getMetadata('version', cls) || 1})`).join(', ')}`);
                     this.startRetentionCleanup();
                     resolve();
                 };
                 request.onerror = () => {
-                    console.error('Error initializing database:', request.error);
+                    this.printError('Error initializing database:', request.error);
                     reject(request.error);
                 };
             });
@@ -664,7 +675,7 @@ class Database {
         if (!cleanupIntervalMs || !this.db || this.retentionTimer) {
             return;
         }
-        console.debug(`Retention cleanup enabled for ${this.retentionPolicies.length} entities every ${cleanupIntervalMs}ms`);
+        this.printDebug(`Retention cleanup enabled for ${this.retentionPolicies.length} entities every ${cleanupIntervalMs}ms`);
         void this.runRetentionCleanup();
         this.retentionTimer = setInterval(() => {
             void this.runRetentionCleanup();
@@ -679,11 +690,11 @@ class Database {
             }
             this.retentionCleanupRunning = true;
             try {
-                console.debug('Retention cleanup tick started');
+                this.printDebug('Retention cleanup tick started');
                 for (const { storeName, className, policy } of this.retentionPolicies) {
                     yield this.cleanupExpiredRecords(storeName, className, policy);
                 }
-                console.debug('Retention cleanup tick finished');
+                this.printDebug('Retention cleanup tick finished');
             }
             finally {
                 this.retentionCleanupRunning = false;
@@ -707,11 +718,11 @@ class Database {
                     }
                     const value = cursor.value;
                     const timestamp = value === null || value === void 0 ? void 0 : value[policy.field];
-                    console.debug(`Retention cleanup inspecting ${className}.${policy.field}:`, timestamp, 'cutoff:', cutoff);
+                    this.printDebug(`Retention cleanup inspecting ${className}.${policy.field}:`, timestamp, 'cutoff:', cutoff);
                     if (typeof timestamp === 'number' && timestamp <= cutoff) {
                         const deleteRequest = cursor.delete();
                         deleteRequest.onsuccess = () => {
-                            console.debug(`Retention cleanup removed expired record from ${className}`);
+                            this.printDebug(`Retention cleanup removed expired record from ${className}`);
                             cursor.continue();
                         };
                         deleteRequest.onerror = () => {
@@ -872,7 +883,7 @@ class Database {
                 applyTimestampFields(item);
                 return this.performOperation(cls.name, 'readwrite', (store) => {
                     return createStoredItem(store, item).then(() => {
-                        console.debug(`Item added to ${cls.name}:`, item);
+                        this.printDebug(`Item added to ${cls.name}:`, item);
                     });
                 }, transaction);
             }),
@@ -887,7 +898,7 @@ class Database {
                     const request = store.get(key);
                     return new Promise((resolve, reject) => {
                         request.onsuccess = () => {
-                            console.debug(`Item read from ${cls.name}:`, request.result);
+                            this.printDebug(`Item read from ${cls.name}:`, request.result);
                             resolve(request.result);
                         };
                         request.onerror = () => reject(request.error);
@@ -898,7 +909,7 @@ class Database {
                 validateItem(item);
                 return this.performOperation(cls.name, 'readwrite', (store) => {
                     return updateStoredItem(store, item).then(() => {
-                        console.debug(`Item updated in ${cls.name}:`, item);
+                        this.printDebug(`Item updated in ${cls.name}:`, item);
                     });
                 }, transaction);
             }),
@@ -911,7 +922,7 @@ class Database {
             delete: (key) => __awaiter(this, void 0, void 0, function* () {
                 return this.performOperation(cls.name, 'readwrite', (store) => {
                     return deleteStoredItem(store, key).then(() => {
-                        console.debug(`Item deleted from ${cls.name}:`, key);
+                        this.printDebug(`Item deleted from ${cls.name}:`, key);
                     });
                 }, transaction);
             }),
@@ -937,7 +948,7 @@ class Database {
                     const request = store.getAll();
                     return new Promise((resolve, reject) => {
                         request.onsuccess = () => {
-                            console.debug(`All items from ${cls.name}:`, request.result);
+                            this.printDebug(`All items from ${cls.name}:`, request.result);
                             resolve(request.result);
                         };
                         request.onerror = () => reject(request.error);
@@ -951,7 +962,7 @@ class Database {
                         request.onsuccess = () => {
                             const items = request.result;
                             const paginatedItems = items.slice((page - 1) * pageSize, page * pageSize);
-                            console.debug(`Paginated items from ${cls.name}:`, paginatedItems);
+                            this.printDebug(`Paginated items from ${cls.name}:`, paginatedItems);
                             resolve(paginatedItems);
                         };
                         request.onerror = () => reject(request.error);
@@ -967,7 +978,7 @@ class Database {
                     const request = index.getAll(value);
                     return new Promise((resolve, reject) => {
                         request.onsuccess = () => {
-                            console.debug(`Items found by index ${indexName} with value ${value}:`, request.result);
+                            this.printDebug(`Items found by index ${indexName} with value ${value}:`, request.result);
                             resolve(request.result);
                         };
                         request.onerror = () => reject(request.error);
@@ -983,7 +994,7 @@ class Database {
                     const request = index.get(value);
                     return new Promise((resolve, reject) => {
                         request.onsuccess = () => {
-                            console.debug(`Item found by index ${indexName} with value ${value}:`, request.result);
+                            this.printDebug(`Item found by index ${indexName} with value ${value}:`, request.result);
                             resolve(request.result);
                         };
                         request.onerror = () => reject(request.error);
@@ -995,7 +1006,7 @@ class Database {
                     const request = store.count();
                     return new Promise((resolve, reject) => {
                         request.onsuccess = () => {
-                            console.debug(`Count for ${cls.name}:`, request.result);
+                            this.printDebug(`Count for ${cls.name}:`, request.result);
                             resolve(request.result);
                         };
                         request.onerror = () => reject(request.error);
@@ -1008,7 +1019,7 @@ class Database {
                     return new Promise((resolve, reject) => {
                         request.onsuccess = () => {
                             const exists = request.result > 0;
-                            console.debug(`Exists check for ${cls.name} with key ${key}:`, exists);
+                            this.printDebug(`Exists check for ${cls.name} with key ${key}:`, exists);
                             resolve(exists);
                         };
                         request.onerror = () => reject(request.error);
@@ -1020,7 +1031,7 @@ class Database {
                     const request = store.clear();
                     return new Promise((resolve, reject) => {
                         request.onsuccess = () => {
-                            console.debug(`Cleared all items from ${cls.name}`);
+                            this.printDebug(`Cleared all items from ${cls.name}`);
                             resolve();
                         };
                         request.onerror = () => reject(request.error);

package/lib/index.js

@@ -517,12 +517,23 @@ function DataClass(options = {}) {
     };
 }
 class Database {
-    constructor(dbName, classes) {
+    constructor(dbName, classes, printEnabled = false) {
         this.db = null;
         this.entityRepositories = new Map();
         this.retentionTimer = null;
         this.retentionCleanupRunning = false;
+        this.printDebug = (...data) => {
+            if (!this.printEnabled)
+                return;
+            console.debug('[idb-ts]:DEBUG:', ...data);
+        };
+        this.printError = (...error) => {
+            if (!this.printEnabled)
+                return;
+            console.error('[idb-ts]:ERROR:', ...error);
+        };
         this.dbName = dbName;
+        this.printEnabled = printEnabled;
         if (!classes.every((cls) => Reflect.getMetadata('dataclass', cls))) {
             throw new Error('All classes should be decorated with @DataClass.');
         }
@@ -562,7 +573,7 @@ class Database {
                     const db = request.result;
                     const oldVersion = event.oldVersion;
                     const newVersion = event.newVersion || this.dbVersion;
-                    console.debug(`Database upgrade from version ${oldVersion} to ${newVersion}`);
+                    this.printDebug(`Database upgrade from version ${oldVersion} to ${newVersion}`);
                     this.classes.forEach((cls) => {
                         var _a;
                         const keyPathMetadata = Reflect.getMetadata('keypath', cls);
@@ -571,7 +582,7 @@ class Database {
                         const storeName = cls.name.toLowerCase();
                         if (classVersion > oldVersion) {
                             if (!db.objectStoreNames.contains(storeName)) {
-                                console.debug(`Creating object store: ${storeName} (version ${classVersion})`);
+                                this.printDebug(`Creating object store: ${storeName} (version ${classVersion})`);
                                 const storeOptions = {};
                                 if (keyPathMetadata) {
                                     storeOptions.keyPath = keyPathMetadata.fields;
@@ -594,7 +605,7 @@ class Database {
                                 });
                             }
                             else {
-                                console.debug(`Updating object store: ${storeName} (version ${classVersion})`);
+                                this.printDebug(`Updating object store: ${storeName} (version ${classVersion})`);
                                 const transaction = request.transaction;
                                 if (transaction) {
                                     const store = transaction.objectStore(storeName);
@@ -607,7 +618,7 @@ class Database {
                                             ? { unique: false }
                                             : ((_a = indexField.options) !== null && _a !== void 0 ? _a : { unique: false });
                                         if (!store.indexNames.contains(indexName)) {
-                                            console.debug(`Adding index: ${indexName} to ${storeName}`);
+                                            this.printDebug(`Adding index: ${indexName} to ${storeName}`);
                                             store.createIndex(indexName, indexName, indexOptions);
                                         }
                                     });
@@ -618,12 +629,12 @@ class Database {
                 };
                 request.onsuccess = () => {
                     this.db = request.result;
-                    console.debug(`Database initialized (version ${this.dbVersion}) with object stores for: ${this.classes.map((cls) => `${cls.name}(v${Reflect.getMetadata('version', cls) || 1})`).join(', ')}`);
+                    this.printDebug(`Database initialized (version ${this.dbVersion}) with object stores for: ${this.classes.map((cls) => `${cls.name}(v${Reflect.getMetadata('version', cls) || 1})`).join(', ')}`);
                     this.startRetentionCleanup();
                     resolve();
                 };
                 request.onerror = () => {
-                    console.error('Error initializing database:', request.error);
+                    this.printError('Error initializing database:', request.error);
                     reject(request.error);
                 };
             });
@@ -664,7 +675,7 @@ class Database {
         if (!cleanupIntervalMs || !this.db || this.retentionTimer) {
             return;
         }
-        console.debug(`Retention cleanup enabled for ${this.retentionPolicies.length} entities every ${cleanupIntervalMs}ms`);
+        this.printDebug(`Retention cleanup enabled for ${this.retentionPolicies.length} entities every ${cleanupIntervalMs}ms`);
         void this.runRetentionCleanup();
         this.retentionTimer = setInterval(() => {
             void this.runRetentionCleanup();
@@ -679,11 +690,11 @@ class Database {
             }
             this.retentionCleanupRunning = true;
             try {
-                console.debug('Retention cleanup tick started');
+                this.printDebug('Retention cleanup tick started');
                 for (const { storeName, className, policy } of this.retentionPolicies) {
                     yield this.cleanupExpiredRecords(storeName, className, policy);
                 }
-                console.debug('Retention cleanup tick finished');
+                this.printDebug('Retention cleanup tick finished');
             }
             finally {
                 this.retentionCleanupRunning = false;
@@ -707,11 +718,11 @@ class Database {
                     }
                     const value = cursor.value;
                     const timestamp = value === null || value === void 0 ? void 0 : value[policy.field];
-                    console.debug(`Retention cleanup inspecting ${className}.${policy.field}:`, timestamp, 'cutoff:', cutoff);
+                    this.printDebug(`Retention cleanup inspecting ${className}.${policy.field}:`, timestamp, 'cutoff:', cutoff);
                     if (typeof timestamp === 'number' && timestamp <= cutoff) {
                         const deleteRequest = cursor.delete();
                         deleteRequest.onsuccess = () => {
-                            console.debug(`Retention cleanup removed expired record from ${className}`);
+                            this.printDebug(`Retention cleanup removed expired record from ${className}`);
                             cursor.continue();
                         };
                         deleteRequest.onerror = () => {
@@ -872,7 +883,7 @@ class Database {
                 applyTimestampFields(item);
                 return this.performOperation(cls.name, 'readwrite', (store) => {
                     return createStoredItem(store, item).then(() => {
-                        console.debug(`Item added to ${cls.name}:`, item);
+                        this.printDebug(`Item added to ${cls.name}:`, item);
                     });
                 }, transaction);
             }),
@@ -887,7 +898,7 @@ class Database {
                     const request = store.get(key);
                     return new Promise((resolve, reject) => {
                         request.onsuccess = () => {
-                            console.debug(`Item read from ${cls.name}:`, request.result);
+                            this.printDebug(`Item read from ${cls.name}:`, request.result);
                             resolve(request.result);
                         };
                         request.onerror = () => reject(request.error);
@@ -898,7 +909,7 @@ class Database {
                 validateItem(item);
                 return this.performOperation(cls.name, 'readwrite', (store) => {
                     return updateStoredItem(store, item).then(() => {
-                        console.debug(`Item updated in ${cls.name}:`, item);
+                        this.printDebug(`Item updated in ${cls.name}:`, item);
                     });
                 }, transaction);
             }),
@@ -911,7 +922,7 @@ class Database {
             delete: (key) => __awaiter(this, void 0, void 0, function* () {
                 return this.performOperation(cls.name, 'readwrite', (store) => {
                     return deleteStoredItem(store, key).then(() => {
-                        console.debug(`Item deleted from ${cls.name}:`, key);
+                        this.printDebug(`Item deleted from ${cls.name}:`, key);
                     });
                 }, transaction);
             }),
@@ -937,7 +948,7 @@ class Database {
                     const request = store.getAll();
                     return new Promise((resolve, reject) => {
                         request.onsuccess = () => {
-                            console.debug(`All items from ${cls.name}:`, request.result);
+                            this.printDebug(`All items from ${cls.name}:`, request.result);
                             resolve(request.result);
                         };
                         request.onerror = () => reject(request.error);
@@ -951,7 +962,7 @@ class Database {
                         request.onsuccess = () => {
                             const items = request.result;
                             const paginatedItems = items.slice((page - 1) * pageSize, page * pageSize);
-                            console.debug(`Paginated items from ${cls.name}:`, paginatedItems);
+                            this.printDebug(`Paginated items from ${cls.name}:`, paginatedItems);
                             resolve(paginatedItems);
                         };
                         request.onerror = () => reject(request.error);
@@ -967,7 +978,7 @@ class Database {
                     const request = index.getAll(value);
                     return new Promise((resolve, reject) => {
                         request.onsuccess = () => {
-                            console.debug(`Items found by index ${indexName} with value ${value}:`, request.result);
+                            this.printDebug(`Items found by index ${indexName} with value ${value}:`, request.result);
                             resolve(request.result);
                         };
                         request.onerror = () => reject(request.error);
@@ -983,7 +994,7 @@ class Database {
                     const request = index.get(value);
                     return new Promise((resolve, reject) => {
                         request.onsuccess = () => {
-                            console.debug(`Item found by index ${indexName} with value ${value}:`, request.result);
+                            this.printDebug(`Item found by index ${indexName} with value ${value}:`, request.result);
                             resolve(request.result);
                         };
                         request.onerror = () => reject(request.error);
@@ -995,7 +1006,7 @@ class Database {
                     const request = store.count();
                     return new Promise((resolve, reject) => {
                         request.onsuccess = () => {
-                            console.debug(`Count for ${cls.name}:`, request.result);
+                            this.printDebug(`Count for ${cls.name}:`, request.result);
                             resolve(request.result);
                         };
                         request.onerror = () => reject(request.error);
@@ -1008,7 +1019,7 @@ class Database {
                     return new Promise((resolve, reject) => {
                         request.onsuccess = () => {
                             const exists = request.result > 0;
-                            console.debug(`Exists check for ${cls.name} with key ${key}:`, exists);
+                            this.printDebug(`Exists check for ${cls.name} with key ${key}:`, exists);
                             resolve(exists);
                         };
                         request.onerror = () => reject(request.error);
@@ -1020,7 +1031,7 @@ class Database {
                     const request = store.clear();
                     return new Promise((resolve, reject) => {
                         request.onsuccess = () => {
-                            console.debug(`Cleared all items from ${cls.name}`);
+                            this.printDebug(`Cleared all items from ${cls.name}`);
                             resolve();
                         };
                         request.onerror = () => reject(request.error);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "idb-ts",
-  "version": "3.14.0",
+  "version": "3.15.0",
   "description": "Easy CRUD for indexed-db, written in TypeScript",
   "main": "lib/index.js",
   "module": "lib/index.esm.js",
@@ -25,7 +25,9 @@
     "test:types": "tsc -p tsconfig.test.json --noEmit",
     "test:watch": "jest --watchAll --runInBand --detectOpenHandles",
     "test:coverage": "jest --coverage --runInBand --detectOpenHandles",
-    "test:coverage:watch": "jest --coverage --watchAll --runInBand --detectOpenHandles"
+    "test:coverage:watch": "jest --coverage --watchAll --runInBand --detectOpenHandles",
+    "test:performance": "npx tsx performance.ts",
+    "docs:generate": "typedoc"
   },
   "repository": {
     "type": "git",
@@ -70,6 +72,7 @@
     "prettier": "^3.8.3",
     "rollup": "^4.60.1",
     "ts-jest": "^29.4.9",
+    "typedoc": "^0.28.19",
     "typescript": "^6.0.3"
   }
-}
+}