idb-ts 3.10.0 → 3.11.1

package/README.md

@@ -31,7 +31,9 @@
 ## 📦 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
@@ -166,6 +168,92 @@ const firstElectronic = await db.Product.findOneByIndex('category', 'Electronics
 - `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
@@ -415,13 +503,11 @@ 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

package/lib/index.d.ts

@@ -13,14 +13,14 @@ declare class QueryBuilder<T> {
     private rangeEnd?;
     private currentField?;
     constructor(db: IDBDatabase, storeName: string);
-    where(field: string): this;
-    and(field: string): this;
+    where(field: Extract<keyof T, string>): this;
+    and(field: Extract<keyof T, string>): this;
     equals(value: any): this;
     gt(value: any): this;
     gte(value: any): this;
     lt(value: any): this;
     lte(value: any): this;
-    orderBy(field: string, direction?: QueryDirection): this;
+    orderBy(field: Extract<keyof T, string>, direction?: QueryDirection): this;
     limit(n: number): this;
     offset(n: number): this;
     useIndex(indexName: string): this;
@@ -31,6 +31,16 @@ interface KeyPathOptions {
     autoIncrement?: boolean;
     generator?: 'uuid' | 'timestamp' | 'random' | ((item?: any) => string | number);
 }
+interface RetentionPolicyOptions {
+    seconds: number;
+    enabled?: boolean;
+    field?: string;
+}
+interface RetentionPolicyMetadata {
+    seconds: number;
+    enabled: boolean;
+    field: string;
+}
 interface KeyPathMetadata {
     fields: string | string[];
     options?: KeyPathOptions;
@@ -42,16 +52,22 @@ declare class KeyGenerators {
 }
 declare function KeyPath(options?: KeyPathOptions): PropertyDecorator;
 declare function CompositeKeyPath(fields: string[], options?: KeyPathOptions): ClassDecorator;
-declare function Index(): PropertyDecorator;
+declare function Index(options?: IDBIndexParameters): PropertyDecorator;
+declare function Validate<T = any>(predicate: (value: any, item: T) => boolean, message: string): PropertyDecorator;
+declare function RetentionPolicy(options: RetentionPolicyOptions): ClassDecorator;
 interface DataClassOptions {
     version?: number;
 }
 declare function DataClass(options?: DataClassOptions): ClassDecorator;
 interface EntityRepository<T> {
     create(item: T): Promise<void>;
+    createMany(items: T[]): Promise<void>;
     read(key: string | string[] | number): Promise<T | undefined>;
     update(item: T): Promise<void>;
+    updateMany(items: T[]): Promise<void>;
     delete(key: string | string[] | number): Promise<void>;
+    deleteMany(keys: Array<string | string[] | number>): Promise<void>;
+    deleteWhere(predicate: (query: QueryBuilder<T>) => QueryBuilder<T> | void): Promise<void>;
     list(): Promise<T[]>;
     listPaginated(page: number, pageSize: number): Promise<T[]>;
     findByIndex(indexName: string, value: any): Promise<T[]>;
@@ -68,17 +84,25 @@ declare class Database {
     private db;
     private entityRepositories;
     private dbVersion;
+    private retentionTimer;
+    private retentionCleanupRunning;
+    private retentionPolicies;
     private constructor();
     private calculateDatabaseVersion;
     static build<T extends Record<string, EntityRepository<any>>>(dbName: string, classes: Function[]): Promise<DatabaseWithRepositories<T>>;
     private initDB;
     private generateEntityRepositories;
+    private calculateRetentionCleanupIntervalMs;
+    private startRetentionCleanup;
+    private runRetentionCleanup;
+    private cleanupExpiredRecords;
     private createEntityRepository;
     private performOperation;
+    close(): void;
     getAvailableEntities(): string[];
     getDatabaseVersion(): number;
     getEntityVersions(): Map<string, number>;
     getEntityVersion(entityName: string): number | undefined;
 }
-export { Database, KeyPath, CompositeKeyPath, DataClass, Index, EntityRepository, KeyGenerators };
-export type { DatabaseWithRepositories, DataClassOptions, KeyPathOptions, KeyPathMetadata };
+export { Database, KeyPath, CompositeKeyPath, DataClass, Index, Validate, RetentionPolicy, EntityRepository, KeyGenerators };
+export type { DatabaseWithRepositories, DataClassOptions, KeyPathOptions, KeyPathMetadata, RetentionPolicyOptions, RetentionPolicyMetadata };

package/lib/index.esm.js

@@ -1,5 +1,5 @@
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.KeyGenerators = exports.Index = exports.DataClass = exports.CompositeKeyPath = exports.KeyPath = exports.Database = void 0;
+exports.KeyGenerators = exports.RetentionPolicy = exports.Validate = exports.Index = exports.DataClass = exports.CompositeKeyPath = exports.KeyPath = exports.Database = void 0;
 const tslib_1 = require("tslib");
 require("reflect-metadata");
 class QueryBuilder {
@@ -78,7 +78,7 @@ class QueryBuilder {
         return tslib_1.__awaiter(this, void 0, void 0, function* () {
             return new Promise((resolve, reject) => {
                 const tx = this.db.transaction(this.storeName, 'readonly');
-                let store = tx.objectStore(this.storeName);
+                const store = tx.objectStore(this.storeName);
                 let request;
                 let results = [];
                 if (this.indexName) {
@@ -155,6 +155,8 @@ class QueryBuilder {
         });
     }
 }
+const INTERNAL_CREATED_AT_FIELD = '__idb_createdAt';
+const INTERNAL_UPDATED_AT_FIELD = '__idb_updatedAt';
 class KeyGenerators {
     static uuid() {
         return 'xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx'.replace(/[xy]/g, function (c) {
@@ -195,14 +197,39 @@ function CompositeKeyPath(fields, options) {
     };
 }
 exports.CompositeKeyPath = CompositeKeyPath;
-function Index() {
+function Index(options) {
     return (target, propertyKey) => {
         const constructor = target.constructor;
         const existing = Reflect.getMetadata("indexes", constructor) || [];
-        Reflect.defineMetadata("indexes", [...existing, propertyKey], constructor);
+        const nextIndexes = [...existing, { field: propertyKey, options }];
+        Reflect.defineMetadata("indexes", nextIndexes, constructor);
     };
 }
 exports.Index = Index;
+function Validate(predicate, message) {
+    return (target, propertyKey) => {
+        const constructor = target.constructor;
+        const existing = Reflect.getMetadata('validators', constructor) || [];
+        const nextRules = [...existing, { field: propertyKey, predicate, message }];
+        Reflect.defineMetadata('validators', nextRules, constructor);
+    };
+}
+exports.Validate = Validate;
+function RetentionPolicy(options) {
+    return (target) => {
+        var _a, _b;
+        if (!Number.isInteger(options.seconds) || options.seconds <= 0) {
+            throw new Error('RetentionPolicy.seconds must be a positive integer.');
+        }
+        const metadata = {
+            seconds: options.seconds,
+            enabled: (_a = options.enabled) !== null && _a !== void 0 ? _a : true,
+            field: (_b = options.field) !== null && _b !== void 0 ? _b : INTERNAL_CREATED_AT_FIELD
+        };
+        Reflect.defineMetadata('retention_policy', metadata, target);
+    };
+}
+exports.RetentionPolicy = RetentionPolicy;
 function DataClass(options = {}) {
     return (target) => {
         const keyPathMetadata = Reflect.getMetadata("keypath", target);
@@ -223,12 +250,27 @@ class Database {
     constructor(dbName, classes) {
         this.db = null;
         this.entityRepositories = new Map();
+        this.retentionTimer = null;
+        this.retentionCleanupRunning = false;
         this.dbName = dbName;
         if (!classes.every(cls => Reflect.getMetadata("dataclass", cls))) {
             throw new Error("All classes should be decorated with @DataClass.");
         }
         this.classes = classes;
         this.dbVersion = this.calculateDatabaseVersion();
+        this.retentionPolicies = this.classes
+            .map((cls) => {
+            const policy = Reflect.getMetadata('retention_policy', cls);
+            if (!(policy === null || policy === void 0 ? void 0 : policy.enabled)) {
+                return null;
+            }
+            return {
+                className: cls.name,
+                storeName: cls.name.toLowerCase(),
+                policy
+            };
+        })
+            .filter((policy) => policy !== null);
     }
     calculateDatabaseVersion() {
         const versions = this.classes.map(cls => Reflect.getMetadata("version", cls) || 1);
@@ -269,8 +311,13 @@ class Database {
                                 }
                                 const store = db.createObjectStore(storeName, storeOptions);
                                 indexFields.forEach((indexField) => {
-                                    if (!store.indexNames.contains(indexField)) {
-                                        store.createIndex(indexField, indexField, { unique: false });
+                                    var _a;
+                                    const indexName = typeof indexField === 'string' ? indexField : indexField.field;
+                                    const indexOptions = typeof indexField === 'string'
+                                        ? { unique: false }
+                                        : ((_a = indexField.options) !== null && _a !== void 0 ? _a : { unique: false });
+                                    if (!store.indexNames.contains(indexName)) {
+                                        store.createIndex(indexName, indexName, indexOptions);
                                     }
                                 });
                             }
@@ -280,9 +327,14 @@ class Database {
                                 if (transaction) {
                                     const store = transaction.objectStore(storeName);
                                     indexFields.forEach((indexField) => {
-                                        if (!store.indexNames.contains(indexField)) {
-                                            console.debug(`Adding index: ${indexField} to ${storeName}`);
-                                            store.createIndex(indexField, indexField, { unique: false });
+                                        var _a;
+                                        const indexName = typeof indexField === 'string' ? indexField : indexField.field;
+                                        const indexOptions = typeof indexField === 'string'
+                                            ? { unique: false }
+                                            : ((_a = indexField.options) !== null && _a !== void 0 ? _a : { unique: false });
+                                        if (!store.indexNames.contains(indexName)) {
+                                            console.debug(`Adding index: ${indexName} to ${storeName}`);
+                                            store.createIndex(indexName, indexName, indexOptions);
                                         }
                                     });
                                 }
@@ -293,6 +345,7 @@ 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.startRetentionCleanup();
                     resolve();
                 };
                 request.onerror = () => {
@@ -315,8 +368,114 @@ class Database {
             });
         });
     }
+    calculateRetentionCleanupIntervalMs() {
+        if (!this.retentionPolicies.length) {
+            return undefined;
+        }
+        const gcd = (left, right) => {
+            let a = left;
+            let b = right;
+            while (b !== 0) {
+                const remainder = a % b;
+                a = b;
+                b = remainder;
+            }
+            return Math.abs(a);
+        };
+        const seconds = this.retentionPolicies.map(({ policy }) => policy.seconds);
+        return seconds.reduce((accumulator, value) => gcd(accumulator, value)) * 1000;
+    }
+    startRetentionCleanup() {
+        const cleanupIntervalMs = this.calculateRetentionCleanupIntervalMs();
+        if (!cleanupIntervalMs || !this.db || this.retentionTimer) {
+            return;
+        }
+        console.debug(`Retention cleanup enabled for ${this.retentionPolicies.length} entities every ${cleanupIntervalMs}ms`);
+        void this.runRetentionCleanup();
+        this.retentionTimer = setInterval(() => {
+            void this.runRetentionCleanup();
+        }, cleanupIntervalMs);
+    }
+    runRetentionCleanup() {
+        return tslib_1.__awaiter(this, void 0, void 0, function* () {
+            if (!this.db || this.retentionCleanupRunning || !this.retentionPolicies.length) {
+                return;
+            }
+            this.retentionCleanupRunning = true;
+            try {
+                console.debug('Retention cleanup tick started');
+                for (const { storeName, className, policy } of this.retentionPolicies) {
+                    yield this.cleanupExpiredRecords(storeName, className, policy);
+                }
+                console.debug('Retention cleanup tick finished');
+            }
+            finally {
+                this.retentionCleanupRunning = false;
+            }
+        });
+    }
+    cleanupExpiredRecords(storeName, className, policy) {
+        if (!this.db) {
+            return Promise.resolve();
+        }
+        return new Promise((resolve, reject) => {
+            try {
+                const transaction = this.db.transaction(storeName, 'readwrite');
+                const store = transaction.objectStore(storeName);
+                const cutoff = Date.now() - (policy.seconds * 1000);
+                const request = store.openCursor();
+                request.onsuccess = () => {
+                    const cursor = request.result;
+                    if (!cursor) {
+                        return;
+                    }
+                    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);
+                    if (typeof timestamp === 'number' && timestamp <= cutoff) {
+                        const deleteRequest = cursor.delete();
+                        deleteRequest.onsuccess = () => {
+                            console.debug(`Retention cleanup removed expired record from ${className}`);
+                            cursor.continue();
+                        };
+                        deleteRequest.onerror = () => { var _a; return reject((_a = deleteRequest.error) !== null && _a !== void 0 ? _a : new Error(`Retention cleanup delete failed for ${className}`)); };
+                        return;
+                    }
+                    cursor.continue();
+                };
+                transaction.oncomplete = () => resolve();
+                transaction.onerror = () => { var _a; return reject((_a = transaction.error) !== null && _a !== void 0 ? _a : new Error(`Retention cleanup failed for ${className}`)); };
+                transaction.onabort = () => { var _a; return reject((_a = transaction.error) !== null && _a !== void 0 ? _a : new Error(`Retention cleanup aborted for ${className}`)); };
+            }
+            catch (error) {
+                reject(error);
+            }
+        });
+    }
     createEntityRepository(cls) {
         const self = this;
+        const creationTimestampField = INTERNAL_CREATED_AT_FIELD;
+        const updateTimestampField = INTERNAL_UPDATED_AT_FIELD;
+        const validators = (Reflect.getMetadata('validators', cls) || []);
+        const validateItem = (item) => {
+            const failures = [];
+            validators.forEach((rule) => {
+                const value = item[rule.field];
+                let valid = false;
+                try {
+                    valid = rule.predicate(value, item);
+                }
+                catch (_a) {
+                    valid = false;
+                }
+                if (!valid) {
+                    failures.push(`${rule.field}: ${rule.message}`);
+                }
+            });
+            if (failures.length) {
+                throw new Error(`Validation failed for ${cls.name}: ${failures.join('; ')}`);
+            }
+        };
         const generateKey = (item) => {
             var _a;
             const keyPathMetadata = Reflect.getMetadata("keypath", cls);
@@ -337,6 +496,46 @@ class Database {
                     return undefined;
             }
         };
+        const applyTimestampFields = (item, existingItem) => {
+            const now = Date.now();
+            const existingCreationValue = existingItem ? existingItem[creationTimestampField] : undefined;
+            item[creationTimestampField] = existingCreationValue !== undefined ? existingCreationValue : now;
+            item[updateTimestampField] = now;
+        };
+        const readExistingItem = (store, key) => {
+            return new Promise((resolve, reject) => {
+                const request = store.get(key);
+                request.onsuccess = () => resolve(request.result);
+                request.onerror = () => reject(request.error);
+            });
+        };
+        const createStoredItem = (store, item) => {
+            return new Promise((resolve, reject) => {
+                const request = store.add(item);
+                request.onsuccess = () => resolve();
+                request.onerror = () => reject(request.error);
+            });
+        };
+        const updateStoredItem = (store, item) => tslib_1.__awaiter(this, void 0, void 0, function* () {
+            const key = extractKey(item);
+            let existingItem;
+            if (key !== undefined && key !== null) {
+                existingItem = yield readExistingItem(store, key);
+            }
+            applyTimestampFields(item, existingItem);
+            yield new Promise((resolve, reject) => {
+                const request = store.put(item);
+                request.onsuccess = () => resolve();
+                request.onerror = () => reject(request.error);
+            });
+        });
+        const deleteStoredItem = (store, key) => {
+            return new Promise((resolve, reject) => {
+                const request = store.delete(key);
+                request.onsuccess = () => resolve();
+                request.onerror = () => reject(request.error);
+            });
+        };
         const extractKey = (item) => {
             const keyPathMetadata = Reflect.getMetadata("keypath", cls);
             if (!keyPathMetadata)
@@ -377,17 +576,20 @@ class Database {
                         }
                     }
                 }
+                validateItem(item);
+                applyTimestampFields(item);
                 return this.performOperation(cls.name, 'readwrite', (store) => {
-                    const request = store.add(item);
-                    return new Promise((resolve, reject) => {
-                        request.onsuccess = () => {
-                            console.debug(`Item added to ${cls.name}:`, item);
-                            resolve();
-                        };
-                        request.onerror = () => reject(request.error);
+                    return createStoredItem(store, item).then(() => {
+                        console.debug(`Item added to ${cls.name}:`, item);
                     });
                 });
             }),
+            createMany: (items) => tslib_1.__awaiter(this, void 0, void 0, function* () {
+                const repository = this.createEntityRepository(cls);
+                for (const item of items) {
+                    yield repository.create(item);
+                }
+            }),
             read: (key) => tslib_1.__awaiter(this, void 0, void 0, function* () {
                 return this.performOperation(cls.name, 'readonly', (store) => {
                     const request = store.get(key);
@@ -401,29 +603,43 @@ class Database {
                 });
             }),
             update: (item) => tslib_1.__awaiter(this, void 0, void 0, function* () {
+                validateItem(item);
                 return this.performOperation(cls.name, 'readwrite', (store) => {
-                    const request = store.put(item);
-                    return new Promise((resolve, reject) => {
-                        request.onsuccess = () => {
-                            console.debug(`Item updated in ${cls.name}:`, item);
-                            resolve();
-                        };
-                        request.onerror = () => reject(request.error);
+                    return updateStoredItem(store, item).then(() => {
+                        console.debug(`Item updated in ${cls.name}:`, item);
                     });
                 });
             }),
+            updateMany: (items) => tslib_1.__awaiter(this, void 0, void 0, function* () {
+                const repository = this.createEntityRepository(cls);
+                for (const item of items) {
+                    yield repository.update(item);
+                }
+            }),
             delete: (key) => tslib_1.__awaiter(this, void 0, void 0, function* () {
                 return this.performOperation(cls.name, 'readwrite', (store) => {
-                    const request = store.delete(key);
-                    return new Promise((resolve, reject) => {
-                        request.onsuccess = () => {
-                            console.debug(`Item deleted from ${cls.name}:`, key);
-                            resolve();
-                        };
-                        request.onerror = () => reject(request.error);
+                    return deleteStoredItem(store, key).then(() => {
+                        console.debug(`Item deleted from ${cls.name}:`, key);
                     });
                 });
             }),
+            deleteMany: (keys) => tslib_1.__awaiter(this, void 0, void 0, function* () {
+                const repository = this.createEntityRepository(cls);
+                for (const key of keys) {
+                    yield repository.delete(key);
+                }
+            }),
+            deleteWhere: (predicate) => tslib_1.__awaiter(this, void 0, void 0, function* () {
+                var _b;
+                const repository = this.createEntityRepository(cls);
+                const query = repository.query();
+                const resolvedQuery = (_b = predicate(query)) !== null && _b !== void 0 ? _b : query;
+                const matches = yield resolvedQuery.execute();
+                const keys = matches
+                    .map((item) => extractKey(item))
+                    .filter((key) => key !== undefined && key !== null);
+                yield repository.deleteMany(keys);
+            }),
             list: () => tslib_1.__awaiter(this, void 0, void 0, function* () {
                 return this.performOperation(cls.name, 'readonly', (store) => {
                     const request = store.getAll();
@@ -532,6 +748,16 @@ class Database {
             return operation(store);
         });
     }
+    close() {
+        if (this.retentionTimer) {
+            clearInterval(this.retentionTimer);
+            this.retentionTimer = null;
+        }
+        if (this.db) {
+            this.db.close();
+            this.db = null;
+        }
+    }
     getAvailableEntities() {
         return Array.from(this.entityRepositories.keys());
     }

package/lib/index.js

@@ -9,7 +9,7 @@ var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, ge
     });
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.KeyGenerators = exports.Index = exports.DataClass = exports.CompositeKeyPath = exports.KeyPath = exports.Database = void 0;
+exports.KeyGenerators = exports.RetentionPolicy = exports.Validate = exports.Index = exports.DataClass = exports.CompositeKeyPath = exports.KeyPath = exports.Database = void 0;
 require("reflect-metadata");
 class QueryBuilder {
     constructor(db, storeName) {
@@ -87,7 +87,7 @@ class QueryBuilder {
         return __awaiter(this, void 0, void 0, function* () {
             return new Promise((resolve, reject) => {
                 const tx = this.db.transaction(this.storeName, 'readonly');
-                let store = tx.objectStore(this.storeName);
+                const store = tx.objectStore(this.storeName);
                 let request;
                 let results = [];
                 if (this.indexName) {
@@ -164,6 +164,8 @@ class QueryBuilder {
         });
     }
 }
+const INTERNAL_CREATED_AT_FIELD = '__idb_createdAt';
+const INTERNAL_UPDATED_AT_FIELD = '__idb_updatedAt';
 class KeyGenerators {
     static uuid() {
         return 'xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx'.replace(/[xy]/g, function (c) {
@@ -204,14 +206,39 @@ function CompositeKeyPath(fields, options) {
     };
 }
 exports.CompositeKeyPath = CompositeKeyPath;
-function Index() {
+function Index(options) {
     return (target, propertyKey) => {
         const constructor = target.constructor;
         const existing = Reflect.getMetadata("indexes", constructor) || [];
-        Reflect.defineMetadata("indexes", [...existing, propertyKey], constructor);
+        const nextIndexes = [...existing, { field: propertyKey, options }];
+        Reflect.defineMetadata("indexes", nextIndexes, constructor);
     };
 }
 exports.Index = Index;
+function Validate(predicate, message) {
+    return (target, propertyKey) => {
+        const constructor = target.constructor;
+        const existing = Reflect.getMetadata('validators', constructor) || [];
+        const nextRules = [...existing, { field: propertyKey, predicate, message }];
+        Reflect.defineMetadata('validators', nextRules, constructor);
+    };
+}
+exports.Validate = Validate;
+function RetentionPolicy(options) {
+    return (target) => {
+        var _a, _b;
+        if (!Number.isInteger(options.seconds) || options.seconds <= 0) {
+            throw new Error('RetentionPolicy.seconds must be a positive integer.');
+        }
+        const metadata = {
+            seconds: options.seconds,
+            enabled: (_a = options.enabled) !== null && _a !== void 0 ? _a : true,
+            field: (_b = options.field) !== null && _b !== void 0 ? _b : INTERNAL_CREATED_AT_FIELD
+        };
+        Reflect.defineMetadata('retention_policy', metadata, target);
+    };
+}
+exports.RetentionPolicy = RetentionPolicy;
 function DataClass(options = {}) {
     return (target) => {
         const keyPathMetadata = Reflect.getMetadata("keypath", target);
@@ -232,12 +259,27 @@ class Database {
     constructor(dbName, classes) {
         this.db = null;
         this.entityRepositories = new Map();
+        this.retentionTimer = null;
+        this.retentionCleanupRunning = false;
         this.dbName = dbName;
         if (!classes.every(cls => Reflect.getMetadata("dataclass", cls))) {
             throw new Error("All classes should be decorated with @DataClass.");
         }
         this.classes = classes;
         this.dbVersion = this.calculateDatabaseVersion();
+        this.retentionPolicies = this.classes
+            .map((cls) => {
+            const policy = Reflect.getMetadata('retention_policy', cls);
+            if (!(policy === null || policy === void 0 ? void 0 : policy.enabled)) {
+                return null;
+            }
+            return {
+                className: cls.name,
+                storeName: cls.name.toLowerCase(),
+                policy
+            };
+        })
+            .filter((policy) => policy !== null);
     }
     calculateDatabaseVersion() {
         const versions = this.classes.map(cls => Reflect.getMetadata("version", cls) || 1);
@@ -278,8 +320,13 @@ class Database {
                                 }
                                 const store = db.createObjectStore(storeName, storeOptions);
                                 indexFields.forEach((indexField) => {
-                                    if (!store.indexNames.contains(indexField)) {
-                                        store.createIndex(indexField, indexField, { unique: false });
+                                    var _a;
+                                    const indexName = typeof indexField === 'string' ? indexField : indexField.field;
+                                    const indexOptions = typeof indexField === 'string'
+                                        ? { unique: false }
+                                        : ((_a = indexField.options) !== null && _a !== void 0 ? _a : { unique: false });
+                                    if (!store.indexNames.contains(indexName)) {
+                                        store.createIndex(indexName, indexName, indexOptions);
                                     }
                                 });
                             }
@@ -289,9 +336,14 @@ class Database {
                                 if (transaction) {
                                     const store = transaction.objectStore(storeName);
                                     indexFields.forEach((indexField) => {
-                                        if (!store.indexNames.contains(indexField)) {
-                                            console.debug(`Adding index: ${indexField} to ${storeName}`);
-                                            store.createIndex(indexField, indexField, { unique: false });
+                                        var _a;
+                                        const indexName = typeof indexField === 'string' ? indexField : indexField.field;
+                                        const indexOptions = typeof indexField === 'string'
+                                            ? { unique: false }
+                                            : ((_a = indexField.options) !== null && _a !== void 0 ? _a : { unique: false });
+                                        if (!store.indexNames.contains(indexName)) {
+                                            console.debug(`Adding index: ${indexName} to ${storeName}`);
+                                            store.createIndex(indexName, indexName, indexOptions);
                                         }
                                     });
                                 }
@@ -302,6 +354,7 @@ 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.startRetentionCleanup();
                     resolve();
                 };
                 request.onerror = () => {
@@ -324,8 +377,114 @@ class Database {
             });
         });
     }
+    calculateRetentionCleanupIntervalMs() {
+        if (!this.retentionPolicies.length) {
+            return undefined;
+        }
+        const gcd = (left, right) => {
+            let a = left;
+            let b = right;
+            while (b !== 0) {
+                const remainder = a % b;
+                a = b;
+                b = remainder;
+            }
+            return Math.abs(a);
+        };
+        const seconds = this.retentionPolicies.map(({ policy }) => policy.seconds);
+        return seconds.reduce((accumulator, value) => gcd(accumulator, value)) * 1000;
+    }
+    startRetentionCleanup() {
+        const cleanupIntervalMs = this.calculateRetentionCleanupIntervalMs();
+        if (!cleanupIntervalMs || !this.db || this.retentionTimer) {
+            return;
+        }
+        console.debug(`Retention cleanup enabled for ${this.retentionPolicies.length} entities every ${cleanupIntervalMs}ms`);
+        void this.runRetentionCleanup();
+        this.retentionTimer = setInterval(() => {
+            void this.runRetentionCleanup();
+        }, cleanupIntervalMs);
+    }
+    runRetentionCleanup() {
+        return __awaiter(this, void 0, void 0, function* () {
+            if (!this.db || this.retentionCleanupRunning || !this.retentionPolicies.length) {
+                return;
+            }
+            this.retentionCleanupRunning = true;
+            try {
+                console.debug('Retention cleanup tick started');
+                for (const { storeName, className, policy } of this.retentionPolicies) {
+                    yield this.cleanupExpiredRecords(storeName, className, policy);
+                }
+                console.debug('Retention cleanup tick finished');
+            }
+            finally {
+                this.retentionCleanupRunning = false;
+            }
+        });
+    }
+    cleanupExpiredRecords(storeName, className, policy) {
+        if (!this.db) {
+            return Promise.resolve();
+        }
+        return new Promise((resolve, reject) => {
+            try {
+                const transaction = this.db.transaction(storeName, 'readwrite');
+                const store = transaction.objectStore(storeName);
+                const cutoff = Date.now() - (policy.seconds * 1000);
+                const request = store.openCursor();
+                request.onsuccess = () => {
+                    const cursor = request.result;
+                    if (!cursor) {
+                        return;
+                    }
+                    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);
+                    if (typeof timestamp === 'number' && timestamp <= cutoff) {
+                        const deleteRequest = cursor.delete();
+                        deleteRequest.onsuccess = () => {
+                            console.debug(`Retention cleanup removed expired record from ${className}`);
+                            cursor.continue();
+                        };
+                        deleteRequest.onerror = () => { var _a; return reject((_a = deleteRequest.error) !== null && _a !== void 0 ? _a : new Error(`Retention cleanup delete failed for ${className}`)); };
+                        return;
+                    }
+                    cursor.continue();
+                };
+                transaction.oncomplete = () => resolve();
+                transaction.onerror = () => { var _a; return reject((_a = transaction.error) !== null && _a !== void 0 ? _a : new Error(`Retention cleanup failed for ${className}`)); };
+                transaction.onabort = () => { var _a; return reject((_a = transaction.error) !== null && _a !== void 0 ? _a : new Error(`Retention cleanup aborted for ${className}`)); };
+            }
+            catch (error) {
+                reject(error);
+            }
+        });
+    }
     createEntityRepository(cls) {
         const self = this;
+        const creationTimestampField = INTERNAL_CREATED_AT_FIELD;
+        const updateTimestampField = INTERNAL_UPDATED_AT_FIELD;
+        const validators = (Reflect.getMetadata('validators', cls) || []);
+        const validateItem = (item) => {
+            const failures = [];
+            validators.forEach((rule) => {
+                const value = item[rule.field];
+                let valid = false;
+                try {
+                    valid = rule.predicate(value, item);
+                }
+                catch (_a) {
+                    valid = false;
+                }
+                if (!valid) {
+                    failures.push(`${rule.field}: ${rule.message}`);
+                }
+            });
+            if (failures.length) {
+                throw new Error(`Validation failed for ${cls.name}: ${failures.join('; ')}`);
+            }
+        };
         const generateKey = (item) => {
             var _a;
             const keyPathMetadata = Reflect.getMetadata("keypath", cls);
@@ -346,6 +505,46 @@ class Database {
                     return undefined;
             }
         };
+        const applyTimestampFields = (item, existingItem) => {
+            const now = Date.now();
+            const existingCreationValue = existingItem ? existingItem[creationTimestampField] : undefined;
+            item[creationTimestampField] = existingCreationValue !== undefined ? existingCreationValue : now;
+            item[updateTimestampField] = now;
+        };
+        const readExistingItem = (store, key) => {
+            return new Promise((resolve, reject) => {
+                const request = store.get(key);
+                request.onsuccess = () => resolve(request.result);
+                request.onerror = () => reject(request.error);
+            });
+        };
+        const createStoredItem = (store, item) => {
+            return new Promise((resolve, reject) => {
+                const request = store.add(item);
+                request.onsuccess = () => resolve();
+                request.onerror = () => reject(request.error);
+            });
+        };
+        const updateStoredItem = (store, item) => __awaiter(this, void 0, void 0, function* () {
+            const key = extractKey(item);
+            let existingItem;
+            if (key !== undefined && key !== null) {
+                existingItem = yield readExistingItem(store, key);
+            }
+            applyTimestampFields(item, existingItem);
+            yield new Promise((resolve, reject) => {
+                const request = store.put(item);
+                request.onsuccess = () => resolve();
+                request.onerror = () => reject(request.error);
+            });
+        });
+        const deleteStoredItem = (store, key) => {
+            return new Promise((resolve, reject) => {
+                const request = store.delete(key);
+                request.onsuccess = () => resolve();
+                request.onerror = () => reject(request.error);
+            });
+        };
         const extractKey = (item) => {
             const keyPathMetadata = Reflect.getMetadata("keypath", cls);
             if (!keyPathMetadata)
@@ -386,17 +585,20 @@ class Database {
                         }
                     }
                 }
+                validateItem(item);
+                applyTimestampFields(item);
                 return this.performOperation(cls.name, 'readwrite', (store) => {
-                    const request = store.add(item);
-                    return new Promise((resolve, reject) => {
-                        request.onsuccess = () => {
-                            console.debug(`Item added to ${cls.name}:`, item);
-                            resolve();
-                        };
-                        request.onerror = () => reject(request.error);
+                    return createStoredItem(store, item).then(() => {
+                        console.debug(`Item added to ${cls.name}:`, item);
                     });
                 });
             }),
+            createMany: (items) => __awaiter(this, void 0, void 0, function* () {
+                const repository = this.createEntityRepository(cls);
+                for (const item of items) {
+                    yield repository.create(item);
+                }
+            }),
             read: (key) => __awaiter(this, void 0, void 0, function* () {
                 return this.performOperation(cls.name, 'readonly', (store) => {
                     const request = store.get(key);
@@ -410,29 +612,43 @@ class Database {
                 });
             }),
             update: (item) => __awaiter(this, void 0, void 0, function* () {
+                validateItem(item);
                 return this.performOperation(cls.name, 'readwrite', (store) => {
-                    const request = store.put(item);
-                    return new Promise((resolve, reject) => {
-                        request.onsuccess = () => {
-                            console.debug(`Item updated in ${cls.name}:`, item);
-                            resolve();
-                        };
-                        request.onerror = () => reject(request.error);
+                    return updateStoredItem(store, item).then(() => {
+                        console.debug(`Item updated in ${cls.name}:`, item);
                     });
                 });
             }),
+            updateMany: (items) => __awaiter(this, void 0, void 0, function* () {
+                const repository = this.createEntityRepository(cls);
+                for (const item of items) {
+                    yield repository.update(item);
+                }
+            }),
             delete: (key) => __awaiter(this, void 0, void 0, function* () {
                 return this.performOperation(cls.name, 'readwrite', (store) => {
-                    const request = store.delete(key);
-                    return new Promise((resolve, reject) => {
-                        request.onsuccess = () => {
-                            console.debug(`Item deleted from ${cls.name}:`, key);
-                            resolve();
-                        };
-                        request.onerror = () => reject(request.error);
+                    return deleteStoredItem(store, key).then(() => {
+                        console.debug(`Item deleted from ${cls.name}:`, key);
                     });
                 });
             }),
+            deleteMany: (keys) => __awaiter(this, void 0, void 0, function* () {
+                const repository = this.createEntityRepository(cls);
+                for (const key of keys) {
+                    yield repository.delete(key);
+                }
+            }),
+            deleteWhere: (predicate) => __awaiter(this, void 0, void 0, function* () {
+                var _b;
+                const repository = this.createEntityRepository(cls);
+                const query = repository.query();
+                const resolvedQuery = (_b = predicate(query)) !== null && _b !== void 0 ? _b : query;
+                const matches = yield resolvedQuery.execute();
+                const keys = matches
+                    .map((item) => extractKey(item))
+                    .filter((key) => key !== undefined && key !== null);
+                yield repository.deleteMany(keys);
+            }),
             list: () => __awaiter(this, void 0, void 0, function* () {
                 return this.performOperation(cls.name, 'readonly', (store) => {
                     const request = store.getAll();
@@ -541,6 +757,16 @@ class Database {
             return operation(store);
         });
     }
+    close() {
+        if (this.retentionTimer) {
+            clearInterval(this.retentionTimer);
+            this.retentionTimer = null;
+        }
+        if (this.db) {
+            this.db.close();
+            this.db = null;
+        }
+    }
     getAvailableEntities() {
         return Array.from(this.entityRepositories.keys());
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "idb-ts",
-  "version": "3.10.0",
+  "version": "3.11.1",
   "description": "Easy CRUD for indexed-db, written in TypeScript",
   "main": "lib/index.js",
   "module": "lib/index.esm.js",
@@ -18,6 +18,8 @@
     "build": "pnpm run build:tsc && pnpm run build:rollup",
     "build:tsc": "tsc",
     "build:rollup": "rollup -c",
+    "lint": "eslint .",
+    "lint:fix": "eslint . --fix",
     "test": "jest --runInBand --detectOpenHandles",
     "test:watch": "jest --watchAll --runInBand --detectOpenHandles",
     "test:coverage": "jest --coverage --runInBand --detectOpenHandles",
@@ -52,14 +54,19 @@
     "tslib": "^2.8.1"
   },
   "devDependencies": {
+    "@eslint/js": "^9.31.0",
     "@rollup/plugin-typescript": "^12.3.0",
+    "@typescript-eslint/eslint-plugin": "^8.37.0",
+    "@typescript-eslint/parser": "^8.37.0",
     "@types/jest": "^30.0.0",
     "@types/node": "^24.12.0",
     "fake-indexeddb": "^6.2.5",
     "jest": "^30.3.0",
     "jest-environment-jsdom": "^30.3.0",
+    "eslint": "^9.31.0",
     "rollup": "^4.60.1",
     "ts-jest": "^29.4.9",
-    "typescript": "^4.9.5"
+    "typescript": "^4.9.5",
+    "globals": "^15.15.0"
   }
 }