idb-ts 3.11.1 → 3.12.0

package/lib/index.esm.js

@@ -1,56 +1,202 @@
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.KeyGenerators = exports.RetentionPolicy = exports.Validate = exports.Index = exports.DataClass = exports.CompositeKeyPath = exports.KeyPath = exports.Database = void 0;
+exports.KeyGenerators = exports.Database = void 0;
+exports.KeyPath = KeyPath;
+exports.CompositeKeyPath = CompositeKeyPath;
+exports.DataClass = DataClass;
+exports.Index = Index;
+exports.Validate = Validate;
+exports.RetentionPolicy = RetentionPolicy;
 const tslib_1 = 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) {
-        this.conditions = [];
+    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);
     }
-    where(field) {
-        this.currentField = field;
+    or() {
+        this.pendingConnector = 'or';
         return this;
     }
-    and(field) {
-        this.currentField = field;
+    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;
     }
-    equals(value) {
-        if (!this.currentField)
-            throw new Error('No field specified for equals');
-        this.conditions.push({ field: this.currentField, op: 'equals', value });
+    clearCurrentField() {
         this.currentField = undefined;
-        return this;
     }
-    gt(value) {
-        if (!this.currentField)
-            throw new Error('No field specified for gt');
-        this.conditions.push({ field: this.currentField, op: 'gt', value });
+    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) {
-        if (!this.currentField)
-            throw new Error('No field specified for gte');
-        this.conditions.push({ field: this.currentField, op: 'gte', value });
-        this.currentField = undefined;
-        return this;
+        return this.addCondition('gte', value);
     }
     lt(value) {
-        if (!this.currentField)
-            throw new Error('No field specified for lt');
-        this.conditions.push({ field: this.currentField, op: 'lt', value });
-        this.currentField = undefined;
-        return this;
+        return this.addCondition('lt', value);
     }
     lte(value) {
-        if (!this.currentField)
-            throw new Error('No field specified for lte');
-        this.conditions.push({ field: this.currentField, op: 'lte', value });
-        this.currentField = undefined;
-        return this;
+        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;
@@ -74,94 +220,226 @@ class QueryBuilder {
         this.rangeEnd = end;
         return this;
     }
-    execute() {
+    groupBy(field) {
+        this.groupField = field;
+        return this;
+    }
+    loadCandidates() {
         return tslib_1.__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) => {
-                const tx = this.db.transaction(this.storeName, 'readonly');
-                const store = tx.objectStore(this.storeName);
-                let request;
-                let results = [];
-                if (this.indexName) {
-                    if (!store.indexNames.contains(this.indexName)) {
-                        reject(new Error(`Index '${this.indexName}' does not exist on ${this.storeName}`));
-                        return;
-                    }
-                    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);
-                    }
-                    request = index.openCursor(keyRange);
-                }
-                else {
-                    request = store.openCursor();
-                }
-                request.onsuccess = () => {
-                    const cursor = request.result;
-                    if (cursor) {
-                        let match = true;
-                        const value = cursor.value;
-                        for (const cond of this.conditions) {
-                            const val = value[cond.field];
-                            switch (cond.op) {
-                                case 'equals':
-                                    match = match && val === cond.value;
-                                    break;
-                                case 'gt':
-                                    match = match && val > cond.value;
-                                    break;
-                                case 'gte':
-                                    match = match && val >= cond.value;
-                                    break;
-                                case 'lt':
-                                    match = match && val < cond.value;
-                                    break;
-                                case 'lte':
-                                    match = match && val <= cond.value;
-                                    break;
-                            }
-                        }
-                        if (match)
-                            results.push(value);
-                        cursor.continue();
-                    }
-                    else {
-                        if (this.orderField) {
-                            results.sort((a, b) => {
-                                const va = a[this.orderField];
-                                const vb = b[this.orderField];
-                                if (va < vb)
-                                    return this.orderDirection === 'asc' ? -1 : 1;
-                                if (va > vb)
-                                    return this.orderDirection === 'asc' ? 1 : -1;
-                                return 0;
-                            });
-                        }
-                        if (this.offsetCount !== undefined)
-                            results = results.slice(this.offsetCount);
-                        if (this.limitCount !== undefined)
-                            results = results.slice(0, this.limitCount);
-                        resolve(results);
-                    }
-                };
+                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_1.__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_1.__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_1.__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_1.__awaiter(this, void 0, void 0, function* () {
+            const results = yield this.collectMatches();
+            return this.applyPagination(this.sortResults(results));
+        });
+    }
+    count() {
+        return tslib_1.__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_1.__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_1.__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_1.__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_1.__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);
+            const r = (Math.random() * 16) | 0;
+            const v = c === 'x' ? r : (r & 0x3) | 0x8;
             return v.toString(16);
         });
     }
