@itwin/core-backend 5.8.2 → 5.9.0-dev.10

package/lib/cjs/workspace/SettingsDb.d.ts

@@ -1,109 +1,30 @@
 /** @packageDocumentation
  * @module Workspace
  */
-import { Setting, SettingName, SettingsContainer, SettingsPriority } from "./Settings";
-import { CloudSqliteContainer, WorkspaceContainerId, WorkspaceDbName } from "./Workspace";
-import { _implementationProhibited } from "../internal/Symbols";
-/** Metadata stored inside a [[SettingsDb]] describing the database's contents, to help users understand
- * the purpose of the [[SettingsDb]] and who to contact with questions about it.
- * @note Only the `settingsName` field is required, and users may add additional fields for their own purposes.
- * @note Since the information is stored inside the [[SettingsDb]], it is versioned along with the rest of the contents.
- * @beta
+import type { WorkspaceDb, WorkspaceDbName } from "./Workspace";
+/**
+ * The fixed db name used by [[WorkspaceDb]]'s meant to hold settings.
+ * [[Workspace.loadSettingsDictionary]] will treat rows in the 'strings' table as setting dictionary entries when [[WorkspaceDbSettingsProps.dbName]] matches this value.
+ * @see [[Workspace.loadSettingsDictionary]]
+ * @internal
  */
-export interface SettingsDbManifest {
-    /** The name of the [[SettingsDb]] to be shown in user interfaces. Organizations should attempt to make this name
-     * informative enough so that users may refer to it in conversations.
-     */
-    readonly settingsName: string;
-    /** A description of the contents of this [[SettingsDb]] to help users understand its purpose and appropriate usage. */
-    readonly description?: string;
-    /** The name of the person to contact with questions about this [[SettingsDb]]. */
-    readonly contactName?: string;
-    /** The name of the person who last modified this [[SettingsDb]]. */
-    readonly lastEditedBy?: string;
-}
-/** Properties that specify how to load a [[SettingsDb]] within a [[CloudSqliteContainer]].
- * @beta
+export declare const settingsWorkspaceDbName: WorkspaceDbName;
+/** The db name type for the iTwin settings [[WorkspaceDb]].
+ * @internal
  */
-export interface SettingsDbProps {
-    /** The base name of the [[SettingsDb]], without any version information. Default: `"settings-db"`. */
-    readonly dbName?: WorkspaceDbName;
-    /** The [semver](https://github.com/npm/node-semver) version string or range for the desired [[SettingsDb]].
-     * If not specified, the latest available version is used.
-     */
-    readonly version?: string;
-}
-/** Arguments for obtaining a [[SettingsDb]] from a previously-loaded container.
- * @beta
+export type SettingsDbName = typeof settingsWorkspaceDbName;
+/** A [[WorkspaceDb]] whose name is the fixed iTwin settings db name.
+ * @internal
  */
-export interface GetSettingsDbArgs {
-    /** The [[WorkspaceContainerId]] of the cloud container that holds the [[SettingsDb]].
-     * This is an opaque GUID assigned by the BlobContainer service when the container is created — it is
-     * **not** the same as an iTwinId or iModelId.
-     */
-    readonly containerId: WorkspaceContainerId;
-    /** The priority to assign to dictionaries loaded from this [[SettingsDb]]. */
-    readonly priority: SettingsPriority;
-    /** The name of the [[SettingsDb]] to retrieve. Default: `"settings-db"`. */
-    readonly dbName?: WorkspaceDbName;
-    /** The semantic version string or range for the desired [[SettingsDb]].
-     * If not specified, the latest available version is used.
-     */
-    readonly version?: string;
-}
-/** A CloudSQLite database dedicated to storing settings as key-value pairs. Unlike a general-purpose [[WorkspaceDb]],
- * a `SettingsDb` restricts its API surface to settings-only operations, providing a focused interface
- * for reading settings by name.
- *
- * Internally, all settings are stored in a single JSON blob. Each setting is a named entry in a [[SettingsContainer]].
- *
- * A `SettingsDb` resides in a [[CloudSqliteContainer]] and can be published to the cloud. Once published,
- * the `SettingsDb` becomes immutable; however, multiple versions may be created to allow settings to evolve over time.
- * @beta
+export type SettingsDb = WorkspaceDb & {
+    readonly dbName: SettingsDbName;
+};
+/** Return true if a [[WorkspaceDb]] is a [[SettingsDb]].
+ * @internal
  */
