@itwin/core-backend 5.1.0-dev.9 → 5.2.0-dev.2

package/lib/esm/ChangesetECAdaptor.js

@@ -5,7 +5,10 @@
 /** @packageDocumentation
  * @module ECDb
  */
-import { DbResult } from "@itwin/core-bentley";
+import { DbResult, Guid } from "@itwin/core-bentley";
+import { Base64EncodedString } from "@itwin/core-common";
+import { ECDb } from "./ECDb";
+import { _nativeDb } from "./internal/Symbols";
 class ECDbMap {
     db;
     _cachedClassMaps = new Map();
@@ -318,6 +321,199 @@ var DateTime;
     }
     DateTime.fromJulianDay = fromJulianDay;
 })(DateTime || (DateTime = {}));
+/** @beta */
+export var ECChangeUnifierCache;
+(function (ECChangeUnifierCache) {
+    /**
+     * Creates and returns a new in-memory cache for EC change unification.
+     * @note This cache is fast but recommended for small to medium size changesets. As it store changes in memory using a hash map, it may run out of memory for larger changesets.
+     * @returns {ECChangeUnifierCache} An instance of cache that store changes in memory using a hash map.
+     */
+    function createInMemoryCache() {
+        return new InMemoryInstanceCache();
+    }
+    ECChangeUnifierCache.createInMemoryCache = createInMemoryCache;
+    /**
+     * Creates an ECChangeUnifierCache that is backed by a database.
+     * @note This cache is suitable for larger changesets and uses SQLite to store changes. It is slower than the in-memory cache but can handle larger datasets without running out of memory.
+     * @param db - The database instance to use for caching.
+     * @param bufferedReadInstanceSizeInBytes - The size in bytes for buffered read instances. Defaults to 10 MB.
+     * @returns An instance of ECChangeUnifierCache backed by SQLite temp db.
+     */
+    function createSqliteBackedCache(db, bufferedReadInstanceSizeInBytes = 1024 * 1024 * 10) {
+        return new SqliteBackedInstanceCache(db, bufferedReadInstanceSizeInBytes);
+    }
+    ECChangeUnifierCache.createSqliteBackedCache = createSqliteBackedCache;
+})(ECChangeUnifierCache || (ECChangeUnifierCache = {}));
+/**
+ * In-memory cache for storing changed EC instances.
+ */
+class InMemoryInstanceCache {
+    _cache = new Map();
+    /**
+     * Retrieves the changed EC instance associated with the specified key.
+     * @param key - The key used to retrieve the instance.
+     * @returns The changed EC instance, or undefined if not found.
+     */
+    get(key) {
+        return this._cache.get(key);
+    }
+    /**
+     * Sets the changed EC instance associated with the specified key.
+     * @param key - The key used to store the instance.
+     * @param value - The changed EC instance to be stored.
+     */
+    set(key, value) {
+        const meta = value.$meta;
+        // Remove undefined keys
+        if (meta) {
+            Object.keys(meta).forEach((k) => meta[k] === undefined && delete meta[k]);
+        }
+        this._cache.set(key, value);
+    }
+    /**
+     * Returns an iterator over all the changed EC instances in the cache.
+     * @returns An iterator over all the changed EC instances.
+     */
+    *all() {
+        for (const key of Array.from(this._cache.keys()).sort()) {
+            const instance = this._cache.get(key);
+            if (instance) {
+                yield instance;
+            }
+        }
+    }
+    /**
+     * Returns the number of changed EC instances in the cache.
+     * @returns The number of changed EC instances.
+     */
+    count() {
+        return this._cache.size;
+    }
+    /**
+     * Disposes the cache.
+     */
+    [Symbol.dispose]() {
+        // Implementation details
+    }
+}
+/**
+ * Represents a cache for unifying EC changes in a SQLite-backed instance cache.
+ */
+class SqliteBackedInstanceCache {
+    _db;
+    bufferedReadInstanceSizeInBytes;
+    _cacheTable = `[temp].[${Guid.createValue()}]`;
+    static defaultBufferSize = 1024 * 1024 * 10; // 10MB
+    /**
+     * Creates an instance of SqliteBackedInstanceCache.
+     * @param _db The underlying database connection.
+     * @param bufferedReadInstanceSizeInBytes The size of read instance buffer defaults to 10Mb.
+     * @throws Error if bufferedReadInstanceSizeInBytes is less than or equal to 0.
+     */
+    constructor(_db, bufferedReadInstanceSizeInBytes = SqliteBackedInstanceCache.defaultBufferSize) {
+        this._db = _db;
+        this.bufferedReadInstanceSizeInBytes = bufferedReadInstanceSizeInBytes;
+        if (bufferedReadInstanceSizeInBytes <= 0)
+            throw new Error("bufferedReadInstanceCount must be greater than 0");
+        this.createTempTable();
+    }
+    /**
+     * Creates a temporary table in the database for caching instances.
+     * @throws Error if unable to create the temporary table.
+     */
+    createTempTable() {
+        this._db.withSqliteStatement(`CREATE TABLE ${this._cacheTable} ([key] text primary key, [value] text)`, (stmt) => {
+            if (DbResult.BE_SQLITE_DONE !== stmt.step())
+                throw new Error("unable to create temp table");
+        });
+    }
+    /**
+     * Drops the temporary table from the database.
+     * @throws Error if unable to drop the temporary table.
+     */
+    dropTempTable() {
+        this._db.saveChanges();
+        if (this._db instanceof ECDb)
+            this._db.clearStatementCache();
+        else {
+            this._db.clearCaches();
+            this._db[_nativeDb].clearECDbCache();
+        }
+        this._db.withSqliteStatement(`DROP TABLE IF EXISTS ${this._cacheTable}`, (stmt) => {
+            if (DbResult.BE_SQLITE_DONE !== stmt.step())
+                throw new Error("unable to drop temp table");
+        });
+    }
+    /**
+     * Retrieves the changed EC instance from the cache based on the specified key.
+     * @param key The key of the instance.
+     * @returns The changed EC instance if found, otherwise undefined.
+     */
+    get(key) {
+        return this._db.withPreparedSqliteStatement(`SELECT [value] FROM ${this._cacheTable} WHERE [key]=?`, (stmt) => {
+            stmt.bindString(1, key);
+            if (stmt.step() === DbResult.BE_SQLITE_ROW) {
+                const out = JSON.parse(stmt.getValueString(0), Base64EncodedString.reviver);
+                return out;
+            }
+            return undefined;
+        });
+    }
+    /**
+     * Sets the changed EC instance in the cache with the specified key.
+     * @param key The key of the instance.
+     * @param value The changed EC instance to be set.
+     */
+    set(key, value) {
+        const shallowCopy = Object.assign({}, value);
+        this._db.withPreparedSqliteStatement(`INSERT INTO ${this._cacheTable} ([key], [value]) VALUES (?, ?) ON CONFLICT ([key]) DO UPDATE SET [value] = [excluded].[value]`, (stmt) => {
+            stmt.bindString(1, key);
+            stmt.bindString(2, JSON.stringify(shallowCopy, Base64EncodedString.replacer));
+            stmt.step();
+        });
+    }
+    /**
+     * Returns an iterator for all the changed EC instances in the cache.
+     * @returns An iterator for all the changed EC instances.
+     */
+    *all() {
+        const sql = `
+      SELECT JSON_GROUP_ARRAY (JSON([value]))
+      FROM   (SELECT
+                    [value],
+                    SUM (LENGTH ([value])) OVER (ORDER BY [key] ROWS UNBOUNDED PRECEDING) / ${this.bufferedReadInstanceSizeInBytes} AS [bucket]
+              FROM   ${this._cacheTable})
+      GROUP  BY [bucket]`;
+        const stmt = this._db.prepareSqliteStatement(sql);
+        while (stmt.step() === DbResult.BE_SQLITE_ROW) {
+            const instanceBucket = JSON.parse(stmt.getValueString(0), Base64EncodedString.reviver);
+            for (const value of instanceBucket) {
+                yield value;
+            }
+        }
+        stmt[Symbol.dispose]();
+    }
+    /**
+     * Returns the number of instances in the cache.
+     * @returns The number of instances in the cache.
+     */
+    count() {
+        return this._db.withPreparedSqliteStatement(`SELECT COUNT(*) FROM ${this._cacheTable}`, (stmt) => {
+            if (stmt.step() === DbResult.BE_SQLITE_ROW)
+                return stmt.getValue(0).getInteger();
+            return 0;
+        });
+    }
+    /**
+     * Disposes the cache by dropping the temporary table.
+     */
+    [Symbol.dispose]() {
+        if (this._db.isOpen) {
+            this.dropTempTable();
+        }
+    }
+}
 /**
  * Combine partial changed instance into single instance.
  * Partial changes is per table and a single instance can
@@ -325,15 +521,26 @@ var DateTime;
  * @beta
  */
 export class PartialECChangeUnifier {
-    _cache = new Map();
+    _db;
+    _cache;
     _readonly = false;
+    constructor(_db, _cache = new InMemoryInstanceCache()) {
+        this._db = _db;
+        this._cache = _cache;
+    }
+    /**
+     * Dispose the instance.
+     */
+    [Symbol.dispose]() {
+        this._cache[Symbol.dispose]();
+    }
     /**
      * Get root class id for a given class
      * @param classId given class id
      * @param db use to find root class
      * @returns return root class id
      */
-    static getRootClassId(classId, db) {
+    getRootClassId(classId) {
         const sql = `
       WITH
       [base_class]([classId], [baseClassId], [Level]) AS(
@@ -356,7 +563,7 @@ export class PartialECChangeUnifier {
                     WHERE  [cc].[Name] = 'IsMixIn'
                             AND [ss].[Name] = 'CoreCustomAttributes'))
       ORDER BY [Level] DESC`;
-        return db.withSqliteStatement(sql, (stmt) => {
+        return this._db.withSqliteStatement(sql, (stmt) => {
             stmt.bindId(1, classId);
             if (stmt.step() === DbResult.BE_SQLITE_ROW && !stmt.isValueNull(0)) {
                 return stmt.getValueString(0);
@@ -364,15 +571,30 @@ export class PartialECChangeUnifier {
             return classId;
         });
     }
+    /**
+     * Checks if the given `rhsClassId` is an instance of the `lhsClassId`.
+     * @param rhsClassId The ID of the right-hand side class.
+     * @param lhsClassId The ID of the left-hand side class.
+     * @returns `true` if `rhsClassId` is an instance of `lhsClassId`, `false` otherwise.
+     */
+    instanceOf(rhsClassId, lhsClassId) {
+        // eslint-disable-next-line @typescript-eslint/no-deprecated
+        return this._db.withPreparedStatement("SELECT ec_instanceof(?,?)", (stmt) => {
+            stmt.bindId(1, rhsClassId);
+            stmt.bindId(2, lhsClassId);
+            stmt.step();
+            return stmt.getValue(0).getInteger() === 1;
+        });
+    }
     /**
      * Combine partial instance with instance with same key if already exists.
      * @param rhs partial instance
      */
-    combine(rhs, db) {
+    combine(rhs) {
         if (!rhs.$meta) {
             throw new Error("PartialECChange being combine must have '$meta' property");
         }
-        const key = PartialECChangeUnifier.buildKey(rhs, db);
+        const key = this.buildKey(rhs);
         const lhs = this._cache.get(key);
         if (lhs) {
             const { $meta: _, ...restOfRhs } = rhs;
@@ -381,37 +603,39 @@ export class PartialECChangeUnifier {
                 lhs.$meta.tables = [...rhs.$meta?.tables, ...lhs.$meta?.tables];
                 lhs.$meta.changeIndexes = [...rhs.$meta?.changeIndexes, ...lhs.$meta?.changeIndexes];
                 // we preserve child class name & id when merging instance.
-                if (rhs.$meta.fallbackClassId && lhs.$meta.fallbackClassId && db && rhs.$meta.fallbackClassId !== lhs.$meta.fallbackClassId) {
+                if (rhs.$meta.fallbackClassId && lhs.$meta.fallbackClassId && rhs.$meta.fallbackClassId !== lhs.$meta.fallbackClassId) {
                     const lhsClassId = lhs.$meta.fallbackClassId;
                     const rhsClassId = rhs.$meta.fallbackClassId;
-                    // eslint-disable-next-line @typescript-eslint/no-deprecated
-                    const isRhsIsSubClassOfLhs = db.withPreparedStatement("SELECT ec_instanceof(?,?)", (stmt) => {
-                        stmt.bindId(1, rhsClassId);
-                        stmt.bindId(2, lhsClassId);
-                        stmt.step();
-                        return stmt.getValue(0).getInteger() === 1;
-                    });
+                    const isRhsIsSubClassOfLhs = this.instanceOf(rhsClassId, lhsClassId);
                     if (isRhsIsSubClassOfLhs) {
                         lhs.$meta.fallbackClassId = rhs.$meta.fallbackClassId;
                         lhs.$meta.classFullName = rhs.$meta.classFullName;
                     }
                 }
             }
+            this._cache.set(key, lhs);
         }
         else {
             this._cache.set(key, rhs);
         }
     }
+    /**
+     * Returns the number of instances in the cache.
+     * @returns The number of instances in the cache.
+     */
+    getInstanceCount() {
+        return this._cache.count();
+    }
     /**
      * Build key from EC change.
      * @param change EC change
      * @returns key created from EC change.
      */
-    static buildKey(change, db) {
+    buildKey(change) {
         let classId = change.ECClassId;
         if (typeof classId === "undefined") {
-            if (db && change.$meta?.fallbackClassId) {
-                classId = this.getRootClassId(change.$meta.fallbackClassId, db);
+            if (change.$meta?.fallbackClassId) {
+                classId = this.getRootClassId(change.$meta.fallbackClassId);
             }
             if (typeof classId === "undefined") {
                 throw new Error(`unable to resolve ECClassId to root class id.`);
@@ -434,32 +658,23 @@ export class PartialECChangeUnifier {
             throw new Error("this instance is marked as readonly.");
         }
         if (adaptor.op === "Updated" && adaptor.inserted && adaptor.deleted) {
-            this.combine(adaptor.inserted, adaptor.reader.db);
-            this.combine(adaptor.deleted, adaptor.reader.db);
+            this.combine(adaptor.inserted);
+            this.combine(adaptor.deleted);
         }
         else if (adaptor.op === "Inserted" && adaptor.inserted) {
-            this.combine(adaptor.inserted, adaptor.reader.db);
+            this.combine(adaptor.inserted);
         }
         else if (adaptor.op === "Deleted" && adaptor.deleted) {
-            this.combine(adaptor.deleted, adaptor.reader.db);
+            this.combine(adaptor.deleted);
         }
     }
-    /**
-     * Delete $meta from all the instances.
-     */
-    stripMetaData() {
-        for (const inst of this._cache.values()) {
-            if ("$meta" in inst) {
-                delete inst.$meta;
-            }
-        }
-        this._readonly = true;
-    }
     /**
      * Returns complete EC change instances.
      * @beta
      */
-    get instances() { return this._cache.values(); }
+    get instances() {
+        return this._cache.all();
+    }
 }
 /**
  * Transform sqlite change to ec change. EC change is partial change as