@itwin/core-backend 5.9.0-dev.9 → 5.10.0-dev.1

package/lib/esm/ChangesetReader.js

@@ -0,0 +1,368 @@
+/*---------------------------------------------------------------------------------------------
+* Copyright (c) Bentley Systems, Incorporated. All rights reserved.
+* See LICENSE.md in the project root for license terms and full copyright notice.
+*--------------------------------------------------------------------------------------------*/
+/** @packageDocumentation
+ * @module ECDb
+ */
+import { DbChangeStage, DbOpcode, IModelStatus } from "@itwin/core-bentley";
+import { IModelError } from "@itwin/core-common";
+import { IModelNative } from "./internal/NativePlatform";
+import { _nativeDb } from "./internal/Symbols";
+import { PropertyFilter } from "./ChangesetReaderTypes";
+// ---------------------------------------------------------------------------
+// ChangesetReader
+// ---------------------------------------------------------------------------
+/**
+ * Reads EC-typed changeset data natively from a changeset file, changeset group,
+ * in-memory transaction, or local un-pushed changes.
+ *
+ * Implements [ChangeSource]($backend) so rows can be fed directly into
+ * [PartialChangeUnifier]($backend) to merge partial (per-table) instances into
+ * complete EC instances.
+ *
+ * When the current row is a non-EC internal SQLite table, [[isECTable]] is `false`
+ * and both [[inserted]] and [[deleted]] remain `undefined`.
+ *
+ * @note The native reader operates one SQLite table-row at a time. Multi-table EC
+ * instances must be merged using [PartialChangeUnifier]($backend).
+ * @beta
+ */
+export class ChangesetReader {
+    _nativeReader = new IModelNative.platform.ChangesetReader();
+    // Internal options — keep ECClassId as raw Id so the unifier can use it as-is.
+    _rowOptions;
+    _propFilter = PropertyFilter.All;
+    _changeIndex = 0;
+    _op;
+    _isECTable;
+    _tableName;
+    _isIndirectChange;
+    /** The db used for EC schema resolution. */
+    db;
+    /**
+     * `true` when the current row belongs to an EC-mapped table.
+     * Valid only after a successful call to [[step]].
+     * @beta
+     */
+    get isECTable() {
+        if (this._isECTable === undefined)
+            throw new IModelError(IModelStatus.BadRequest, "ChangesetReader.isECTable is only valid after step() has positioned the reader on a current valid change.");
+        return this._isECTable;
+    }
+    /**
+     * Name of the SQLite table for the current change row.
+     * Valid only after a successful call to [[step]].
+     * @beta
+     */
+    get tableName() {
+        if (this._tableName === undefined)
+            throw new IModelError(IModelStatus.BadRequest, "ChangesetReader.tableName is only valid after step() has positioned the reader on a current valid change.");
+        return this._tableName;
+    }
+    /**
+     * `true` when the current change was applied indirectly
+     * Valid only after a successful call to [[step]].
+     * @beta
+     */
+    get isIndirectChange() {
+        if (this._isIndirectChange === undefined)
+            throw new IModelError(IModelStatus.BadRequest, "ChangesetReader.isIndirectChange is only valid after step() has positioned the reader on a current valid change.");
+        return this._isIndirectChange;
+    }
+    /**
+     * Post-change (inserted or updated-new) EC instance, populated after each [[step]] call.
+     * `undefined` when the current row is a Delete or a non-EC table row or [[step]] returned false.
+     * @beta
+     */
+    inserted;
+    /**
+     * Pre-change (deleted or updated-old) EC instance, populated after each [[step]] call.
+     * `undefined` when the current row is an Insert or a non-EC table row or [[step]] returned false.
+     * @beta
+     */
+    deleted;
+    // Private — callers use static factory methods.
+    constructor(db) {
+        this.db = db;
+    }
+    /** Map public RowFormatOptions to the native adaptor options.
+     * @internal */
+    toNativeRowOptions(opts) {
+        return {
+            abbreviateBlobs: opts.abbreviateBlobs,
+            classIdsToClassNames: opts.classIdsToClassNames,
+            useJsName: opts.useJsName,
+        };
+    }
+    // ---------------------------------------------------------------------------
+    // Static factory methods
+    // ---------------------------------------------------------------------------
+    /**
+     * 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.propFilter Controls which properties are included. Defaults to `All`.
+     * @beta
+     */
+    static openFile(args) {
+        const reader = new ChangesetReader(args.db);
+        reader._rowOptions = args.rowOptions;
+        const propFilter = args.propFilter ?? PropertyFilter.All;
+        reader._propFilter = propFilter;
+        try {
+            reader._nativeReader.openFile(args.db[_nativeDb], args.fileName, args.invert ?? false, reader._propFilter);
+        }
+        catch (e) {
+            reader.close();
+            throw e;
+        }
+        return reader;
+    }
+    /**
+     * 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.propFilter Controls which properties are included. Defaults to `All`.
+     * @beta
+     */
+    static openGroup(args) {
+        if (args.changesetFiles.length === 0)
+            throw new Error("changesetFiles must contain at least one file.");
+        const reader = new ChangesetReader(args.db);
+        reader._rowOptions = args.rowOptions;
+        const propFilter = args.propFilter ?? PropertyFilter.All;
+        reader._propFilter = propFilter;
+        try {
+            reader._nativeReader.openGroup(args.db[_nativeDb], args.changesetFiles, args.invert ?? false, reader._propFilter);
+        }
+        catch (e) {
+            reader.close();
+            throw e;
+        }
+        return reader;
+    }
+    /**
+     * 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.propFilter Controls which properties are included. Defaults to `All`.
+     * @beta
+     */
+    static openLocalChanges(args) {
+        const reader = new ChangesetReader(args.db);
+        reader._rowOptions = args.rowOptions;
+        const propFilter = args.propFilter ?? PropertyFilter.All;
+        reader._propFilter = propFilter;
+        try {
+            reader._nativeReader.openLocalChanges(args.db[_nativeDb], args.includeInMemoryChanges ?? false, args.invert ?? false, reader._propFilter);
+        }
+        catch (e) {
+            reader.close();
+            throw e;
+        }
+        return reader;
+    }
+    /**
+     * 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`.
+     * @beta
+     */
+    static openInMemoryChanges(args) {
+        const reader = new ChangesetReader(args.db);
+        reader._rowOptions = args.rowOptions;
+        const propFilter = args.propFilter ?? PropertyFilter.All;
+        reader._propFilter = propFilter;
+        try {
+            reader._nativeReader.openInMemoryChanges(args.db[_nativeDb], args.invert ?? false, reader._propFilter);
+        }
+        catch (e) {
+            reader.close();
+            throw e;
+        }
+        return reader;
+    }
+    /**
+     * 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.propFilter Controls which properties are included. Defaults to `All`.
+     * @beta
+     */
+    static openTxn(args) {
+        const reader = new ChangesetReader(args.db);
+        reader._rowOptions = args.rowOptions ?? {};
+        const propFilter = args.propFilter ?? PropertyFilter.All;
+        reader._propFilter = propFilter;
+        try {
+            reader._nativeReader.openTxn(args.db[_nativeDb], args.txnId, args.invert ?? false, reader._propFilter);
+        }
+        catch (e) {
+            reader.close();
+            throw e;
+        }
+        return reader;
+    }
+    // ---------------------------------------------------------------------------
+    // Filtering
+    // ---------------------------------------------------------------------------
+    /**
+     * 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.
+     * @beta
+     */
+    setTableNameFilters(tableNames) {
+        this._nativeReader.setTableNameFilters(Array.from(tableNames));
+    }
+    /**
+     * 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.
+     * @beta
+     */
+    setOpCodeFilters(ops) {
+        this._nativeReader.setOpCodeFilters(Array.from(ops));
+    }
+    /**
+     * Restrict iteration to changes for the given EC class names.
+     * 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.
+     * @beta
+     */
+    setClassNameFilters(classNames) {
+        this._nativeReader.setClassNameFilters(Array.from(classNames));
+    }
+    /**
+     * Remove the table-name filters
+     * @beta
+     */
+    clearTableNameFilters() {
+        this._nativeReader.clearTableNameFilters();
+    }
+    /**
+     * Remove the op-code filters
+     * @beta
+     */
+    clearOpCodeFilters() {
+        this._nativeReader.clearOpCodeFilters();
+    }
+    /**
+     * Remove the class-name filters
+     * @beta
+     */
+    clearClassNameFilters() {
+        this._nativeReader.clearClassNameFilters();
+    }
+    // ---------------------------------------------------------------------------
+    // 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.
+     * @beta
+     */
+    step() {
+        this.inserted = undefined;
+        this.deleted = undefined;
+        this._op = undefined;
+        this._isECTable = undefined;
+        this._tableName = undefined;
+        this._isIndirectChange = undefined;
+        if (this._nativeReader.step()) {
+            this._changeIndex++;
+            const meta = this._nativeReader.getChangeMetadata();
+            const nativeOp = meta.opCode;
+            const op = nativeOp === DbOpcode.Insert ? "Inserted" : nativeOp === DbOpcode.Update ? "Updated" : "Deleted";
+            this._op = op;
+            this._tableName = meta.tableName;
+            this._isIndirectChange = meta.isIndirectChange;
+            this._isECTable = meta.isECTable;
+            const nativeRowOpts = this._rowOptions ? this.toNativeRowOptions(this._rowOptions) : {};
+            if (op === "Inserted" || op === "Updated") {
+                const rowValue = this._nativeReader.getValue(DbChangeStage.New, nativeRowOpts);
+                if (rowValue !== undefined) {
+                    this.inserted = {
+                        ...rowValue.data,
+                        $meta: {
+                            op,
+                            tables: [this._tableName],
+                            changeIndexes: [this._changeIndex],
+                            stage: "New",
+                            instanceKey: rowValue.key,
+                            propFilter: this._propFilter,
+                            changeFetchedPropNames: rowValue.changeFetchedPropNames,
+                            rowOptions: this._rowOptions,
+                            isIndirectChange: this._isIndirectChange,
+                        },
+                    };
+                }
+            }
+            if (op === "Deleted" || op === "Updated") {
+                const rowValue = this._nativeReader.getValue(DbChangeStage.Old, nativeRowOpts);
+                if (rowValue !== undefined) {
+                    this.deleted = {
+                        ...rowValue.data,
+                        $meta: {
+                            op,
+                            tables: [this._tableName],
+                            changeIndexes: [this._changeIndex],
+                            stage: "Old",
+                            instanceKey: rowValue.key,
+                            propFilter: this._propFilter,
+                            changeFetchedPropNames: rowValue.changeFetchedPropNames,
+                            rowOptions: this._rowOptions,
+                            isIndirectChange: this._isIndirectChange,
+                        },
+                    };
+                }
+            }
+            return true;
+        }
+        return false;
+    }
+    /**
+     * SQLite opcode of the current change.
+     * Valid only after a successful call to [[step]].
+     * @beta
+     */
+    get op() {
+        if (this._op === undefined)
+            throw new IModelError(IModelStatus.BadRequest, "ChangesetReader.op is only valid after step() has positioned the reader on a current valid change.");
+        return this._op;
+    }
+    // ---------------------------------------------------------------------------
+    // Lifecycle
+    // ---------------------------------------------------------------------------
+    /**
+     * Close the reader and release all native resources.
+     * @beta
+     */
+    close() {
+        this._changeIndex = 0;
+        this._op = undefined;
+        this._isECTable = undefined;
+        this._tableName = undefined;
+        this._isIndirectChange = undefined;
+        this.inserted = undefined;
+        this.deleted = undefined;
+        this._nativeReader.close();
+    }
+    /**
+     * Implements the `Disposable` contract — calls [[close]].
+     * @beta
+     */
+    [Symbol.dispose]() {
+        this.close();
+    }
+}
+//# sourceMappingURL=ChangesetReader.js.map