-export interface SettingsDb {
-    /** @internal */
-    [_implementationProhibited]: unknown;
-    /** The [[CloudSqliteContainer]] in which this database resides. */
-    readonly container: CloudSqliteContainer;
-    /** The base name of this SettingsDb, without version. */
-    readonly dbName: string;
-    /** The resolved [semver](https://github.com/npm/node-semver) version of this SettingsDb.
-     * @note For local (non-cloud) containers, this property returns `"0.0.0"`.
-     */
-    readonly version: string;
-    /** The priority assigned to dictionaries loaded from this SettingsDb. */
-    readonly priority: SettingsPriority;
-    /** Whether the underlying database is currently open. */
-    readonly isOpen: boolean;
-    /** The manifest describing the contents of this SettingsDb. */
-    readonly manifest: SettingsDbManifest;
-    /** Open the underlying database for querying. When performing significant activity against a SettingsDb,
-     * open it before the operations and [[close]] it afterwards.
-     * @note Explicit open/close is a performance optimization for batches of operations. Individual methods like
-     * [[getSetting]] and [[getSettings]] will auto-open and auto-close the database if it is not already open.
-     */
-    open(): void;
-    /** Close the underlying database. You should call this after [[open]]ing the database and completing your queries.
-     * @note For [[EditableSettingsDb]] instances, if the container's write lock is currently held, closing persists
-     * any pending changes and updates the manifest's `lastEditedBy` field with the current write lock holder.
-     */
-    close(): void;
-    /** Return a copy of the value of the setting named `settingName`, or `undefined` if not found.
-     * The returned value is always cloned using [[Setting.clone]].
-     * @param settingName The name of the setting to retrieve.
-     */
-    getSetting<T extends Setting>(settingName: SettingName): T | undefined;
-    /** Return a deep copy of all settings stored in this SettingsDb as a [[SettingsContainer]].
-     * @note The returned object is a fresh copy — mutating it will not affect the stored settings.
-     */
-    getSettings(): SettingsContainer;
-}
-/** The default resource name used to store settings in a [[SettingsDb]].
- * This is the key under which all settings are stored in the SQLite `strings` table.
- * When loading settings at runtime via [[Workspace.loadSettingsDictionary]], the `resourceName` defaults
- * to this value, ensuring the read and write paths always agree on which key to use.
+export declare function isSettingsDb(db: WorkspaceDb): db is SettingsDb;
+/** Query all string resource names from a [[SettingsDb]].
  * @internal
  */
-export declare const settingsResourceName = "settings";
+export declare function queryStringResourceNames(db: SettingsDb): WorkspaceDbName[];
 //# sourceMappingURL=SettingsDb.d.ts.map

package/lib/cjs/workspace/SettingsDb.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"SettingsDb.d.ts","sourceRoot":"","sources":["../../../src/workspace/SettingsDb.ts"],"names":[],"mappings":"AAIA;;GAEG;AAEH,OAAO,EAAE,OAAO,EAAE,WAAW,EAAE,iBAAiB,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AACvF,OAAO,EAAE,oBAAoB,EAAE,oBAAoB,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAC1F,OAAO,EAAE,yBAAyB,EAAE,MAAM,qBAAqB,CAAC;AAEhE;;;;;GAKG;AACH,MAAM,WAAW,kBAAkB;IACjC;;OAEG;IACH,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,uHAAuH;IACvH,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,kFAAkF;IAClF,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,oEAAoE;IACpE,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;CAChC;AAED;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,sGAAsG;IACtG,QAAQ,CAAC,MAAM,CAAC,EAAE,eAAe,CAAC;IAClC;;OAEG;IACH,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;CAC3B;AAED;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC;;;OAGG;IACH,QAAQ,CAAC,WAAW,EAAE,oBAAoB,CAAC;IAC3C,8EAA8E;IAC9E,QAAQ,CAAC,QAAQ,EAAE,gBAAgB,CAAC;IACpC,4EAA4E;IAC5E,QAAQ,CAAC,MAAM,CAAC,EAAE,eAAe,CAAC;IAClC;;OAEG;IACH,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;CAC3B;AAED;;;;;;;;;GASG;AACH,MAAM,WAAW,UAAU;IACzB,gBAAgB;IAChB,CAAC,yBAAyB,CAAC,EAAE,OAAO,CAAC;IACrC,mEAAmE;IACnE,QAAQ,CAAC,SAAS,EAAE,oBAAoB,CAAC;IACzC,yDAAyD;IACzD,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB;;OAEG;IACH,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,yEAAyE;IACzE,QAAQ,CAAC,QAAQ,EAAE,gBAAgB,CAAC;IACpC,yDAAyD;IACzD,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;IACzB,+DAA+D;IAC/D,QAAQ,CAAC,QAAQ,EAAE,kBAAkB,CAAC;IAEtC;;;;OAIG;IACH,IAAI,IAAI,IAAI,CAAC;IAEb;;;OAGG;IACH,KAAK,IAAI,IAAI,CAAC;IAEd;;;OAGG;IACH,UAAU,CAAC,CAAC,SAAS,OAAO,EAAE,WAAW,EAAE,WAAW,GAAG,CAAC,GAAG,SAAS,CAAC;IAEvE;;OAEG;IACH,WAAW,IAAI,iBAAiB,CAAC;CAClC;AAED;;;;;GAKG;AACH,eAAO,MAAM,oBAAoB,aAAa,CAAC"}
+{"version":3,"file":"SettingsDb.d.ts","sourceRoot":"","sources":["../../../src/workspace/SettingsDb.ts"],"names":[],"mappings":"AAIA;;GAEG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAEhE;;;;;GAKG;AACH,eAAO,MAAM,uBAAuB,EAAE,eAA+B,CAAC;AAEtE;;GAEG;AACH,MAAM,MAAM,cAAc,GAAG,OAAO,uBAAuB,CAAC;AAE5D;;GAEG;AACH,MAAM,MAAM,UAAU,GAAG,WAAW,GAAG;IAAE,QAAQ,CAAC,MAAM,EAAE,cAAc,CAAA;CAAE,CAAC;AAE3E;;GAEG;AACH,wBAAgB,YAAY,CAAC,EAAE,EAAE,WAAW,GAAG,EAAE,IAAI,UAAU,CAE9D;AAED;;GAEG;AACH,wBAAgB,wBAAwB,CAAC,EAAE,EAAE,UAAU,GAAG,eAAe,EAAE,CAI1E"}