@@ -176,45 +454,47 @@ exports.KeyGenerators = KeyGenerators;
 function KeyPath(options) {
     return (target, propertyKey) => {
         const constructor = target.constructor;
-        const existingKeypaths = Reflect.getMetadata("individual_keypaths", constructor) || [];
+        const existingKeypaths = Reflect.getMetadata('individual_keypaths', constructor) || [];
         existingKeypaths.push(propertyKey);
-        Reflect.defineMetadata("individual_keypaths", existingKeypaths, constructor);
+        Reflect.defineMetadata('individual_keypaths', existingKeypaths, constructor);
         const metadata = {
             fields: propertyKey,
-            options: options
+            options: options,
         };
-        Reflect.defineMetadata("keypath", metadata, constructor);
+        Reflect.defineMetadata('keypath', metadata, constructor);
     };
 }
-exports.KeyPath = KeyPath;
 function CompositeKeyPath(fields, options) {
     return (target) => {
         const metadata = {
             fields: fields,
-            options: options
+            options: options,
         };
-        Reflect.defineMetadata("keypath", metadata, target);
+        Reflect.defineMetadata('keypath', metadata, target);
     };
 }
-exports.CompositeKeyPath = CompositeKeyPath;
 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);
+        const existing = Reflect.getMetadata('indexes', 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 }];
+        const nextRules = [
+            ...existing,
+            { field: propertyKey, predicate, message },
+        ];
         Reflect.defineMetadata('validators', nextRules, constructor);
     };
 }
-exports.Validate = Validate;
 function RetentionPolicy(options) {
     return (target) => {
         var _a, _b;
@@ -224,28 +504,26 @@ function RetentionPolicy(options) {
         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
+            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);
+        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) || [];
+        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);
+        Reflect.defineMetadata('dataclass', true, target);
+        Reflect.defineMetadata('version', version, target);
     };
 }
