@itwin/core-backend 4.8.0-dev.3 → 4.8.0-dev.5

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

@@ -3,185 +3,214 @@
  */
 import { BeEvent, JSONSchemaType } from "@itwin/core-bentley";
 import { LocalDirName, LocalFileName } from "@itwin/core-common";
-/** The type of a Setting, according to its schema
+import { WorkspaceDb } from "./Workspace";
+import { implementationProhibited } from "../internal/ImplementationProhibited";
+/** The value of a single named parameter within a [[Workspace.settings]] that configures some aspect of the applications run-time behavior.
+ * Settings are stored in a [[SettingsDictionary]]. A setting is described by its [[SettingSchema]].
  * @beta
  */
-export type SettingType = JSONSchemaType;
+export type Setting = JSONSchemaType;
+/** @beta */
+export declare namespace Setting {
+    /** Create a deep copy of a [[Setting]]. */
+    function clone<T extends Setting>(setting: T): T;
+    /** Returns true if `a` and `b` are considered equivalent [[Setting]] values.
+     * Settings of primitive types like `number` and `string` are compared using `===`.
+     * Settings of type "object" are compared by comparing each property using `areEqual`; the objects are considered
+     * equal if they have the exact same set of property names with equivalent values.
+     * Settings of type "array" are compared by comparing each element of the arrays use `areEqual`; the arrays are considered
+     * equal if they have the same number of elements with equivalent values in the same exact order.
+     */
+    function areEqual(a: Setting | undefined, b: Setting | undefined): boolean;
+}
 /**
- * The name of a Setting. SettingNames must be valid JavaScript property names, defined in a [[SettingSchema]].
- * @see [SettingName]($docs/learning/backend/Workspace#settingnames)
+ * The name of a [[Setting]].
+ * Setting names must be [valid JavaScript property names](https://developer.mozilla.org/en-US/docs/Glossary/property/JavaScript) containing no spaces or periods.
+ * The name of a setting begins with the schema prefix of the [[SettingGroupSchema]] in which its [[SettingSchema]] is defined.
+ * A setting name therefore forms a path like file names in a file system.
+ * For example, the following are setting names defined in the `energyAnalysis`, `iot-scan-visualization`, and `vibration-map` schemas.
+ *
+ * ```ts
+ * "energyAnalysis/formats/totalWork"
+ * "energyAnalysis/formats/totalHours"
+ * "energyAnalysis/units/power"
+ * "energyAnalysis/units/temperature"
+ * "energyAnalysis/startupMode"
+ * "iot-scan-visualization/ports/cameras"
+ * "vibration-map/filters/scope"
+ * "vibration-map/filters/prefabricated"
+ * ```
+ *
  * @beta
  */
 export type SettingName = string;
-/** The name of a [[SettingDictionary]]. `SettingDictionary`s are stored in [[Settings]] and may be removed by DictionaryName.
- * DictionaryNames must be valid JavaScript property names.
+/** An object that defines the values for any number of [[Setting]]s. Each of its properties' names must conform to the semantics of a [[SettingName]].
  * @beta
  */
-export type DictionaryName = string;
-/**
- * A function called by [[Settings.resolveSetting]] for every SettingDictionary with a Setting that matches a name. The
- * SettingDictionaries are sorted by priority and this function is called in priority order with the highest priority first.
- * When this function returns a non-undefined value, the iteration is stopped and that value is returned. In this way,
- * applications can "combine" the prioritized Setting values as appropriate. The default implementation of this function
- * used by [[Settings.getSetting]] merely returns a clone of the value the first time it is called, so the highest priority
- * value is returned.
+export interface SettingsContainer {
+    /** Accesses settings by their names. */
+    [name: SettingName]: Setting | undefined;
+}
+/** Defines the precedence of a [[SettingsDictionary]].
+ * [[Settings]] may contain multiple dictionaries containing different values for the same [[SettingName]].
+ * When resolving the value of a [[Setting]], the value from the highest-priority dictionary is used.
+ * Priorities are grouped into coarse categories like [[SettingsPriority.application]] and [[SettingsPriority.iModel]].
+ * Settings with priorities less than or equal to [[SettingsPriority.application]] are stored in [[IModelHost.appWorkspace]], while
+ * those with priorities higher than [[SettingsPriority.application]] are stored inside [[IModelDb.workspace]].
  * @beta
  */