package/lib/cjs/workspace/SettingsDb.js

@@ -7,13 +7,29 @@
  * @module Workspace
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.settingsResourceName = void 0;
-const Symbols_1 = require("../internal/Symbols");
-/** The default resource name used to store settings in a [[SettingsDb]].
- * This is the key under which all settings are stored in the SQLite `strings` table.
- * When loading settings at runtime via [[Workspace.loadSettingsDictionary]], the `resourceName` defaults
- * to this value, ensuring the read and write paths always agree on which key to use.
+exports.settingsWorkspaceDbName = void 0;
+exports.isSettingsDb = isSettingsDb;
+exports.queryStringResourceNames = queryStringResourceNames;
+/**
+ * The fixed db name used by [[WorkspaceDb]]'s meant to hold settings.
+ * [[Workspace.loadSettingsDictionary]] will treat rows in the 'strings' table as setting dictionary entries when [[WorkspaceDbSettingsProps.dbName]] matches this value.
+ * @see [[Workspace.loadSettingsDictionary]]
  * @internal
  */
-exports.settingsResourceName = "settings";
+exports.settingsWorkspaceDbName = "settings-db";
+/** Return true if a [[WorkspaceDb]] is a [[SettingsDb]].
+ * @internal
+ */
+function isSettingsDb(db) {
+    return db.dbName === exports.settingsWorkspaceDbName;
+}
+/** Query all string resource names from a [[SettingsDb]].
+ * @internal
+ */
+function queryStringResourceNames(db) {
+    const resourceNames = [];
+    db.queryResources({ type: "string", callback: (names) => { for (const n of names)
+            resourceNames.push(n); } });
+    return resourceNames;
+}
 //# sourceMappingURL=SettingsDb.js.map

package/lib/cjs/workspace/SettingsDb.js.map

