idb-ts 3.14.0 → 3.16.0

package/lib/index.esm.js

@@ -217,6 +217,34 @@ class QueryBuilder {
         this.groupField = field;
         return this;
     }
+    clone() {
+        const copy = new QueryBuilder(this.db, this.storeName, this.transaction);
+        copy.clauses = [...this.clauses];
+        copy.orderField = this.orderField;
+        copy.orderDirection = this.orderDirection;
+        copy.limitCount = this.limitCount;
+        copy.offsetCount = this.offsetCount;
+        copy.indexName = this.indexName;
+        copy.rangeStart = this.rangeStart;
+        copy.rangeEnd = this.rangeEnd;
+        copy.groupField = this.groupField;
+        copy.pendingConnector = this.pendingConnector;
+        return copy;
+    }
+    reset() {
+        this.clauses = [];
+        this.orderField = undefined;
+        this.orderDirection = 'asc';
+        this.limitCount = undefined;
+        this.offsetCount = undefined;
+        this.indexName = undefined;
+        this.rangeStart = undefined;
+        this.rangeEnd = undefined;
+        this.currentField = undefined;
+        this.groupField = undefined;
+        this.pendingConnector = 'and';
+        return this;
+    }
     loadCandidates() {
         return __awaiter(this, void 0, void 0, function* () {
             const store = this.transaction
@@ -233,6 +261,12 @@ class QueryBuilder {
     }
     createReadRequest(store) {
         if (!this.indexName) {
+            if (this.rangeStart !== undefined || this.rangeEnd !== undefined) {
+                throw new Error('range() requires useIndex(): key ranges are applied at the ' +
+                    'IndexedDB layer through an index. Either call useIndex(indexName) ' +
+                    'before range(), or express the bounds as in-memory filters via ' +
+                    'where(field).between(start, end) / gte() / lte().');
+            }
             return store.getAll();
         }
         if (!store.indexNames.contains(this.indexName)) {
@@ -429,12 +463,65 @@ class QueryBuilder {
 const INTERNAL_CREATED_AT_FIELD = '__idb_createdAt';
 const INTERNAL_UPDATED_AT_FIELD = '__idb_updatedAt';
 class KeyGenerators {
+    static getRandomValues(array) {
+        var _a;
+        if (typeof globalThis !== 'undefined' && ((_a = globalThis.crypto) === null || _a === void 0 ? void 0 : _a.getRandomValues)) {
+            globalThis.crypto.getRandomValues(array);
+            return array;
+        }
+        try {
+            const { randomBytes } = require('crypto');
+            const bytes = randomBytes(array.length);
+            return new Uint8Array(bytes);
+        }
+        catch (_b) {
+            for (let i = 0; i < array.length; i++) {
+                array[i] = Math.random() * 256 | 0;
+            }
+            return array;
+        }
+    }
+    static uuidV4() {
+        var _a;
+        try {
+            if (typeof globalThis !== 'undefined' && ((_a = globalThis.crypto) === null || _a === void 0 ? void 0 : _a.randomUUID)) {
+                return globalThis.crypto.randomUUID();
+            }
+        }
+        catch (_b) {
+        }
+        try {
+            const { randomUUID } = require('crypto');
+            return randomUUID();
+        }
+        catch (_c) {
+        }
+        const bytes = new Uint8Array(16);
+        this.getRandomValues(bytes);
+        bytes[6] = (bytes[6] & 0x0f) | 0x40;
+        bytes[8] = (bytes[8] & 0x3f) | 0x80;
+        const hex = Array.from(bytes, (b) => b.toString(16).padStart(2, '0')).join('');
+        return `${hex.substring(0, 8)}-${hex.substring(8, 12)}-${hex.substring(12, 16)}-${hex.substring(16, 20)}-${hex.substring(20)}`;
+    }
+    static uuidV6() {
+        const bytes = new Uint8Array(16);
+        this.getRandomValues(bytes);
+        const now = Date.now();
+        const timeHi = Math.floor(now / 1000) & 0xffffffff;
+        const timeLo = (now % 1000) * 4096;
+        bytes[0] = (timeHi >>> 24) & 0xff;
+        bytes[1] = (timeHi >>> 16) & 0xff;
+        bytes[2] = (timeHi >>> 8) & 0xff;
+        bytes[3] = timeHi & 0xff;
+        bytes[4] = (timeLo >>> 8) & 0xff;
+        bytes[5] = timeLo & 0xff;
+        bytes[6] = (bytes[6] & 0x0f) | 0x60;
+        bytes[8] = (bytes[8] & 0x3f) | 0x80;
+        const hex = Array.from(bytes, (b) => b.toString(16).padStart(2, '0')).join('');
+        return `${hex.substring(0, 8)}-${hex.substring(8, 12)}-${hex.substring(12, 16)}-${hex.substring(16, 20)}-${hex.substring(20)}`;
+    }
     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);
-        });
+        return this.uuidV4();
     }
     static timestamp() {
         return Date.now();
@@ -458,6 +545,13 @@ function KeyPath(options) {
 }
 function CompositeKeyPath(fields, options) {
     return (target) => {
+        if (options === null || options === void 0 ? void 0 : options.generator) {
+            throw new Error(`Key generators are not supported for composite keys on class ${target.name}. ` +
+                'Provide all key fields explicitly before calling create().');
+        }
+        if (options === null || options === void 0 ? void 0 : options.autoIncrement) {
+            throw new Error(`autoIncrement is not supported for composite keys on class ${target.name}.`);
+        }
         const metadata = {
             fields: fields,
             options: options,
@@ -487,6 +581,17 @@ function Validate(predicate, message) {
         Reflect.defineMetadata('validators', nextRules, constructor);
     };
 }
+function Calculated(compute) {
+    return (target, propertyKey) => {
+        const constructor = target.constructor;
+        const existing = Reflect.getMetadata('calculated', constructor) || [];
+        const nextFields = [
+            ...existing,
+            { field: propertyKey, compute },
+        ];
+        Reflect.defineMetadata('calculated', nextFields, constructor);
+    };
+}
 function RetentionPolicy(options) {
     return (target) => {
         var _a, _b;
@@ -516,18 +621,152 @@ function DataClass(options = {}) {
         Reflect.defineMetadata('version', version, target);
     };
 }
+class EntitySchema {
+    constructor(className, storeName, version, keyPath, autoIncrement, indexes) {
+        this.className = className;
+        this.storeName = storeName;
+        this.version = version;
+        this.keyPath = keyPath;
+        this.autoIncrement = autoIncrement;
+        this.indexes = indexes;
+    }
+    static fromClass(cls) {
+        var _a;
+        const keyPathMetadata = Reflect.getMetadata('keypath', cls);
+        const rawIndexes = (Reflect.getMetadata('indexes', cls) || []);
+        const indexes = rawIndexes.map((entry) => {
+            var _a;
+            return typeof entry === 'string'
+                ? { name: entry, options: { unique: false } }
+                : { name: entry.field, options: (_a = entry.options) !== null && _a !== void 0 ? _a : { unique: false } };
+        });
+        return new EntitySchema(cls.name, cls.name.toLowerCase(), Reflect.getMetadata('version', cls) || 1, keyPathMetadata === null || keyPathMetadata === void 0 ? void 0 : keyPathMetadata.fields, ((_a = keyPathMetadata === null || keyPathMetadata === void 0 ? void 0 : keyPathMetadata.options) === null || _a === void 0 ? void 0 : _a.autoIncrement) === true, indexes);
+    }
+    hasIndex(name) {
+        return this.indexes.some((index) => index.name === name);
+    }
+}
+class SchemaMigrator {
+    constructor(schemas, logDebug, logWarn) {
+        this.schemas = schemas;
+        this.logDebug = logDebug;
+        this.logWarn = logWarn;
+    }
+    get targetVersion() {
+        return Math.max(1, ...this.schemas.map((schema) => schema.version));
+    }
+    applyTo(db, transaction) {
+        this.schemas.forEach((schema) => {
+            if (!db.objectStoreNames.contains(schema.storeName)) {
+                this.createStore(db, schema);
+            }
+            else if (transaction) {
+                this.syncStore(transaction.objectStore(schema.storeName), schema);
+            }
+        });
+        this.reportOrphanedStores(db);
+    }
+    detectFixableDrift(db) {
+        const drift = [];
+        const existing = this.schemas.filter((schema) => db.objectStoreNames.contains(schema.storeName));
+        this.schemas.forEach((schema) => {
+            if (!db.objectStoreNames.contains(schema.storeName)) {
+                drift.push(`missing object store '${schema.storeName}'`);
+            }
+        });
+        if (existing.length) {
+            const transaction = db.transaction(existing.map((schema) => schema.storeName), 'readonly');
+            existing.forEach((schema) => {
+                const store = transaction.objectStore(schema.storeName);
+                schema.indexes.forEach(({ name }) => {
+                    if (!store.indexNames.contains(name)) {
+                        drift.push(`missing index '${name}' on '${schema.storeName}'`);
+                    }
+                });
+                Array.from(store.indexNames).forEach((name) => {
+                    if (!schema.hasIndex(name)) {
+                        drift.push(`stale index '${name}' on '${schema.storeName}'`);
+                    }
+                });
+            });
+        }
+        return drift;
+    }
+    createStore(db, schema) {
+        const options = {};
+        if (schema.keyPath !== undefined) {
+            options.keyPath = schema.keyPath;
+        }
+        if (schema.autoIncrement) {
+            options.autoIncrement = true;
+        }
+        const store = db.createObjectStore(schema.storeName, options);
+        schema.indexes.forEach(({ name, options: indexOptions }) => {
+            store.createIndex(name, name, indexOptions);
+        });
+        this.logDebug(`Created object store '${schema.storeName}' (entity version ${schema.version})`);
+    }
+    syncStore(store, schema) {
+        if (!this.keyPathMatches(store, schema)) {
+            this.logWarn(`Key path of object store '${schema.storeName}' differs from the ` +
+                `declaration on ${schema.className}. IndexedDB cannot change a ` +
+                'store\'s key path in place; migrate the data to a new entity or ' +
+                'delete the database to apply this change.');
+        }
+        schema.indexes.forEach(({ name, options }) => {
+            if (!store.indexNames.contains(name)) {
+                store.createIndex(name, name, options);
+                this.logDebug(`Added index '${name}' to '${schema.storeName}'`);
+            }
+        });
+        Array.from(store.indexNames).forEach((name) => {
+            if (!schema.hasIndex(name)) {
+                store.deleteIndex(name);
+                this.logDebug(`Removed stale index '${name}' from '${schema.storeName}'`);
+            }
+        });
+    }
+    keyPathMatches(store, schema) {
+        const normalise = (keyPath) => (Array.isArray(keyPath) ? keyPath.join(',') : (keyPath !== null && keyPath !== void 0 ? keyPath : ''));
+        return (normalise(store.keyPath) === normalise(schema.keyPath) &&
+            store.autoIncrement === schema.autoIncrement);
+    }
+    reportOrphanedStores(db) {
+        const declared = new Set(this.schemas.map((schema) => schema.storeName));
+        Array.from(db.objectStoreNames).forEach((storeName) => {
+            if (!declared.has(storeName)) {
+                this.logWarn(`Object store '${storeName}' has no registered entity class. ` +
+                    'Its data is preserved; register the entity again or delete the ' +
+                    'store manually if it is no longer needed.');
+            }
+        });
+    }
+}
 class Database {
-    constructor(dbName, classes) {
+    constructor(dbName, classes, printEnabled = false) {
         this.db = null;
         this.entityRepositories = new Map();
         this.retentionTimer = null;
         this.retentionCleanupRunning = false;
+        this.printDebug = (...data) => {
+            if (!this.printEnabled)
+                return;
+            console.debug('[idb-ts]:DEBUG:', ...data);
+        };
+        this.printError = (...error) => {
+            if (!this.printEnabled)
+                return;
+            console.error('[idb-ts]:ERROR:', ...error);
+        };
         this.dbName = dbName;
+        this.printEnabled = printEnabled;
         if (!classes.every((cls) => Reflect.getMetadata('dataclass', cls))) {
             throw new Error('All classes should be decorated with @DataClass.');
         }
         this.classes = classes;
-        this.dbVersion = this.calculateDatabaseVersion();
+        this.schemas = classes.map((cls) => EntitySchema.fromClass(cls));
+        this.migrator = new SchemaMigrator(this.schemas, this.printDebug, this.printError);
+        this.dbVersion = this.migrator.targetVersion;
         this.retentionPolicies = this.classes
             .map((cls) => {
             const policy = Reflect.getMetadata('retention_policy', cls);
@@ -542,9 +781,52 @@ class Database {
         })
             .filter((policy) => policy !== null);
     }
-    calculateDatabaseVersion() {
-        const versions = this.classes.map((cls) => Reflect.getMetadata('version', cls) || 1);
-        return Math.max(...versions);
+    readPersistedVersion() {
+        return __awaiter(this, void 0, void 0, function* () {
+            var _a;
+            const databasesFn = indexedDB.databases;
+            if (typeof databasesFn === 'function') {
+                try {
+                    const infos = yield databasesFn.call(indexedDB);
+                    const info = infos.find((entry) => entry.name === this.dbName);
+                    return (_a = info === null || info === void 0 ? void 0 : info.version) !== null && _a !== void 0 ? _a : 0;
+                }
+                catch (_b) {
+                }
+            }
+            return new Promise((resolve) => {
+                const request = indexedDB.open(this.dbName);
+                request.onupgradeneeded = () => {
+                    var _a;
+                    (_a = request.transaction) === null || _a === void 0 ? void 0 : _a.abort();
+                    resolve(0);
+                };
+                request.onsuccess = () => {
+                    const version = request.result.version;
+                    request.result.close();
+                    resolve(version);
+                };
+                request.onerror = () => resolve(0);
+            });
+        });
+    }
+    openConnection(version) {
+        return new Promise((resolve, reject) => {
+            const request = indexedDB.open(this.dbName, version);
+            request.onupgradeneeded = (event) => {
+                var _a;
+                this.printDebug(`Database upgrade from version ${event.oldVersion} to ${(_a = event.newVersion) !== null && _a !== void 0 ? _a : version}`);
+                this.migrator.applyTo(request.result, request.transaction);
+            };
+            request.onblocked = () => {
+                this.printDebug(`Opening '${this.dbName}' at version ${version} is blocked by another open connection.`);
+            };
+            request.onsuccess = () => resolve(request.result);
+            request.onerror = () => {
+                this.printError('Error initializing database:', request.error);
+                reject(request.error);
+            };
+        });
     }
     static build(dbName, classes) {
         return __awaiter(this, void 0, void 0, function* () {
@@ -556,77 +838,25 @@ class Database {
     }
     initDB() {
         return __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;
-                    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 storeName = cls.name.toLowerCase();
-                        if (classVersion > oldVersion) {
-                            if (!db.objectStoreNames.contains(storeName)) {
-                                console.debug(`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 {
-                                console.debug(`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)) {
-                                            console.debug(`Adding index: ${indexName} to ${storeName}`);
-                                            store.createIndex(indexName, indexName, indexOptions);
-                                        }
-                                    });
-                                }
-                            }
-                        }
-                    });
-                };
-                request.onsuccess = () => {
-                    this.db = request.result;
-                    console.debug(`Database initialized (version ${this.dbVersion}) with object stores for: ${this.classes.map((cls) => `${cls.name}(v${Reflect.getMetadata('version', cls) || 1})`).join(', ')}`);
-                    this.startRetentionCleanup();
-                    resolve();
-                };
-                request.onerror = () => {
-                    console.error('Error initializing database:', request.error);
-                    reject(request.error);
-                };
-            });
+            const persistedVersion = yield this.readPersistedVersion();
+            if (persistedVersion > this.dbVersion) {
+                this.printDebug(`Declared schema version ${this.dbVersion} is lower than the ` +
+                    `persisted database version ${persistedVersion}. IndexedDB cannot ` +
+                    `downgrade; opening at version ${persistedVersion}.`);
+            }
+            let db = yield this.openConnection(Math.max(this.dbVersion, persistedVersion));
+            const drift = this.migrator.detectFixableDrift(db);
+            if (drift.length > 0) {
+                this.printDebug(`Schema drift detected without a version bump: ${drift.join('; ')}. ` +
+                    `Reopening at version ${db.version + 1} to reconcile.`);
+                const nextVersion = db.version + 1;
+                db.close();
+                db = yield this.openConnection(nextVersion);
+            }
+            this.db = db;
+            this.dbVersion = db.version;
+            this.printDebug(`Database initialized (version ${this.dbVersion}) with object stores for: ${this.schemas.map((schema) => `${schema.className}(v${schema.version})`).join(', ')}`);
+            this.startRetentionCleanup();
         });
     }
     generateEntityRepositories() {
@@ -664,7 +894,7 @@ class Database {
         if (!cleanupIntervalMs || !this.db || this.retentionTimer) {
             return;
         }
-        console.debug(`Retention cleanup enabled for ${this.retentionPolicies.length} entities every ${cleanupIntervalMs}ms`);
+        this.printDebug(`Retention cleanup enabled for ${this.retentionPolicies.length} entities every ${cleanupIntervalMs}ms`);
         void this.runRetentionCleanup();
         this.retentionTimer = setInterval(() => {
             void this.runRetentionCleanup();
@@ -679,11 +909,11 @@ class Database {
             }
             this.retentionCleanupRunning = true;
             try {
-                console.debug('Retention cleanup tick started');
+                this.printDebug('Retention cleanup tick started');
                 for (const { storeName, className, policy } of this.retentionPolicies) {
                     yield this.cleanupExpiredRecords(storeName, className, policy);
                 }
-                console.debug('Retention cleanup tick finished');
+                this.printDebug('Retention cleanup tick finished');
             }
             finally {
                 this.retentionCleanupRunning = false;
@@ -707,11 +937,11 @@ class Database {
                     }
                     const value = cursor.value;
                     const timestamp = value === null || value === void 0 ? void 0 : value[policy.field];
-                    console.debug(`Retention cleanup inspecting ${className}.${policy.field}:`, timestamp, 'cutoff:', cutoff);
+                    this.printDebug(`Retention cleanup inspecting ${className}.${policy.field}:`, timestamp, 'cutoff:', cutoff);
                     if (typeof timestamp === 'number' && timestamp <= cutoff) {
                         const deleteRequest = cursor.delete();
                         deleteRequest.onsuccess = () => {
-                            console.debug(`Retention cleanup removed expired record from ${className}`);
+                            this.printDebug(`Retention cleanup removed expired record from ${className}`);
                             cursor.continue();
                         };
                         deleteRequest.onerror = () => {
@@ -738,11 +968,17 @@ class Database {
         });
     }
     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 calculatedFields = (Reflect.getMetadata('calculated', cls) ||
+            []);
+        const applyCalculatedFields = (item) => {
+            calculatedFields.forEach(({ field, compute }) => {
+                item[field] = compute(item);
+            });
+        };
         const validateItem = (item) => {
             const failures = [];
             validators.forEach((rule) => {
@@ -773,7 +1009,10 @@ class Database {
             }
             switch (generator) {
                 case 'uuid':
-                    return KeyGenerators.uuid();
+                case 'uuidv4':
+                    return KeyGenerators.uuidV4();
+                case 'uuidv6':
+                    return KeyGenerators.uuidV6();
                 case 'timestamp':
                     return KeyGenerators.timestamp();
                 case 'random':
@@ -847,11 +1086,11 @@ class Database {
             }
         };
         return {
-            query() {
-                if (!self.db)
+            query: () => {
+                if (!this.db)
                     throw new Error('Database not initialized.');
                 const storeName = cls.name.toLowerCase();
-                return new QueryBuilder(self.db, storeName, transaction);
+                return new QueryBuilder(this.db, storeName, transaction);
             },
             create: (item) => __awaiter(this, void 0, void 0, function* () {
                 var _a;
@@ -868,11 +1107,12 @@ class Database {
                         }
                     }
                 }
+                applyCalculatedFields(item);
                 validateItem(item);
                 applyTimestampFields(item);
                 return this.performOperation(cls.name, 'readwrite', (store) => {
                     return createStoredItem(store, item).then(() => {
-                        console.debug(`Item added to ${cls.name}:`, item);
+                        this.printDebug(`Item added to ${cls.name}:`, item);
                     });
                 }, transaction);
             }),
@@ -887,7 +1127,7 @@ class Database {
                     const request = store.get(key);
                     return new Promise((resolve, reject) => {
                         request.onsuccess = () => {
-                            console.debug(`Item read from ${cls.name}:`, request.result);
+                            this.printDebug(`Item read from ${cls.name}:`, request.result);
                             resolve(request.result);
                         };
                         request.onerror = () => reject(request.error);
@@ -895,10 +1135,11 @@ class Database {
                 }, transaction);
             }),
             update: (item) => __awaiter(this, void 0, void 0, function* () {
+                applyCalculatedFields(item);
                 validateItem(item);
                 return this.performOperation(cls.name, 'readwrite', (store) => {
                     return updateStoredItem(store, item).then(() => {
-                        console.debug(`Item updated in ${cls.name}:`, item);
+                        this.printDebug(`Item updated in ${cls.name}:`, item);
                     });
                 }, transaction);
             }),
@@ -911,7 +1152,7 @@ class Database {
             delete: (key) => __awaiter(this, void 0, void 0, function* () {
                 return this.performOperation(cls.name, 'readwrite', (store) => {
                     return deleteStoredItem(store, key).then(() => {
-                        console.debug(`Item deleted from ${cls.name}:`, key);
+                        this.printDebug(`Item deleted from ${cls.name}:`, key);
                     });
                 }, transaction);
             }),
@@ -937,7 +1178,7 @@ class Database {
                     const request = store.getAll();
                     return new Promise((resolve, reject) => {
                         request.onsuccess = () => {
-                            console.debug(`All items from ${cls.name}:`, request.result);
+                            this.printDebug(`All items from ${cls.name}:`, request.result);
                             resolve(request.result);
                         };
                         request.onerror = () => reject(request.error);
@@ -951,7 +1192,7 @@ class Database {
                         request.onsuccess = () => {
                             const items = request.result;
                             const paginatedItems = items.slice((page - 1) * pageSize, page * pageSize);
-                            console.debug(`Paginated items from ${cls.name}:`, paginatedItems);
+                            this.printDebug(`Paginated items from ${cls.name}:`, paginatedItems);
                             resolve(paginatedItems);
                         };
                         request.onerror = () => reject(request.error);
@@ -967,7 +1208,7 @@ class Database {
                     const request = index.getAll(value);
                     return new Promise((resolve, reject) => {
                         request.onsuccess = () => {
-                            console.debug(`Items found by index ${indexName} with value ${value}:`, request.result);
+                            this.printDebug(`Items found by index ${indexName} with value ${value}:`, request.result);
                             resolve(request.result);
                         };
                         request.onerror = () => reject(request.error);
@@ -983,7 +1224,7 @@ class Database {
                     const request = index.get(value);
                     return new Promise((resolve, reject) => {
                         request.onsuccess = () => {
-                            console.debug(`Item found by index ${indexName} with value ${value}:`, request.result);
+                            this.printDebug(`Item found by index ${indexName} with value ${value}:`, request.result);
                             resolve(request.result);
                         };
                         request.onerror = () => reject(request.error);
@@ -995,7 +1236,19 @@ class Database {
                     const request = store.count();
                     return new Promise((resolve, reject) => {
                         request.onsuccess = () => {
-                            console.debug(`Count for ${cls.name}:`, request.result);
+                            this.printDebug(`Count for ${cls.name}:`, request.result);
+                            resolve(request.result);
+                        };
+                        request.onerror = () => reject(request.error);
+                    });
+                }, transaction);
+            }),
+            getKeys: () => __awaiter(this, void 0, void 0, function* () {
+                return this.performOperation(cls.name, 'readonly', (store) => {
+                    const request = store.getAllKeys();
+                    return new Promise((resolve, reject) => {
+                        request.onsuccess = () => {
+                            this.printDebug(`Keys for ${cls.name}:`, request.result);
                             resolve(request.result);
                         };
                         request.onerror = () => reject(request.error);
@@ -1008,7 +1261,7 @@ class Database {
                     return new Promise((resolve, reject) => {
                         request.onsuccess = () => {
                             const exists = request.result > 0;
-                            console.debug(`Exists check for ${cls.name} with key ${key}:`, exists);
+                            this.printDebug(`Exists check for ${cls.name} with key ${key}:`, exists);
                             resolve(exists);
                         };
                         request.onerror = () => reject(request.error);
@@ -1020,7 +1273,7 @@ class Database {
                     const request = store.clear();
                     return new Promise((resolve, reject) => {
                         request.onsuccess = () => {
-                            console.debug(`Cleared all items from ${cls.name}`);
+                            this.printDebug(`Cleared all items from ${cls.name}`);
                             resolve();
                         };
                         request.onerror = () => reject(request.error);
@@ -1116,6 +1369,107 @@ class Database {
             }
         });
     }
+    exportDatabase() {
+        return __awaiter(this, void 0, void 0, function* () {
+            const dump = {};
+            for (const cls of this.classes) {
+                const repository = this.entityRepositories.get(cls.name);
+                if (repository) {
+                    dump[cls.name] = yield repository.list();
+                }
+            }
+            return dump;
+        });
+    }
+    importDatabase(dump_1) {
+        return __awaiter(this, arguments, void 0, function* (dump, options = {}) {
+            for (const [entityName, records] of Object.entries(dump)) {
+                const entityClass = this.classes.find((cls) => cls.name === entityName);
+                if (!entityClass) {
+                    this.printDebug(`Skipping import for unregistered entity '${entityName}'.`);
+                    continue;
+                }
+                if (!Array.isArray(records)) {
+                    this.printDebug(`Skipping import for '${entityName}': expected an array of records.`);
+                    continue;
+                }
+                yield this.performOperation(entityName, 'readwrite', (store) => {
+                    return new Promise((resolve, reject) => {
+                        const writeRecords = () => {
+                            let pending = records.length;
+                            if (!pending) {
+                                resolve();
+                                return;
+                            }
+                            records.forEach((record) => {
+                                const request = store.put(record);
+                                request.onsuccess = () => {
+                                    pending -= 1;
+                                    if (!pending)
+                                        resolve();
+                                };
+                                request.onerror = () => reject(request.error);
+                            });
+                        };
+                        if (options.clear) {
+                            const clearRequest = store.clear();
+                            clearRequest.onsuccess = () => writeRecords();
+                            clearRequest.onerror = () => reject(clearRequest.error);
+                            return;
+                        }
+                        writeRecords();
+                    });
+                });
+                this.printDebug(`Imported ${records.length} record(s) into '${entityName}'.`);
+            }
+        });
+    }
+    pushTo(adapter) {
+        return __awaiter(this, void 0, void 0, function* () {
+            for (const cls of this.classes) {
+                const repository = this.entityRepositories.get(cls.name);
+                if (!repository) {
+                    continue;
+                }
+                const records = yield repository.list();
+                yield adapter.push(cls.name, records);
+                this.printDebug(`Pushed ${records.length} record(s) of '${cls.name}' to adapter.`);
+            }
+        });
+    }
+    pullFrom(adapter) {
+        return __awaiter(this, void 0, void 0, function* () {
+            for (const cls of this.classes) {
+                const records = yield adapter.pull(cls.name);
+                if (records === undefined) {
+                    continue;
+                }
+                if (!Array.isArray(records)) {
+                    this.printDebug(`Skipping pull for '${cls.name}': adapter did not return an array.`);
+                    continue;
+                }
+                yield this.performOperation(cls.name, 'readwrite', (store) => {
+                    return new Promise((resolve, reject) => {
+                        let pending = records.length;
+                        if (!pending) {
+                            resolve();
+                            return;
+                        }
+                        records.forEach((record) => {
+                            const request = store.put(record);
+                            request.onsuccess = () => {
+                                pending -= 1;
+                                if (!pending)
+                                    resolve();
+                            };
+                            request.onerror = () => reject(request.error);
+                        });
+                    });
+                });
+                this.printDebug(`Pulled ${records.length} record(s) of '${cls.name}' from adapter.`);
+            }
+        });
+    }
     close() {
         if (this.retentionTimer) {
             clearInterval(this.retentionTimer);
@@ -1146,4 +1500,4 @@ class Database {
     }
 }
 
-export { CompositeKeyPath, DataClass, Database, Index, KeyGenerators, KeyPath, RetentionPolicy, Validate };
+export { Calculated, CompositeKeyPath, DataClass, Database, Index, KeyGenerators, KeyPath, RetentionPolicy, Validate };