package/lib/esm/ChangesetReader.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ChangesetReader.js","sourceRoot":"","sources":["../../src/ChangesetReader.ts"],"names":[],"mappings":"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","sourcesContent":["/*---------------------------------------------------------------------------------------------\r\n* Copyright (c) Bentley Systems, Incorporated. All rights reserved.\r\n* See LICENSE.md in the project root for license terms and full copyright notice.\r\n*--------------------------------------------------------------------------------------------*/\r\n/** @packageDocumentation\r\n * @module ECDb\r\n */\r\nimport { DbChangeStage, DbOpcode, Id64String, IModelStatus } from \"@itwin/core-bentley\";\r\nimport { IModelError } from \"@itwin/core-common\";\r\nimport { IModelDb } from \"./IModelDb\";\r\nimport { IModelNative } from \"./internal/NativePlatform\";\r\nimport { _nativeDb } from \"./internal/Symbols\";\r\nimport { IModelJsNative } from \"@bentley/imodeljs-native\";\r\nimport { ChangeInstance, ChangesetReaderArgs, ChangeSource, PropertyFilter, RowFormatOptions } from \"./ChangesetReaderTypes\";\r\nimport { AnyDb, SqliteChangeOp } from \"./SqliteChangesetReader\";\r\n\r\n\r\n// ---------------------------------------------------------------------------\r\n// ChangesetReader\r\n// ---------------------------------------------------------------------------\r\n\r\n/**\r\n * Reads EC-typed changeset data natively from a changeset file, changeset group,\r\n * in-memory transaction, or local un-pushed changes.\r\n *\r\n * Implements [ChangeSource]($backend) so rows can be fed directly into\r\n * [PartialChangeUnifier]($backend) to merge partial (per-table) instances into\r\n * complete EC instances.\r\n *\r\n * When the current row is a non-EC internal SQLite table, [[isECTable]] is `false`\r\n * and both [[inserted]] and [[deleted]] remain `undefined`.\r\n *\r\n * @note The native reader operates one SQLite table-row at a time. Multi-table EC\r\n * instances must be merged using [PartialChangeUnifier]($backend).\r\n * @beta\r\n */\r\nexport class ChangesetReader implements Disposable, ChangeSource {\r\n  private readonly _nativeReader: IModelJsNative.ChangesetReader = new IModelNative.platform.ChangesetReader();\r\n  // Internal options — keep ECClassId as raw Id so the unifier can use it as-is.\r\n  private _rowOptions?: RowFormatOptions;\r\n  private _propFilter: PropertyFilter = PropertyFilter.All;\r\n  private _changeIndex = 0;\r\n  private _op?: SqliteChangeOp;\r\n  private _isECTable?: boolean;\r\n  private _tableName?: string;\r\n  private _isIndirectChange?: boolean;\r\n\r\n  /** The db used for EC schema resolution. */\r\n  public readonly db: AnyDb;\r\n\r\n  /**\r\n   * `true` when the current row belongs to an EC-mapped table.\r\n   * Valid only after a successful call to [[step]].\r\n   * @beta\r\n   */\r\n  public get isECTable(): boolean {\r\n    if (this._isECTable === undefined)\r\n      throw new IModelError(IModelStatus.BadRequest, \"ChangesetReader.isECTable is only valid after step() has positioned the reader on a current valid change.\");\r\n    return this._isECTable;\r\n  }\r\n\r\n  /**\r\n   * Name of the SQLite table for the current change row.\r\n   * Valid only after a successful call to [[step]].\r\n   * @beta\r\n   */\r\n  public get tableName(): string {\r\n    if (this._tableName === undefined)\r\n      throw new IModelError(IModelStatus.BadRequest, \"ChangesetReader.tableName is only valid after step() has positioned the reader on a current valid change.\");\r\n    return this._tableName;\r\n  }\r\n\r\n  /**\r\n   * `true` when the current change was applied indirectly\r\n   * Valid only after a successful call to [[step]].\r\n   * @beta\r\n   */\r\n  public get isIndirectChange(): boolean {\r\n    if (this._isIndirectChange === undefined)\r\n      throw new IModelError(IModelStatus.BadRequest, \"ChangesetReader.isIndirectChange is only valid after step() has positioned the reader on a current valid change.\");\r\n    return this._isIndirectChange;\r\n  }\r\n\r\n  /**\r\n   * Post-change (inserted or updated-new) EC instance, populated after each [[step]] call.\r\n   * `undefined` when the current row is a Delete or a non-EC table row or [[step]] returned false.\r\n   * @beta\r\n   */\r\n  public inserted?: ChangeInstance;\r\n\r\n  /**\r\n   * Pre-change (deleted or updated-old) EC instance, populated after each [[step]] call.\r\n   * `undefined` when the current row is an Insert or a non-EC table row or [[step]] returned false.\r\n   * @beta\r\n   */\r\n  public deleted?: ChangeInstance;\r\n\r\n  // Private — callers use static factory methods.\r\n  private constructor(db: AnyDb) {\r\n    this.db = db;\r\n  }\r\n\r\n  /** Map public RowFormatOptions to the native adaptor options.\r\n   * @internal */\r\n  private toNativeRowOptions(opts: RowFormatOptions): IModelJsNative.ECSqlRowAdaptorOptions {\r\n    return {\r\n      abbreviateBlobs: opts.abbreviateBlobs,\r\n      classIdsToClassNames: opts.classIdsToClassNames,\r\n      useJsName: opts.useJsName,\r\n    };\r\n  }\r\n\r\n  // ---------------------------------------------------------------------------\r\n  // Static factory methods\r\n  // ---------------------------------------------------------------------------\r\n\r\n  /**\r\n   * Open a changeset file from disk.\r\n   * @param args.fileName Absolute path to the changeset file.\r\n   * @param args.db Database at or after the changeset's ending state, used for schema resolution.\r\n   * @param args.invert When `true`, invert all operations (Insert↔Delete).\r\n   * @param args.valueOptions Row adaptor options controlling how EC property values are formatted.\r\n   * @param args.propFilter Controls which properties are included. Defaults to `All`.\r\n   * @beta\r\n   */\r\n  public static openFile(args: { readonly fileName: string } & ChangesetReaderArgs): ChangesetReader {\r\n    const reader = new ChangesetReader(args.db);\r\n    reader._rowOptions = args.rowOptions;\r\n    const propFilter = args.propFilter ?? PropertyFilter.All;\r\n    reader._propFilter = propFilter;\r\n    try {\r\n      reader._nativeReader.openFile(args.db[_nativeDb], args.fileName, args.invert ?? false, reader._propFilter);\r\n    }\r\n    catch (e) {\r\n      reader.close();\r\n      throw e;\r\n    }\r\n    return reader;\r\n  }\r\n\r\n  /**\r\n   * Concatenate multiple changeset files and read them as a single logical stream.\r\n   * @param args.changesetFiles Ordered list of changeset file paths.\r\n   * @param args.db Database with schema at or ahead of the last changeset.\r\n   * @param args.valueOptions Row adaptor options controlling how EC property values are formatted.\r\n   * @param args.propFilter Controls which properties are included. Defaults to `All`.\r\n   * @beta\r\n   */\r\n  public static openGroup(args: { readonly changesetFiles: string[] } & ChangesetReaderArgs): ChangesetReader {\r\n    if (args.changesetFiles.length === 0)\r\n      throw new Error(\"changesetFiles must contain at least one file.\");\r\n    const reader = new ChangesetReader(args.db);\r\n    reader._rowOptions = args.rowOptions;\r\n    const propFilter = args.propFilter ?? PropertyFilter.All;\r\n    reader._propFilter = propFilter;\r\n    try {\r\n      reader._nativeReader.openGroup(args.db[_nativeDb], args.changesetFiles, args.invert ?? false, reader._propFilter);\r\n    }\r\n    catch (e) {\r\n      reader.close();\r\n      throw e;\r\n    }\r\n    return reader;\r\n  }\r\n\r\n  /**\r\n   * Read pending (not yet pushed) local changes from an open IModelDb.\r\n   * @param args.db Must be an [IModelDb]($backend) (not [ECDb]($backend)).\r\n   * @param args.includeInMemoryChanges Also include in-memory (not yet saved to disk) changes.\r\n   * @param args.valueOptions Row adaptor options controlling how EC property values are formatted.\r\n   * @param args.propFilter Controls which properties are included. Defaults to `All`.\r\n   * @beta\r\n   */\r\n  public static openLocalChanges(\r\n    args: Omit<ChangesetReaderArgs, \"db\"> & { db: IModelDb; includeInMemoryChanges?: boolean },\r\n  ): ChangesetReader {\r\n    const reader = new ChangesetReader(args.db);\r\n    reader._rowOptions = args.rowOptions;\r\n    const propFilter = args.propFilter ?? PropertyFilter.All;\r\n    reader._propFilter = propFilter;\r\n    try {\r\n      reader._nativeReader.openLocalChanges(args.db[_nativeDb], args.includeInMemoryChanges ?? false, args.invert ?? false, reader._propFilter);\r\n    } catch (e) {\r\n      reader.close();\r\n      throw e;\r\n    }\r\n    return reader;\r\n  }\r\n\r\n  /**\r\n   * Read the in-memory (not yet saved to disk) changes of an open IModelDb.\r\n   * @param args.db Must be an [IModelDb]($backend).\r\n   * @param args.valueOptions Row adaptor options controlling how EC property values are formatted.\r\n   * @param args.propFilter Controls which properties are included. Defaults to `All`.\r\n   * @beta\r\n   */\r\n  public static openInMemoryChanges(\r\n    args: Omit<ChangesetReaderArgs, \"db\"> & { db: IModelDb },\r\n  ): ChangesetReader {\r\n    const reader = new ChangesetReader(args.db);\r\n    reader._rowOptions = args.rowOptions;\r\n    const propFilter = args.propFilter ?? PropertyFilter.All;\r\n    reader._propFilter = propFilter;\r\n    try {\r\n      reader._nativeReader.openInMemoryChanges(args.db[_nativeDb], args.invert ?? false, reader._propFilter);\r\n    } catch (e) {\r\n      reader.close();\r\n      throw e;\r\n    }\r\n    return reader;\r\n  }\r\n\r\n  /**\r\n   * Read a single saved transaction by its id.\r\n   * @param args.db Must be an [IModelDb]($backend) ([ECDb]($backend) does not support transactions).\r\n   * @param args.txnId The id of the saved transaction to read.\r\n   * @param args.valueOptions Row adaptor options controlling how EC property values are formatted.\r\n   * @param args.propFilter Controls which properties are included. Defaults to `All`.\r\n   * @beta\r\n   */\r\n  public static openTxn(\r\n    args: Omit<ChangesetReaderArgs, \"db\"> & { db: IModelDb; txnId: Id64String },\r\n  ): ChangesetReader {\r\n    const reader = new ChangesetReader(args.db);\r\n    reader._rowOptions = args.rowOptions ?? {};\r\n    const propFilter = args.propFilter ?? PropertyFilter.All;\r\n    reader._propFilter = propFilter;\r\n    try {\r\n      reader._nativeReader.openTxn(args.db[_nativeDb], args.txnId, args.invert ?? false, reader._propFilter);\r\n    } catch (e) {\r\n      reader.close();\r\n      throw e;\r\n    }\r\n    return reader;\r\n  }\r\n\r\n  // ---------------------------------------------------------------------------\r\n  // Filtering\r\n  // ---------------------------------------------------------------------------\r\n\r\n  /**\r\n   * Restrict iteration to changes from the named SQLite tables.\r\n   * That means the rows for changes from other tables will be skipped entirely and won't be visible through the reader.\r\n   * @param tableNames SQLite table names to include.\r\n   * Note: Table names must be provided in the correct case for proper filtering.\r\n   * @beta\r\n   */\r\n  public setTableNameFilters(tableNames: Set<string>): void {\r\n    this._nativeReader.setTableNameFilters(Array.from(tableNames));\r\n  }\r\n\r\n  /**\r\n   * Restrict iteration to changes with the given operation types.\r\n   * That means the rows for changes with other operation types will be skipped entirely and won't be visible through the reader.\r\n   * @param ops Operations to include.\r\n   * @beta\r\n   */\r\n  public setOpCodeFilters(ops: Set<SqliteChangeOp>): void {\r\n    this._nativeReader.setOpCodeFilters(Array.from(ops));\r\n  }\r\n\r\n  /**\r\n   * Restrict iteration to changes for the given EC class names.\r\n   * That means the rows for changes from other EC classes will be skipped entirely and won't be visible through the reader.\r\n   * @param classNames EC class names to include. The classNames should be in the full name format(i.e. \"SchemaName:ClassName\").\r\n   * 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.\r\n   * @beta\r\n   */\r\n  public setClassNameFilters(classNames: Set<string>): void {\r\n    this._nativeReader.setClassNameFilters(Array.from(classNames));\r\n  }\r\n\r\n  /**\r\n   * Remove the table-name filters\r\n   * @beta\r\n   */\r\n  public clearTableNameFilters(): void {\r\n    this._nativeReader.clearTableNameFilters();\r\n  }\r\n\r\n  /**\r\n   * Remove the op-code filters\r\n   * @beta\r\n   */\r\n  public clearOpCodeFilters(): void {\r\n    this._nativeReader.clearOpCodeFilters();\r\n  }\r\n\r\n  /**\r\n   * Remove the class-name filters\r\n   * @beta\r\n   */\r\n  public clearClassNameFilters(): void {\r\n    this._nativeReader.clearClassNameFilters();\r\n  }\r\n\r\n  // ---------------------------------------------------------------------------\r\n  // Iteration\r\n  // ---------------------------------------------------------------------------\r\n\r\n  /**\r\n   * Advance to the next change and populate `inserted` and/or `deleted`.\r\n   * @returns `true` while positioned on a valid change; `false` when the stream is exhausted.\r\n   * @beta\r\n   */\r\n  public step(): boolean {\r\n    this.inserted = undefined;\r\n    this.deleted = undefined;\r\n    this._op = undefined;\r\n    this._isECTable = undefined;\r\n    this._tableName = undefined;\r\n    this._isIndirectChange = undefined;\r\n\r\n    if (this._nativeReader.step()) {\r\n      this._changeIndex++;\r\n      const meta = this._nativeReader.getChangeMetadata();\r\n      const nativeOp = meta.opCode;\r\n      const op: SqliteChangeOp = nativeOp === DbOpcode.Insert ? \"Inserted\" : nativeOp === DbOpcode.Update ? \"Updated\" : \"Deleted\";\r\n      this._op = op;\r\n\r\n      this._tableName = meta.tableName;\r\n      this._isIndirectChange = meta.isIndirectChange;\r\n      this._isECTable = meta.isECTable;\r\n\r\n      const nativeRowOpts = this._rowOptions ? this.toNativeRowOptions(this._rowOptions) : {};\r\n\r\n      if (op === \"Inserted\" || op === \"Updated\") {\r\n        const rowValue = this._nativeReader.getValue(DbChangeStage.New, nativeRowOpts);\r\n        if (rowValue !== undefined) {\r\n          this.inserted = {\r\n            ...rowValue.data,\r\n            $meta: {\r\n              op,\r\n              tables: [this._tableName],\r\n              changeIndexes: [this._changeIndex],\r\n              stage: \"New\",\r\n              instanceKey: rowValue.key,\r\n              propFilter: this._propFilter,\r\n              changeFetchedPropNames: rowValue.changeFetchedPropNames,\r\n              rowOptions: this._rowOptions,\r\n              isIndirectChange: this._isIndirectChange,\r\n            },\r\n          };\r\n        }\r\n      }\r\n\r\n      if (op === \"Deleted\" || op === \"Updated\") {\r\n        const rowValue = this._nativeReader.getValue(DbChangeStage.Old, nativeRowOpts);\r\n        if (rowValue !== undefined) {\r\n          this.deleted = {\r\n            ...rowValue.data,\r\n            $meta: {\r\n              op,\r\n              tables: [this._tableName],\r\n              changeIndexes: [this._changeIndex],\r\n              stage: \"Old\",\r\n              instanceKey: rowValue.key,\r\n              propFilter: this._propFilter,\r\n              changeFetchedPropNames: rowValue.changeFetchedPropNames,\r\n              rowOptions: this._rowOptions,\r\n              isIndirectChange: this._isIndirectChange,\r\n            },\r\n          };\r\n        }\r\n      }\r\n\r\n      return true;\r\n    }\r\n\r\n    return false;\r\n  }\r\n\r\n  /**\r\n   * SQLite opcode of the current change.\r\n   * Valid only after a successful call to [[step]].\r\n   * @beta\r\n   */\r\n  public get op(): SqliteChangeOp {\r\n    if (this._op === undefined)\r\n      throw new IModelError(IModelStatus.BadRequest, \"ChangesetReader.op is only valid after step() has positioned the reader on a current valid change.\");\r\n    return this._op;\r\n  }\r\n\r\n  // ---------------------------------------------------------------------------\r\n  // Lifecycle\r\n  // ---------------------------------------------------------------------------\r\n\r\n  /**\r\n   * Close the reader and release all native resources.\r\n   * @beta\r\n   */\r\n  public close(): void {\r\n    this._changeIndex = 0;\r\n    this._op = undefined;\r\n    this._isECTable = undefined;\r\n    this._tableName = undefined;\r\n    this._isIndirectChange = undefined;\r\n    this.inserted = undefined;\r\n    this.deleted = undefined;\r\n    this._nativeReader.close();\r\n  }\r\n\r\n  /**\r\n   * Implements the `Disposable` contract — calls [[close]].\r\n   * @beta\r\n   */\r\n  public [Symbol.dispose](): void {\r\n    this.close();\r\n  }\r\n}\r\n\r\n\r\n"]}

