@itwin/core-backend 4.0.0-dev.24 → 4.0.0-dev.28

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

@@ -1,187 +1,187 @@
-/** @packageDocumentation
- * @module Workspace
- */
-import { BeEvent, JSONSchemaType } from "@itwin/core-bentley";
-import { LocalDirName, LocalFileName } from "@itwin/core-common";
-/** The type of a Setting, according to its schema
- * @beta
- */
-export declare type SettingType = JSONSchemaType;
-/**
- * The name of a Setting. SettingNames must be valid JavaScript property names, defined in a [[SettingSchema]].
- * @see [SettingName]($docs/learning/backend/Workspace#settingnames)
- * @beta
- */
-export declare 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.
- * @beta
- */
-export declare 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.
- * @beta
- */
-export declare type SettingResolver<T> = (val: T, dict: DictionaryName, priority: SettingsPriority) => T | undefined;
-/** An entry in the array returned by [[Settings.inspectSetting]]
- * @beta
- *
- */
-export interface SettingInspector<T> {
-    value: T;
-    dictionary: DictionaryName;
-    priority: number;
-}
-/** An object with string-named members (as opposed to an array object).
- * @beta
- */
-export interface SettingObject {
-    [name: string]: SettingType;
-}
-/**
- * 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
- * @beta
- */
-export declare 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
-}
-/** The current set of Settings for a Workspace.
- * @beta
- */
-export interface Settings {
-    /** @internal */
-    close(): void;
-    /** 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.
-     */
-    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
-     */
-    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(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
-     * 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
-     * if its type is correct.
-     */
-    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.
-     */
-    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.
-    */
-    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.
-    */
-    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.
-    */
-    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.
-     */
-    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;
-}
+/** @packageDocumentation
+ * @module Workspace
+ */
+import { BeEvent, JSONSchemaType } from "@itwin/core-bentley";
+import { LocalDirName, LocalFileName } from "@itwin/core-common";
+/** The type of a Setting, according to its schema
+ * @beta
+ */
+export declare type SettingType = JSONSchemaType;
+/**
+ * The name of a Setting. SettingNames must be valid JavaScript property names, defined in a [[SettingSchema]].
+ * @see [SettingName]($docs/learning/backend/Workspace#settingnames)
+ * @beta
+ */
+export declare 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.
+ * @beta
+ */
+export declare 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.
+ * @beta
+ */
+export declare type SettingResolver<T> = (val: T, dict: DictionaryName, priority: SettingsPriority) => T | undefined;
+/** An entry in the array returned by [[Settings.inspectSetting]]
+ * @beta
+ *
+ */
+export interface SettingInspector<T> {
+    value: T;
+    dictionary: DictionaryName;
+    priority: number;
+}
+/** An object with string-named members (as opposed to an array object).
+ * @beta
+ */
+export interface SettingObject {
+    [name: string]: SettingType;
+}
+/**
+ * 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
+ * @beta
+ */
+export declare 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
+}
+/** The current set of Settings for a Workspace.
+ * @beta
+ */
+export interface Settings {
+    /** @internal */
+    close(): void;
+    /** 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.
+     */
+    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
+     */
+    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(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
+     * 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
+     * if its type is correct.
+     */
+    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.
+     */
+    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.
+    */
+    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.
+    */
+    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.
+    */
+    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.
+     */
+    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;
+}
 //# sourceMappingURL=Settings.d.ts.map