@itwin/core-backend 5.10.0-dev.19 → 5.10.0-dev.20

package/lib/esm/IModelDb.js

@@ -46,7 +46,7 @@ import { IModelNative } from "./internal/NativePlatform";
 import { createNoOpLockControl } from "./internal/NoLocks";
 import { createIModelDbFonts } from "./internal/IModelDbFontsImpl";
 import { _activeTxn, _cache, _close, _hubAccess, _implicitTxn, _instanceKeyCache, _nativeDb, _releaseAllLocks, _resetIModelDb } from "./internal/Symbols";
-import { ECVersion, SchemaContext, SchemaJsonLocater } from "@itwin/ecschema-metadata";
+import { ECVersion, SchemaContext, SchemaJsonLocater, SchemaView } from "@itwin/ecschema-metadata";
 import { SchemaMap } from "./Schema";
 import { ElementLRUCache, InstanceKeyLRUCache } from "./internal/ElementLRUCache";
 import { IModelIncrementalSchemaLocater } from "./IModelIncrementalSchemaLocater";
@@ -162,6 +162,7 @@ export class IModelDb extends IModel {
     _jsClassMap;
     _schemaMap;
     _schemaContext;
+    _schemasPromise;
     /** @deprecated in 5.0.0 - will not be removed until after 2026-06-13. Use [[fonts]]. */
     _fontMap; // eslint-disable-line @typescript-eslint/no-deprecated
     _fonts = createIModelDbFonts(this);
@@ -794,6 +795,11 @@ export class IModelDb extends IModel {
             this._jsClassMap = undefined;
             this._schemaMap = undefined;
             this._schemaContext = undefined;
+            if (this._schemasPromise) {
+                const old = this._schemasPromise;
+                this._schemasPromise = undefined;
+                old.then((view) => view.markOutdated()).catch(() => { });
+            }
             this[_nativeDb].clearECDbCache();
         }
         this.elements[_cache].clear();
@@ -1234,7 +1240,7 @@ export class IModelDb extends IModel {
     }
     /** The registry of entity metadata for this iModel.
      * @internal
-     * @deprecated in 5.0 - will not be removed until after 2026-06-13. Please use `schemaContext` from the `iModel` instead.
+     * @deprecated in 5.0 - will not be removed until after 2026-06-13. Use `getSchemaView()` from the `iModel` instead.
      *
      * @example
      * ```typescript
@@ -1242,7 +1248,8 @@ export class IModelDb extends IModel {
      * const classMetaData: EntityMetaData | undefined = iModel.classMetaDataRegistry.find("SchemaName:ClassName");
      *
      * // Replacement:
-     * const metaData: EntityClass | undefined = imodel.schemaContext.getSchemaItemSync("SchemaName.ClassName", EntityClass);
+     * const view = await imodel.getSchemaView();
+     * const cls = view.findClass("SchemaName:ClassName");
      * ```
      */
     // eslint-disable-next-line @typescript-eslint/no-deprecated
@@ -1269,7 +1276,11 @@ export class IModelDb extends IModel {
         return this._schemaMap;
     }
     /**
-     * Gets the context that allows accessing the metadata (ecschema-metadata package) of this iModel
+     * Gets the context that allows accessing the metadata (`@itwin/ecschema-metadata` package) of this iModel.
+     *
+     * For runtime read-only access - class/property iteration, IS-A checks, navigating relationships, KOQ lookups -
+     * prefer [[getSchemaView]]. `schemaContext` remains the right choice when you need schema authoring
+     * (via `@itwin/ecschema-editing`), custom-attribute deserialization, or the full ecschema-metadata object graph.
      * @public @preview
      */
     get schemaContext() {
@@ -1283,6 +1294,55 @@ export class IModelDb extends IModel {
         }
         return this._schemaContext;
     }
+    /** Get the schema view for this iModel. The view is built lazily on
+     * first call by fetching compact binary schema data via `PRAGMA schema_view` through
+     * the ConcurrentQuery thread pool. Subsequent calls return the cached view. Multiple
+     * concurrent callers share a single in-flight build.
+     *
+     * The returned `SchemaView` is a lightweight, read-only, synchronous API for
+     * navigating schema metadata - classes, properties, relationships, enumerations, etc.
+     * It is the recommended default for runtime read-only metadata access and is significantly
+     * faster and lower-memory than [[schemaContext]]. Use [[schemaContext]] for schema authoring,
+     * custom-attribute deserialization, or anywhere you need the full ecschema-metadata object graph.
+     * @beta
+     */
+    async getSchemaView() {
+        if (this._schemasPromise) {
+            const ctx = await this._schemasPromise;
+            if (!ctx.isOutdated)
+                return ctx;
+        }
+        // Capture the in-flight promise locally so the rejection handler only clears
+        // `_schemasPromise` if it still points at this build. A concurrent invalidation +
+        // re-fetch could otherwise replace the field before our hydrate fails, and a naive
+        // `_schemasPromise = undefined` would clobber that newer reference.
+        const inflight = this._hydrateSchemas();
+        this._schemasPromise = inflight;
+        inflight.catch(() => {
+            if (this._schemasPromise === inflight)
+                this._schemasPromise = undefined;
+        });
+        return inflight;
+    }
+    async _hydrateSchemas() {
+        // PRAGMA returns exactly one row with format, formatVersion, data (binary), schemaToken.
+        // Important: only call reader.next() once - do NOT use `for await` on PRAGMA results.
+        // ConcurrentQuery wraps regular ECSQL in LIMIT/OFFSET for pagination but skips this for
+        // PRAGMAs. If the serialized result exceeds the memory threshold, the response is marked
+        // "Partial", and a `for await` loop would re-issue the same PRAGMA forever since PRAGMAs
+        // don't support OFFSET-based pagination.
+        // This implementation uses the non-pinned version of the pragma other than frontend - because backend
+        // is always strictly coupled with the native code.
+        const reader = this.createQueryReader("PRAGMA schema_view");
+        const result = await reader.next();
+        if (result.done)
+            throw new IModelError(DbResult.BE_SQLITE_ERROR, "PRAGMA schema_view returned no rows");
+        const data = result.value.data;
+        const token = result.value.schemaToken;
+        if (data === undefined || data === null)
+            throw new IModelError(DbResult.BE_SQLITE_ERROR, "PRAGMA schema_view returned null data column");
+        return SchemaView.fromBinary(data, token ?? "");
+    }
     /** Get the linkTableRelationships for this IModel */
     get relationships() {
         return this._relationships || (this._relationships = new Relationships(this));
@@ -1357,7 +1417,7 @@ export class IModelDb extends IModel {
     }
     /** Get metadata for a class. This method will load the metadata from the iModel into the cache as a side-effect, if necessary.
      * @throws [[IModelError]] if the metadata cannot be found nor loaded.
-     * @deprecated in 5.0 - will not be removed until after 2026-06-13. Please use `getSchemaItem` from `SchemaContext` class instead.
+     * @deprecated in 5.0 - will not be removed until after 2026-06-13. Use `getSchemaView()` on the iModel and call `view.findClass(...)` instead.
      *
      * @example
      *  * ```typescript
@@ -1365,7 +1425,8 @@ export class IModelDb extends IModel {
      * const metaData: EntityMetaData = imodel.getMetaData("SchemaName:ClassName");
      *
      * // Replacement:
-     * const metaData: EntityClass | undefined = imodel.schemaContext.getSchemaItemSync("SchemaName", "ClassName", EntityClass);
+     * const view = await imodel.getSchemaView();
+     * const cls = view.findClass("SchemaName:ClassName");
      * ```
      */
     // eslint-disable-next-line @typescript-eslint/no-deprecated
@@ -1383,7 +1444,7 @@ export class IModelDb extends IModel {
         return metadata;
     }
     /** Identical to [[getMetaData]], except it returns `undefined` instead of throwing an error if the metadata cannot be found nor loaded.
-     * @deprecated in 5.0 - will not be removed until after 2026-06-13. Please use `getSchemaItem` from `SchemaContext` class instead.
+     * @deprecated in 5.0 - will not be removed until after 2026-06-13. Use `getSchemaView()` on the iModel and call `view.findClass(...)` instead.
      *
      * @example
      *  * ```typescript
@@ -1391,7 +1452,8 @@ export class IModelDb extends IModel {
      * const metaData: EntityMetaData | undefined = imodel.tryGetMetaData("SchemaName:ClassName");
      *
      * // Replacement:
-     * const metaData: EntityClass | undefined = imodel.schemaContext.getSchemaItemSync("SchemaName.ClassName", EntityClass);
+     * const view = await imodel.getSchemaView();
+     * const cls = view.findClass("SchemaName:ClassName");
      * ```
      */
     // eslint-disable-next-line @typescript-eslint/no-deprecated
@@ -1411,7 +1473,7 @@ export class IModelDb extends IModel {
      * @param func The callback to be invoked on each property
      * @param includeCustom If true (default), include custom-handled properties in the iteration. Otherwise, skip custom-handled properties.
      * @note Custom-handled properties are core properties that have behavior enforced by C++ handlers.
-     * @deprecated in 5.0 - will not be removed until after 2026-06-13. Please use `forEachProperty` instead.
+     * @deprecated in 5.0 - will not be removed until after 2026-06-13. Use `getSchemaView()` on the iModel and iterate `view.findClass(classFullName)?.getProperties()` instead.
      *
      * @example
      * ```typescript
@@ -1421,9 +1483,10 @@ export class IModelDb extends IModel {
      * }, false);
      *
      * // Replacement:
-     * await IModelDb.forEachProperty(imodel, "TestDomain.TestDomainClass", true, (propName: string, property: Property) => {
-     *   console.log(`Property name: ${propName}, Property type: ${property.propertyType}`);
-     * }, false);
+     * const view = await imodel.getSchemaView();
+     * for (const property of view.findClass("BisCore:Element")?.getProperties() ?? []) {
+     *   console.log(`Property name: ${property.name}, Kind: ${property.kind}`);
+     * }
      * ```
      */
     // eslint-disable-next-line @typescript-eslint/no-deprecated
@@ -1437,7 +1500,7 @@ export class IModelDb extends IModel {
      * @param func The callback to be invoked on each property
      * @param includeCustom If true (default), include custom-handled properties in the iteration. Otherwise, skip custom-handled properties.
      * @note Custom-handled properties are core properties that have behavior enforced by C++ handlers.
-     * @deprecated in 5.0 - will not be removed until after 2026-06-13. Use `forEachProperty` from `SchemaContext` class instead.
+     * @deprecated in 5.0 - will not be removed until after 2026-06-13. Use `getSchemaView()` on the iModel and iterate `view.findClass(classFullName)?.getProperties()` instead.
      *
      * @example
      * ```typescript
@@ -1447,9 +1510,10 @@ export class IModelDb extends IModel {
      * });
      *
      * // Replacement:
-     * imodel.schemaContext.forEachProperty("BisCore:Element", true, (propName: string, property: Property) => {
-     *   console.log(`Property name: ${propName}, Property type: ${property.propertyType}`);
-     * });
+     * const view = await imodel.getSchemaView();
+     * for (const property of view.findClass("BisCore:Element")?.getProperties() ?? []) {
+     *   console.log(`Property name: ${property.name}, Kind: ${property.kind}`);
+     * }
      * ```
      */
     // eslint-disable-next-line @typescript-eslint/no-deprecated
@@ -2529,9 +2593,9 @@ function processSchemaWriteStatus(status) {
          */
         getAspects(elementId, aspectClassFullName, excludedClassFullNames) {
             if (aspectClassFullName === undefined) {
-                const allAspects = this.runInstanceQuery(`SELECT $ FROM (
-          SELECT ECInstanceId, ECClassId FROM Bis.ElementMultiAspect WHERE Element.Id = :elementId
-            UNION ALL
+                const allAspects = this.runInstanceQuery(`SELECT $ FROM (
+          SELECT ECInstanceId, ECClassId FROM Bis.ElementMultiAspect WHERE Element.Id = :elementId
+            UNION ALL
           SELECT ECInstanceId, ECClassId FROM Bis.ElementUniqueAspect WHERE Element.Id = :elementId) OPTIONS USE_JS_PROP_NAMES DO_NOT_TRUNCATE_BLOB`, elementId, excludedClassFullNames);
                 if (allAspects.length === 0)
                     Logger.logInfo(BackendLoggerCategory.ECDb, `No aspects found for class ${aspectClassFullName} and element ${elementId}`);
@@ -2551,7 +2615,7 @@ function processSchemaWriteStatus(status) {
             if (classIdList === undefined) {
                 const classIds = [];
                 // eslint-disable-next-line @typescript-eslint/no-deprecated
-                this._iModel.withPreparedStatement(`select SourceECInstanceId from meta.ClassHasAllBaseClasses where TargetECInstanceId = (select ECInstanceId from meta.ECClassDef where Name='${fullClassName[1]}'
+                this._iModel.withPreparedStatement(`select SourceECInstanceId from meta.ClassHasAllBaseClasses where TargetECInstanceId = (select ECInstanceId from meta.ECClassDef where Name='${fullClassName[1]}'
         and Schema.Id = (select ECInstanceId from meta.ECSchemaDef where Name='${fullClassName[0]}')) and SourceECInstanceId != TargetECInstanceId`, 
                 // eslint-disable-next-line @typescript-eslint/no-deprecated
                 (statement) => {
@@ -2568,10 +2632,10 @@ function processSchemaWriteStatus(status) {
                 return [];
             }
             // Execute an instance query to retrieve all aspects from all the derived classes
-            const aspects = this.runInstanceQuery(`SELECT $ FROM (
-        SELECT ECInstanceId, ECClassId FROM Bis.ElementMultiAspect WHERE Element.Id = :elementId AND ECClassId IN (${classIdList})
-          UNION ALL
-        SELECT ECInstanceId, ECClassId FROM Bis.ElementUniqueAspect WHERE Element.Id = :elementId AND ECClassId IN (${classIdList})
+            const aspects = this.runInstanceQuery(`SELECT $ FROM (
+        SELECT ECInstanceId, ECClassId FROM Bis.ElementMultiAspect WHERE Element.Id = :elementId AND ECClassId IN (${classIdList})
+          UNION ALL
+        SELECT ECInstanceId, ECClassId FROM Bis.ElementUniqueAspect WHERE Element.Id = :elementId AND ECClassId IN (${classIdList})
         ) OPTIONS USE_JS_PROP_NAMES DO_NOT_TRUNCATE_BLOB`, elementId, excludedClassFullNames);
             if (aspects.length === 0)
                 Logger.logInfo(BackendLoggerCategory.ECDb, `No aspects found for class ${aspectClassFullName} and element ${elementId}`);
@@ -3335,7 +3399,63 @@ export class BriefcaseDb extends IModelDb {
     async getAllChangesetHealthData() {
         return this[_nativeDb].getAllChangesetHealthData();
     }
-    /** Revert timeline changes and then push resulting changeset */
+    /**
+     * Whether file-based transactions are enabled for this briefcase.
+     *
+     * When enabled, transaction data is stored in separate temporary `.txn` files rather than in the
+     * briefcase's internal transaction table. This avoids SQLite blob size limits and reduces memory
+     * pressure for very large changesets, at the cost of additional disk I/O.
+     * @see [[enableFileBasedTxns]] to enable, [[disableFileBasedTxns]] to disable.
+     * @internal
+     */
+    get isFileBasedTxnsEnabled() {
+        return this[_nativeDb].queryLocalValue("fileBasedTxns") === "1";
+    }
+    /**
+     * Enable file-based transactions for this briefcase.
+     * @throws IModelError with [[ChangeSetStatus.HasUncommittedChanges]] if there are unsaved changes.
+     * @throws IModelError with [[ChangeSetStatus.HasLocalChanges]] if there are pending transactions.
+     * @internal
+     */
+    enableFileBasedTxns() {
+        this._setFileBasedTxnsSetting(true);
+    }
+    /**
+     * Disable file-based transactions for this briefcase, reverting to the default storage mode
+     * (transactions stored within the briefcase's internal transaction table).
+     * @throws IModelError with [[ChangeSetStatus.HasUncommittedChanges]] if there are unsaved changes.
+     * @throws IModelError with [[ChangeSetStatus.HasLocalChanges]] if there are pending transactions.
+     * @internal
+     */
+    disableFileBasedTxns() {
+        this._setFileBasedTxnsSetting(false);
+    }
+    _setFileBasedTxnsSetting(enabled) {
+        if (this.isFileBasedTxnsEnabled === enabled)
+            return;
+        const nativeDb = this[_nativeDb];
+        if (nativeDb.hasUnsavedChanges())
+            throw new IModelError(ChangeSetStatus.HasUncommittedChanges, "Cannot change file-based transactions setting while there are unsaved changes");
+        if (nativeDb.hasPendingTxns())
+            throw new IModelError(ChangeSetStatus.HasLocalChanges, "Cannot change file-based transactions setting while there are pending transactions");
+        if (enabled)
+            nativeDb.saveLocalValue("fileBasedTxns", "1");
+        else
+            nativeDb.deleteLocalValue("fileBasedTxns");
+    }
+    /**
+     * Revert timeline changes and push the resulting changeset.
+     *
+     * Pulls the latest changes, acquires the schema lock, reverts the inclusive range of
+     * changesets `[toIndex..current]`, and pushes the revert as a new changeset. On failure,
+     * follow the behavior specified by `arg.inCaseOfFailure`, which may discard local changes,
+     * retain local changes, or delete the briefcase.
+     *
+     * @param arg - Arguments specifying the target changeset index, push options, access token, and failure handling behavior.
+     * @throws IModelError with [[ChangeSetStatus.ApplyError]] if `toIndex` is not specified.
+     * @throws IModelError with [[ChangeSetStatus.HasUncommittedChanges]] if there are unsaved changes.
+     * @throws IModelError with [[ChangeSetStatus.HasLocalChanges]] if there are pending transactions.
+     */
     async revertAndPushChanges(arg) {
         const nativeDb = this[_nativeDb];
         if (arg.toIndex === undefined) {
@@ -3367,11 +3487,14 @@ export class BriefcaseDb extends IModelDb {
         if (nativeDb.schemaSyncEnabled()) {
             arg.skipSchemaChanges = true;
         }
+        // The native side enables file-based txns during revert. Restore the original setting afterward.
+        const wasFileBasedTxnsEnabled = this.isFileBasedTxnsEnabled;
+        const preRevertIndex = this.changeset.index;
         try {
             await BriefcaseManager.revertTimelineChanges(this, arg);
-            this[_nativeDb].saveChanges("Revert changes");
+            nativeDb.saveChanges("Revert changes");
             if (!arg.description) {
-                arg.description = `Reverted changes from ${this.changeset.index} to ${arg.toIndex}${arg.skipSchemaChanges ? " (schema changes skipped)" : ""}`;
+                arg.description = `Reverted changes from ${preRevertIndex} to ${arg.toIndex}${arg.skipSchemaChanges ? " (schema changes skipped)" : ""}`;
             }
             const pushArgs = {
                 description: arg.description,
@@ -3386,13 +3509,49 @@ export class BriefcaseDb extends IModelDb {
             this.clearCaches();
         }
         catch (err) {
-            if (!arg.retainLocks) {
-                await this.locks.releaseAllLocks();
-                throw err;
+            const failureAction = arg.inCaseOfFailure ?? "revert";
+            try {
+                switch (failureAction) {
+                    case "revert":
+                        // Restore the briefcase to its pre-revert state: save any unsaved changes into txns,
+                        // reverse all txns, then delete them.
+                        nativeDb.saveChanges();
+                        if (nativeDb.hasPendingTxns())
+                            nativeDb.reverseAll();
+                        nativeDb.deleteAllTxns();
+                        break;
+                    case "delete":
+                        // Clear local changes first so lock release can succeed.
+                        nativeDb.abandonChanges();
+                        nativeDb.deleteAllTxns();
+                        if (!arg.retainLocks)
+                            await this.locks.releaseAllLocks();
+                        const filePath = this.pathName;
+                        this.close();
+                        await BriefcaseManager.deleteBriefcaseFiles(filePath, arg.accessToken);
+                        break;
+                    case "retain":
+                        // Keep local changes as-is for caller inspection/recovery.
+                        nativeDb.saveChanges();
+                        break;
+                }
+            }
+            catch (cleanupErr) {
+                Logger.logError(loggerCategory, `Failed to clean up after revert error (action=${failureAction}): ${String(cleanupErr)}`);
+            }
+            if (!arg.retainLocks && this.isOpen) {
+                try {
+                    await this.locks.releaseAllLocks();
+                }
+                catch (lockErr) {
+                    Logger.logError(loggerCategory, `Failed to release locks after revert failure (action=${failureAction}): ${String(lockErr)}`);
+                }
             }
+            throw err;
         }
         finally {
-            this[_nativeDb].abandonChanges();
+            if (this.isOpen && !wasFileBasedTxnsEnabled && !nativeDb.hasPendingTxns() && !nativeDb.hasUnsavedChanges())
+                this.disableFileBasedTxns();
         }
     }
     /**