package/lib/esm/ChangesetReaderTypes.d.ts

@@ -0,0 +1,120 @@
+/** @packageDocumentation
+ * @module ECDb
+ */
+import { AnyDb, SqliteChangeOp, SqliteValueStage } from "./SqliteChangesetReader";
+/**
+ * Controls which properties are included in the output of [ChangesetReader]($backend).
+ * @beta
+ */
+export declare enum PropertyFilter {
+    /** All EC properties mapped to changed tables. */
+    All = 0,
+    /** For classes whose base class is `BisCore:Element`, only `BisCore:Element` properties
+     * mapped to changed tables are returned. If no `BisCore:Element` class property changed,
+     * only `ECInstanceId` and `ECClassId` are returned. For other classes all mapped properties
+     * are returned. */
+    BisCoreElement = 1,
+    /** Only `ECInstanceId` and `ECClassId`. */
+    InstanceKey = 2
+}
+/**
+ * Row-formatting options for [ChangesetReader]($backend) factory methods.
+ * Controls how EC property values are represented in the returned instances.
+ * @beta
+ */
+export interface RowFormatOptions {
+    /**
+     * When `false`, binary properties are returned as full `Uint8Array` values.
+     * When `true` (or omitted), binary properties are summarized as `{ bytes: N }`.
+     */
+    abbreviateBlobs?: boolean;
+    /**
+     * When `true`, `ECClassId` and `RelECClassId` values are converted from hex strings
+     * to fully-qualified class names (e.g. `"BisCore.DrawingModel"`).
+     */
+    classIdsToClassNames?: boolean;
+    /**
+     * When `true`, all property keys and struct sub-keys are returned in camelCase
+     * (e.g. `id`, `className`, `lastMod`). Navigation property sub-keys use
+     * `{ id, relClassName }` instead of `{ Id, RelECClassId }`.
+     */
+    useJsName?: boolean;
+}
+/**
+ * Metadata attached to every [[ChangeInstance]].
+ * @beta
+ */
+export interface ChangeMeta {
+    /** SQLite tables that contributed columns to this change row. */
+    tables: string[];
+    /** Operation that produced this change. */
+    op: SqliteChangeOp;
+    /** Whether this is the pre-change (`"Old"`) or post-change (`"New"`) snapshot. */
+    stage: SqliteValueStage;
+    /** Change-stream index positions. */
+    changeIndexes: number[];
+    /**
+     * ECInstanceId and class Id in format "<ECInstanceId>-<ECClassId>".
+     */
+    instanceKey: string;
+    /** Reader property filter that was active when this change row was captured. */
+    propFilter: PropertyFilter;
+    /** EC property names fetched from the current row of changeset or transaction or any other change stream.
+     For compound data properties like point2d, point3d or navigation properties,
+    the full name of the property is returned in case all the components of the property are fetched from the change.
+    If all of the components are not fetched from the changes(meaning they did not change),
+    then the individual component names which changed are returned smartly by using `.` as a separator (e.g. "MyPoint.X", "MyPoint.Y" for a point3d property "MyPoint" if only X and Y changed).
+    For struct properties the property names are always returned in the "StructProp.MemberName" format.
+    So if only X changed for a point2d property named "Myp2d" inide a struct "CustomStruct", the returned property name will be "CustomStruct.Myp2d.X".
+    Similaly if both X and Y changed for the same point2d property, the returned property name will be "CustomStruct.Myp2d". */
+    changeFetchedPropNames: string[];
+    /** Row adaptor options that were active when this change row was captured. */
+    rowOptions?: RowFormatOptions;
+    /** `true` when the change was applied indirectly */
+    isIndirectChange: boolean;
+}
+/**
+ * An EC instance produced by [ChangesetReader]($backend) after each `step()`.
+ * Contains the EC property bag plus mandatory `$meta` metadata.
+ * @beta
+ */
+export interface ChangeInstance {
+    /** Metadata describing the origin and identity of this change. */
+    $meta: ChangeMeta;
+    /** EC property bag (ECClassId, ECInstanceId, user-defined properties, ...). */
+    [key: string]: any;
+}
+/**
+ * Contract for any reader that produces EC-typed changed instances compatible with
+ * [PartialChangeUnifier]($backend).
+ * @beta
+ */
+export interface ChangeSource {
+    /** The SQLite opcode of the current change row. */
+    readonly op: SqliteChangeOp;
+    /**
+     * The newly-inserted or post-update EC instance.
+     * `undefined` when the current row is a Delete, or when `isECTable` is `false`.
+     */
+    readonly inserted?: ChangeInstance;
+    /**
+     * The deleted or pre-update EC instance.
+     * `undefined` when the current row is an Insert, or when `isECTable` is `false`.
+     */
+    readonly deleted?: ChangeInstance;
+}
+/**
+ * Arguments common to all [ChangesetReader]($backend) `open*` factory methods.
+ * @beta
+ */
+export interface ChangesetReaderArgs {
+    /** The db used to resolve EC schema. Must be at or ahead of the changeset being read. */
+    readonly db: AnyDb;
+    /** invert the changeset operations */
+    readonly invert?: boolean;
+    /** Row adaptor options controlling how EC property values are formatted. */
+    readonly rowOptions?: RowFormatOptions;
+    /** Controls which properties are included in the change output. Defaults to PropertyFilter.All. */
+    readonly propFilter?: PropertyFilter;
+}
+//# sourceMappingURL=ChangesetReaderTypes.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"ChangesetReaderTypes.d.ts","sourceRoot":"","sources":["../../src/ChangesetReaderTypes.ts"],"names":[],"mappings":"AAIA;;GAEG;AACH,OAAO,EAAE,KAAK,EAAE,cAAc,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAC;AAMlF;;;GAGG;AACH,oBAAY,cAAc;IACxB,kDAAkD;IAClD,GAAG,IAAI;IACP;;;uBAGmB;IACnB,cAAc,IAAI;IAClB,2CAA2C;IAC3C,WAAW,IAAI;CAChB;AAED;;;;GAIG;AACH,MAAM,WAAW,gBAAgB;IAC/B;;;OAGG;IACH,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B;;;OAGG;IACH,oBAAoB,CAAC,EAAE,OAAO,CAAC;IAC/B;;;;OAIG;IACH,SAAS,CAAC,EAAE,OAAO,CAAC;CACrB;AAMD;;;GAGG;AACH,MAAM,WAAW,UAAU;IACzB,iEAAiE;IACjE,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,2CAA2C;IAC3C,EAAE,EAAE,cAAc,CAAC;IACnB,kFAAkF;IAClF,KAAK,EAAE,gBAAgB,CAAC;IACxB,qCAAqC;IACrC,aAAa,EAAE,MAAM,EAAE,CAAC;IACxB;;OAEG;IACH,WAAW,EAAE,MAAM,CAAC;IACpB,gFAAgF;IAChF,UAAU,EAAE,cAAc,CAAC;IAC3B;;;;;;;+HAO2H;IAC3H,sBAAsB,EAAE,MAAM,EAAE,CAAC;IACjC,8EAA8E;IAC9E,UAAU,CAAC,EAAE,gBAAgB,CAAC;IAC9B,oDAAoD;IACpD,gBAAgB,EAAE,OAAO,CAAC;CAC3B;AAED;;;;GAIG;AACH,MAAM,WAAW,cAAc;IAC7B,kEAAkE;IAClE,KAAK,EAAE,UAAU,CAAC;IAClB,+EAA+E;IAC/E,CAAC,GAAG,EAAE,MAAM,GAAG,GAAG,CAAC;CACpB;AAED;;;;GAIG;AACH,MAAM,WAAW,YAAY;IAC3B,mDAAmD;IACnD,QAAQ,CAAC,EAAE,EAAE,cAAc,CAAC;IAC5B;;;OAGG;IACH,QAAQ,CAAC,QAAQ,CAAC,EAAE,cAAc,CAAC;IACnC;;;OAGG;IACH,QAAQ,CAAC,OAAO,CAAC,EAAE,cAAc,CAAC;CACnC;AAMD;;;GAGG;AACH,MAAM,WAAW,mBAAmB;IAClC,yFAAyF;IACzF,QAAQ,CAAC,EAAE,EAAE,KAAK,CAAC;IACnB,sCAAsC;IACtC,QAAQ,CAAC,MAAM,CAAC,EAAE,OAAO,CAAC;IAC1B,4EAA4E;IAC5E,QAAQ,CAAC,UAAU,CAAC,EAAE,gBAAgB,CAAC;IACvC,mGAAmG;IACnG,QAAQ,CAAC,UAAU,CAAC,EAAE,cAAc,CAAC;CACtC"}