-exports.DataClass = DataClass;
 class Database {
     constructor(dbName, classes) {
         this.db = null;
@@ -253,8 +531,8 @@ class Database {
         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.");
+        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();
@@ -267,13 +545,13 @@ class Database {
             return {
                 className: cls.name,
                 storeName: cls.name.toLowerCase(),
-                policy
+                policy,
             };
         })
             .filter((policy) => policy !== null);
     }
     calculateDatabaseVersion() {
-        const versions = this.classes.map(cls => Reflect.getMetadata("version", cls) || 1);
+        const versions = this.classes.map((cls) => Reflect.getMetadata('version', cls) || 1);
         return Math.max(...versions);
     }
     static build(dbName, classes) {
@@ -295,9 +573,9 @@ class Database {
                     console.debug(`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 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)) {
@@ -312,7 +590,9 @@ class Database {
                                 const store = db.createObjectStore(storeName, storeOptions);
                                 indexFields.forEach((indexField) => {
                                     var _a;
-                                    const indexName = typeof indexField === 'string' ? indexField : indexField.field;
+                                    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 });
@@ -328,7 +608,9 @@ class Database {
                                     const store = transaction.objectStore(storeName);
                                     indexFields.forEach((indexField) => {
                                         var _a;
-                                        const indexName = typeof indexField === 'string' ? indexField : indexField.field;
+                                        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 });
@@ -344,19 +626,19 @@ 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(", ")}`);
+                    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 = () => {
-                    console.error("Error initializing database:", request.error);
+                    console.error('Error initializing database:', request.error);
                     reject(request.error);
                 };
             });
         });
     }
     generateEntityRepositories() {
-        this.classes.forEach(cls => {
+        this.classes.forEach((cls) => {
             const entityName = cls.name;
             const repository = this.createEntityRepository(cls);
             this.entityRepositories.set(entityName, repository);
@@ -364,7 +646,7 @@ class Database {
                 value: repository,
                 writable: false,
                 enumerable: true,
-                configurable: false
+                configurable: false,
             });
         });
     }
@@ -383,7 +665,7 @@ class Database {
             return Math.abs(a);
         };
         const seconds = this.retentionPolicies.map(({ policy }) => policy.seconds);
-        return seconds.reduce((accumulator, value) => gcd(accumulator, value)) * 1000;
+        return (seconds.reduce((accumulator, value) => gcd(accumulator, value)) * 1000);
     }
     startRetentionCleanup() {
         const cleanupIntervalMs = this.calculateRetentionCleanupIntervalMs();
@@ -398,7 +680,9 @@ class Database {
     }
     runRetentionCleanup() {
         return tslib_1.__awaiter(this, void 0, void 0, function* () {
-            if (!this.db || this.retentionCleanupRunning || !this.retentionPolicies.length) {
+            if (!this.db ||
+                this.retentionCleanupRunning ||
+                !this.retentionPolicies.length) {
                 return;
             }
             this.retentionCleanupRunning = true;
@@ -422,7 +706,7 @@ class Database {
             try {
                 const transaction = this.db.transaction(storeName, 'readwrite');
                 const store = transaction.objectStore(storeName);
-                const cutoff = Date.now() - (policy.seconds * 1000);
+                const cutoff = Date.now() - policy.seconds * 1000;
                 const request = store.openCursor();
                 request.onsuccess = () => {
                     const cursor = request.result;
@@ -438,25 +722,35 @@ class Database {
                             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}`)); };
+                        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}`)); };
+                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) {
+    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 validators = (Reflect.getMetadata('validators', cls) ||
+            []);
         const validateItem = (item) => {
             const failures = [];
             validators.forEach((rule) => {
@@ -478,7 +772,7 @@ class Database {
         };
         const generateKey = (item) => {
             var _a;
-            const keyPathMetadata = Reflect.getMetadata("keypath", cls);
+            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;
@@ -498,8 +792,11 @@ class Database {
         };
         const applyTimestampFields = (item, existingItem) => {
             const now = Date.now();
-            const existingCreationValue = existingItem ? existingItem[creationTimestampField] : undefined;
-            item[creationTimestampField] = existingCreationValue !== undefined ? existingCreationValue : now;
+            const existingCreationValue = existingItem
+                ? existingItem[creationTimestampField]
+                : undefined;
+            item[creationTimestampField] =
+                existingCreationValue !== undefined ? existingCreationValue : now;
             item[updateTimestampField] = now;
         };
         const readExistingItem = (store, key) => {
@@ -537,19 +834,19 @@ class Database {
             });
         };
         const extractKey = (item) => {
-            const keyPathMetadata = Reflect.getMetadata("keypath", cls);
+            const keyPathMetadata = Reflect.getMetadata('keypath', cls);
             if (!keyPathMetadata)
                 return undefined;
             const fields = keyPathMetadata.fields;
             if (Array.isArray(fields)) {
-                return fields.map(field => item[field]);
+                return fields.map((field) => item[field]);
             }
             else {
                 return item[fields];
             }
         };
         const setKey = (item, key) => {
-            const keyPathMetadata = Reflect.getMetadata("keypath", cls);
+            const keyPathMetadata = Reflect.getMetadata('keypath', cls);
             if (!keyPathMetadata)
                 return;
             const fields = keyPathMetadata.fields;
@@ -562,14 +859,17 @@ class Database {
                 if (!self.db)
                     throw new Error('Database not initialized.');
                 const storeName = cls.name.toLowerCase();
-                return new QueryBuilder(self.db, storeName);
+                return new QueryBuilder(self.db, storeName, transaction);
             },
             create: (item) => tslib_1.__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 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 === '') {
+                    if (currentKey === undefined ||
+                        currentKey === null ||
+                        currentKey === '') {
                         const generatedKey = generateKey(item);
                         if (generatedKey !== undefined) {
                             setKey(item, generatedKey);
@@ -582,10 +882,10 @@ class Database {
                     return createStoredItem(store, item).then(() => {
                         console.debug(`Item added to ${cls.name}:`, item);
                     });
-                });
+                }, transaction);
             }),
             createMany: (items) => tslib_1.__awaiter(this, void 0, void 0, function* () {
-                const repository = this.createEntityRepository(cls);
+                const repository = this.createEntityRepository(cls, transaction);
                 for (const item of items) {
                     yield repository.create(item);
                 }
@@ -600,7 +900,7 @@ class Database {
                         };
                         request.onerror = () => reject(request.error);
                     });
-                });
+                }, transaction);
             }),
             update: (item) => tslib_1.__awaiter(this, void 0, void 0, function* () {
                 validateItem(item);
@@ -608,10 +908,10 @@ class Database {
                     return updateStoredItem(store, item).then(() => {
                         console.debug(`Item updated in ${cls.name}:`, item);
                     });
-                });
+                }, transaction);
             }),
             updateMany: (items) => tslib_1.__awaiter(this, void 0, void 0, function* () {
-                const repository = this.createEntityRepository(cls);
+                const repository = this.createEntityRepository(cls, transaction);
                 for (const item of items) {
                     yield repository.update(item);
                 }
@@ -621,19 +921,19 @@ class Database {
                     return deleteStoredItem(store, key).then(() => {
                         console.debug(`Item deleted from ${cls.name}:`, key);
                     });
-                });
+                }, transaction);
             }),
             deleteMany: (keys) => tslib_1.__awaiter(this, void 0, void 0, function* () {
-                const repository = this.createEntityRepository(cls);
+                const repository = this.createEntityRepository(cls, transaction);
                 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);
+                var _a;
+                const repository = this.createEntityRepository(cls, transaction);
                 const query = repository.query();
-                const resolvedQuery = (_b = predicate(query)) !== null && _b !== void 0 ? _b : query;
+                const resolvedQuery = (_a = predicate(query)) !== null && _a !== void 0 ? _a : query;
                 const matches = yield resolvedQuery.execute();
                 const keys = matches
                     .map((item) => extractKey(item))
@@ -650,7 +950,7 @@ class Database {
                         };
                         request.onerror = () => reject(request.error);
                     });