@@ -1 +1 @@
-{"version":3,"file":"SettingsDb.js","sourceRoot":"","sources":["../../../src/workspace/SettingsDb.ts"],"names":[],"mappings":";AAAA;;;+FAG+F;AAC/F;;GAEG;;;AAIH,iDAAgE;AAyGhE;;;;;GAKG;AACU,QAAA,oBAAoB,GAAG,UAAU,CAAC","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 Workspace\r\n */\r\n\r\nimport { Setting, SettingName, SettingsContainer, SettingsPriority } from \"./Settings\";\r\nimport { CloudSqliteContainer, WorkspaceContainerId, WorkspaceDbName } from \"./Workspace\";\r\nimport { _implementationProhibited } from \"../internal/Symbols\";\r\n\r\n/** Metadata stored inside a [[SettingsDb]] describing the database's contents, to help users understand\r\n * the purpose of the [[SettingsDb]] and who to contact with questions about it.\r\n * @note Only the `settingsName` field is required, and users may add additional fields for their own purposes.\r\n * @note Since the information is stored inside the [[SettingsDb]], it is versioned along with the rest of the contents.\r\n * @beta\r\n */\r\nexport interface SettingsDbManifest {\r\n  /** The name of the [[SettingsDb]] to be shown in user interfaces. Organizations should attempt to make this name\r\n   * informative enough so that users may refer to it in conversations.\r\n   */\r\n  readonly settingsName: string;\r\n  /** A description of the contents of this [[SettingsDb]] to help users understand its purpose and appropriate usage. */\r\n  readonly description?: string;\r\n  /** The name of the person to contact with questions about this [[SettingsDb]]. */\r\n  readonly contactName?: string;\r\n  /** The name of the person who last modified this [[SettingsDb]]. */\r\n  readonly lastEditedBy?: string;\r\n}\r\n\r\n/** Properties that specify how to load a [[SettingsDb]] within a [[CloudSqliteContainer]].\r\n * @beta\r\n */\r\nexport interface SettingsDbProps {\r\n  /** The base name of the [[SettingsDb]], without any version information. Default: `\"settings-db\"`. */\r\n  readonly dbName?: WorkspaceDbName;\r\n  /** The [semver](https://github.com/npm/node-semver) version string or range for the desired [[SettingsDb]].\r\n   * If not specified, the latest available version is used.\r\n   */\r\n  readonly version?: string;\r\n}\r\n\r\n/** Arguments for obtaining a [[SettingsDb]] from a previously-loaded container.\r\n * @beta\r\n */\r\nexport interface GetSettingsDbArgs {\r\n  /** The [[WorkspaceContainerId]] of the cloud container that holds the [[SettingsDb]].\r\n   * This is an opaque GUID assigned by the BlobContainer service when the container is created — it is\r\n   * **not** the same as an iTwinId or iModelId.\r\n   */\r\n  readonly containerId: WorkspaceContainerId;\r\n  /** The priority to assign to dictionaries loaded from this [[SettingsDb]]. */\r\n  readonly priority: SettingsPriority;\r\n  /** The name of the [[SettingsDb]] to retrieve. Default: `\"settings-db\"`. */\r\n  readonly dbName?: WorkspaceDbName;\r\n  /** The semantic version string or range for the desired [[SettingsDb]].\r\n   * If not specified, the latest available version is used.\r\n   */\r\n  readonly version?: string;\r\n}\r\n\r\n/** A CloudSQLite database dedicated to storing settings as key-value pairs. Unlike a general-purpose [[WorkspaceDb]],\r\n * a `SettingsDb` restricts its API surface to settings-only operations, providing a focused interface\r\n * for reading settings by name.\r\n *\r\n * Internally, all settings are stored in a single JSON blob. Each setting is a named entry in a [[SettingsContainer]].\r\n *\r\n * A `SettingsDb` resides in a [[CloudSqliteContainer]] and can be published to the cloud. Once published,\r\n * the `SettingsDb` becomes immutable; however, multiple versions may be created to allow settings to evolve over time.\r\n * @beta\r\n */\r\nexport interface SettingsDb {\r\n  /** @internal */\r\n  [_implementationProhibited]: unknown;\r\n  /** The [[CloudSqliteContainer]] in which this database resides. */\r\n  readonly container: CloudSqliteContainer;\r\n  /** The base name of this SettingsDb, without version. */\r\n  readonly dbName: string;\r\n  /** The resolved [semver](https://github.com/npm/node-semver) version of this SettingsDb.\r\n   * @note For local (non-cloud) containers, this property returns `\"0.0.0\"`.\r\n   */\r\n  readonly version: string;\r\n  /** The priority assigned to dictionaries loaded from this SettingsDb. */\r\n  readonly priority: SettingsPriority;\r\n  /** Whether the underlying database is currently open. */\r\n  readonly isOpen: boolean;\r\n  /** The manifest describing the contents of this SettingsDb. */\r\n  readonly manifest: SettingsDbManifest;\r\n\r\n  /** Open the underlying database for querying. When performing significant activity against a SettingsDb,\r\n   * open it before the operations and [[close]] it afterwards.\r\n   * @note Explicit open/close is a performance optimization for batches of operations. Individual methods like\r\n   * [[getSetting]] and [[getSettings]] will auto-open and auto-close the database if it is not already open.\r\n   */\r\n  open(): void;\r\n\r\n  /** Close the underlying database. You should call this after [[open]]ing the database and completing your queries.\r\n   * @note For [[EditableSettingsDb]] instances, if the container's write lock is currently held, closing persists\r\n   * any pending changes and updates the manifest's `lastEditedBy` field with the current write lock holder.\r\n   */\r\n  close(): void;\r\n\r\n  /** Return a copy of the value of the setting named `settingName`, or `undefined` if not found.\r\n   * The returned value is always cloned using [[Setting.clone]].\r\n   * @param settingName The name of the setting to retrieve.\r\n   */\r\n  getSetting<T extends Setting>(settingName: SettingName): T | undefined;\r\n\r\n  /** Return a deep copy of all settings stored in this SettingsDb as a [[SettingsContainer]].\r\n   * @note The returned object is a fresh copy — mutating it will not affect the stored settings.\r\n   */\r\n  getSettings(): SettingsContainer;\r\n}\r\n\r\n/** The default resource name used to store settings in a [[SettingsDb]].\r\n * This is the key under which all settings are stored in the SQLite `strings` table.\r\n * When loading settings at runtime via [[Workspace.loadSettingsDictionary]], the `resourceName` defaults\r\n * to this value, ensuring the read and write paths always agree on which key to use.\r\n * @internal\r\n */\r\nexport const settingsResourceName = \"settings\";\r\n"]}
+{"version":3,"file":"SettingsDb.js","sourceRoot":"","sources":["../../../src/workspace/SettingsDb.ts"],"names":[],"mappings":";AAAA;;;+FAG+F;AAC/F;;GAEG;;;AAyBH,oCAEC;AAKD,4DAIC;AAhCD;;;;;GAKG;AACU,QAAA,uBAAuB,GAAoB,aAAa,CAAC;AAYtE;;GAEG;AACH,SAAgB,YAAY,CAAC,EAAe;IAC1C,OAAO,EAAE,CAAC,MAAM,KAAK,+BAAuB,CAAC;AAC/C,CAAC;AAED;;GAEG;AACH,SAAgB,wBAAwB,CAAC,EAAc;IACrD,MAAM,aAAa,GAAa,EAAE,CAAC;IACnC,EAAE,CAAC,cAAc,CAAC,EAAE,IAAI,EAAE,QAAQ,EAAE,QAAQ,EAAE,CAAC,KAAK,EAAE,EAAE,GAAG,KAAK,MAAM,CAAC,IAAI,KAAK;YAAE,aAAa,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;IAC9G,OAAO,aAAa,CAAC;AACvB,CAAC","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 Workspace\n */\n\nimport type { WorkspaceDb, WorkspaceDbName } from \"./Workspace\";\n\n/**\n * The fixed db name used by [[WorkspaceDb]]'s meant to hold settings.\n * [[Workspace.loadSettingsDictionary]] will treat rows in the 'strings' table as setting dictionary entries when [[WorkspaceDbSettingsProps.dbName]] matches this value.\n * @see [[Workspace.loadSettingsDictionary]]\n * @internal\n */\nexport const settingsWorkspaceDbName: WorkspaceDbName = \"settings-db\";\n\n/** The db name type for the iTwin settings [[WorkspaceDb]].\n * @internal\n */\nexport type SettingsDbName = typeof settingsWorkspaceDbName;\n\n/** A [[WorkspaceDb]] whose name is the fixed iTwin settings db name.\n * @internal\n */\nexport type SettingsDb = WorkspaceDb & { readonly dbName: SettingsDbName };\n\n/** Return true if a [[WorkspaceDb]] is a [[SettingsDb]].\n * @internal\n */\nexport function isSettingsDb(db: WorkspaceDb): db is SettingsDb {\n  return db.dbName === settingsWorkspaceDbName;\n}\n\n/** Query all string resource names from a [[SettingsDb]].\n * @internal\n */\nexport function queryStringResourceNames(db: SettingsDb): WorkspaceDbName[] {\n  const resourceNames: string[] = [];\n  db.queryResources({ type: \"string\", callback: (names) => { for (const n of names) resourceNames.push(n); } });\n  return resourceNames;\n}\n"]}