package/lib/esm/ChangesetReaderTypes.js

@@ -0,0 +1,20 @@
+// ---------------------------------------------------------------------------
+// Type aliases
+// ---------------------------------------------------------------------------
+/**
+ * Controls which properties are included in the output of [ChangesetReader]($backend).
+ * @beta
+ */
+export var PropertyFilter;
+(function (PropertyFilter) {
+    /** All EC properties mapped to changed tables. */
+    PropertyFilter[PropertyFilter["All"] = 0] = "All";
+    /** For classes whose base class is `BisCore:Element`, only `BisCore:Element` properties
+     * mapped to changed tables are returned. If no `BisCore:Element` class property changed,
+     * only `ECInstanceId` and `ECClassId` are returned. For other classes all mapped properties
+     * are returned. */
+    PropertyFilter[PropertyFilter["BisCoreElement"] = 1] = "BisCoreElement";
+    /** Only `ECInstanceId` and `ECClassId`. */
+    PropertyFilter[PropertyFilter["InstanceKey"] = 2] = "InstanceKey";
+})(PropertyFilter || (PropertyFilter = {}));
+//# sourceMappingURL=ChangesetReaderTypes.js.map

package/lib/esm/ChangesetReaderTypes.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ChangesetReaderTypes.js","sourceRoot":"","sources":["../../src/ChangesetReaderTypes.ts"],"names":[],"mappings":"AASA,8EAA8E;AAC9E,eAAe;AACf,8EAA8E;AAE9E;;;GAGG;AACH,MAAM,CAAN,IAAY,cAUX;AAVD,WAAY,cAAc;IACxB,kDAAkD;IAClD,iDAAO,CAAA;IACP;;;uBAGmB;IACnB,uEAAkB,CAAA;IAClB,2CAA2C;IAC3C,iEAAe,CAAA;AACjB,CAAC,EAVW,cAAc,KAAd,cAAc,QAUzB","sourcesContent":["/*---------------------------------------------------------------------------------------------\r\n* Copyright (c) Bentley Systems, Incorporated. All rights reserved.\r\n* See LICENSE.md in the project root for license terms and full copyright notice.\r\n*--------------------------------------------------------------------------------------------*/\r\n/** @packageDocumentation\r\n * @module ECDb\r\n */\r\nimport { AnyDb, SqliteChangeOp, SqliteValueStage } from \"./SqliteChangesetReader\";\r\n\r\n// ---------------------------------------------------------------------------\r\n// Type aliases\r\n// ---------------------------------------------------------------------------\r\n\r\n/**\r\n * Controls which properties are included in the output of [ChangesetReader]($backend).\r\n * @beta\r\n */\r\nexport enum PropertyFilter {\r\n  /** All EC properties mapped to changed tables. */\r\n  All = 0,\r\n  /** For classes whose base class is `BisCore:Element`, only `BisCore:Element` properties\r\n   * mapped to changed tables are returned. If no `BisCore:Element` class property changed,\r\n   * only `ECInstanceId` and `ECClassId` are returned. For other classes all mapped properties\r\n   * are returned. */\r\n  BisCoreElement = 1,\r\n  /** Only `ECInstanceId` and `ECClassId`. */\r\n  InstanceKey = 2,\r\n}\r\n\r\n/**\r\n * Row-formatting options for [ChangesetReader]($backend) factory methods.\r\n * Controls how EC property values are represented in the returned instances.\r\n * @beta\r\n */\r\nexport interface RowFormatOptions {\r\n  /**\r\n   * When `false`, binary properties are returned as full `Uint8Array` values.\r\n   * When `true` (or omitted), binary properties are summarized as `{ bytes: N }`.\r\n   */\r\n  abbreviateBlobs?: boolean;\r\n  /**\r\n   * When `true`, `ECClassId` and `RelECClassId` values are converted from hex strings\r\n   * to fully-qualified class names (e.g. `\"BisCore.DrawingModel\"`).\r\n   */\r\n  classIdsToClassNames?: boolean;\r\n  /**\r\n   * When `true`, all property keys and struct sub-keys are returned in camelCase\r\n   * (e.g. `id`, `className`, `lastMod`). Navigation property sub-keys use\r\n   * `{ id, relClassName }` instead of `{ Id, RelECClassId }`.\r\n   */\r\n  useJsName?: boolean;\r\n}\r\n\r\n// ---------------------------------------------------------------------------\r\n// Public interfaces\r\n// ---------------------------------------------------------------------------\r\n\r\n/**\r\n * Metadata attached to every [[ChangeInstance]].\r\n * @beta\r\n */\r\nexport interface ChangeMeta {\r\n  /** SQLite tables that contributed columns to this change row. */\r\n  tables: string[];\r\n  /** Operation that produced this change. */\r\n  op: SqliteChangeOp;\r\n  /** Whether this is the pre-change (`\"Old\"`) or post-change (`\"New\"`) snapshot. */\r\n  stage: SqliteValueStage;\r\n  /** Change-stream index positions. */\r\n  changeIndexes: number[];\r\n  /**\r\n   * ECInstanceId and class Id in format \"<ECInstanceId>-<ECClassId>\".\r\n   */\r\n  instanceKey: string;\r\n  /** Reader property filter that was active when this change row was captured. */\r\n  propFilter: PropertyFilter;\r\n  /** EC property names fetched from the current row of changeset or transaction or any other change stream.\r\n   For compound data properties like point2d, point3d or navigation properties,\r\n  the full name of the property is returned in case all the components of the property are fetched from the change.\r\n  If all of the components are not fetched from the changes(meaning they did not change),\r\n  then the individual component names which changed are returned smartly by using `.` as a separator (e.g. \"MyPoint.X\", \"MyPoint.Y\" for a point3d property \"MyPoint\" if only X and Y changed).\r\n  For struct properties the property names are always returned in the \"StructProp.MemberName\" format.\r\n  So if only X changed for a point2d property named \"Myp2d\" inide a struct \"CustomStruct\", the returned property name will be \"CustomStruct.Myp2d.X\".\r\n  Similaly if both X and Y changed for the same point2d property, the returned property name will be \"CustomStruct.Myp2d\". */\r\n  changeFetchedPropNames: string[];\r\n  /** Row adaptor options that were active when this change row was captured. */\r\n  rowOptions?: RowFormatOptions;\r\n  /** `true` when the change was applied indirectly */\r\n  isIndirectChange: boolean;\r\n}\r\n\r\n/**\r\n * An EC instance produced by [ChangesetReader]($backend) after each `step()`.\r\n * Contains the EC property bag plus mandatory `$meta` metadata.\r\n * @beta\r\n */\r\nexport interface ChangeInstance {\r\n  /** Metadata describing the origin and identity of this change. */\r\n  $meta: ChangeMeta;\r\n  /** EC property bag (ECClassId, ECInstanceId, user-defined properties, ...). */\r\n  [key: string]: any;\r\n}\r\n\r\n/**\r\n * Contract for any reader that produces EC-typed changed instances compatible with\r\n * [PartialChangeUnifier]($backend).\r\n * @beta\r\n */\r\nexport interface ChangeSource {\r\n  /** The SQLite opcode of the current change row. */\r\n  readonly op: SqliteChangeOp;\r\n  /**\r\n   * The newly-inserted or post-update EC instance.\r\n   * `undefined` when the current row is a Delete, or when `isECTable` is `false`.\r\n   */\r\n  readonly inserted?: ChangeInstance;\r\n  /**\r\n   * The deleted or pre-update EC instance.\r\n   * `undefined` when the current row is an Insert, or when `isECTable` is `false`.\r\n   */\r\n  readonly deleted?: ChangeInstance;\r\n}\r\n\r\n// ---------------------------------------------------------------------------\r\n// ChangesetReader args / options\r\n// ---------------------------------------------------------------------------\r\n\r\n/**\r\n * Arguments common to all [ChangesetReader]($backend) `open*` factory methods.\r\n * @beta\r\n */\r\nexport interface ChangesetReaderArgs {\r\n  /** The db used to resolve EC schema. Must be at or ahead of the changeset being read. */\r\n  readonly db: AnyDb;\r\n  /** invert the changeset operations */\r\n  readonly invert?: boolean;\r\n  /** Row adaptor options controlling how EC property values are formatted. */\r\n  readonly rowOptions?: RowFormatOptions;\r\n  /** Controls which properties are included in the change output. Defaults to PropertyFilter.All. */\r\n  readonly propFilter?: PropertyFilter;\r\n}\r\n"]}

