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

package/lib/cjs/ChangesetReader.d.ts

@@ -21,6 +21,7 @@ import { AnyDb, SqliteChangeOp } from "./SqliteChangesetReader";
  * @beta
  */
 export declare class ChangesetReader implements Disposable, ChangeSource {
+    private static readonly defaultSpillThresholdInBytes;
     private readonly _nativeReader;
     private _rowOptions?;
     private _propFilter;
@@ -34,18 +35,21 @@ export declare class ChangesetReader implements Disposable, ChangeSource {
     /**
      * `true` when the current row belongs to an EC-mapped table.
      * Valid only after a successful call to [[step]].
+     * @throws [[IModelError]] if called before a successful [[step]] call.
      * @beta
      */
     get isECTable(): boolean;
     /**
      * Name of the SQLite table for the current change row.
      * Valid only after a successful call to [[step]].
+     * @throws [[IModelError]] if called before a successful [[step]] call.
      * @beta
      */
     get tableName(): string;
     /**
      * `true` when the current change was applied indirectly
      * Valid only after a successful call to [[step]].
+     * @throws [[IModelError]] if called before a successful [[step]] call.
      * @beta
      */
     get isIndirectChange(): boolean;
@@ -72,6 +76,7 @@ export declare class ChangesetReader implements Disposable, ChangeSource {
      * @param args.invert When `true`, invert all operations (Insert↔Delete).
      * @param args.valueOptions Row adaptor options controlling how EC property values are formatted.
      * @param args.propFilter Controls which properties are included. Defaults to `All`.
+     * @throws if the native layer fails to open the file.
      * @beta
      */
     static openFile(args: {
@@ -83,10 +88,17 @@ export declare class ChangesetReader implements Disposable, ChangeSource {
      * @param args.db Database with schema at or ahead of the last changeset.
      * @param args.valueOptions Row adaptor options controlling how EC property values are formatted.
      * @param args.propFilter Controls which properties are included. Defaults to `All`.
+     * @param args.spillThresholdInBytes When the total size of the changeset data in the change group exceeds this threshold (in bytes),
+     * the reader writes the data to a temporary file on disk and streams it from there instead of buffering everything in memory.
+     * This keeps peak memory usage bounded, making the API suitable for processing large changeset groups under low-memory conditions.
+     * Defaults to 50 MiB.
+     * @throws if `changesetFiles` is empty, or if the native layer fails to open
+     * the group.
      * @beta
      */
     static openGroup(args: {
         readonly changesetFiles: string[];
+        spillThresholdInBytes?: number;
     } & ChangesetReaderArgs): ChangesetReader;
     /**
      * Read pending (not yet pushed) local changes from an open IModelDb.
@@ -94,21 +106,34 @@ export declare class ChangesetReader implements Disposable, ChangeSource {
      * @param args.includeInMemoryChanges Also include in-memory (not yet saved to disk) changes.
      * @param args.valueOptions Row adaptor options controlling how EC property values are formatted.
      * @param args.propFilter Controls which properties are included. Defaults to `All`.
+     * @param args.spillThresholdInBytes When the total size of all local un-pushed saved changes exceeds this threshold (in bytes),
+     * the reader writes the data to a temporary file on disk and streams it from there instead of buffering everything in memory.
+     * This keeps peak memory usage bounded, making the API suitable for iModels with large local change backlogs under low-memory conditions.
+     * Defaults to 50 MiB.
+     * @throws if the native layer
+     * fails to open the local changes.
      * @beta
      */
     static openLocalChanges(args: Omit<ChangesetReaderArgs, "db"> & {
         db: IModelDb;
         includeInMemoryChanges?: boolean;
+        spillThresholdInBytes?: number;
     }): ChangesetReader;
     /**
      * Read the in-memory (not yet saved to disk) changes of an open IModelDb.
      * @param args.db Must be an [IModelDb]($backend).
      * @param args.valueOptions Row adaptor options controlling how EC property values are formatted.
      * @param args.propFilter Controls which properties are included. Defaults to `All`.
+     * @param args.spillThresholdInBytes When the total size of the in-memory (unsaved) change data exceeds this threshold (in bytes),
+     * the reader writes the data to a temporary file on disk and streams it from there instead of buffering everything in memory.
+     * This keeps peak memory usage bounded, making the API suitable for large in-memory transactions under low-memory conditions.
+     * Defaults to 50 MiB.
+     * @throws if the native layer encounters an error while opening the in-memory changes.
      * @beta
      */
     static openInMemoryChanges(args: Omit<ChangesetReaderArgs, "db"> & {
         db: IModelDb;
+        spillThresholdInBytes?: number;
     }): ChangesetReader;
     /**
      * Read a single saved transaction by its id.
@@ -116,17 +141,27 @@ export declare class ChangesetReader implements Disposable, ChangeSource {
      * @param args.txnId The id of the saved transaction to read.
      * @param args.valueOptions Row adaptor options controlling how EC property values are formatted.
      * @param args.propFilter Controls which properties are included. Defaults to `All`.
+     * @param args.spillThresholdInBytes When the total size of the transaction's change data exceeds this threshold (in bytes),
+     * the reader writes the data to a temporary file on disk and streams it from there instead of buffering everything in memory.
+     * This keeps peak memory usage bounded, making the API suitable for large transactions under low-memory conditions.
+     * Defaults to 50 MiB.
+     * @throws if `txnId` is not found, or
+     * the native layer fails to open the transaction data.
      * @beta
      */
     static openTxn(args: Omit<ChangesetReaderArgs, "db"> & {
         db: IModelDb;
         txnId: Id64String;
+        spillThresholdInBytes?: number;
     }): ChangesetReader;
+    /** Handle errors that occur while auto closing the reader if there is also an error while opening the reader */
+    private handleCloseErrorWhileOpening;
     /**
      * Restrict iteration to changes from the named SQLite tables.
      * That means the rows for changes from other tables will be skipped entirely and won't be visible through the reader.
      * @param tableNames SQLite table names to include.
      * Note: Table names must be provided in the correct case for proper filtering.
+     * @throws if the native layer encounters an error while setting the filter.
      * @beta
      */
     setTableNameFilters(tableNames: Set<string>): void;
@@ -134,6 +169,7 @@ export declare class ChangesetReader implements Disposable, ChangeSource {
      * Restrict iteration to changes with the given operation types.
      * That means the rows for changes with other operation types will be skipped entirely and won't be visible through the reader.
      * @param ops Operations to include.
+     * @throws if the native layer encounters an error while setting the filter.
      * @beta
      */
     setOpCodeFilters(ops: Set<SqliteChangeOp>): void;
@@ -142,43 +178,90 @@ export declare class ChangesetReader implements Disposable, ChangeSource {
      * That means the rows for changes from other EC classes will be skipped entirely and won't be visible through the reader.
      * @param classNames EC class names to include. The classNames should be in the full name format(i.e. "SchemaName:ClassName").
      * Note: Schema names and class names must be provided in the correct case for proper filtering. Derived classes are not automatically included, so they must be specified explicitly if needed.
+     * @throws if the native layer encounters an error while setting the filter.
      * @beta
      */
     setClassNameFilters(classNames: Set<string>): void;
     /**
      * Remove the table-name filters
+     * @throws if the native layer encounters an error.
      * @beta
      */
     clearTableNameFilters(): void;
     /**
      * Remove the op-code filters
+     * @throws if the native layer encounters an error.
      * @beta
      */
     clearOpCodeFilters(): void;
     /**
      * Remove the class-name filters
+     * @throws if the native layer encounters an error.
      * @beta
      */
     clearClassNameFilters(): void;
+    /**
+     * Enable strict mode on the reader.
+     *
+     * Strict mode affects how the reader handles a **column-count mismatch** between a change
+     * record and the corresponding live database table. Such a mismatch can occur when columns
+     * have been added to a table after the changeset was created.
+     *
+     * When strict mode is **enabled**: if the number of columns recorded in a change row differs
+     * from the number of columns currently present in the live table, the reader throws an error
+     * instead of processing that row.
+     *
+     * Use strict mode when you need to be certain that every change row is interpreted against
+     * exactly the schema that was in effect when the changeset was written.
+     *
+     * @see [[disableStrictMode]] — the default (lenient) behaviour.
+     * @throws if the native layer encounters an error.
+     * @beta
+     */
+    enableStrictMode(): void;
+    /**
+     * Disable strict mode on the reader (this is the default).
+     *
+     * When strict mode is **disabled**: if the number of columns recorded in a change row differs
+     * from the number of columns currently present in the live table, the reader takes the
+     * **minimum** of the two column counts and proceeds normally with that subset. This is safe
+     * because SQLite only ever appends new columns at the end of a table and never removes them —
+     * so older change records simply lack the trailing columns that were added later, and those
+     * missing columns are silently ignored.
+     *
+     * @see [[enableStrictMode]] — throw on column-count mismatches instead.
+     * @throws if the native layer encounters an error.
+     * @beta
+     */
+    disableStrictMode(): void;
     /**
      * Advance to the next change and populate `inserted` and/or `deleted`.
      * @returns `true` while positioned on a valid change; `false` when the stream is exhausted.
+     * @throws if the native layer encounters an error while reading or decoding
+     * the next change.
      * @beta
      */
     step(): boolean;
     /**
      * SQLite opcode of the current change.
      * Valid only after a successful call to [[step]].
+     * @throws [[IModelError]] if called before a successful [[step]] call.
      * @beta
      */
     get op(): SqliteChangeOp;
     /**
      * Close the reader and release all native resources.
+     *
+     * @throws if the native layer encounters an error during cleanup. Native resources
+     * are not fully released when this throws — check the native error
+     * logs for details.
      * @beta
      */
     close(): void;
     /**
-     * Implements the `Disposable` contract — calls [[close]].
+     * Implements the `Disposable` contract — delegates to [[close]].
+     *
+     * @throws if the native layer fails to release its resources (re-thrown from [[close]]).
      * @beta
      */
     [Symbol.dispose](): void;

package/lib/cjs/ChangesetReader.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ChangesetReader.d.ts","sourceRoot":"","sources":["../../src/ChangesetReader.ts"],"names":[],"mappings":"AAIA;;GAEG;AACH,OAAO,EAA2B,UAAU,EAAgB,MAAM,qBAAqB,CAAC;AAExF,OAAO,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAItC,OAAO,EAAE,cAAc,EAAE,mBAAmB,EAAE,YAAY,EAAoC,MAAM,wBAAwB,CAAC;AAC7H,OAAO,EAAE,KAAK,EAAE,cAAc,EAAE,MAAM,yBAAyB,CAAC;AAOhE;;;;;;;;;;;;;;GAcG;AACH,qBAAa,eAAgB,YAAW,UAAU,EAAE,YAAY;IAC9D,OAAO,CAAC,QAAQ,CAAC,aAAa,CAA+E;IAE7G,OAAO,CAAC,WAAW,CAAC,CAAmB;IACvC,OAAO,CAAC,WAAW,CAAsC;IACzD,OAAO,CAAC,YAAY,CAAK;IACzB,OAAO,CAAC,GAAG,CAAC,CAAiB;IAC7B,OAAO,CAAC,UAAU,CAAC,CAAU;IAC7B,OAAO,CAAC,UAAU,CAAC,CAAS;IAC5B,OAAO,CAAC,iBAAiB,CAAC,CAAU;IAEpC,4CAA4C;IAC5C,SAAgB,EAAE,EAAE,KAAK,CAAC;IAE1B;;;;OAIG;IACH,IAAW,SAAS,IAAI,OAAO,CAI9B;IAED;;;;OAIG;IACH,IAAW,SAAS,IAAI,MAAM,CAI7B;IAED;;;;OAIG;IACH,IAAW,gBAAgB,IAAI,OAAO,CAIrC;IAED;;;;OAIG;IACI,QAAQ,CAAC,EAAE,cAAc,CAAC;IAEjC;;;;OAIG;IACI,OAAO,CAAC,EAAE,cAAc,CAAC;IAGhC,OAAO;IAIP;mBACe;IACf,OAAO,CAAC,kBAAkB;IAY1B;;;;;;;;OAQG;WACW,QAAQ,CAAC,IAAI,EAAE;QAAE,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;KAAE,GAAG,mBAAmB,GAAG,eAAe;IAelG;;;;;;;OAOG;WACW,SAAS,CAAC,IAAI,EAAE;QAAE,QAAQ,CAAC,cAAc,EAAE,MAAM,EAAE,CAAA;KAAE,GAAG,mBAAmB,GAAG,eAAe;IAiB3G;;;;;;;OAOG;WACW,gBAAgB,CAC5B,IAAI,EAAE,IAAI,CAAC,mBAAmB,EAAE,IAAI,CAAC,GAAG;QAAE,EAAE,EAAE,QAAQ,CAAC;QAAC,sBAAsB,CAAC,EAAE,OAAO,CAAA;KAAE,GACzF,eAAe;IAclB;;;;;;OAMG;WACW,mBAAmB,CAC/B,IAAI,EAAE,IAAI,CAAC,mBAAmB,EAAE,IAAI,CAAC,GAAG;QAAE,EAAE,EAAE,QAAQ,CAAA;KAAE,GACvD,eAAe;IAclB;;;;;;;OAOG;WACW,OAAO,CACnB,IAAI,EAAE,IAAI,CAAC,mBAAmB,EAAE,IAAI,CAAC,GAAG;QAAE,EAAE,EAAE,QAAQ,CAAC;QAAC,KAAK,EAAE,UAAU,CAAA;KAAE,GAC1E,eAAe;IAkBlB;;;;;;OAMG;IACI,mBAAmB,CAAC,UAAU,EAAE,GAAG,CAAC,MAAM,CAAC,GAAG,IAAI;IAIzD;;;;;OAKG;IACI,gBAAgB,CAAC,GAAG,EAAE,GAAG,CAAC,cAAc,CAAC,GAAG,IAAI;IAIvD;;;;;;OAMG;IACI,mBAAmB,CAAC,UAAU,EAAE,GAAG,CAAC,MAAM,CAAC,GAAG,IAAI;IAIzD;;;OAGG;IACI,qBAAqB,IAAI,IAAI;IAIpC;;;OAGG;IACI,kBAAkB,IAAI,IAAI;IAIjC;;;OAGG;IACI,qBAAqB,IAAI,IAAI;IAQpC;;;;OAIG;IACI,IAAI,IAAI,OAAO;IAmEtB;;;;OAIG;IACH,IAAW,EAAE,IAAI,cAAc,CAI9B;IAMD;;;OAGG;IACI,KAAK,IAAI,IAAI;IAWpB;;;OAGG;IACI,CAAC,MAAM,CAAC,OAAO,CAAC,IAAI,IAAI;CAGhC"}
+{"version":3,"file":"ChangesetReader.d.ts","sourceRoot":"","sources":["../../src/ChangesetReader.ts"],"names":[],"mappings":"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"}

package/lib/cjs/ChangesetReader.js

@@ -32,6 +32,7 @@ const ChangesetReaderTypes_1 = require("./ChangesetReaderTypes");
  * @beta
  */
 class ChangesetReader {
+    static defaultSpillThresholdInBytes = 50 * 1024 * 1024; // 50 MiB
     _nativeReader = new NativePlatform_1.IModelNative.platform.ChangesetReader();
     // Internal options — keep ECClassId as raw Id so the unifier can use it as-is.
     _rowOptions;
@@ -46,6 +47,7 @@ class ChangesetReader {
     /**
      * `true` when the current row belongs to an EC-mapped table.
      * Valid only after a successful call to [[step]].
+     * @throws [[IModelError]] if called before a successful [[step]] call.
      * @beta
      */
     get isECTable() {
@@ -56,6 +58,7 @@ class ChangesetReader {
     /**
      * Name of the SQLite table for the current change row.
      * Valid only after a successful call to [[step]].
+     * @throws [[IModelError]] if called before a successful [[step]] call.
      * @beta
      */
     get tableName() {
@@ -66,6 +69,7 @@ class ChangesetReader {
     /**
      * `true` when the current change was applied indirectly
      * Valid only after a successful call to [[step]].
+     * @throws [[IModelError]] if called before a successful [[step]] call.
      * @beta
      */
     get isIndirectChange() {
@@ -108,6 +112,7 @@ class ChangesetReader {
      * @param args.invert When `true`, invert all operations (Insert↔Delete).
      * @param args.valueOptions Row adaptor options controlling how EC property values are formatted.
      * @param args.propFilter Controls which properties are included. Defaults to `All`.
+     * @throws if the native layer fails to open the file.
      * @beta
      */
     static openFile(args) {
@@ -119,7 +124,7 @@ class ChangesetReader {
             reader._nativeReader.openFile(args.db[Symbols_1._nativeDb], args.fileName, args.invert ?? false, reader._propFilter);
         }
         catch (e) {
-            reader.close();
+            reader.handleCloseErrorWhileOpening(e);
             throw e;
         }
         return reader;
@@ -130,20 +135,26 @@ class ChangesetReader {
      * @param args.db Database with schema at or ahead of the last changeset.
      * @param args.valueOptions Row adaptor options controlling how EC property values are formatted.
      * @param args.propFilter Controls which properties are included. Defaults to `All`.
+     * @param args.spillThresholdInBytes When the total size of the changeset data in the change group exceeds this threshold (in bytes),
+     * the reader writes the data to a temporary file on disk and streams it from there instead of buffering everything in memory.
+     * This keeps peak memory usage bounded, making the API suitable for processing large changeset groups under low-memory conditions.
+     * Defaults to 50 MiB.
+     * @throws if `changesetFiles` is empty, or if the native layer fails to open
+     * the group.
      * @beta
      */
     static openGroup(args) {
         if (args.changesetFiles.length === 0)
-            throw new Error("changesetFiles must contain at least one file.");
+            throw new core_common_1.IModelError(core_bentley_1.IModelStatus.BadArg, "changesetFiles must contain at least one file.");
         const reader = new ChangesetReader(args.db);
         reader._rowOptions = args.rowOptions;
         const propFilter = args.propFilter ?? ChangesetReaderTypes_1.PropertyFilter.All;
         reader._propFilter = propFilter;
         try {
-            reader._nativeReader.openGroup(args.db[Symbols_1._nativeDb], args.changesetFiles, args.invert ?? false, reader._propFilter);
+            reader._nativeReader.openGroup(args.db[Symbols_1._nativeDb], args.changesetFiles, args.invert ?? false, reader._propFilter, args.spillThresholdInBytes ?? this.defaultSpillThresholdInBytes);
         }
         catch (e) {
-            reader.close();
+            reader.handleCloseErrorWhileOpening(e);
             throw e;
         }
         return reader;
@@ -154,6 +165,12 @@ class ChangesetReader {
      * @param args.includeInMemoryChanges Also include in-memory (not yet saved to disk) changes.
      * @param args.valueOptions Row adaptor options controlling how EC property values are formatted.
      * @param args.propFilter Controls which properties are included. Defaults to `All`.
+     * @param args.spillThresholdInBytes When the total size of all local un-pushed saved changes exceeds this threshold (in bytes),
+     * the reader writes the data to a temporary file on disk and streams it from there instead of buffering everything in memory.
+     * This keeps peak memory usage bounded, making the API suitable for iModels with large local change backlogs under low-memory conditions.
+     * Defaults to 50 MiB.
+     * @throws if the native layer
+     * fails to open the local changes.
      * @beta
      */
     static openLocalChanges(args) {
@@ -162,10 +179,10 @@ class ChangesetReader {
         const propFilter = args.propFilter ?? ChangesetReaderTypes_1.PropertyFilter.All;
         reader._propFilter = propFilter;
         try {
-            reader._nativeReader.openLocalChanges(args.db[Symbols_1._nativeDb], args.includeInMemoryChanges ?? false, args.invert ?? false, reader._propFilter);
+            reader._nativeReader.openLocalChanges(args.db[Symbols_1._nativeDb], args.includeInMemoryChanges ?? false, args.invert ?? false, reader._propFilter, args.spillThresholdInBytes ?? this.defaultSpillThresholdInBytes);
         }
         catch (e) {
-            reader.close();
+            reader.handleCloseErrorWhileOpening(e);
             throw e;
         }
         return reader;
@@ -175,6 +192,11 @@ class ChangesetReader {
      * @param args.db Must be an [IModelDb]($backend).
      * @param args.valueOptions Row adaptor options controlling how EC property values are formatted.
      * @param args.propFilter Controls which properties are included. Defaults to `All`.
+     * @param args.spillThresholdInBytes When the total size of the in-memory (unsaved) change data exceeds this threshold (in bytes),
+     * the reader writes the data to a temporary file on disk and streams it from there instead of buffering everything in memory.
+     * This keeps peak memory usage bounded, making the API suitable for large in-memory transactions under low-memory conditions.
+     * Defaults to 50 MiB.
+     * @throws if the native layer encounters an error while opening the in-memory changes.
      * @beta
      */
     static openInMemoryChanges(args) {
@@ -183,10 +205,10 @@ class ChangesetReader {
         const propFilter = args.propFilter ?? ChangesetReaderTypes_1.PropertyFilter.All;
         reader._propFilter = propFilter;
         try {
-            reader._nativeReader.openInMemoryChanges(args.db[Symbols_1._nativeDb], args.invert ?? false, reader._propFilter);
+            reader._nativeReader.openInMemoryChanges(args.db[Symbols_1._nativeDb], args.invert ?? false, reader._propFilter, args.spillThresholdInBytes ?? this.defaultSpillThresholdInBytes);
         }
         catch (e) {
-            reader.close();
+            reader.handleCloseErrorWhileOpening(e);
             throw e;
         }
         return reader;
@@ -197,22 +219,40 @@ class ChangesetReader {
      * @param args.txnId The id of the saved transaction to read.
      * @param args.valueOptions Row adaptor options controlling how EC property values are formatted.
      * @param args.propFilter Controls which properties are included. Defaults to `All`.
+     * @param args.spillThresholdInBytes When the total size of the transaction's change data exceeds this threshold (in bytes),
+     * the reader writes the data to a temporary file on disk and streams it from there instead of buffering everything in memory.
+     * This keeps peak memory usage bounded, making the API suitable for large transactions under low-memory conditions.
+     * Defaults to 50 MiB.
+     * @throws if `txnId` is not found, or
+     * the native layer fails to open the transaction data.
      * @beta
      */
     static openTxn(args) {
         const reader = new ChangesetReader(args.db);
-        reader._rowOptions = args.rowOptions ?? {};
+        reader._rowOptions = args.rowOptions;
         const propFilter = args.propFilter ?? ChangesetReaderTypes_1.PropertyFilter.All;
         reader._propFilter = propFilter;
         try {
-            reader._nativeReader.openTxn(args.db[Symbols_1._nativeDb], args.txnId, args.invert ?? false, reader._propFilter);
+            reader._nativeReader.openTxn(args.db[Symbols_1._nativeDb], args.txnId, args.invert ?? false, reader._propFilter, args.spillThresholdInBytes ?? this.defaultSpillThresholdInBytes);
         }
         catch (e) {
-            reader.close();
+            reader.handleCloseErrorWhileOpening(e);
             throw e;
         }
         return reader;
     }
+    /** Handle errors that occur while auto closing the reader if there is also an error while opening the reader */
+    handleCloseErrorWhileOpening(e) {
+        try {
+            this.close();
+        }
+        catch (closeError) {
+            throw new core_common_1.IModelError(core_bentley_1.IModelStatus.BadArg, `Failed to open ChangesetReader with error ${e instanceof Error ? e.message : String(e)}.
+      Additionally, that triggered an automatic closure of the reader
+      releasing native resources which also failed with failure ${closeError instanceof Error ? closeError.message : String(closeError)}.
+      Check native error logs for more details.`);
+        }
+    }
     // ---------------------------------------------------------------------------
     // Filtering
     // ---------------------------------------------------------------------------
@@ -221,6 +261,7 @@ class ChangesetReader {
      * That means the rows for changes from other tables will be skipped entirely and won't be visible through the reader.
      * @param tableNames SQLite table names to include.
      * Note: Table names must be provided in the correct case for proper filtering.
+     * @throws if the native layer encounters an error while setting the filter.
      * @beta
      */
     setTableNameFilters(tableNames) {
@@ -230,6 +271,7 @@ class ChangesetReader {
      * Restrict iteration to changes with the given operation types.
      * That means the rows for changes with other operation types will be skipped entirely and won't be visible through the reader.
      * @param ops Operations to include.
+     * @throws if the native layer encounters an error while setting the filter.
      * @beta
      */
     setOpCodeFilters(ops) {
@@ -240,6 +282,7 @@ class ChangesetReader {
      * That means the rows for changes from other EC classes will be skipped entirely and won't be visible through the reader.
      * @param classNames EC class names to include. The classNames should be in the full name format(i.e. "SchemaName:ClassName").
      * Note: Schema names and class names must be provided in the correct case for proper filtering. Derived classes are not automatically included, so they must be specified explicitly if needed.
+     * @throws if the native layer encounters an error while setting the filter.
      * @beta
      */
     setClassNameFilters(classNames) {
@@ -247,6 +290,7 @@ class ChangesetReader {
     }
     /**
      * Remove the table-name filters
+     * @throws if the native layer encounters an error.
      * @beta
      */
     clearTableNameFilters() {
@@ -254,6 +298,7 @@ class ChangesetReader {
     }
     /**
      * Remove the op-code filters
+     * @throws if the native layer encounters an error.
      * @beta
      */
     clearOpCodeFilters() {
@@ -261,17 +306,61 @@ class ChangesetReader {
     }
     /**
      * Remove the class-name filters
+     * @throws if the native layer encounters an error.
      * @beta
      */
     clearClassNameFilters() {
         this._nativeReader.clearClassNameFilters();
     }
     // ---------------------------------------------------------------------------
+    // Strict mode
+    // ---------------------------------------------------------------------------
+    /**
+     * Enable strict mode on the reader.
+     *
+     * Strict mode affects how the reader handles a **column-count mismatch** between a change
+     * record and the corresponding live database table. Such a mismatch can occur when columns
+     * have been added to a table after the changeset was created.
+     *
+     * When strict mode is **enabled**: if the number of columns recorded in a change row differs
+     * from the number of columns currently present in the live table, the reader throws an error
+     * instead of processing that row.
+     *
+     * Use strict mode when you need to be certain that every change row is interpreted against
+     * exactly the schema that was in effect when the changeset was written.
+     *
+     * @see [[disableStrictMode]] — the default (lenient) behaviour.
+     * @throws if the native layer encounters an error.
+     * @beta
+     */
+    enableStrictMode() {
+        this._nativeReader.enableStrictMode();
+    }
+    /**
+     * Disable strict mode on the reader (this is the default).
+     *
+     * When strict mode is **disabled**: if the number of columns recorded in a change row differs
+     * from the number of columns currently present in the live table, the reader takes the
+     * **minimum** of the two column counts and proceeds normally with that subset. This is safe
+     * because SQLite only ever appends new columns at the end of a table and never removes them —
+     * so older change records simply lack the trailing columns that were added later, and those
+     * missing columns are silently ignored.
+     *
+     * @see [[enableStrictMode]] — throw on column-count mismatches instead.
+     * @throws if the native layer encounters an error.
+     * @beta
+     */
+    disableStrictMode() {
+        this._nativeReader.disableStrictMode();
+    }
+    // ---------------------------------------------------------------------------
     // Iteration
     // ---------------------------------------------------------------------------
     /**
      * Advance to the next change and populate `inserted` and/or `deleted`.
      * @returns `true` while positioned on a valid change; `false` when the stream is exhausted.
+     * @throws if the native layer encounters an error while reading or decoding
+     * the next change.
      * @beta
      */
     step() {
@@ -336,6 +425,7 @@ class ChangesetReader {
     /**
      * SQLite opcode of the current change.
      * Valid only after a successful call to [[step]].
+     * @throws [[IModelError]] if called before a successful [[step]] call.
      * @beta
      */
     get op() {
@@ -348,6 +438,10 @@ class ChangesetReader {
     // ---------------------------------------------------------------------------
     /**
      * Close the reader and release all native resources.
+     *
+     * @throws if the native layer encounters an error during cleanup. Native resources
+     * are not fully released when this throws — check the native error
+     * logs for details.
      * @beta
      */
     close() {
@@ -361,7 +455,9 @@ class ChangesetReader {
         this._nativeReader.close();
     }
     /**
-     * Implements the `Disposable` contract — calls [[close]].
+     * Implements the `Disposable` contract — delegates to [[close]].
+     *
+     * @throws if the native layer fails to release its resources (re-thrown from [[close]]).
      * @beta
      */
     [Symbol.dispose]() {