package/lib/cjs/workspace/SettingsEditor.d.ts

@@ -1,250 +1,64 @@
 /** @packageDocumentation
  * @module Workspace
  */
-import { LocalFileName } from "@itwin/core-common";
 import { GuidString } from "@itwin/core-bentley";
-import { Setting, SettingName, SettingsContainer } from "./Settings";
-import { BlobContainer } from "../BlobContainerService";
-import { CloudSqliteContainer, GetWorkspaceContainerArgs, Workspace, WorkspaceContainerProps, WorkspaceDbName, WorkspaceDbNameAndVersion, WorkspaceDbVersion } from "./Workspace";
-import { SettingsDb, SettingsDbManifest, SettingsDbProps } from "./SettingsDb";
-import { _implementationProhibited } from "../internal/Symbols";
-import { CloudSqlite } from "../CloudSqlite";
-/** @beta */
+import { WorkspaceContainerId, WorkspaceDbSettingsProps } from "./Workspace";
+import { EditableWorkspaceContainer, WorkspaceEditor } from "./WorkspaceEditor";
+/** The default resource name used to store settings in a [[WorkspaceDb]].
+ * This is the key under which all settings are stored in the SQLite `strings` table.
+ * When loading settings at runtime via [[Workspace.loadSettingsDictionary]], the `resourceName` defaults
+ * to this value, ensuring the read and write paths always agree on which key to use.
+ * @internal
+ */
+export declare const settingsResourceName = "settingsDictionary";
+/** @internal */
 export declare namespace SettingsEditor {
+    /** The type of workspace container used to store settings. */
+    const containerType = "settings";
     /**
      * Create a new [[SettingsEditor]] for creating new versions of [[SettingsDb]]s.
      * @note The caller becomes the owner of the SettingsEditor and is responsible for calling [[SettingsEditor.close]] on it when finished.
      * @note It is illegal to have more than one SettingsEditor active in a single session.
      */
-    function construct(): SettingsEditor;
+    function constructForITwin(iTwinId: GuidString): Promise<{
+        editor: WorkspaceEditor;
+        container: EditableWorkspaceContainer;
+    }>;
     /**
-     * Create a new, empty, [[SettingsDb]] file on the local filesystem for importing settings dictionaries.
-     * @note Do not pass an untrusted or unintended path in `localFileName`.
-     * This helper creates or overwrites the file at that location; callers that need fail-if-exists behavior should check first.
+     * Obtain a [[SettingsEditor]] for the existing settings container associated with an iTwin.
+     * @returns The editor and container, or `undefined` if no settings container exists for the iTwin.
+     * @note The caller becomes the owner of the SettingsEditor and is responsible for calling [[SettingsEditor.close]] on it when finished.
+     * @note It is illegal to have more than one SettingsEditor active in a single session.
      */
-    function createEmptyDb(args: {
-        localFileName: LocalFileName;
-        manifest: SettingsDbManifest;
-    }): void;
-    /** Arguments for [[SettingsEditor.queryContainers]] and [[SettingsEditor.findContainers]]. */
-    interface QuerySettingsContainersArgs {
+    function getForITwin(iTwinId: GuidString): Promise<{
+        editor: WorkspaceEditor;
+        container: EditableWorkspaceContainer;
+    } | undefined>;
+}
+/**
+ * Help locate and obtain access to known containers with type "settings".
+ * @internal
+ */
+export declare namespace SettingsContainers {
+    /** Arguments for [[SettingsContainers.queryContainers]]. */
+    interface QueryArgs {
         /** The iTwinId whose settings containers should be queried. */
         iTwinId: GuidString;
-        /** Optional iModelId to further scope the query to containers associated with a specific iModel. */
-        iModelId?: GuidString;
         /** Optional label filter. */
         label?: string;
     }
     /**
-     * Query the [[BlobContainer]] service for all settings containers associated with a given iTwin.
-     * This is a convenience wrapper around `BlobContainer.service.queryContainersMetadata` that
-     * automatically filters by `containerType: "settings"`.
-     * @param args - The query arguments including the iTwinId.
-     * @returns A promise that resolves to the matching container metadata entries.
-     * @note Requires [[IModelHost.authorizationClient]] to be configured.
-     */
-    function queryContainers(args: QuerySettingsContainersArgs): Promise<BlobContainer.MetadataResponse[]>;
-}
-/** Arguments supplied to [[SettingsEditor.createNewCloudContainer]] to create a new [[EditableSettingsCloudContainer]].
- * The created container will automatically have `containerType: "settings"` in its metadata, enabling discovery
- * via `BlobContainer.service.queryContainersMetadata({ containerType: "settings" })`.
- * @beta
- */
-export interface CreateNewSettingsContainerArgs {
-    /**
-     * The scope of the container. This determines the ownership of the container, how RBAC rights are assigned,
-     * and the location of the datacenter.
-     */
-    scope: BlobContainer.Scope;
-    /** The manifest to be stored in the default SettingsDb in the new container. */
-    manifest: SettingsDbManifest;
-    /** Metadata stored by the BlobContainer service. The `containerType` field is omitted here because it is
-     * automatically set to `"settings"` when the container is created (mirroring the `"workspace"` convention for WorkspaceDb containers).
-     */
-    metadata: Omit<BlobContainer.Metadata, "containerType">;
-    /** The name of the default [[SettingsDb]] created inside the new container.
-     * Default: "settings-db";
-     */
-    dbName?: WorkspaceDbName;
-}
-/** Arguments supplied to [[EditableSettingsCloudContainer.createNewSettingsDbVersion]].
- * @beta
- */
-export interface CreateNewSettingsDbVersionArgs {
-    /**
-     * The properties that determine the source [[SettingsDb]] to serve as the basis for the new version.
-     * This is usually the latest version, but it is possible to create patches to older versions.
-     */
-    fromProps?: SettingsDbProps;
-    /** The type of version increment to apply to the source version. */
-    versionType: CloudSqlite.SemverIncrement;
-    /** For prerelease versions, a string that becomes part of the version name. */
-    identifier?: string;
-}
-/** The result of creating a new version of a [[SettingsDb]].
- * @beta
- */
-export interface SettingsDbVersionResult {
-    /** The name and version of the source SettingsDb. */
-    oldDb: WorkspaceDbNameAndVersion;
-    /** The name and version of the newly-created SettingsDb. */
-    newDb: WorkspaceDbNameAndVersion;
-}
-/** Arguments supplied to [[EditableSettingsCloudContainer.createDb]] to create a new [[SettingsDb]] in a container.
- * @beta
- */
-export interface CreateSettingsDbArgs {
-    /** The name of the new SettingsDb. Default: `"settings-db"`. */
-    dbName?: WorkspaceDbName;
-    /** The initial version of the new SettingsDb. Default: `"0.0.0"`. */
-    version?: WorkspaceDbVersion;
-    /** The manifest for the new SettingsDb. */
-    manifest: SettingsDbManifest;
-}
-/** Arguments supplied to [[EditableSettingsDb.updateSetting]] to add or update a single [[Setting]].
- * @beta
- */
-export interface UpdateSettingArgs {
-    /** The [[SettingName]] of the setting to add or update. */
-    readonly settingName: SettingName;
-    /** The new value for the setting. */
-    readonly value: Setting;
-}
-/**
- * A [[CloudSqliteContainer]] opened for editing settings by a [[SettingsEditor]].
- * You can create new [[SettingsDb]]s or new versions of existing [[SettingsDb]]s inside it.
- * Before actually making any changes to the container's contents, you must first obtain an exclusive write lock on it via
- * [[acquireWriteLock]]. Only one user can hold the write lock at any given time. When you have finished making changes,
- * you can use [[releaseWriteLock]] to publish your changes, or [[abandonChanges]] to discard them.
- * @note Settings containers are separate from workspace containers, providing independent write locks.
- * Editing settings does not block workspace resource editing, and vice versa.
- * @beta
- */
-export interface EditableSettingsCloudContainer extends CloudSqliteContainer {
-    /**
-     * Create a copy of an existing [[SettingsDb]] in this container with a new [[WorkspaceDbVersion]].
-     * The copy should be modified with new content before the write lock is released,
-     * and thereafter may never be modified again.
-     * @param args - The properties that determine the source SettingsDb and the version increment to apply.
-     * @returns A promise that resolves to an object containing the old and new SettingsDb names and versions.
-     */
-    createNewSettingsDbVersion(args: CreateNewSettingsDbVersionArgs): Promise<SettingsDbVersionResult>;
-    /**
-     * Create a new, empty [[SettingsDb]].
-     * @param args - The arguments for creating the new SettingsDb.
-     * @returns A promise that resolves to an EditableSettingsDb.
-     */
-    createDb(args: CreateSettingsDbArgs): Promise<EditableSettingsDb>;
-    /**
-     * Get the cloud properties of this container.
+     * Query the [[BlobContainer]] service for the single settings container associated with a given iTwin.
+     * @returns The containerId, or `undefined` if no container exists.
+     * @throws if more than one settings container is found.
      */
-    readonly cloudProps: WorkspaceContainerProps | undefined;
+    function getITwinContainerId(iTwinId: GuidString): Promise<WorkspaceContainerId | undefined>;
     /**
-     * Get an editable [[SettingsDb]] to add, delete, or update settings *within a newly created version* of a SettingsDb.
-     * Repeated calls that resolve to the same SettingsDb return the same cached instance.
-     * @param props - The properties of the SettingsDb.
-     * @returns An EditableSettingsDb for modifying settings.
-     * @throws if the targeted SettingsDb has already been published and is immutable. Use [[createNewSettingsDbVersion]] first to create an editable version.
-     */
-    getEditableDb(props?: SettingsDbProps): EditableSettingsDb;
-    /**
-     * Acquire the write lock on the container. Use [[releaseWriteLock]] to release the lock after publishing your changes, or
-     * [[abandonChanges]] to release the lock and discard your changes.
-     * Only one user can hold the write lock at any given time. However, readers can continue to read the published contents of the container while
-     * a writer holds the write lock. Readers will only see the writer's changes after they are published by [[releaseWriteLock]].
-     * @param user - The name of the user acquiring the write lock.
-     * @throws if the write lock is already held by another user.
-     */
-    acquireWriteLock(user: string): void;
-    /**
-     * Release the write lock on the container. This should be called after all changes to the container's contents are complete. It
-     * publishes and uploads the changes made to any [[SettingsDb]]s while the lock was held, after which those dbs become immutable.
-     */
-    releaseWriteLock(): void;
-    /**
-     * Abandon any changes made to the container and release the write lock. Any newly created versions of SettingsDbs are discarded.
-     */
-    abandonChanges(): void;
-}
-/**
- * An editable [[SettingsDb]]. This is used only by tools to allow administrators to create and modify SettingsDbs.
- * For cloud-based SettingsDbs, the container's write token must be obtained via [[EditableSettingsCloudContainer.acquireWriteLock]] before the methods in this interface may be used.
- * Normally, only admins will have write access.
- * Only one admin at a time may be editing a settings container.
- * @note Unlike [[EditableWorkspaceDb]], this interface only supports settings operations — no blob, file, or string resource methods.
- * @beta
- */
-export interface EditableSettingsDb extends SettingsDb {
-    /** The editable container that owns this SettingsDb. */
-    readonly container: EditableSettingsCloudContainer;
-    /**
-     * Update the contents of the manifest in this SettingsDb.
-     * @note This replaces the stored manifest entirely; omitted fields are lost.
-     * @param manifest - The updated manifest.
-     */
-    updateManifest(manifest: SettingsDbManifest): void;
-    /**
-     * Replace all settings in this SettingsDb with the given container.
-     * @param settings - The settings object to store.
-     */
-    updateSettings(settings: SettingsContainer): void;
-    /**
-     * Add or update a single [[Setting]] by name.
-     * If a setting with the given name already exists, its value is replaced.
-     * If it does not exist, it is added. Other settings are preserved.
-     * @param args - The arguments specifying the setting name and value.
-     */
-    updateSetting(args: UpdateSettingArgs): void;
-    /**
-     * Remove a single [[Setting]] by name. Other settings are preserved.
-     * @param settingName - The name of the setting to remove.
-     */
-    removeSetting(settingName: SettingName): void;
-}
-/** An object that permits administrators to modify the contents of settings containers.
- * Use [[SettingsEditor.construct]] to obtain a SettingsEditor, and [[close]] when finished using it.
- * Only one SettingsEditor may be in use at any given time.
- * Use [[getContainer]] to edit an existing container, or [[createNewCloudContainer]] to create a new container.
- * @beta
- */
-export interface SettingsEditor {
-    /** @internal */
-    [_implementationProhibited]: unknown;
-    /**
-     * The workspace dedicated to this editor.
-     * @note This workspace is independent from [[IModelHost.appWorkspace]] and all [[IModelDb.workspace]]s.
-     */
-    readonly workspace: Workspace;
-    /**
-     * Retrieves a container for the editor with the specified properties and access token.
-     */
-    getContainer(args: GetWorkspaceContainerArgs): EditableSettingsCloudContainer;
-    /**
-     * Asynchronously retrieves a container for the editor with the specified properties.
-     */
-    getContainerAsync(props: WorkspaceContainerProps): Promise<EditableSettingsCloudContainer>;
-    /**
-     * Creates a new cloud container for holding SettingsDbs, from the [[BlobContainer]] service.
-     * The container is automatically assigned `containerType: "settings"` in its metadata and
-     * initialized with a default [[SettingsDb]].
-     * @param args - The arguments for creating the container, including scope, metadata, and manifest.
-     * @returns A promise that resolves to the new EditableSettingsCloudContainer.
-     * @note The current user must have administrator rights for the iTwin for the container.
+     * Look up the settings container for an iTwin and obtain a read-only access token.
+     * @returns container props needed by [[IModelHost.getITwinWorkspace]].
      * @note Requires [[IModelHost.authorizationClient]] to be configured.
+     * @note Requires [[BlobContainer.service]] to be configured.
      */
-    createNewCloudContainer(args: CreateNewSettingsContainerArgs): Promise<EditableSettingsCloudContainer>;
-    /**
-     * Find and open existing settings containers by querying the [[BlobContainer]] service.
-     * This is a convenience method that queries for all settings containers matching the given iTwinId
-     * (and optionally iModelId), requests write access tokens, and opens each matching container.
-     * @param args - The query arguments including iTwinId and optionally iModelId and label.
-     * @returns A promise that resolves to an array of opened [[EditableSettingsCloudContainer]]s.
-     * @note Requires [[IModelHost.authorizationClient]] and [[BlobContainer.service]] to be configured.
-     */
-    findContainers(args: SettingsEditor.QuerySettingsContainersArgs): Promise<EditableSettingsCloudContainer[]>;
-    /**
-     * Closes this editor. All settings containers are dropped.
-     */
-    close(): void;
+    function getITwinSettingsSources(iTwinId: GuidString): Promise<WorkspaceDbSettingsProps[] | undefined>;
 }
 //# sourceMappingURL=SettingsEditor.d.ts.map

package/lib/cjs/workspace/SettingsEditor.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"SettingsEditor.d.ts","sourceRoot":"","sources":["../../../src/workspace/SettingsEditor.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"SettingsEditor.d.ts","sourceRoot":"","sources":["../../../src/workspace/SettingsEditor.ts"],"names":[],"mappings":"AAIA;;GAEG;AAGH,OAAO,EAAE,UAAU,EAAE,MAAM,qBAAqB,CAAC;AACjD,OAAO,EAAE,oBAAoB,EAAE,wBAAwB,EAAE,MAAM,aAAa,CAAC;AAI7E,OAAO,EAAE,0BAA0B,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AAIhF;;;;;GAKG;AACH,eAAO,MAAM,oBAAoB,uBAAuB,CAAC;AAEzD,gBAAgB;AAChB,yBAAiB,cAAc,CAAC;IAC9B,8DAA8D;IACvD,MAAM,aAAa,aAAa,CAAC;IAExC;;;;OAIG;IACH,SAAsB,iBAAiB,CAAC,OAAO,EAAE,UAAU,GAAG,OAAO,CAAC;QAAE,MAAM,EAAE,eAAe,CAAC;QAAC,SAAS,EAAE,0BAA0B,CAAA;KAAE,CAAC,CAExI;IAED;;;;;OAKG;IACH,SAAsB,WAAW,CAAC,OAAO,EAAE,UAAU,GAAG,OAAO,CAAC;QAAE,MAAM,EAAE,eAAe,CAAC;QAAC,SAAS,EAAE,0BAA0B,CAAA;KAAE,GAAG,SAAS,CAAC,CAE9I;CACF;AAED;;;GAGG;AACH,yBAAiB,kBAAkB,CAAC;IAClC,4DAA4D;IAC5D,UAAiB,SAAS;QACxB,+DAA+D;QAC/D,OAAO,EAAE,UAAU,CAAC;QACpB,6BAA6B;QAC7B,KAAK,CAAC,EAAE,MAAM,CAAC;KAChB;IAeD;;;;OAIG;IACH,SAAsB,mBAAmB,CAAC,OAAO,EAAE,UAAU,GAAG,OAAO,CAAC,oBAAoB,GAAG,SAAS,CAAC,CASxG;IAED;;;;;OAKG;IACH,SAAsB,uBAAuB,CAAC,OAAO,EAAE,UAAU,GAAG,OAAO,CAAC,wBAAwB,EAAE,GAAG,SAAS,CAAC,CAwBlH;CACF"}