package/lib/esm/ChannelControl.js.map

@@ -1 +1 @@
-{"version":3,"file":"ChannelControl.js","sourceRoot":"","sources":["../../src/ChannelControl.ts"],"names":[],"mappings":"AAAA;;;+FAG+F;AAC/F;;GAEG;AAGH,OAAO,EAAE,yBAAyB,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AAyH/E,YAAY;AACZ,MAAM,KAAW,cAAc,CAG9B;AAHD,WAAiB,cAAc;IAC7B,wGAAwG;IAC3F,gCAAiB,GAAG,QAAQ,CAAC;AAC5C,CAAC,EAHgB,cAAc,KAAd,cAAc,QAG9B","sourcesContent":["/*---------------------------------------------------------------------------------------------\n* Copyright (c) Bentley Systems, Incorporated. All rights reserved.\n* See LICENSE.md in the project root for license terms and full copyright notice.\n*--------------------------------------------------------------------------------------------*/\n/** @packageDocumentation\n * @module Elements\n */\n\nimport { Id64String } from \"@itwin/core-bentley\";\nimport { _implementationProhibited, _verifyChannel } from \"./internal/Symbols\";\nimport { IModelDb } from \"./IModelDb\";\nimport type { EditTxn } from \"./EditTxn\";\n\n/** The key for a channel. Used for \"allowed channels\" in [[ChannelControl]]\n * @beta\n */\nexport type ChannelKey = string;\n\n/**\n * Context provided to the channel upgrade callback.\n * @beta\n */\nexport interface ChannelUpgradeContext<T = any> {\n  iModel: IModelDb;\n  channelKey: string;\n  fromVersion: string;\n  toVersion: string;\n  /** Optional data to be used during the upgrade */\n  data?: T;\n}\n\n/**\n * Options for upgrading a channel before schema import.\n * The framework will automatically populate the context with iModel and data.\n * @beta\n */\nexport interface ChannelUpgradeOptions<T = any> {\n  channelKey: string;\n  fromVersion: string;\n  toVersion: string;\n  callback: (context: ChannelUpgradeContext<T>) => Promise<void>;\n}\n\n/**\n * Controls which channels of an iModel are permitted for write operations. An implementation of this interface is\n * available via [[IModelDb.channels]].\n * @see [Working With Channels]($docs/learning/backend/Channel.md) for details\n * @beta\n */\nexport interface ChannelControl {\n  /** @internal */\n  readonly [_implementationProhibited]: unknown;\n\n  /** Add a new channel to the list of allowed channels of the [[IModelDb]] for this session.\n   * @param channelKey The key for the channel to become editable in this session.\n   */\n  addAllowedChannel(channelKey: ChannelKey): void;\n  /** Remove a channel from the list of allowed channels of the [[IModelDb]] for this session.\n   * @param channelKey The key of the channel that should no longer be editable in this session.\n   */\n  removeAllowedChannel(channelKey: ChannelKey): void;\n  /** Get the channelKey of the channel for an element by ElementId.\n   * @throws if the element does not exist\n   */\n  getChannelKey(elementId: Id64String): ChannelKey;\n  /** Make an existing element a new Channel root.\n   * @throws if the element is already in a channel different than the shared channel, or if\n   * there is already another channelRoot element for the specified channelKey\n   */\n  makeChannelRoot(args: {\n    elementId: Id64String;\n    channelKey: ChannelKey;\n    /** The transaction to use for the operation. */\n    txn: EditTxn;\n  }): void;\n  /** Make an existing element a new Channel root.\n   * @throws if the element is already in a channel different than the shared channel, or if\n   * there is already another channelRoot element for the specified channelKey\n   * @deprecated Use [[makeChannelRoot]] and supply `txn`.\n   */\n  makeChannelRoot(args: { elementId: Id64String, channelKey: ChannelKey }): void;\n  /** Insert a new Subject element that is a Channel Root in this iModel.\n   * @returns the ElementId of the new Subject element.\n   * @note if the parentSubject element is already in a channel, this will add the Subject element and then throw an error without making it a Channel root.\n   */\n  insertChannelSubject(args: {\n    /** The name of the new Subject element */\n    subjectName: string;\n    /** The channel key for the new [[Subject]]. This is the string to pass to [[addAllowedChannel]]*/\n    channelKey: ChannelKey;\n    /** the Id of the parent of the new Subject. Default is [[IModel.rootSubjectId]]. */\n    parentSubjectId?: Id64String;\n    /** Optional description for new Subject. */\n    description?: string;\n    /** The EditTxn to use for the operation. */\n    txn: EditTxn;\n  }): Id64String;\n  /** Insert a new Subject element that is a Channel Root in this iModel.\n   * @returns the ElementId of the new Subject element.\n   * @note if the parentSubject element is already in a channel, this will add the Subject element and then throw an error without making it a Channel root.\n   * @deprecated Use [[insertChannelSubject]] and supply `txn`.\n   */\n  insertChannelSubject(args: {\n    /** The name of the new Subject element */\n    subjectName: string;\n    /** The channel key for the new [[Subject]]. This is the string to pass to [[addAllowedChannel]]*/\n    channelKey: ChannelKey;\n    /** the Id of the parent of the new Subject. Default is [[IModel.rootSubjectId]]. */\n    parentSubjectId?: Id64String;\n    /** Optional description for new Subject. */\n    description?: string;\n  }): Id64String;\n  /**\n   * Queries for the element Id acting as the ChannelRoot for a given channelKey, if any\n   * @param channelKey The key for the channel to query for\n   * @returns The element Id of the ChannelRoot element of the specified Channel key, or undefined if\n   * there is no ChannelRoot for it\n   */\n  queryChannelRoot(channelKey: ChannelKey): Id64String | undefined;\n\n  /** @internal */\n  [_verifyChannel]: (modelId: Id64String) => void;\n\n  /**\n   * Upgrade a channel to a new version.\n   * @beta\n   */\n  upgradeChannel(options: ChannelUpgradeOptions, iModel: IModelDb, data?: any): Promise<void>;\n}\n\n/** @beta */\nexport namespace ChannelControl {\n  /** the name of the special \"shared\" channel holding information that is editable by any application. */\n  export const sharedChannelName = \"shared\";\n}\n\n"]}
+{"version":3,"file":"ChannelControl.js","sourceRoot":"","sources":["../../src/ChannelControl.ts"],"names":[],"mappings":"AAAA;;;+FAG+F;AAC/F;;GAEG;AAGH,OAAO,EAAE,yBAAyB,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AAyH/E,YAAY;AACZ,MAAM,KAAW,cAAc,CAG9B;AAHD,WAAiB,cAAc;IAC7B,wGAAwG;IAC3F,gCAAiB,GAAG,QAAQ,CAAC;AAC5C,CAAC,EAHgB,cAAc,KAAd,cAAc,QAG9B","sourcesContent":["/*---------------------------------------------------------------------------------------------\r\n* Copyright (c) Bentley Systems, Incorporated. All rights reserved.\r\n* See LICENSE.md in the project root for license terms and full copyright notice.\r\n*--------------------------------------------------------------------------------------------*/\r\n/** @packageDocumentation\r\n * @module Elements\r\n */\r\n\r\nimport { Id64String } from \"@itwin/core-bentley\";\r\nimport { _implementationProhibited, _verifyChannel } from \"./internal/Symbols\";\r\nimport { IModelDb } from \"./IModelDb\";\r\nimport type { EditTxn } from \"./EditTxn\";\r\n\r\n/** The key for a channel. Used for \"allowed channels\" in [[ChannelControl]]\r\n * @beta\r\n */\r\nexport type ChannelKey = string;\r\n\r\n/**\r\n * Context provided to the channel upgrade callback.\r\n * @beta\r\n */\r\nexport interface ChannelUpgradeContext<T = any> {\r\n  iModel: IModelDb;\r\n  channelKey: string;\r\n  fromVersion: string;\r\n  toVersion: string;\r\n  /** Optional data to be used during the upgrade */\r\n  data?: T;\r\n}\r\n\r\n/**\r\n * Options for upgrading a channel before schema import.\r\n * The framework will automatically populate the context with iModel and data.\r\n * @beta\r\n */\r\nexport interface ChannelUpgradeOptions<T = any> {\r\n  channelKey: string;\r\n  fromVersion: string;\r\n  toVersion: string;\r\n  callback: (context: ChannelUpgradeContext<T>) => Promise<void>;\r\n}\r\n\r\n/**\r\n * Controls which channels of an iModel are permitted for write operations. An implementation of this interface is\r\n * available via [[IModelDb.channels]].\r\n * @see [Working With Channels]($docs/learning/backend/Channel.md) for details\r\n * @beta\r\n */\r\nexport interface ChannelControl {\r\n  /** @internal */\r\n  readonly [_implementationProhibited]: unknown;\r\n\r\n  /** Add a new channel to the list of allowed channels of the [[IModelDb]] for this session.\r\n   * @param channelKey The key for the channel to become editable in this session.\r\n   */\r\n  addAllowedChannel(channelKey: ChannelKey): void;\r\n  /** Remove a channel from the list of allowed channels of the [[IModelDb]] for this session.\r\n   * @param channelKey The key of the channel that should no longer be editable in this session.\r\n   */\r\n  removeAllowedChannel(channelKey: ChannelKey): void;\r\n  /** Get the channelKey of the channel for an element by ElementId.\r\n   * @throws if the element does not exist\r\n   */\r\n  getChannelKey(elementId: Id64String): ChannelKey;\r\n  /** Make an existing element a new Channel root.\r\n   * @throws if the element is already in a channel different than the shared channel, or if\r\n   * there is already another channelRoot element for the specified channelKey\r\n   */\r\n  makeChannelRoot(args: {\r\n    elementId: Id64String;\r\n    channelKey: ChannelKey;\r\n    /** The transaction to use for the operation. */\r\n    txn: EditTxn;\r\n  }): void;\r\n  /** Make an existing element a new Channel root.\r\n   * @throws if the element is already in a channel different than the shared channel, or if\r\n   * there is already another channelRoot element for the specified channelKey\r\n   * @deprecated Use [[makeChannelRoot]] and supply `txn`.\r\n   */\r\n  makeChannelRoot(args: { elementId: Id64String, channelKey: ChannelKey }): void;\r\n  /** Insert a new Subject element that is a Channel Root in this iModel.\r\n   * @returns the ElementId of the new Subject element.\r\n   * @note if the parentSubject element is already in a channel, this will add the Subject element and then throw an error without making it a Channel root.\r\n   */\r\n  insertChannelSubject(args: {\r\n    /** The name of the new Subject element */\r\n    subjectName: string;\r\n    /** The channel key for the new [[Subject]]. This is the string to pass to [[addAllowedChannel]]*/\r\n    channelKey: ChannelKey;\r\n    /** the Id of the parent of the new Subject. Default is [[IModel.rootSubjectId]]. */\r\n    parentSubjectId?: Id64String;\r\n    /** Optional description for new Subject. */\r\n    description?: string;\r\n    /** The EditTxn to use for the operation. */\r\n    txn: EditTxn;\r\n  }): Id64String;\r\n  /** Insert a new Subject element that is a Channel Root in this iModel.\r\n   * @returns the ElementId of the new Subject element.\r\n   * @note if the parentSubject element is already in a channel, this will add the Subject element and then throw an error without making it a Channel root.\r\n   * @deprecated Use [[insertChannelSubject]] and supply `txn`.\r\n   */\r\n  insertChannelSubject(args: {\r\n    /** The name of the new Subject element */\r\n    subjectName: string;\r\n    /** The channel key for the new [[Subject]]. This is the string to pass to [[addAllowedChannel]]*/\r\n    channelKey: ChannelKey;\r\n    /** the Id of the parent of the new Subject. Default is [[IModel.rootSubjectId]]. */\r\n    parentSubjectId?: Id64String;\r\n    /** Optional description for new Subject. */\r\n    description?: string;\r\n  }): Id64String;\r\n  /**\r\n   * Queries for the element Id acting as the ChannelRoot for a given channelKey, if any\r\n   * @param channelKey The key for the channel to query for\r\n   * @returns The element Id of the ChannelRoot element of the specified Channel key, or undefined if\r\n   * there is no ChannelRoot for it\r\n   */\r\n  queryChannelRoot(channelKey: ChannelKey): Id64String | undefined;\r\n\r\n  /** @internal */\r\n  [_verifyChannel]: (modelId: Id64String) => void;\r\n\r\n  /**\r\n   * Upgrade a channel to a new version.\r\n   * @beta\r\n   */\r\n  upgradeChannel(options: ChannelUpgradeOptions, iModel: IModelDb, data?: any): Promise<void>;\r\n}\r\n\r\n/** @beta */\r\nexport namespace ChannelControl {\r\n  /** the name of the special \"shared\" channel holding information that is editable by any application. */\r\n  export const sharedChannelName = \"shared\";\r\n}\r\n\r\n"]}