@itwin/core-backend 5.12.0-dev.6 → 5.12.0-dev.7

package/lib/esm/ChangesetReader.d.ts

@@ -24,14 +24,29 @@ export declare class ChangesetReader implements Disposable, ChangeSource {
     private static readonly defaultSpillThresholdInBytes;
     private readonly _nativeReader;
     private _rowOptions?;
+    private _batchSizeOverride?;
     private _propFilter;
     private _changeIndex;
-    private _op?;
-    private _isECTable?;
-    private _tableName?;
-    private _isIndirectChange?;
+    /** Rows fetched in the most recent native batch call. */
+    private _cache;
+    /**
+     * Index of the current row in `_cache`.
+     * Equals `_cache.length` (i.e. out-of-bounds) when no row is active:
+     * initial state, after exhaustion, or after close().
+     */
+    private _cacheIndex;
+    /** Cached result of the `inserted` getter for the current row. `undefined` when not yet computed or not applicable. */
+    private _cachedInserted;
+    /** Cached result of the `deleted` getter for the current row. `undefined` when not yet computed or not applicable. */
+    private _cachedDeleted;
     /** The db used for EC schema resolution. */
     readonly db: AnyDb;
+    /** Returns the active cached row, throwing if no row is current.
+     * @internal */
+    private get _currentRow();
+    /** Returns the batch size to use for native step() calls based on the active property filter.
+     * @internal */
+    private get _batchSize();
     /**
      * `true` when the current row belongs to an EC-mapped table.
      * Valid only after a successful call to [[step]].
@@ -54,17 +69,21 @@ export declare class ChangesetReader implements Disposable, ChangeSource {
      */
     get isIndirectChange(): boolean;
     /**
-     * Post-change (inserted or updated-new) EC instance, populated after each [[step]] call.
+     * Post-change (inserted or updated-new) EC instance, computed lazily after each [[step]] call.
      * `undefined` when the current row is a Delete or a non-EC table row or [[step]] returned false.
+     * For UPDATE,inserted instances indicate the new state of the instance after the change has been applied and
+     * deleted instances indicate the old state of the instance before the change has been applied.
+     * For INSERT, inserted instances indicate the new state of the instance after the change has been applied and deleted instances are undefined.
+     * For DELETE, deleted instances indicate the old state of the instance before the change has been applied and inserted instances are undefined.
      * @beta
      */
-    inserted?: ChangeInstance;
+    get inserted(): ChangeInstance | undefined;
     /**
-     * Pre-change (deleted or updated-old) EC instance, populated after each [[step]] call.
+     * Pre-change (deleted or updated-old) EC instance, computed lazily after each [[step]] call.
      * `undefined` when the current row is an Insert or a non-EC table row or [[step]] returned false.
      * @beta
      */
-    deleted?: ChangeInstance;
+    get deleted(): ChangeInstance | undefined;
     private constructor();
     /** Map public RowFormatOptions to the native adaptor options.
      * @internal */
@@ -73,8 +92,8 @@ export declare class ChangesetReader implements Disposable, ChangeSource {
      * Open a changeset file from disk.
      * @param args.fileName Absolute path to the changeset file.
      * @param args.db Database at or after the changeset's ending state, used for schema resolution.
-     * @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.invert When `true`, invert all operations (Insert↔Delete, New↔Old).
+     * @param args.rowOptions 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
@@ -86,7 +105,8 @@ export declare class ChangesetReader implements Disposable, ChangeSource {
      * Concatenate multiple changeset files and read them as a single logical stream.
      * @param args.changesetFiles Ordered list of changeset file paths.
      * @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.invert When `true`, invert all operations (Insert↔Delete, New↔Old).
+     * @param args.rowOptions 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.
@@ -104,7 +124,8 @@ export declare class ChangesetReader implements Disposable, ChangeSource {
      * Read pending (not yet pushed) local changes from an open IModelDb.
      * @param args.db Must be an [IModelDb]($backend) (not [ECDb]($backend)).
      * @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.invert When `true`, invert all operations (Insert↔Delete, New↔Old).
+     * @param args.rowOptions 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.
@@ -122,7 +143,8 @@ export declare class ChangesetReader implements Disposable, ChangeSource {
     /**
      * 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.invert When `true`, invert all operations (Insert↔Delete, New↔Old).
+     * @param args.rowOptions 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.
@@ -139,7 +161,8 @@ export declare class ChangesetReader implements Disposable, ChangeSource {
      * Read a single saved transaction by its id.
      * @param args.db Must be an [IModelDb]($backend) ([ECDb]($backend) does not support transactions).
      * @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.invert When `true`, invert all operations (Insert↔Delete, New↔Old).
+     * @param args.rowOptions 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.
@@ -154,14 +177,33 @@ export declare class ChangesetReader implements Disposable, ChangeSource {
         txnId: Id64String;
         spillThresholdInBytes?: number;
     }): ChangesetReader;
+    /** Throws if [[step]] has already been called, preventing filter/mode changes mid-iteration.
+     * @internal */
+    private throwIfAlreadyStepped;
     /** Handle errors that occur while auto closing the reader if there is also an error while opening the reader */
     private handleCloseErrorWhileOpening;
+    /**
+     * Set the number of rows to fetch and cache while stepping.
+     * This is an advanced option that can be used to tune performance for large changesets.
+     * Increasing the batch size improves throughput at the cost of higher peak memory; decreasing it keeps memory consumption lower.
+     *
+     * Default batch sizes when `setBatchSize` is not called:
+     * - `InstanceKey` filter: **100**.
+     * - `BisCoreElement` filter (any `abbreviateBlobs` setting): **20**.
+     * - `All` filter, `abbreviateBlobs: false`: **5**.
+     * - `All` filter (blobs abbreviated or unset): **10**.
+     *
+     * @param batchSize Number of rows to fetch and cache while stepping. Must be a positive integer.
+     * @throws [[IModelError]] if [[step]] has already been called successfully, or if `batchSize` is not a positive integer.
+     * @beta
+     */
+    setBatchSize(batchSize: number): void;
     /**
      * 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.
+     * @throws if [[step]] has already been called and the reader successfully stepped at least once(i.e. returned true for a step() call) or if the native layer encounters an error while setting the filter.
      * @beta
      */
     setTableNameFilters(tableNames: Set<string>): void;
@@ -169,7 +211,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.
+     * @throws if [[step]] has already been called and the reader successfully stepped at least once(i.e. returned true for a step() call) or if the native layer encounters an error while setting the filter.
      * @beta
      */
     setOpCodeFilters(ops: Set<SqliteChangeOp>): void;
@@ -178,25 +220,25 @@ 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.
+     * @throws if [[step]] has already been called and the reader successfully stepped at least once(i.e. returned true for a step() call) or 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.
+     * @throws if [[step]] has already been called and the reader successfully stepped at least once(i.e. returned true for a step() call) or if the native layer encounters an error.
      * @beta
      */
     clearTableNameFilters(): void;
     /**
      * Remove the op-code filters
-     * @throws if the native layer encounters an error.
+     * @throws if [[step]] has already been called and the reader successfully stepped at least once(i.e. returned true for a step() call) or if the native layer encounters an error.
      * @beta
      */
     clearOpCodeFilters(): void;
     /**
      * Remove the class-name filters
-     * @throws if the native layer encounters an error.
+     * @throws if [[step]] has already been called and the reader successfully stepped at least once(i.e. returned true for a step() call) or if the native layer encounters an error.
      * @beta
      */
     clearClassNameFilters(): void;
@@ -215,7 +257,7 @@ export declare class ChangesetReader implements Disposable, ChangeSource {
      * 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.
+     * @throws if [[step]] has already been called and the reader successfully stepped at least once(i.e. returned true for a step() call) or if the native layer encounters an error.
      * @beta
      */
     enableStrictMode(): void;
@@ -230,12 +272,12 @@ export declare class ChangesetReader implements Disposable, ChangeSource {
      * missing columns are silently ignored.
      *
      * @see [[enableStrictMode]] — throw on column-count mismatches instead.
-     * @throws if the native layer encounters an error.
+     * @throws if [[step]] has already been called and the reader successfully stepped at least once(i.e. returned true for a step() call) or if the native layer encounters an error.
      * @beta
      */
     disableStrictMode(): void;
     /**
-     * Advance to the next change and populate `inserted` and/or `deleted`.
+     * Advance to the next change.
      * @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.

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

@@ -1 +1 @@
-{"version":3,"file":"ChangesetReader.d.ts","sourceRoot":"","sources":["../../src/ChangesetReader.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"ChangesetReader.d.ts","sourceRoot":"","sources":["../../src/ChangesetReader.ts"],"names":[],"mappings":"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"}