-export type SettingResolver<T> = (val: T, dict: DictionaryName, priority: SettingsPriority) => T | undefined;
-/** An entry in the array returned by [[Settings.inspectSetting]]
+export type SettingsPriority = number;
+/** @beta */
+export declare namespace SettingsPriority {
+    /** Settings that originate from default setting files loaded automatically at the start of a session. */
+    const defaults = 100;
+    /** Settings supplied by an application at runtime. */
+    const application = 200;
+    /** Settings that apply to all iTwins for an organization. */
+    const organization = 300;
+    /** Settings that apply to all iModels in an iTwin. */
+    const iTwin = 400;
+    /** Settings that apply to all branches of an iModel. */
+    const branch = 500;
+    /** Settings that apply to a specific iModel. */
+    const iModel = 600;
+}
+/** A named container that supplies values for [[Setting]]s.
+ * @see [[Settings.addDictionary]] to register a new settings dictionary.
  * @beta
- *
  */
-export interface SettingInspector<T> {
-    value: T;
-    dictionary: DictionaryName;
-    priority: number;
+export interface SettingsDictionary {
+    /** @internal */
+    [implementationProhibited]: unknown;
+    /** Metadata describing the dictionary. */
+    readonly props: SettingsDictionaryProps;
+    /** Obtain a copy of the value of the setting named `settingName` stored in this dictionary, or `undefined` if no such setting exists.
+     * The returned value is always cloned using [[Setting.clone]].
+     * @note Generally, applications use methods like [[Settings.getString]] and [[Setting.getArray]] to resolve a setting value from multiple
+     * dictionaries. Those methods - unlike this one - also validate that `settingName` is of type `T` as defined by its [[SettingSchema]].
+     */
+    getSetting<T extends Setting>(settingName: SettingName): T | undefined;
 }
-/** An object with string-named members (as opposed to an array object).
+/** Uniquely identifies a [[SettingsDictionary]].
  * @beta
  */
-export interface SettingObject {
-    [name: string]: SettingType;
+export interface SettingsDictionarySource {
+    /** The name of the dictionary, which must be unique within its [[workspaceDb]], or - if [[workspaceDb]] is undefined - unique among all dictionaries not associated with any [[WorkspaceDb]]. */
+    readonly name: string;
+    /** The [[WorkspaceDb]] from which the dictionary originated. */
+    readonly workspaceDb?: WorkspaceDb;
 }
-/**
- * An object with Settings as its members. A SettingDictionary also has a name and generally comes from a parsed JSON file, but
- * may also be created in memory by applications
+/** Properties of a [[SettingsDictionary]], defining its name, the [[WorkspaceDb]] (if any) from which it originated, and its [[priority]] relative to other dictionaries.
  * @beta
  */
-export type SettingDictionary = SettingObject;
-/**
- * Values for SettingsPriority determine the sort order for Settings. Higher values take precedence over lower values.
- * @beta
-*/
-export declare enum SettingsPriority {
-    /** values supplied default-settings files */
-    defaults = 100,
-    /** values supplied by applications at runtime */
-    application = 200,
-    /** values that apply to all iTwins for an organization. */
-    organization = 300,
-    /** values that apply to all iModels in an iTwin. */
-    iTwin = 400,
-    /** values that apply to a single iModel. */
-    iModel = 500
+export interface SettingsDictionaryProps extends SettingsDictionarySource {
+    /** Precedence value determining which setting value to use when multiple dictionaries supply values for the same [[SettingName]]. */
+    readonly priority: SettingsPriority;
 }
-/** The current set of Settings for a Workspace.
+/**
+ * The collection of [[Setting]]s that supply the run-time configuration of a [[Workspace]].
+ * The `Settings` object comprises a collection of named [[SettingsDictionary]] objects.
+ * Methods like [[getSetting]], [[getString]], and [[getArray]] provide access to the value of an individual [[Setting]] by searching
+ * the [[dictionaries]] in order by their [[SettingsPriority]] to find the highest-priority setting with the requested [[SettingName]].
+ * Most methods that retrieve [[Setting]] values validate them against their [[SettingSchema]]s to ensure that they are of the correct type.
+ * A [[SettingsDictionary]] can be added or removed using [[addDictionary]] and [[dropDictionary]].
+ * Because [[Setting]]s can change at any time during the session, you should avoid caching their values wherever possible.
+ * If you must cache them (for example, to display in a user interface), you should listen for the [[onSettingsChanged]] event to be
+ * notified of potential changes.
+ *
+ * Settings are accessed via [[Workspace.settings]]. They are defined at the application level by [[IModelHost.appWorkspace]], but individual iModels may supply
+ * additional iModel-specific settings or overrides for application-level settings. When working in the context of a specific iModel, use [[IModelDb.workspace]]'s `settings`
+ * property. Any settings not overridden by the iModel will fall back to the settings defined in [[IModelHost.appWorkspace]].
+ *
+ * Application settings are loaded into [[IModelHost.appWorkspace]] when the session begins (i.e., when [[IModelHost.startup]] is invoked), and unloaded when it ends (in [[IModelHost.shutdown]]).
+ * They are read from [JSON5](https://json5.org/) files delivered with the application. The application should register any additional [[SettingsDictionary]]'s '(and their corresponding
+ * [[SettingGroupSchema]]s) at this time.
+ *
+ * iModel-specific settings are stored in the iModel's property table and loaded into [[IModelDb.workspace]] when the iModel is first opened.
+ * You can add and remove a [[SettingsDictionary]] from the property table using [[IModelDb.saveSettingDictionary]] and [[IModelDb.deleteSettingDictionary]].
+ *
+ * See the [learning article]($docs/learning/backend/Workspace) for a detailed overiew and examples.
+ *
+ * @see [[IModelHost.appWorkspace]] application-wide settings, and [[IModelDb.workspace]] for settings specific to a given iModel.
  * @beta
  */
 export interface Settings {
+    /** @internal */
+    [implementationProhibited]: unknown;
     /** @internal */
     close(): void;
-    /** Event raised whenever a SettingsDictionary is added or removed. */
+    /** The set of settings dictionaries from which [[Setting]] values are obtained, sorted by [[SettingsPriority]].
+     * The set can contain at most one dictionary for each unique combination of name and [[WorkspaceDb]].
+     * @see [[addDictionary]], [[addFile]], [[addJson]], and [[addDirectory]] to add a new dictionary.
+     * @see [[dropDictionary]] to remove a dictionary.
+     * @see [[getDictionary]] to look up a dictionary.
+     */
+    readonly dictionaries: readonly SettingsDictionary[];
+    /** Event raised whenever a [[SettingsDictionary]] is added or removed. */
     readonly onSettingsChanged: BeEvent<() => void>;
-    /** Add a SettingDictionary from a local settings file. The file should be in [JSON5](https://json5.org/) format. It is read
-     * and parsed and the fileName is used as the DictionaryName.
-     * @param fileName the name of a local settings file of the SettingDictionary. This becomes the DictionaryName.
-     * @param priority the SettingsPriority for the SettingDictionary
-     * @note If the SettingDictionary was previously added, the new content overrides the old content.
+    /** Parses the contents of a local [JSON5](https://json5.org/) file as a [[SettingsContainer]] and invokes [[addDictionary]] to
+     * add a [[SettingsDictionary]] named `fileName` with the specified priority.
+     * @param fileName the name of a local settings file containing the dictionary.
+     * @param priority the priority for the dictionary.
      */
     addFile(fileName: LocalFileName, priority: SettingsPriority): void;
-    /** Add all files in the supplied directory with the extension ".json" or ".json5"
-     * @param dirName the name of a local settings directory
+    /** Invokes [[addFile]] for all files in `directory` with the extension ".json" or ".json5". */
+    addDirectory(directory: LocalDirName, priority: SettingsPriority): void;
+    /** Parses `settingsJson` as a [[SettingsContainer]] and invokes [[addDictionary]] to add a [[SettingsDictionary]] with the specified `props`.
+     * This is typically used when reading dictionaries out of a [[WorkspaceDb]], where they are stored as stringified JSON.
      */
-    addDirectory(dirName: LocalDirName, priority: SettingsPriority): void;
-    /** Add a SettingDictionary from a JSON5 stringified string. The string is parsed and the resultant object is added as a SettingDictionary.
-     * @param dictionaryName the name of the SettingDictionary
-     * @param priority the SettingsPriority for the SettingDictionary
-     * @param settingsJson the JSON5 stringified string to be parsed.
-     * @note If the SettingDictionary was previously added, the new content overrides the old content.
+    addJson(props: SettingsDictionaryProps, settingsJson: string): void;
+    /** Find a [[SettingsDictionary]] with the same name and [[WorkspaceDb]] as `source`. */
+    getDictionary(source: SettingsDictionarySource): SettingsDictionary | undefined;
+    /** Add a new [[SettingsDictionary]] with the priority, name, and [[WorkspaceDb]] specified by `props` and setting values supplied by `settings`.
+     * @note If a dictionary with the same name and [[WorkspaceDb]] already exists, it will be replaced.
+     * @see [[addFile]], [[addJson]], and [[addDirectory]] for convenient ways to add dictionaries from various sources.
      */
-    addJson(dictionaryName: DictionaryName, priority: SettingsPriority, settingsJson: string): void;
-    /** Add a SettingDictionary object.
-     * @param dictionaryName the name of the SettingDictionary
-     * @param priority the SettingsPriority for the SettingDictionary
-     * @param settings the SettingDictionary object to be added.
-     * @note If the SettingDictionary was previously added, the new content overrides the old content.
-     */
-    addDictionary(dictionaryName: DictionaryName, priority: SettingsPriority, settings: SettingDictionary): void;
-    /** Remove a SettingDictionary by name. */
-    dropDictionary(dictionaryName: DictionaryName): void;
-    /**
-     * Resolve a setting, by name, using a SettingResolver.
-     * @param settingName The name of the setting to resolve
-     * @param resolver function to be called for each SettingDictionary with a matching Setting. Iteration stops when it returns a non-undefined value.
-     * @param defaultValue value returned if settingName is not present in any SettingDictionary or resolver never returned a value.
-     * @returns the resolved setting value.
-     */
-    resolveSetting<T extends SettingType>(settingName: SettingName, resolver: SettingResolver<T>, defaultValue: T): T;
-    resolveSetting<T extends SettingType>(settingName: SettingName, resolver: SettingResolver<T>, defaultValue?: T): T | undefined;
-    /** Get the highest priority setting for a SettingName.
-     * @param settingName The name of the setting
-     * @param defaultValue value returned if settingName is not present in any SettingDictionary.
-     * @note This method is generic on SettingType, but no type checking is actually performed at run time. So, if you
+    addDictionary(props: SettingsDictionaryProps, settings: SettingsContainer): void;
+    /** Removes a previously-added [[SettingsDictionary]]. */
+    dropDictionary(props: SettingsDictionarySource): void;
+    /** Looks up the highest priority setting value for a SettingName, falling back to a default value if no value for the setting is found.
+     * The [[dictionaries]] are searched in order by [[SettingsPriority]]; the first one that provides a value for `settingName` wins.
+     * @param settingName The name of the setting.
+     * @param defaultValue value returned if settingName is not present in any [[SettingsDictionary]].
+     * @note This method is generic on [[Setting]] type, but no type checking is actually performed at run time. So, if you
      * use this method to get a setting with an expected type, but its value is a different type, the return type of this method will be wrong.
-     * You must always type check the result. Use the non-generic "get" methods (e.g. [[getString]]) if you only want the value
+     * You must always type check the result. Use the non-generic "get" methods like [[getString]] and [[getArray]] if you only want the value
      * if its type is correct.
+     * @note Unlike [[getArray]], this method does not combine arrays - it ignores [[SettingsSchema.combineArrays]].
      */
-    getSetting<T extends SettingType>(settingName: SettingName, defaultValue?: T): T | undefined;
-    /** Get a string setting by SettingName.
-     * @param settingName The name of the setting
-     * @param defaultValue value returned if settingName is not present in any SettingDictionary, or if the highest priority setting is not a string.
+    getSetting<T extends Setting>(settingName: SettingName, defaultValue?: T): T | undefined;
+    /** Obtain an iterator over all of the values in the [[dictionaries]] for the [[Setting]] identified by `settingName`, ordered by [[SettingsPriority]]. */
+    getSettingEntries<T extends Setting>(settingName: SettingName): Iterable<{
+        value: T;
+        dictionary: SettingsDictionary;
+    }>;
+    /** Obtain an iterator over all of the values in the [[dictionaries]] for the [[Setting]] identified by `settingName`, ordered by [[SettingsPriority]]. */
+    getSettingValues<T extends Setting>(settingName: SettingName): Iterable<T>;
+    /** Look up the value of a string [[Setting]] named `settingName`, returning `defaultValue` if no such value is defined.
+     * @throws Error if the setting exists but is not a string.
      */
     getString(settingName: SettingName, defaultValue: string): string;
     getString(settingName: SettingName, defaultValue?: string): string | undefined;
-    /** Get a boolean setting by SettingName.
-    * @param settingName The name of the setting
-    * @param defaultValue value returned if settingName is not present in any SettingDictionary, or if the highest priority setting is not a boolean.
-    */
+    /** Look up the value of a boolean [[Setting]] named `settingName`, returning `defaultValue` if no such value is defined.
+     * @throws Error if the setting exists but is not a boolean.
+     */
     getBoolean(settingName: SettingName, defaultValue: boolean): boolean;
     getBoolean(settingName: SettingName, defaultValue?: boolean): boolean | undefined;
-    /** Get a number setting by SettingName.
-    * @param settingName The name of the setting
-    * @param defaultValue value returned if settingName is not present in any SettingDictionary, or if the highest priority setting is not a number.
-    */
+    /** Look up the value of a numeric [[Setting]] named `settingName`, returning `defaultValue` if no such value is defined.
+     * @throws Error if the setting exists but is not a number.
+     */
     getNumber(settingName: SettingName, defaultValue: number): number;
     getNumber(settingName: SettingName): number | undefined;
-    /** Get an object setting by SettingName.
-    * @param settingName The name of the setting
-    * @param defaultValue value returned if settingName is not present in any SettingDictionary, or if the highest priority setting is not an object.
-    */
+    /** Look up the value of an object [[Setting]] named `settingName`, returning `defaultValue` if no such value is defined.
+     * @throws Error if the setting exists but is not an object.
+     */
     getObject<T extends object>(settingName: SettingName, defaultValue: T): T;
     getObject<T extends object>(settingName: SettingName): T | undefined;
-    /** Get an array setting by SettingName.
-    * @param settingName The name of the setting
-    * @param defaultValue value returned if settingName is not present in any SettingDictionary, or if the highest priority setting is not an array.
-    */
-    getArray<T extends SettingType>(settingName: SettingName, defaultValue: Array<T>): Array<T>;
-    getArray<T extends SettingType>(settingName: SettingName): Array<T> | undefined;
-    /** Get an array of [[SettingInspector] objects, sorted in priority order, for all Settings that match a SettingName.
-     * @note this method is mainly for debugging and diagnostics.
-     */
-    inspectSetting<T extends SettingType>(name: SettingName): SettingInspector<T>[];
-}
-/**
- * Internal implementation of Settings interface.
- * @internal
- */
-export declare class BaseSettings implements Settings {
-    private _dictionaries;
-    protected verifyPriority(_priority: SettingsPriority): void;
-    close(): void;
-    readonly onSettingsChanged: BeEvent<() => void>;
-    addFile(fileName: LocalFileName, priority: SettingsPriority): void;
-    addDirectory(dirName: LocalDirName, priority: SettingsPriority): void;
-    addJson(dictionaryName: string, priority: SettingsPriority, settingsJson: string): void;
-    addDictionary(dictionaryName: string, priority: SettingsPriority, settings: SettingDictionary): void;
-    dropDictionary(dictionaryName: DictionaryName, raiseEvent?: boolean): boolean;
-    resolveSetting<T extends SettingType>(name: SettingName, resolver: SettingResolver<T>, defaultValue?: T): T | undefined;
-    getSetting<T extends SettingType>(name: SettingName, defaultValue?: T): T | undefined;
-    /** for debugging. Returns an array of all values for a setting, sorted by priority.
-     * @note values are not cloned. Do not modify objects or arrays.
+    /** Look up the value of an array [[Setting]] named `settingName`, returning `defaultValue` if no such value is defined.
+     * @throws Error if the setting exists but is not an array.
      */
-    inspectSetting<T extends SettingType>(name: SettingName): SettingInspector<T>[];
-    getString(name: SettingName, defaultValue: string): string;
-    getString(name: SettingName): string | undefined;
-    getBoolean(name: SettingName, defaultValue: boolean): boolean;
-    getBoolean(name: SettingName): boolean | undefined;
-    getNumber(name: SettingName, defaultValue: number): number;
-    getNumber(name: SettingName): number | undefined;
-    getObject<T extends object>(name: SettingName, defaultValue: T): T;
-    getObject<T extends object>(name: SettingName): T | undefined;
-    getArray<T extends SettingType>(name: SettingName, defaultValue: Array<T>): Array<T>;
-    getArray<T extends SettingType>(name: SettingName): Array<T> | undefined;
+    getArray<T extends Setting>(settingName: SettingName, defaultValue: Array<T>): Array<T>;
+    getArray<T extends Setting>(settingName: SettingName): Array<T> | undefined;
 }
 //# sourceMappingURL=Settings.d.ts.map

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

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

package/lib/cjs/workspace/Settings.js

@@ -7,150 +7,80 @@
  * @module Workspace
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.BaseSettings = exports.SettingsPriority = void 0;
-const fs = require("fs-extra");
-const json5_1 = require("json5");
-const path_1 = require("path");
-const core_bentley_1 = require("@itwin/core-bentley");
-const IModelJsFs_1 = require("../IModelJsFs");
-/**
- * Values for SettingsPriority determine the sort order for Settings. Higher values take precedence over lower values.
- * @beta
-*/
-var SettingsPriority;
-(function (SettingsPriority) {
-    /** values supplied default-settings files */
-    SettingsPriority[SettingsPriority["defaults"] = 100] = "defaults";
-    /** values supplied by applications at runtime */
-    SettingsPriority[SettingsPriority["application"] = 200] = "application";
-    /** values that apply to all iTwins for an organization. */
-    SettingsPriority[SettingsPriority["organization"] = 300] = "organization";
-    /** values that apply to all iModels in an iTwin. */
-    SettingsPriority[SettingsPriority["iTwin"] = 400] = "iTwin";
-    /** values that apply to a single iModel. */
-    SettingsPriority[SettingsPriority["iModel"] = 500] = "iModel";
-})(SettingsPriority || (exports.SettingsPriority = SettingsPriority = {}));
-/** @internal */
-function deepClone(obj) {
-    if (!obj || typeof obj !== "object")
-        return obj;
-    const result = Array.isArray(obj) ? [] : {};
-    Object.keys(obj).forEach((key) => {
-        const val = obj[key];
-        if (val && typeof val === "object") {
-            result[key] = deepClone(val);
+exports.SettingsPriority = exports.Setting = void 0;
+const ImplementationProhibited_1 = require("../internal/ImplementationProhibited");
+/** @beta */
+var Setting;
+(function (Setting) {
+    /** Create a deep copy of a [[Setting]]. */
+    function clone(setting) {
+        if (!setting || typeof setting !== "object")
+            return setting;
+        const result = Array.isArray(setting) ? [] : {};
+        Object.keys(setting).forEach((key) => result[key] = clone(setting[key]));
+        return result;
+    }
+    Setting.clone = clone;
+    /** Returns true if `a` and `b` are considered equivalent [[Setting]] values.
+     * Settings of primitive types like `number` and `string` are compared using `===`.
+     * Settings of type "object" are compared by comparing each property using `areEqual`; the objects are considered
+     * equal if they have the exact same set of property names with equivalent values.
+     * Settings of type "array" are compared by comparing each element of the arrays use `areEqual`; the arrays are considered
+     * equal if they have the same number of elements with equivalent values in the same exact order.
+     */
+    function areEqual(a, b) {
+        if (a === b) {
+            return true;
         }
-        else {
-            result[key] = val;
+        // For primitive types, === suffices.
+        if (typeof a !== "object" || typeof b !== "object") {
+            return false;
         }
-    });
-    return result;
-}
-class SettingsDictionary {
-    constructor(name, priority, settings) {
-        this.name = name;
-        this.priority = priority;
-        this.settings = settings;
-    }
-    getSetting(settingName) {
-        return this.settings[settingName];
-    }
-}
-/**
- * Internal implementation of Settings interface.
- * @internal
- */
-class BaseSettings {
-    constructor() {
-        this._dictionaries = [];
-        this.onSettingsChanged = new core_bentley_1.BeEvent();
-    }
-    verifyPriority(_priority) { }
-    close() { }
-    addFile(fileName, priority) {
-        this.addJson(fileName, priority, fs.readFileSync(fileName, "utf-8"));
-    }
-    addDirectory(dirName, priority) {
-        for (const fileName of IModelJsFs_1.IModelJsFs.readdirSync(dirName)) {
-            const ext = (0, path_1.extname)(fileName);
-            if (ext === ".json5" || ext === ".json")
-                this.addFile((0, path_1.join)(dirName, fileName), priority);
-        }
-    }
-    addJson(dictionaryName, priority, settingsJson) {
-        this.addDictionary(dictionaryName, priority, (0, json5_1.parse)(settingsJson));
-    }
-    addDictionary(dictionaryName, priority, settings) {
-        this.verifyPriority(priority);
-        this.dropDictionary(dictionaryName, false); // make sure we don't have the same dictionary twice
-        const file = new SettingsDictionary(dictionaryName, priority, settings);
-        const doAdd = () => {
-            for (let i = 0; i < this._dictionaries.length; ++i) {
-                if (this._dictionaries[i].priority <= file.priority) {
-                    this._dictionaries.splice(i, 0, file);
-                    return;
-                }
+        if (Array.isArray(a) || Array.isArray(b)) {
+            if (!Array.isArray(a) || !Array.isArray(b) || a.length !== b.length) {
+                return false;
             }
-            this._dictionaries.push(file);
-        };
-        doAdd();
-        this.onSettingsChanged.raiseEvent();
-    }
-    dropDictionary(dictionaryName, raiseEvent = true) {
-        for (let i = 0; i < this._dictionaries.length; ++i) {
-            if (this._dictionaries[i].name === dictionaryName) {
-                this._dictionaries.splice(i, 1);
-                if (raiseEvent)
-                    this.onSettingsChanged.raiseEvent();
-                return true;
+            for (let i = 0; i < a.length; i++) {
+                if (!areEqual(a[i], b[i])) {
+                    return false;
+                }
             }
+            return true;
         }
-        return false;
-    }
-    resolveSetting(name, resolver, defaultValue) {
-        for (const dict of this._dictionaries) {
-            const val = dict.getSetting(name);
-            const resolved = val && resolver(val, dict.name, dict.priority);
-            if (undefined !== resolved) {
-                return resolved;
+        const aKeys = Object.keys(a);
+        const bKeys = Object.keys(b);
+        if (aKeys.length !== bKeys.length) {
+            return false;
+        }
+        aKeys.sort();
+        bKeys.sort();
+        for (let i = 0; i < aKeys.length; i++) {
+            const key = aKeys[i];
+            if (key !== bKeys[i]) {
+                return false;
+            }
+            if (!areEqual(a[key], b[key])) {
+                return false;
             }
         }
-        return defaultValue;
-    }
-    getSetting(name, defaultValue) {
-        return this.resolveSetting(name, (val) => deepClone(val)) ?? defaultValue;
-    }
-    /** for debugging. Returns an array of all values for a setting, sorted by priority.
-     * @note values are not cloned. Do not modify objects or arrays.
-     */
-    inspectSetting(name) {
-        const all = [];
-        this.resolveSetting(name, (value, dictionary, priority) => {
-            all.push({ value, dictionary, priority });
-            return undefined;
-        });
-        return all;
-    }
-    getString(name, defaultValue) {
-        const out = this.getSetting(name);
-        return typeof out === "string" ? out : defaultValue;
+        return true;
     }
-    getBoolean(name, defaultValue) {
-        const out = this.getSetting(name);
-        return typeof out === "boolean" ? out : defaultValue;
-    }
-    getNumber(name, defaultValue) {
-        const out = this.getSetting(name);
-        return typeof out === "number" ? out : defaultValue;
-    }
-    getObject(name, defaultValue) {
-        const out = this.getSetting(name);
-        return typeof out === "object" ? out : defaultValue;
-    }
-    getArray(name, defaultValue) {
-        const out = this.getSetting(name);
-        return Array.isArray(out) ? out : defaultValue;
-    }
-}
-exports.BaseSettings = BaseSettings;
+    Setting.areEqual = areEqual;
+})(Setting || (exports.Setting = Setting = {}));
+/** @beta */
+var SettingsPriority;
+(function (SettingsPriority) {
+    /** Settings that originate from default setting files loaded automatically at the start of a session. */
+    SettingsPriority.defaults = 100;
+    /** Settings supplied by an application at runtime. */
+    SettingsPriority.application = 200;
+    /** Settings that apply to all iTwins for an organization. */
+    SettingsPriority.organization = 300;
+    /** Settings that apply to all iModels in an iTwin. */
+    SettingsPriority.iTwin = 400;
+    /** Settings that apply to all branches of an iModel. */
+    SettingsPriority.branch = 500;
+    /** Settings that apply to a specific iModel. */
+    SettingsPriority.iModel = 600;
+})(SettingsPriority || (exports.SettingsPriority = SettingsPriority = {}));
 //# sourceMappingURL=Settings.js.map