-                });
+                }, transaction);
             }),
             listPaginated: (page, pageSize) => tslib_1.__awaiter(this, void 0, void 0, function* () {
                 return this.performOperation(cls.name, 'readonly', (store) => {
@@ -664,7 +964,7 @@ class Database {
                         };
                         request.onerror = () => reject(request.error);
                     });
-                });
+                }, transaction);
             }),
             findByIndex: (indexName, value) => tslib_1.__awaiter(this, void 0, void 0, function* () {
                 return this.performOperation(cls.name, 'readonly', (store) => {
@@ -680,7 +980,7 @@ class Database {
                         };
                         request.onerror = () => reject(request.error);
                     });
-                });
+                }, transaction);
             }),
             findOneByIndex: (indexName, value) => tslib_1.__awaiter(this, void 0, void 0, function* () {
                 return this.performOperation(cls.name, 'readonly', (store) => {
@@ -696,7 +996,7 @@ class Database {
                         };
                         request.onerror = () => reject(request.error);
                     });
-                });
+                }, transaction);
             }),
             count: () => tslib_1.__awaiter(this, void 0, void 0, function* () {
                 return this.performOperation(cls.name, 'readonly', (store) => {
@@ -708,7 +1008,7 @@ class Database {
                         };
                         request.onerror = () => reject(request.error);
                     });
-                });
+                }, transaction);
             }),
             exists: (key) => tslib_1.__awaiter(this, void 0, void 0, function* () {
                 return this.performOperation(cls.name, 'readonly', (store) => {
@@ -721,7 +1021,7 @@ class Database {
                         };
                         request.onerror = () => reject(request.error);
                     });
-                });
+                }, transaction);
             }),
             clear: () => tslib_1.__awaiter(this, void 0, void 0, function* () {
                 return this.performOperation(cls.name, 'readwrite', (store) => {
@@ -733,21 +1033,97 @@ class Database {
                         };
                         request.onerror = () => reject(request.error);
                     });
-                });
-            })
+                }, transaction);
+            }),
         };
     }
-    performOperation(className, mode, operation) {
+    performOperation(className, mode, operation, transaction) {
         return tslib_1.__awaiter(this, void 0, void 0, function* () {
-            if (!this.db) {
-                throw new Error("Database not initialized.");
+            if (!this.db && !transaction) {
+                throw new Error('Database not initialized.');
             }
             const storeName = className.toLowerCase();
-            const transaction = this.db.transaction(storeName, mode);
-            const store = transaction.objectStore(storeName);
+            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_1.__awaiter(this, void 0, void 0, function* () {
+            if (typeof nativeTransaction.commit === 'function') {
+                nativeTransaction.commit();
+            }
+            yield completion;
+        });
+        handle.rollback = () => tslib_1.__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_1.__awaiter(this, arguments, void 0, function* (entityNames, mode = 'readwrite') {
+            return this.createTransactionHandle(entityNames, mode);
+        });
+    }
+    transaction(callback) {
+        return tslib_1.__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);
@@ -766,15 +1142,15 @@ class Database {
     }
     getEntityVersions() {
         const versions = new Map();
-        this.classes.forEach(cls => {
-            const version = Reflect.getMetadata("version", cls) || 1;
+        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;
+        const cls = this.classes.find((c) => c.name === entityName);
+        return cls ? Reflect.getMetadata('version', cls) || 1 : undefined;
     }
 }
 exports.Database = Database;