idb-ts 3.13.0 → 3.15.0

package/lib/index.cjs

@@ -0,0 +1,1169 @@
+'use strict';
+
+var tslib = require('tslib');
+require('reflect-metadata');
+
+class FieldQueryBuilder {
+    constructor(parent, field) {
+        this.parent = parent;
+        this.field = field;
+    }
+    equals(value) {
+        this.parent.appendCondition(this.field, 'equals', value);
+        this.parent.clearCurrentField();
+        return this.parent;
+    }
+    gt(value) {
+        this.parent.appendCondition(this.field, 'gt', value);
+        this.parent.clearCurrentField();
+        return this.parent;
+    }
+    gte(value) {
+        this.parent.appendCondition(this.field, 'gte', value);
+        this.parent.clearCurrentField();
+        return this.parent;
+    }
+    lt(value) {
+        this.parent.appendCondition(this.field, 'lt', value);
+        this.parent.clearCurrentField();
+        return this.parent;
+    }
+    lte(value) {
+        this.parent.appendCondition(this.field, 'lte', value);
+        this.parent.clearCurrentField();
+        return this.parent;
+    }
+    startsWith(value) {
+        this.parent.appendCondition(this.field, 'startsWith', value);
+        this.parent.clearCurrentField();
+        return this.parent;
+    }
+    endsWith(value) {
+        this.parent.appendCondition(this.field, 'endsWith', value);
+        this.parent.clearCurrentField();
+        return this.parent;
+    }
+    contains(value) {
+        this.parent.appendCondition(this.field, 'contains', value);
+        this.parent.clearCurrentField();
+        return this.parent;
+    }
+    matches(value) {
+        this.parent.appendCondition(this.field, 'matches', value);
+        this.parent.clearCurrentField();
+        return this.parent;
+    }
+    between(start, end) {
+        this.parent.appendCondition(this.field, 'between', [start, end]);
+        this.parent.clearCurrentField();
+        return this.parent;
+    }
+    notBetween(start, end) {
+        this.parent.appendCondition(this.field, 'notBetween', [start, end]);
+        this.parent.clearCurrentField();
+        return this.parent;
+    }
+    in(values) {
+        this.parent.appendCondition(this.field, 'in', values);
+        this.parent.clearCurrentField();
+        return this.parent;
+    }
+    notIn(values) {
+        this.parent.appendCondition(this.field, 'notIn', values);
+        this.parent.clearCurrentField();
+        return this.parent;
+    }
+    containsAny(values) {
+        this.parent.appendCondition(this.field, 'containsAny', values);
+        this.parent.clearCurrentField();
+        return this.parent;
+    }
+    containsAll(values) {
+        this.parent.appendCondition(this.field, 'containsAll', values);
+        this.parent.clearCurrentField();
+        return this.parent;
+    }
+    and(field) {
+        this.parent.clearCurrentField();
+        return this.parent.and(field);
+    }
+    or() {
+        this.parent.clearCurrentField();
+        return this.parent.or();
+    }
+}
+class QueryBuilder {
+    constructor(db, storeName, transaction) {
+        this.clauses = [];
+        this.orderDirection = 'asc';
+        this.pendingConnector = 'and';
+        this.db = db;
+        this.storeName = storeName;
+        this.transaction = transaction;
+    }
+    where(fieldOrBuilder) {
+        if (typeof fieldOrBuilder === 'function') {
+            this.clearCurrentField();
+            return this.addNestedGroup(fieldOrBuilder);
+        }
+        this.currentField = fieldOrBuilder;
+        return new FieldQueryBuilder(this, fieldOrBuilder);
+    }
+    and(fieldOrBuilder) {
+        return this.where(fieldOrBuilder);
+    }
+    or() {
+        this.pendingConnector = 'or';
+        return this;
+    }
+    addNestedGroup(builder) {
+        var _a;
+        const nested = new QueryBuilder(this.db, this.storeName, this.transaction);
+        const returned = (_a = builder(nested)) !== null && _a !== void 0 ? _a : nested;
+        const clauses = returned instanceof QueryBuilder ? returned.clauses : nested.clauses;
+        this.appendClause({ kind: 'group', clauses });
+        return this;
+    }
+    clearCurrentField() {
+        this.currentField = undefined;
+    }
+    appendCondition(field, op, value) {
+        this.appendClause({ kind: 'condition', field, op, value });
+    }
+    appendClause(clause) {
+        const connector = this.clauses.length === 0 ? null : this.pendingConnector;
+        this.clauses.push(Object.assign(Object.assign({}, clause), { connector }));
+        this.pendingConnector = 'and';
+    }
+    requireCurrentField(operation) {
+        if (!this.currentField) {
+            throw new Error(`No field specified for ${operation}`);
+        }
+        const field = this.currentField;
+        this.currentField = undefined;
+        return field;
+    }
+    addCondition(op, value) {
+        const field = this.requireCurrentField(op);
+        this.appendCondition(field, op, value);
+        return this;
+    }
+    equals(value) {
+        return this.addCondition('equals', value);
+    }
+    gt(value) {
+        return this.addCondition('gt', value);
+    }
+    gte(value) {
+        return this.addCondition('gte', value);
+    }
+    lt(value) {
+        return this.addCondition('lt', value);
+    }
+    lte(value) {
+        return this.addCondition('lte', value);
+    }
+    startsWith(value) {
+        return this.addCondition('startsWith', value);
+    }
+    endsWith(value) {
+        return this.addCondition('endsWith', value);
+    }
+    contains(value) {
+        return this.addCondition('contains', value);
+    }
+    matches(value) {
+        return this.addCondition('matches', value);
+    }
+    between(start, end) {
+        return this.addCondition('between', [start, end]);
+    }
+    notBetween(start, end) {
+        return this.addCondition('notBetween', [start, end]);
+    }
+    ['in'](values) {
+        return this.addCondition('in', values);
+    }
+    notIn(values) {
+        return this.addCondition('notIn', values);
+    }
+    containsAny(values) {
+        return this.addCondition('containsAny', values);
+    }
+    containsAll(values) {
+        return this.addCondition('containsAll', values);
+    }
+    orderBy(field, direction = 'asc') {
+        this.orderField = field;
+        this.orderDirection = direction;
+        return this;
+    }
+    limit(n) {
+        this.limitCount = n;
+        return this;
+    }
+    offset(n) {
+        this.offsetCount = n;
+        return this;
+    }
+    useIndex(indexName) {
+        this.indexName = indexName;
+        return this;
+    }
+    range(start, end) {
+        this.rangeStart = start;
+        this.rangeEnd = end;
+        return this;
+    }
+    groupBy(field) {
+        this.groupField = field;
+        return this;
+    }
+    loadCandidates() {
+        return tslib.__awaiter(this, void 0, void 0, function* () {
+            const store = this.transaction
+                ? this.transaction.objectStore(this.storeName)
+                : this.db
+                    .transaction(this.storeName, 'readonly')
+                    .objectStore(this.storeName);
+            const request = this.createReadRequest(store);
+            return new Promise((resolve, reject) => {
+                request.onsuccess = () => { var _a; return resolve((_a = request.result) !== null && _a !== void 0 ? _a : []); };
+                request.onerror = () => reject(request.error);
+            });
+        });
+    }
+    createReadRequest(store) {
+        if (!this.indexName) {
+            return store.getAll();
+        }
+        if (!store.indexNames.contains(this.indexName)) {
+            throw new Error(`Index '${this.indexName}' does not exist on ${this.storeName}`);
+        }
+        const index = store.index(this.indexName);
+        let keyRange;
+        if (this.rangeStart !== undefined && this.rangeEnd !== undefined) {
+            keyRange = IDBKeyRange.bound(this.rangeStart, this.rangeEnd);
+        }
+        else if (this.rangeStart !== undefined) {
+            keyRange = IDBKeyRange.lowerBound(this.rangeStart);
+        }
+        else if (this.rangeEnd !== undefined) {
+            keyRange = IDBKeyRange.upperBound(this.rangeEnd);
+        }
+        return keyRange ? index.getAll(keyRange) : index.getAll();
+    }
+    matchesClause(item, clause) {
+        if (clause.kind === 'group') {
+            return this.evaluateClauses(item, clause.clauses);
+        }
+        const value = item[clause.field];
+        switch (clause.op) {
+            case 'equals':
+                return value === clause.value;
+            case 'gt':
+                return value > clause.value;
+            case 'gte':
+                return value >= clause.value;
+            case 'lt':
+                return value < clause.value;
+            case 'lte':
+                return value <= clause.value;
+            case 'startsWith':
+                return (typeof value === 'string' && value.startsWith(String(clause.value)));
+            case 'endsWith':
+                return (typeof value === 'string' && value.endsWith(String(clause.value)));
+            case 'contains':
+                if (typeof value === 'string') {
+                    return value.includes(String(clause.value));
+                }
+                return Array.isArray(value) && value.includes(clause.value);
+            case 'matches': {
+                const pattern = clause.value instanceof RegExp
+                    ? new RegExp(clause.value.source, clause.value.flags)
+                    : new RegExp(String(clause.value));
+                return typeof value === 'string' && pattern.test(value);
+            }
+            case 'between': {
+                const [start, end] = clause.value;
+                return value >= start && value <= end;
+            }
+            case 'notBetween': {
+                const [start, end] = clause.value;
+                return value < start || value > end;
+            }
+            case 'in':
+                return Array.isArray(clause.value) && clause.value.includes(value);
+            case 'notIn':
+                return Array.isArray(clause.value) && !clause.value.includes(value);
+            case 'containsAny':
+                return (Array.isArray(value) &&
+                    Array.isArray(clause.value) &&
+                    clause.value.some((entry) => value.includes(entry)));
+            case 'containsAll':
+                return (Array.isArray(value) &&
+                    Array.isArray(clause.value) &&
+                    clause.value.every((entry) => value.includes(entry)));
+        }
+    }
+    evaluateClauses(item, clauses) {
+        if (!clauses.length) {
+            return true;
+        }
+        let result = this.matchesClause(item, clauses[0]);
+        for (let index = 1; index < clauses.length; index += 1) {
+            const clause = clauses[index];
+            const matches = this.matchesClause(item, clause);
+            result =
+                clause.connector === 'or' ? result || matches : result && matches;
+        }
+        return result;
+    }
+    collectMatches() {
+        return tslib.__awaiter(this, void 0, void 0, function* () {
+            const candidates = yield this.loadCandidates();
+            return candidates.filter((item) => this.evaluateClauses(item, this.clauses));
+        });
+    }
+    sortResults(results) {
+        if (!this.orderField) {
+            return results;
+        }
+        return [...results].sort((left, right) => {
+            const leftValue = left[this.orderField];
+            const rightValue = right[this.orderField];
+            if (leftValue < rightValue)
+                return this.orderDirection === 'asc' ? -1 : 1;
+            if (leftValue > rightValue)
+                return this.orderDirection === 'asc' ? 1 : -1;
+            return 0;
+        });
+    }
+    applyPagination(results) {
+        let nextResults = results;
+        if (this.offsetCount !== undefined) {
+            nextResults = nextResults.slice(this.offsetCount);
+        }
+        if (this.limitCount !== undefined) {
+            nextResults = nextResults.slice(0, this.limitCount);
+        }
+        return nextResults;
+    }
+    aggregateValues(field, reducer) {
+        return tslib.__awaiter(this, void 0, void 0, function* () {
+            const results = yield this.collectMatches();
+            const values = field
+                ? results.map((item) => item[field])
+                : results;
+            return reducer(values);
+        });
+    }
+    aggregateGroupedCount(field) {
+        return tslib.__awaiter(this, void 0, void 0, function* () {
+            var _a;
+            const results = yield this.collectMatches();
+            const groups = new Map();
+            for (const item of results) {
+                const key = item[field];
+                groups.set(key, ((_a = groups.get(key)) !== null && _a !== void 0 ? _a : 0) + 1);
+            }
+            return Array.from(groups.entries())
+                .sort(([left], [right]) => {
+                if (left < right)
+                    return -1;
+                if (left > right)
+                    return 1;
+                return 0;
+            })
+                .map(([key, count]) => ({ [field]: key, count }));
+        });
+    }
+    execute() {
+        return tslib.__awaiter(this, void 0, void 0, function* () {
+            const results = yield this.collectMatches();
+            return this.applyPagination(this.sortResults(results));
+        });
+    }
+    count() {
+        return tslib.__awaiter(this, void 0, void 0, function* () {
+            if (this.groupField) {
+                return this.aggregateGroupedCount(this.groupField);
+            }
+            const results = yield this.collectMatches();
+            return results.length;
+        });
+    }
+    sum(field) {
+        return tslib.__awaiter(this, void 0, void 0, function* () {
+            const total = yield this.aggregateValues(field, (values) => values.reduce((accumulator, value) => accumulator + (Number(value) || 0), 0));
+            return total;
+        });
+    }
+    avg(field) {
+        return tslib.__awaiter(this, void 0, void 0, function* () {
+            const values = yield this.aggregateValues(field, (items) => items);
+            if (!values.length) {
+                return 0;
+            }
+            const total = values.reduce((accumulator, value) => accumulator + (Number(value) || 0), 0);
+            return total / values.length;
+        });
+    }
+    min(field) {
+        return tslib.__awaiter(this, void 0, void 0, function* () {
+            const values = yield this.aggregateValues(field, (items) => items);
+            if (!values.length) {
+                return null;
+            }
+            return values.reduce((currentMin, value) => value < currentMin ? value : currentMin);
+        });
+    }
+    max(field) {
+        return tslib.__awaiter(this, void 0, void 0, function* () {
+            const values = yield this.aggregateValues(field, (items) => items);
+            if (!values.length) {
+                return null;
+            }
+            return values.reduce((currentMax, value) => value > currentMax ? value : currentMax);
+        });
+    }
+}
+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) {
+            const r = (Math.random() * 16) | 0;
+            const v = c === 'x' ? r : (r & 0x3) | 0x8;
+            return v.toString(16);
+        });
+    }
+    static timestamp() {
+        return Date.now();
+    }
+    static random() {
+        return Math.random().toString(36).substring(2, 15);
+    }
+}
+function KeyPath(options) {
+    return (target, propertyKey) => {
+        const constructor = target.constructor;
+        const existingKeypaths = Reflect.getMetadata('individual_keypaths', constructor) || [];
+        existingKeypaths.push(propertyKey);
+        Reflect.defineMetadata('individual_keypaths', existingKeypaths, constructor);
+        const metadata = {
+            fields: propertyKey,
+            options: options,
+        };
+        Reflect.defineMetadata('keypath', metadata, constructor);
+    };
+}
+function CompositeKeyPath(fields, options) {
+    return (target) => {
+        const metadata = {
+            fields: fields,
+            options: options,
+        };
+        Reflect.defineMetadata('keypath', metadata, target);
+    };
+}
+function Index(options) {
+    return (target, propertyKey) => {
+        const constructor = target.constructor;
+        const existing = Reflect.getMetadata('indexes', constructor) || [];
+        const nextIndexes = [
+            ...existing,
+            { field: propertyKey, options },
+        ];
+        Reflect.defineMetadata('indexes', nextIndexes, constructor);
+    };
+}
+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);
+    };
+}
+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);
+    };
+}
+function DataClass(options = {}) {
+    return (target) => {
+        const keyPathMetadata = Reflect.getMetadata('keypath', target);
+        if (!keyPathMetadata) {
+            throw new Error(`No keypath field defined for the class ${target.name}.`);
+        }
+        const individualKeypaths = Reflect.getMetadata('individual_keypaths', target) || [];
+        if (individualKeypaths.length > 1) {
+            throw new Error(`Only one keypath field can be defined for the class ${target.name}.`);
+        }
+        const version = options.version || 1;
+        Reflect.defineMetadata('dataclass', true, target);
+        Reflect.defineMetadata('version', version, target);
+    };
+}
+class Database {
+    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.');
+        }
+        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);
+        return Math.max(...versions);
+    }
+    static build(dbName, classes) {
+        return tslib.__awaiter(this, void 0, void 0, function* () {
+            const instance = new Database(dbName, classes);
+            yield instance.initDB();
+            instance.generateEntityRepositories();
+            return instance;
+        });
+    }
+    initDB() {
+        return tslib.__awaiter(this, void 0, void 0, function* () {
+            return new Promise((resolve, reject) => {
+                const request = indexedDB.open(this.dbName, this.dbVersion);
+                request.onupgradeneeded = (event) => {
+                    const db = request.result;
+                    const oldVersion = event.oldVersion;
+                    const newVersion = event.newVersion || this.dbVersion;
+                    this.printDebug(`Database upgrade from version ${oldVersion} to ${newVersion}`);
+                    this.classes.forEach((cls) => {
+                        var _a;
+                        const keyPathMetadata = Reflect.getMetadata('keypath', cls);
+                        const indexFields = Reflect.getMetadata('indexes', cls) || [];
+                        const classVersion = Reflect.getMetadata('version', cls) || 1;
+                        const storeName = cls.name.toLowerCase();
+                        if (classVersion > oldVersion) {
+                            if (!db.objectStoreNames.contains(storeName)) {
+                                this.printDebug(`Creating object store: ${storeName} (version ${classVersion})`);
+                                const storeOptions = {};
+                                if (keyPathMetadata) {
+                                    storeOptions.keyPath = keyPathMetadata.fields;
+                                    if ((_a = keyPathMetadata.options) === null || _a === void 0 ? void 0 : _a.autoIncrement) {
+                                        storeOptions.autoIncrement = true;
+                                    }
+                                }
+                                const store = db.createObjectStore(storeName, storeOptions);
+                                indexFields.forEach((indexField) => {
+                                    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);
+                                    }
+                                });
+                            }
+                            else {
+                                this.printDebug(`Updating object store: ${storeName} (version ${classVersion})`);
+                                const transaction = request.transaction;
+                                if (transaction) {
+                                    const store = transaction.objectStore(storeName);
+                                    indexFields.forEach((indexField) => {
+                                        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)) {
+                                            this.printDebug(`Adding index: ${indexName} to ${storeName}`);
+                                            store.createIndex(indexName, indexName, indexOptions);
+                                        }
+                                    });
+                                }
+                            }
+                        }
+                    });
+                };
+                request.onsuccess = () => {
+                    this.db = request.result;
+                    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 = () => {
+                    this.printError('Error initializing database:', request.error);
+                    reject(request.error);
+                };
+            });
+        });
+    }
+    generateEntityRepositories() {
+        this.classes.forEach((cls) => {
+            const entityName = cls.name;
+            const repository = this.createEntityRepository(cls);
+            this.entityRepositories.set(entityName, repository);
+            Object.defineProperty(this, entityName, {
+                value: repository,
+                writable: false,
+                enumerable: true,
+                configurable: false,
+            });
+        });
+    }
+    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;
+        }
+        this.printDebug(`Retention cleanup enabled for ${this.retentionPolicies.length} entities every ${cleanupIntervalMs}ms`);
+        void this.runRetentionCleanup();
+        this.retentionTimer = setInterval(() => {
+            void this.runRetentionCleanup();
+        }, cleanupIntervalMs);
+    }
+    runRetentionCleanup() {
+        return tslib.__awaiter(this, void 0, void 0, function* () {
+            if (!this.db ||
+                this.retentionCleanupRunning ||
+                !this.retentionPolicies.length) {
+                return;
+            }
+            this.retentionCleanupRunning = true;
+            try {
+                this.printDebug('Retention cleanup tick started');
+                for (const { storeName, className, policy } of this.retentionPolicies) {
+                    yield this.cleanupExpiredRecords(storeName, className, policy);
+                }
+                this.printDebug('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];
+                    this.printDebug(`Retention cleanup inspecting ${className}.${policy.field}:`, timestamp, 'cutoff:', cutoff);
+                    if (typeof timestamp === 'number' && timestamp <= cutoff) {
+                        const deleteRequest = cursor.delete();
+                        deleteRequest.onsuccess = () => {
+                            this.printDebug(`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, transaction) {
+        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);
+            if (!((_a = keyPathMetadata === null || keyPathMetadata === void 0 ? void 0 : keyPathMetadata.options) === null || _a === void 0 ? void 0 : _a.generator))
+                return undefined;
+            const generator = keyPathMetadata.options.generator;
+            if (typeof generator === 'function') {
+                return generator(item);
+            }
+            switch (generator) {
+                case 'uuid':
+                    return KeyGenerators.uuid();
+                case 'timestamp':
+                    return KeyGenerators.timestamp();
+                case 'random':
+                    return KeyGenerators.random();
+                default:
+                    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.__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)
+                return undefined;
+            const fields = keyPathMetadata.fields;
+            if (Array.isArray(fields)) {
+                return fields.map((field) => item[field]);
+            }
+            else {
+                return item[fields];
+            }
+        };
+        const setKey = (item, key) => {
+            const keyPathMetadata = Reflect.getMetadata('keypath', cls);
+            if (!keyPathMetadata)
+                return;
+            const fields = keyPathMetadata.fields;
+            if (typeof fields === 'string') {
+                item[fields] = key;
+            }
+        };
+        return {
+            query() {
+                if (!self.db)
+                    throw new Error('Database not initialized.');
+                const storeName = cls.name.toLowerCase();
+                return new QueryBuilder(self.db, storeName, transaction);
+            },
+            create: (item) => tslib.__awaiter(this, void 0, void 0, function* () {
+                var _a;
+                const keyPathMetadata = Reflect.getMetadata('keypath', cls);
+                if (((_a = keyPathMetadata === null || keyPathMetadata === void 0 ? void 0 : keyPathMetadata.options) === null || _a === void 0 ? void 0 : _a.generator) &&
+                    !keyPathMetadata.options.autoIncrement) {
+                    const currentKey = extractKey(item);
+                    if (currentKey === undefined ||
+                        currentKey === null ||
+                        currentKey === '') {
+                        const generatedKey = generateKey(item);
+                        if (generatedKey !== undefined) {
+                            setKey(item, generatedKey);
+                        }
+                    }
+                }
+                validateItem(item);
+                applyTimestampFields(item);
+                return this.performOperation(cls.name, 'readwrite', (store) => {
+                    return createStoredItem(store, item).then(() => {
+                        this.printDebug(`Item added to ${cls.name}:`, item);
+                    });
+                }, transaction);
+            }),
+            createMany: (items) => tslib.__awaiter(this, void 0, void 0, function* () {
+                const repository = this.createEntityRepository(cls, transaction);
+                for (const item of items) {
+                    yield repository.create(item);
+                }
+            }),
+            read: (key) => tslib.__awaiter(this, void 0, void 0, function* () {
+                return this.performOperation(cls.name, 'readonly', (store) => {
+                    const request = store.get(key);
+                    return new Promise((resolve, reject) => {
+                        request.onsuccess = () => {
+                            this.printDebug(`Item read from ${cls.name}:`, request.result);
+                            resolve(request.result);
+                        };
+                        request.onerror = () => reject(request.error);
+                    });
+                }, transaction);
+            }),
+            update: (item) => tslib.__awaiter(this, void 0, void 0, function* () {
+                validateItem(item);
+                return this.performOperation(cls.name, 'readwrite', (store) => {
+                    return updateStoredItem(store, item).then(() => {
+                        this.printDebug(`Item updated in ${cls.name}:`, item);
+                    });
+                }, transaction);
+            }),
+            updateMany: (items) => tslib.__awaiter(this, void 0, void 0, function* () {
+                const repository = this.createEntityRepository(cls, transaction);
+                for (const item of items) {
+                    yield repository.update(item);
+                }
+            }),
+            delete: (key) => tslib.__awaiter(this, void 0, void 0, function* () {
+                return this.performOperation(cls.name, 'readwrite', (store) => {
+                    return deleteStoredItem(store, key).then(() => {
+                        this.printDebug(`Item deleted from ${cls.name}:`, key);
+                    });
+                }, transaction);
+            }),
+            deleteMany: (keys) => tslib.__awaiter(this, void 0, void 0, function* () {
+                const repository = this.createEntityRepository(cls, transaction);
+                for (const key of keys) {
+                    yield repository.delete(key);
+                }
+            }),
+            deleteWhere: (predicate) => tslib.__awaiter(this, void 0, void 0, function* () {
+                var _a;
+                const repository = this.createEntityRepository(cls, transaction);
+                const query = repository.query();
+                const resolvedQuery = (_a = predicate(query)) !== null && _a !== void 0 ? _a : 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.__awaiter(this, void 0, void 0, function* () {
+                return this.performOperation(cls.name, 'readonly', (store) => {
+                    const request = store.getAll();
+                    return new Promise((resolve, reject) => {
+                        request.onsuccess = () => {
+                            this.printDebug(`All items from ${cls.name}:`, request.result);
+                            resolve(request.result);
+                        };
+                        request.onerror = () => reject(request.error);
+                    });
+                }, transaction);
+            }),
+            listPaginated: (page, pageSize) => tslib.__awaiter(this, void 0, void 0, function* () {
+                return this.performOperation(cls.name, 'readonly', (store) => {
+                    const request = store.getAll();
+                    return new Promise((resolve, reject) => {
+                        request.onsuccess = () => {
+                            const items = request.result;
+                            const paginatedItems = items.slice((page - 1) * pageSize, page * pageSize);
+                            this.printDebug(`Paginated items from ${cls.name}:`, paginatedItems);
+                            resolve(paginatedItems);
+                        };
+                        request.onerror = () => reject(request.error);
+                    });
+                }, transaction);
+            }),
+            findByIndex: (indexName, value) => tslib.__awaiter(this, void 0, void 0, function* () {
+                return this.performOperation(cls.name, 'readonly', (store) => {
+                    if (!store.indexNames.contains(indexName)) {
+                        throw new Error(`Index '${indexName}' does not exist on ${cls.name}`);
+                    }
+                    const index = store.index(indexName);
+                    const request = index.getAll(value);
+                    return new Promise((resolve, reject) => {
+                        request.onsuccess = () => {
+                            this.printDebug(`Items found by index ${indexName} with value ${value}:`, request.result);
+                            resolve(request.result);
+                        };
+                        request.onerror = () => reject(request.error);
+                    });
+                }, transaction);
+            }),
+            findOneByIndex: (indexName, value) => tslib.__awaiter(this, void 0, void 0, function* () {
+                return this.performOperation(cls.name, 'readonly', (store) => {
+                    if (!store.indexNames.contains(indexName)) {
+                        throw new Error(`Index '${indexName}' does not exist on ${cls.name}`);
+                    }
+                    const index = store.index(indexName);
+                    const request = index.get(value);
+                    return new Promise((resolve, reject) => {
+                        request.onsuccess = () => {
+                            this.printDebug(`Item found by index ${indexName} with value ${value}:`, request.result);
+                            resolve(request.result);
+                        };
+                        request.onerror = () => reject(request.error);
+                    });
+                }, transaction);
+            }),
+            count: () => tslib.__awaiter(this, void 0, void 0, function* () {
+                return this.performOperation(cls.name, 'readonly', (store) => {
+                    const request = store.count();
+                    return new Promise((resolve, reject) => {
+                        request.onsuccess = () => {
+                            this.printDebug(`Count for ${cls.name}:`, request.result);
+                            resolve(request.result);
+                        };
+                        request.onerror = () => reject(request.error);
+                    });
+                }, transaction);
+            }),
+            exists: (key) => tslib.__awaiter(this, void 0, void 0, function* () {
+                return this.performOperation(cls.name, 'readonly', (store) => {
+                    const request = store.count(key);
+                    return new Promise((resolve, reject) => {
+                        request.onsuccess = () => {
+                            const exists = request.result > 0;
+                            this.printDebug(`Exists check for ${cls.name} with key ${key}:`, exists);
+                            resolve(exists);
+                        };
+                        request.onerror = () => reject(request.error);
+                    });
+                }, transaction);
+            }),
+            clear: () => tslib.__awaiter(this, void 0, void 0, function* () {
+                return this.performOperation(cls.name, 'readwrite', (store) => {
+                    const request = store.clear();
+                    return new Promise((resolve, reject) => {
+                        request.onsuccess = () => {
+                            this.printDebug(`Cleared all items from ${cls.name}`);
+                            resolve();
+                        };
+                        request.onerror = () => reject(request.error);
+                    });
+                }, transaction);
+            }),
+        };
+    }
+    performOperation(className, mode, operation, transaction) {
+        return tslib.__awaiter(this, void 0, void 0, function* () {
+            if (!this.db && !transaction) {
+                throw new Error('Database not initialized.');
+            }
+            const storeName = className.toLowerCase();
+            const activeTransaction = transaction !== null && transaction !== void 0 ? transaction : this.db.transaction(storeName, mode);
+            const store = activeTransaction.objectStore(storeName);
+            return operation(store);
+        });
+    }
+    createTransactionHandle(entityNames, mode) {
+        if (!this.db) {
+            throw new Error('Database not initialized.');
+        }
+        const uniqueEntityNames = [...new Set(entityNames)];
+        const storeNames = uniqueEntityNames.map((entityName) => {
+            const entityClass = this.classes.find((cls) => cls.name === entityName);
+            if (!entityClass) {
+                throw new Error(`Entity '${entityName}' is not registered in ${this.dbName}.`);
+            }
+            return entityClass.name.toLowerCase();
+        });
+        const nativeTransaction = this.db.transaction(storeNames, mode);
+        let rollbackRequested = false;
+        const completion = new Promise((resolve, reject) => {
+            nativeTransaction.oncomplete = () => resolve();
+            nativeTransaction.onabort = () => {
+                var _a;
+                if (rollbackRequested) {
+                    resolve();
+                    return;
+                }
+                reject((_a = nativeTransaction.error) !== null && _a !== void 0 ? _a : new Error('Transaction aborted.'));
+            };
+            nativeTransaction.onerror = () => {
+                var _a;
+                if (rollbackRequested) {
+                    resolve();
+                    return;
+                }
+                reject((_a = nativeTransaction.error) !== null && _a !== void 0 ? _a : new Error('Transaction failed.'));
+            };
+        });
+        const handle = {};
+        uniqueEntityNames.forEach((entityName) => {
+            const entityClass = this.classes.find((cls) => cls.name === entityName);
+            if (entityClass) {
+                handle[entityName] = this.createEntityRepository(entityClass, nativeTransaction);
+            }
+        });
+        handle.commit = () => tslib.__awaiter(this, void 0, void 0, function* () {
+            if (typeof nativeTransaction.commit === 'function') {
+                nativeTransaction.commit();
+            }
+            yield completion;
+        });
+        handle.rollback = () => tslib.__awaiter(this, void 0, void 0, function* () {
+            rollbackRequested = true;
+            try {
+                nativeTransaction.abort();
+            }
+            catch (_a) {
+            }
+            yield completion.catch(() => undefined);
+        });
+        return handle;
+    }
+    beginTransaction(entityNames_1) {
+        return tslib.__awaiter(this, arguments, void 0, function* (entityNames, mode = 'readwrite') {
+            return this.createTransactionHandle(entityNames, mode);
+        });
+    }
+    transaction(callback) {
+        return tslib.__awaiter(this, void 0, void 0, function* () {
+            const tx = this.createTransactionHandle(this.classes.map((cls) => cls.name), 'readwrite');
+            try {
+                const result = yield callback(tx);
+                yield tx.commit();
+                return result;
+            }
+            catch (error) {
+                yield tx.rollback();
+                throw error;
+            }
+        });
+    }
+    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());
+    }
+    getDatabaseVersion() {
+        return this.dbVersion;
+    }
+    getEntityVersions() {
+        const versions = new Map();
+        this.classes.forEach((cls) => {
+            const version = Reflect.getMetadata('version', cls) || 1;
+            versions.set(cls.name, version);
+        });
+        return versions;
+    }
+    getEntityVersion(entityName) {
+        const cls = this.classes.find((c) => c.name === entityName);
+        return cls ? Reflect.getMetadata('version', cls) || 1 : undefined;
+    }
+}
+
+exports.CompositeKeyPath = CompositeKeyPath;
+exports.DataClass = DataClass;
+exports.Database = Database;
+exports.Index = Index;
+exports.KeyGenerators = KeyGenerators;
+exports.KeyPath = KeyPath;
+exports.RetentionPolicy = RetentionPolicy;
+exports.Validate = Validate;