@itwin/core-backend 3.4.0-dev.3 → 3.4.0-dev.33

package/lib/cjs/Material.js.map

@@ -1 +1 @@
-{"version":3,"file":"Material.js","sourceRoot":"","sources":["../../src/Material.ts"],"names":[],"mappings":"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","sourcesContent":["/*---------------------------------------------------------------------------------------------\r\n* Copyright (c) Bentley Systems, Incorporated. All rights reserved.\r\n* See LICENSE.md in the project root for license terms and full copyright notice.\r\n*--------------------------------------------------------------------------------------------*/\r\n/** @packageDocumentation\r\n * @module Elements\r\n */\r\n\r\nimport { Id64String } from \"@itwin/core-bentley\";\r\nimport { BisCodeSpec, Code, CodeScopeProps, CodeSpec, DefinitionElementProps, RenderMaterialProps, TextureMapProps } from \"@itwin/core-common\";\r\nimport { DefinitionElement } from \"./Element\";\r\nimport { IModelDb } from \"./IModelDb\";\r\n\r\n/* eslint-disable @typescript-eslint/naming-convention */\r\n\r\n/** A PhysicalMaterial defines the matter that makes up physical elements.\r\n * @note See [[RenderMaterialElement]] for the DefinitionElement used to define rendering characteristics.\r\n * @public\r\n */\r\nexport abstract class PhysicalMaterial extends DefinitionElement {\r\n  /** @internal */\r\n  public static override get className(): string { return \"PhysicalMaterial\"; }\r\n  /** Create a Code for a PhysicalMaterial given a name that is meant to be unique within the scope of the specified DefinitionModel.\r\n   * @param iModel  The IModelDb\r\n   * @param definitionModelId The Id of the DefinitionModel that will contain the PhysicalMaterial and provide the scope for its name.\r\n   * @param name The name (codeValue) of the PhysicalMaterial\r\n   */\r\n  public static createCode(iModel: IModelDb, definitionModelId: CodeScopeProps, name: string): Code {\r\n    const codeSpec: CodeSpec = iModel.codeSpecs.getByName(BisCodeSpec.physicalMaterial);\r\n    return new Code({ spec: codeSpec.id, scope: definitionModelId, value: name });\r\n  }\r\n  /** Create a PhysicalMaterial\r\n   * @param iModelDb The IModelDb\r\n   * @param definitionModelId The Id of the DefinitionModel that will contain the PhysicalMaterial and provide the scope for its name.\r\n   * @param name The name (codeValue) of the PhysicalMaterial\r\n   * @returns The newly constructed PhysicalMaterial\r\n   * @throws [[IModelError]] if there is a problem creating the PhysicalMaterial\r\n   */\r\n  public static create<T extends PhysicalMaterial>(iModelDb: IModelDb, definitionModelId: CodeScopeProps, name: string): T {\r\n    const elementProps: DefinitionElementProps = {\r\n      classFullName: this.classFullName,\r\n      model: definitionModelId,\r\n      code: this.createCode(iModelDb, definitionModelId, name),\r\n    };\r\n    return iModelDb.elements.createElement(elementProps);\r\n  }\r\n}\r\n\r\n/** Defines a rendering material.\r\n * @note See [[PhysicalMaterial]] for the DefinitionElement used to define the matter that makes up physical elements.\r\n * @public\r\n */\r\nexport class RenderMaterialElement extends DefinitionElement {\r\n  /** @internal */\r\n  public static override get className(): string { return \"RenderMaterial\"; }\r\n\r\n  /** The name of a palette that can be used to categorize multiple materials. */\r\n  public paletteName: string;\r\n  /** An optional description of the material. */\r\n  public description?: string;\r\n  /** @internal */\r\n  constructor(props: RenderMaterialProps, iModel: IModelDb) {\r\n    super(props, iModel);\r\n    this.paletteName = props.paletteName;\r\n    this.description = props.description;\r\n  }\r\n  /** @internal */\r\n  public override toJSON(): RenderMaterialProps {\r\n    const val = super.toJSON() as RenderMaterialProps;\r\n    val.paletteName = this.paletteName;\r\n    val.description = this.description;\r\n    return val;\r\n  }\r\n  /** Create a Code for a RenderMaterial given a name that is meant to be unique within the scope of the specified DefinitionModel.\r\n   * @param iModel  The IModelDb\r\n   * @param scopeModelId The Id of the DefinitionModel that contains the RenderMaterial and provides the scope for its name.\r\n   * @param name The RenderMaterial name\r\n   */\r\n  public static createCode(iModel: IModelDb, scopeModelId: CodeScopeProps, name: string): Code {\r\n    const codeSpec: CodeSpec = iModel.codeSpecs.getByName(BisCodeSpec.texture);\r\n    return 0 === name.length ? Code.createEmpty() : new Code({ spec: codeSpec.id, scope: scopeModelId, value: name });\r\n  }\r\n  /**\r\n   * Create a RenderMaterial with given parameters.\r\n   * @param iModelDb The iModel\r\n   * @param definitionModelId The [[DefinitionModel]]\r\n   * @param materialName The name/CodeValue of the RenderMaterial\r\n   * @param params Parameters object which describes how to construct the RenderMaterial\r\n   * @returns The newly constructed RenderMaterial element.\r\n   * @throws [[IModelError]] if unable to create the element.\r\n   */\r\n  public static create(iModelDb: IModelDb, definitionModelId: Id64String, materialName: string, params: RenderMaterialElement.Params): RenderMaterialElement {\r\n    const map = undefined !== params.patternMap ? { Pattern: params.patternMap } : undefined;\r\n    const renderMaterialProps: RenderMaterialProps = {\r\n      classFullName: this.classFullName,\r\n      code: this.createCode(iModelDb, definitionModelId, materialName),\r\n      paletteName: params.paletteName,\r\n      description: params.description,\r\n      jsonProperties: {\r\n        materialAssets: {\r\n          renderMaterial: {\r\n            HasBaseColor: params.color !== undefined,\r\n            color: params.color,\r\n            HasSpecularColor: params.specularColor !== undefined,\r\n            specular_color: params.specularColor,\r\n            HasFinish: params.finish !== undefined,\r\n            finish: params.finish,\r\n            HasTransmit: params.transmit !== undefined,\r\n            transmit: params.transmit,\r\n            HasDiffuse: params.diffuse !== undefined,\r\n            diffuse: params.diffuse,\r\n            HasSpecular: params.specular !== undefined,\r\n            specular: params.specular,\r\n            HasReflect: params.reflect !== undefined,\r\n            reflect: params.reflect,\r\n            HasReflectColor: params.reflectColor !== undefined,\r\n            reflect_color: params.reflectColor,\r\n            Map: map,\r\n          },\r\n        },\r\n      },\r\n      model: definitionModelId,\r\n      isPrivate: false,\r\n    };\r\n    return new RenderMaterialElement(renderMaterialProps, iModelDb);\r\n  }\r\n  /**\r\n   * Insert a new RenderMaterial into a model.\r\n   * @param iModelDb Insert into this iModel\r\n   * @param definitionModelId Insert the new Texture into this DefinitionModel\r\n   * @param materialName The name/CodeValue of the RenderMaterial\r\n   * @param params Parameters object which describes how to construct the RenderMaterial\r\n   * @returns The Id of the newly inserted RenderMaterial element.\r\n   * @throws [[IModelError]] if unable to insert the element.\r\n   */\r\n  public static insert(iModelDb: IModelDb, definitionModelId: Id64String, materialName: string, params: RenderMaterialElement.Params): Id64String {\r\n    const renderMaterial = this.create(iModelDb, definitionModelId, materialName, params);\r\n    return iModelDb.elements.insertElement(renderMaterial.toJSON());\r\n  }\r\n}\r\n\r\n/** @public */\r\nexport namespace RenderMaterialElement { // eslint-disable-line no-redeclare\r\n  /** Parameters used to construct a [[RenderMaterial]]. */\r\n  export class Params {\r\n    /** The palette name which categorizes this RenderMaterial */\r\n    public paletteName: string;\r\n    /** The optional description for this RenderMaterial */\r\n    public description?: string;\r\n    /** If defined, use this color for surface fill or diffuse illumination; if undefined, defaults to black */\r\n    public color?: number[];\r\n    /** If defined, use this color for surface specular illumination; if undefined, defaults to black */\r\n    public specularColor?: number[];\r\n    /** If defined, apply this specular exponent(surface shininess); range is 0 to 128; if undefined, defaults to 15.0 * 0.9  */\r\n    public finish?: number;\r\n    /** If defined, apply this surface transparency; if undefined, defaults to 0.0 */\r\n    public transmit?: number;\r\n    /** If defined, apply this surface diffuse reflectivity; if undefined, defaults to 0.6 */\r\n    public diffuse?: number;\r\n    /** If defined, apply this surface specular reflectivity; if undefined, defaults to 0.0.  NOTE: The actual JSON allows a HasSpecular property to be true and the specular value itself undefined, in which case the value 0.4 would be used.  This API does not allow this case. */\r\n    public specular?: number;\r\n    /** If defined, apply this surface environmental reflectivity; stored as fraction of specular in V8 material settings; if undefined, defaults to 0.0 */\r\n    public reflect?: number;\r\n    /** If defined, apply this surface reflectance color; if undefined, defaults to whatever the specularColor is */\r\n    public reflectColor?: number[];\r\n    /** If defined, specifies the pattern mapping. */\r\n    public patternMap?: TextureMapProps;\r\n\r\n    /** Construct a new RenderMaterial.Params object with the specified paletteName.  Alter the public members on that object to specify settings. */\r\n    public constructor(paletteName: string) {\r\n      this.paletteName = paletteName;\r\n    }\r\n  }\r\n}\r\n"]}
+{"version":3,"file":"Material.js","sourceRoot":"","sources":["../../src/Material.ts"],"names":[],"mappings":"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","sourcesContent":["/*---------------------------------------------------------------------------------------------\r\n* Copyright (c) Bentley Systems, Incorporated. All rights reserved.\r\n* See LICENSE.md in the project root for license terms and full copyright notice.\r\n*--------------------------------------------------------------------------------------------*/\r\n/** @packageDocumentation\r\n * @module Elements\r\n */\r\n\r\nimport { Id64String } from \"@itwin/core-bentley\";\r\nimport { BisCodeSpec, Code, CodeScopeProps, CodeSpec, DefinitionElementProps, RenderMaterialProps, TextureMapProps } from \"@itwin/core-common\";\r\nimport { DefinitionElement } from \"./Element\";\r\nimport { IModelDb } from \"./IModelDb\";\r\n\r\n/* eslint-disable @typescript-eslint/naming-convention */\r\n\r\n/** A PhysicalMaterial defines the matter that makes up physical elements.\r\n * @note See [[RenderMaterialElement]] for the DefinitionElement used to define rendering characteristics.\r\n * @public\r\n */\r\nexport abstract class PhysicalMaterial extends DefinitionElement {\r\n  /** @internal */\r\n  public static override get className(): string { return \"PhysicalMaterial\"; }\r\n  /** Create a Code for a PhysicalMaterial given a name that is meant to be unique within the scope of the specified DefinitionModel.\r\n   * @param iModel  The IModelDb\r\n   * @param definitionModelId The Id of the DefinitionModel that will contain the PhysicalMaterial and provide the scope for its name.\r\n   * @param name The name (codeValue) of the PhysicalMaterial\r\n   */\r\n  public static createCode(iModel: IModelDb, definitionModelId: CodeScopeProps, name: string): Code {\r\n    const codeSpec: CodeSpec = iModel.codeSpecs.getByName(BisCodeSpec.physicalMaterial);\r\n    return new Code({ spec: codeSpec.id, scope: definitionModelId, value: name });\r\n  }\r\n  /** Create a PhysicalMaterial\r\n   * @param iModelDb The IModelDb\r\n   * @param definitionModelId The Id of the DefinitionModel that will contain the PhysicalMaterial and provide the scope for its name.\r\n   * @param name The name (codeValue) of the PhysicalMaterial\r\n   * @returns The newly constructed PhysicalMaterial\r\n   * @throws [[IModelError]] if there is a problem creating the PhysicalMaterial\r\n   */\r\n  public static create<T extends PhysicalMaterial>(iModelDb: IModelDb, definitionModelId: CodeScopeProps, name: string): T {\r\n    const elementProps: DefinitionElementProps = {\r\n      classFullName: this.classFullName,\r\n      model: definitionModelId,\r\n      code: this.createCode(iModelDb, definitionModelId, name),\r\n    };\r\n    return iModelDb.elements.createElement(elementProps);\r\n  }\r\n}\r\n\r\n/** Defines a rendering material.\r\n * @note See [[PhysicalMaterial]] for the DefinitionElement used to define the matter that makes up physical elements.\r\n * @public\r\n */\r\nexport class RenderMaterialElement extends DefinitionElement {\r\n  /** @internal */\r\n  public static override get className(): string { return \"RenderMaterial\"; }\r\n\r\n  /** The name of a palette that can be used to categorize multiple materials. */\r\n  public paletteName: string;\r\n  /** An optional description of the material. */\r\n  public description?: string;\r\n  /** @internal */\r\n  constructor(props: RenderMaterialProps, iModel: IModelDb) {\r\n    super(props, iModel);\r\n    this.paletteName = props.paletteName;\r\n    this.description = props.description;\r\n  }\r\n  /** @internal */\r\n  public override toJSON(): RenderMaterialProps {\r\n    const val = super.toJSON() as RenderMaterialProps;\r\n    val.paletteName = this.paletteName;\r\n    val.description = this.description;\r\n    return val;\r\n  }\r\n  /** Create a Code for a RenderMaterial given a name that is meant to be unique within the scope of the specified DefinitionModel.\r\n   * @param iModel  The IModelDb\r\n   * @param scopeModelId The Id of the DefinitionModel that contains the RenderMaterial and provides the scope for its name.\r\n   * @param name The RenderMaterial name\r\n   */\r\n  public static createCode(iModel: IModelDb, scopeModelId: CodeScopeProps, name: string): Code {\r\n    const codeSpec: CodeSpec = iModel.codeSpecs.getByName(BisCodeSpec.texture);\r\n    return 0 === name.length ? Code.createEmpty() : new Code({ spec: codeSpec.id, scope: scopeModelId, value: name });\r\n  }\r\n  /**\r\n   * Create a RenderMaterial with given parameters.\r\n   * @param iModelDb The iModel\r\n   * @param definitionModelId The [[DefinitionModel]]\r\n   * @param materialName The name/CodeValue of the RenderMaterial\r\n   * @param params Parameters object which describes how to construct the RenderMaterial\r\n   * @returns The newly constructed RenderMaterial element.\r\n   * @throws [[IModelError]] if unable to create the element.\r\n   */\r\n  public static create(iModelDb: IModelDb, definitionModelId: Id64String, materialName: string, params: RenderMaterialElement.Params): RenderMaterialElement {\r\n    const map = undefined !== params.patternMap ? { Pattern: params.patternMap } : undefined;\r\n    const renderMaterialProps: RenderMaterialProps = {\r\n      classFullName: this.classFullName,\r\n      code: this.createCode(iModelDb, definitionModelId, materialName),\r\n      paletteName: params.paletteName,\r\n      description: params.description,\r\n      jsonProperties: {\r\n        materialAssets: {\r\n          renderMaterial: {\r\n            HasBaseColor: params.color !== undefined,\r\n            color: params.color,\r\n            HasSpecularColor: params.specularColor !== undefined,\r\n            specular_color: params.specularColor,\r\n            HasFinish: params.finish !== undefined,\r\n            finish: params.finish,\r\n            HasTransmit: params.transmit !== undefined,\r\n            transmit: params.transmit,\r\n            HasDiffuse: params.diffuse !== undefined,\r\n            diffuse: params.diffuse,\r\n            HasSpecular: params.specular !== undefined,\r\n            specular: params.specular,\r\n            HasReflect: params.reflect !== undefined,\r\n            reflect: params.reflect,\r\n            HasReflectColor: params.reflectColor !== undefined,\r\n            reflect_color: params.reflectColor,\r\n            Map: map,\r\n          },\r\n        },\r\n      },\r\n      model: definitionModelId,\r\n      isPrivate: false,\r\n    };\r\n    return new RenderMaterialElement(renderMaterialProps, iModelDb);\r\n  }\r\n  /**\r\n   * Insert a new RenderMaterial into a model.\r\n   * @param iModelDb Insert into this iModel\r\n   * @param definitionModelId Insert the new Texture into this DefinitionModel\r\n   * @param materialName The name/CodeValue of the RenderMaterial\r\n   * @param params Parameters object which describes how to construct the RenderMaterial\r\n   * @returns The Id of the newly inserted RenderMaterial element.\r\n   * @throws [[IModelError]] if unable to insert the element.\r\n   */\r\n  public static insert(iModelDb: IModelDb, definitionModelId: Id64String, materialName: string, params: RenderMaterialElement.Params): Id64String {\r\n    const renderMaterial = this.create(iModelDb, definitionModelId, materialName, params);\r\n    return iModelDb.elements.insertElement(renderMaterial.toJSON());\r\n  }\r\n}\r\n\r\n/** @public\r\n * @note color, specularColor and reflectColor are stored as [R,G,B] where each value is between 0 and 1\r\n*/\r\nexport namespace RenderMaterialElement { // eslint-disable-line no-redeclare\r\n  /** Parameters used to construct a [[RenderMaterial]]. */\r\n  export class Params {\r\n    /** The palette name which categorizes this RenderMaterial */\r\n    public paletteName: string;\r\n    /** The optional description for this RenderMaterial */\r\n    public description?: string;\r\n    /** If defined, use this color for surface fill or diffuse illumination; if undefined, defaults to black */\r\n    public color?: number[];\r\n    /** If defined, use this color for surface specular illumination; if undefined, defaults to black */\r\n    public specularColor?: number[];\r\n    /** If defined, apply this specular exponent(surface shininess); range is 0 to 128; if undefined, defaults to 15.0 * 0.9  */\r\n    public finish?: number;\r\n    /** If defined, apply this surface transparency; if undefined, defaults to 0.0 */\r\n    public transmit?: number;\r\n    /** If defined, apply this surface diffuse reflectivity; if undefined, defaults to 0.6 */\r\n    public diffuse?: number;\r\n    /** If defined, apply this surface specular reflectivity; if undefined, defaults to 0.0.  NOTE: The actual JSON allows a HasSpecular property to be true and the specular value itself undefined, in which case the value 0.4 would be used.  This API does not allow this case. */\r\n    public specular?: number;\r\n    /** If defined, apply this surface environmental reflectivity; stored as fraction of specular in V8 material settings; if undefined, defaults to 0.0 */\r\n    public reflect?: number;\r\n    /** If defined, apply this surface reflectance color; if undefined, defaults to whatever the specularColor is */\r\n    public reflectColor?: number[];\r\n    /** If defined, specifies the pattern mapping. */\r\n    public patternMap?: TextureMapProps;\r\n\r\n    /** Construct a new RenderMaterial.Params object with the specified paletteName.  Alter the public members on that object to specify settings. */\r\n    public constructor(paletteName: string) {\r\n      this.paletteName = paletteName;\r\n    }\r\n  }\r\n}\r\n"]}

package/lib/cjs/PropertyStore.d.ts

@@ -0,0 +1,134 @@
+import { CloudSqlite } from "@bentley/imodeljs-native";
+import { AccessToken } from "@itwin/core-bentley";
+import { SQLiteDb } from "./SQLiteDb";
+import { SettingObject } from "./workspace/Settings";
+/**
+ * A persistent storage for a set of values of type `PropertyType`, each with a unique `PropertyName`.
+ * `PropertyStore`s are stored in cloud containers, and require an access token that grants permission to read and/or write them.
+ * All write operations will fail without an access token that grants write permission.
+ * A `PropertyStore` is cached on a local drive so reads are fast and inexpensive, and may even be done offline after a prefetch.
+ * However, that means that callers are responsible for synchronizing the local cache to ensure it includes changes
+ * made by others, as appropriate (see [[synchronizeWithCloud]]).
+ * @alpha */
+export interface PropertyStore {
+    /** The collection of property values in the PropertyStore as of the last time it was synchronized. */
+    readonly values: PropertyStore.Values;
+    /** Application-supplied parameters for obtaining the write lock on the container for a PropertyStore.*/
+    readonly appParams: SQLiteDb.ObtainLockParams;
+    /**
+     * The token that grants access to the cloud container for this PropertyStore. If it does not grant write permissions, all
+     * write operations will fail. It should be refreshed (via a timer) before it expires.
+     */
+    sasToken: AccessToken;
+    /**
+     * Synchronize the local values in this PropertyStore with any changes by made by others.
+     * @note This is called automatically whenever any write operation is performed on the PropertyStore. It is only necessary to
+     * call this directly if you have not changed the PropertyStore recently, but wish to perform a readonly operation and want to
+     * ensure it is up-to-date as of now.
+     * @note There is no guarantee that the Values are up-to-date even immediately after calling this method, since others
+     * may be modifying them at any time.
+     */
+    synchronizeWithCloud(): void;
+    /** initiate a prefetch operation on this PropertyStore
+     * @internal
+     */
+    startPrefetch(): SQLiteDb.CloudPrefetch;
+    /** Save a single property in this PropertyStore. If the property already exists, its value is overwritten.
+     * @note This will obtain the write lock, save the value, and then release the write lock.
+     */
+    saveProperty(name: PropertyStore.PropertyName, value: PropertyStore.PropertyType): Promise<void>;
+    /** Save an array of properties in this PropertyStore. If a property already exists, its value is overwritten.
+     * @note This will obtain the write lock, save the values, and then release the write lock.
+     */
+    saveProperties(props: PropertyStore.PropertyArray): Promise<void>;
+    /** Delete a single property from this PropertyStore. If the value does not exist, this method does nothing.
+     * @note This will obtain the write lock, delete the value, and then release the write lock.
+     */
+    deleteProperty(propName: PropertyStore.PropertyName): Promise<void>;
+    /** Delete an array of properties from this PropertyStore. Any value that does not exist is ignored.
+     * @note This will obtain the write lock, delete the values, and then release the write lock.
+     */
+    deleteProperties(propNames: PropertyStore.PropertyName[]): Promise<void>;
+}
+/** @alpha */
+export declare namespace PropertyStore {
+    /** @internal */
+    let openPropertyStore: ((props: CloudSqlite.ContainerAccessProps) => PropertyStore) | undefined;
+    /** The set of valid types for properties in a PropertyStore. */
+    type PropertyType = string | number | boolean | Uint8Array | SettingObject;
+    /** The name of a Property. May not have leading or trailing spaces, and must be between 3 and 2048 characters long. */
+    type PropertyName = string;
+    /** An array of PropertyName/PropertyType pairs to be stored in a PropertyStore. */
+    type PropertyArray = {
+        name: PropertyName;
+        value: PropertyType;
+    }[];
+    /** The return status of an iteration function. The value "stop" causes the iteration to terminate. */
+    type IterationReturn = void | "stop";
+    /** An iteration function over Properties in a PropertyStore. It is called with the name of a each Property. */
+    type PropertyIteration = (name: string) => IterationReturn;
+    /** A filter used to limit and/or sort the values returned by an iteration. */
+    interface PropertyFilter {
+        /** A value filter. May include wild cards when used with `GLOB` or `LIKE` */
+        readonly value?: string;
+        /** The comparison operator for `value`. Default is `=` */
+        readonly valueCompare?: "GLOB" | "LIKE" | "NOT GLOB" | "NOT LIKE" | "=" | "<" | ">";
+        /** Order results ascending or descending. If not supplied, the results are unordered (random). */
+        readonly orderBy?: "ASC" | "DESC";
+        /** An SQL expression to further filter results. This string is appended to the `WHERE` clause with an `AND` (that should not be part of the sqlExpression) */
+        readonly sqlExpression?: string;
+    }
+    /**
+     * A readonly set of Property values in a PropertyStore.
+     * @alpha
+     */
+    interface Values {
+        /** get the value of a Property by name.
+         * @returns the property's value if it exists, `undefined` otherwise.
+         */
+        getProperty(name: PropertyName): PropertyType | undefined;
+        /** Get the value of a string property by name.
+        * @returns the property's value if it exists and is a string, `undefined` otherwise.
+        */
+        getString(name: PropertyName): string | undefined;
+        /** Get the value of a string property by name.
+        * @returns the property's value if it exists and is a string, otherwise the supplied default value.
+        */
+        getString(name: PropertyName, defaultValue: string): string;
+        /** Get the value of a boolean property by name.
+        * @returns the property's value if it exists and is a boolean, `undefined` otherwise.
+        */
+        getBoolean(name: PropertyName): boolean | undefined;
+        /** Get the value of a boolean property by name.
+        * @returns the property's value if it exists and is a boolean, otherwise the supplied default value.
+        */
+        getBoolean(name: PropertyName, defaultValue: boolean): boolean;
+        /** Get the value of a number property by name.
+        * @returns the property's value if it exists and is a number, `undefined` otherwise.
+        */
+        getNumber(name: PropertyName): number | undefined;
+        /** Get the value of a number property by name.
+        * @returns the property's value if it exists and is a number, otherwise the supplied default value.
+        */
+        getNumber(name: PropertyName, defaultValue: number): number;
+        /** Get the value of a blob property by name.
+        * @returns the property's value if it exists and is a blob, `undefined` otherwise.
+        */
+        getBlob(name: PropertyName): Uint8Array | undefined;
+        /** Get the value of a blob property by name.
+        * @returns the property's value if it exists and is a blob, otherwise the supplied default value.
+        */
+        getBlob(name: PropertyName, defaultValue: Uint8Array): Uint8Array;
+        /** Get the value of an object property by name.
+        * @returns the property's value if it exists and is an object, `undefined` otherwise.
+        */
+        getObject<T extends SettingObject>(name: PropertyName): T | undefined;
+        /** Get the value of an object property by name.
+        * @returns the property's value if it exists and is an object, otherwise the supplied default value.
+        */
+        getObject<T extends SettingObject>(name: PropertyName, defaultValue: T): T;
+        /** call an iteration function for each property, optionally applying a filter */
+        forAllProperties(iter: PropertyIteration, filter?: PropertyFilter): void;
+    }
+}
+//# sourceMappingURL=PropertyStore.d.ts.map

package/lib/cjs/PropertyStore.d.ts.map

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

package/lib/cjs/PropertyStore.js

@@ -0,0 +1,12 @@
+"use strict";
+/*---------------------------------------------------------------------------------------------
+* Copyright (c) Bentley Systems, Incorporated. All rights reserved.
+* See LICENSE.md in the project root for license terms and full copyright notice.
+*--------------------------------------------------------------------------------------------*/
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PropertyStore = void 0;
+/** @alpha */
+var PropertyStore;
+(function (PropertyStore) {
+})(PropertyStore = exports.PropertyStore || (exports.PropertyStore = {}));
+//# sourceMappingURL=PropertyStore.js.map

package/lib/cjs/PropertyStore.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"PropertyStore.js","sourceRoot":"","sources":["../../src/PropertyStore.ts"],"names":[],"mappings":";AAAA;;;+FAG+F;;;AA8D/F,aAAa;AACb,IAAiB,aAAa,CA+E7B;AA/ED,WAAiB,aAAa;AA+E9B,CAAC,EA/EgB,aAAa,GAAb,qBAAa,KAAb,qBAAa,QA+E7B","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\r\nimport { CloudSqlite } from \"@bentley/imodeljs-native\";\r\nimport { AccessToken } from \"@itwin/core-bentley\";\r\nimport { SQLiteDb } from \"./SQLiteDb\";\r\nimport { SettingObject } from \"./workspace/Settings\";\r\n\r\n/**\r\n * A persistent storage for a set of values of type `PropertyType`, each with a unique `PropertyName`.\r\n * `PropertyStore`s are stored in cloud containers, and require an access token that grants permission to read and/or write them.\r\n * All write operations will fail without an access token that grants write permission.\r\n * A `PropertyStore` is cached on a local drive so reads are fast and inexpensive, and may even be done offline after a prefetch.\r\n * However, that means that callers are responsible for synchronizing the local cache to ensure it includes changes\r\n * made by others, as appropriate (see [[synchronizeWithCloud]]).\r\n * @alpha */\r\nexport interface PropertyStore {\r\n\r\n  /** The collection of property values in the PropertyStore as of the last time it was synchronized. */\r\n  readonly values: PropertyStore.Values;\r\n\r\n  /** Application-supplied parameters for obtaining the write lock on the container for a PropertyStore.*/\r\n  readonly appParams: SQLiteDb.ObtainLockParams;\r\n\r\n  /**\r\n   * The token that grants access to the cloud container for this PropertyStore. If it does not grant write permissions, all\r\n   * write operations will fail. It should be refreshed (via a timer) before it expires.\r\n   */\r\n  sasToken: AccessToken;\r\n\r\n  /**\r\n   * Synchronize the local values in this PropertyStore with any changes by made by others.\r\n   * @note This is called automatically whenever any write operation is performed on the PropertyStore. It is only necessary to\r\n   * call this directly if you have not changed the PropertyStore recently, but wish to perform a readonly operation and want to\r\n   * ensure it is up-to-date as of now.\r\n   * @note There is no guarantee that the Values are up-to-date even immediately after calling this method, since others\r\n   * may be modifying them at any time.\r\n   */\r\n  synchronizeWithCloud(): void;\r\n\r\n  /** initiate a prefetch operation on this PropertyStore\r\n   * @internal\r\n   */\r\n  startPrefetch(): SQLiteDb.CloudPrefetch;\r\n\r\n  /** Save a single property in this PropertyStore. If the property already exists, its value is overwritten.\r\n   * @note This will obtain the write lock, save the value, and then release the write lock.\r\n   */\r\n  saveProperty(name: PropertyStore.PropertyName, value: PropertyStore.PropertyType): Promise<void>;\r\n  /** Save an array of properties in this PropertyStore. If a property already exists, its value is overwritten.\r\n   * @note This will obtain the write lock, save the values, and then release the write lock.\r\n   */\r\n  saveProperties(props: PropertyStore.PropertyArray): Promise<void>;\r\n  /** Delete a single property from this PropertyStore. If the value does not exist, this method does nothing.\r\n   * @note This will obtain the write lock, delete the value, and then release the write lock.\r\n   */\r\n  deleteProperty(propName: PropertyStore.PropertyName): Promise<void>;\r\n  /** Delete an array of properties from this PropertyStore. Any value that does not exist is ignored.\r\n   * @note This will obtain the write lock, delete the values, and then release the write lock.\r\n   */\r\n  deleteProperties(propNames: PropertyStore.PropertyName[]): Promise<void>;\r\n}\r\n\r\n/** @alpha */\r\nexport namespace PropertyStore {\r\n  /** @internal */\r\n  export let openPropertyStore: ((props: CloudSqlite.ContainerAccessProps) => PropertyStore) | undefined;\r\n\r\n  /** The set of valid types for properties in a PropertyStore. */\r\n  export type PropertyType = string | number | boolean | Uint8Array | SettingObject;\r\n  /** The name of a Property. May not have leading or trailing spaces, and must be between 3 and 2048 characters long. */\r\n  export type PropertyName = string;\r\n  /** An array of PropertyName/PropertyType pairs to be stored in a PropertyStore. */\r\n  export type PropertyArray = { name: PropertyName, value: PropertyType }[];\r\n  /** The return status of an iteration function. The value \"stop\" causes the iteration to terminate. */\r\n  export type IterationReturn = void | \"stop\";\r\n  /** An iteration function over Properties in a PropertyStore. It is called with the name of a each Property. */\r\n  export type PropertyIteration = (name: string) => IterationReturn;\r\n\r\n  /** A filter used to limit and/or sort the values returned by an iteration. */\r\n  export interface PropertyFilter {\r\n    /** A value filter. May include wild cards when used with `GLOB` or `LIKE` */\r\n    readonly value?: string;\r\n    /** The comparison operator for `value`. Default is `=` */\r\n    readonly valueCompare?: \"GLOB\" | \"LIKE\" | \"NOT GLOB\" | \"NOT LIKE\" | \"=\" | \"<\" | \">\";\r\n    /** Order results ascending or descending. If not supplied, the results are unordered (random). */\r\n    readonly orderBy?: \"ASC\" | \"DESC\";\r\n    /** An SQL expression to further filter results. This string is appended to the `WHERE` clause with an `AND` (that should not be part of the sqlExpression) */\r\n    readonly sqlExpression?: string;\r\n  }\r\n\r\n  /**\r\n   * A readonly set of Property values in a PropertyStore.\r\n   * @alpha\r\n   */\r\n  export interface Values {\r\n    /** get the value of a Property by name.\r\n     * @returns the property's value if it exists, `undefined` otherwise.\r\n     */\r\n    getProperty(name: PropertyName): PropertyType | undefined;\r\n    /** Get the value of a string property by name.\r\n    * @returns the property's value if it exists and is a string, `undefined` otherwise.\r\n    */\r\n    getString(name: PropertyName): string | undefined;\r\n    /** Get the value of a string property by name.\r\n    * @returns the property's value if it exists and is a string, otherwise the supplied default value.\r\n    */\r\n    getString(name: PropertyName, defaultValue: string): string;\r\n    /** Get the value of a boolean property by name.\r\n    * @returns the property's value if it exists and is a boolean, `undefined` otherwise.\r\n    */\r\n    getBoolean(name: PropertyName): boolean | undefined;\r\n    /** Get the value of a boolean property by name.\r\n    * @returns the property's value if it exists and is a boolean, otherwise the supplied default value.\r\n    */\r\n    getBoolean(name: PropertyName, defaultValue: boolean): boolean;\r\n    /** Get the value of a number property by name.\r\n    * @returns the property's value if it exists and is a number, `undefined` otherwise.\r\n    */\r\n    getNumber(name: PropertyName): number | undefined;\r\n    /** Get the value of a number property by name.\r\n    * @returns the property's value if it exists and is a number, otherwise the supplied default value.\r\n    */\r\n    getNumber(name: PropertyName, defaultValue: number): number;\r\n    /** Get the value of a blob property by name.\r\n    * @returns the property's value if it exists and is a blob, `undefined` otherwise.\r\n    */\r\n    getBlob(name: PropertyName): Uint8Array | undefined;\r\n    /** Get the value of a blob property by name.\r\n    * @returns the property's value if it exists and is a blob, otherwise the supplied default value.\r\n    */\r\n    getBlob(name: PropertyName, defaultValue: Uint8Array): Uint8Array;\r\n    /** Get the value of an object property by name.\r\n    * @returns the property's value if it exists and is an object, `undefined` otherwise.\r\n    */\r\n    getObject<T extends SettingObject>(name: PropertyName): T | undefined;\r\n    /** Get the value of an object property by name.\r\n    * @returns the property's value if it exists and is an object, otherwise the supplied default value.\r\n    */\r\n    getObject<T extends SettingObject>(name: PropertyName, defaultValue: T): T;\r\n    /** call an iteration function for each property, optionally applying a filter */\r\n    forAllProperties(iter: PropertyIteration, filter?: PropertyFilter): void;\r\n  }\r\n}\r\n"]}

package/lib/cjs/SQLiteDb.d.ts

@@ -36,55 +36,44 @@ export declare class SQLiteDb implements IDisposable {
      */
     openDb(dbName: string, openMode: OpenMode | SQLiteDb.OpenParams, container?: SQLiteDb.CloudContainer): void;
     /** Close SQLiteDb.
-     * @param saveChanges if true, call `saveChanges` before closing db.
+     * @param saveChanges if true, call `saveChanges` before closing db. Otherwise unsaved changes are abandoned.
      */
     closeDb(saveChanges?: boolean): void;
-    /** Returns true if the SQLiteDb is open */
+    /** Returns true if this SQLiteDb is open */
     get isOpen(): boolean;
+    /** Returns true if this SQLiteDb is open readonly */
+    get isReadonly(): boolean;
     /**
-     * 1. open a database
-     * 2. call a function supplying the open SQliteDb as argument. If it is async, await its return.
-     * 3. close the database (even if exceptions are thrown)
+     * Open a database, perform an operation, then close the database.
+     *
+     * Details:
+     * - if database is open, throw an error
+     * - open a database
+     * - call a function with the database opened. If it is async, await its return.
+     * - if function throws, abandon all changes, close database, and rethrow
+     * - save all changes
+     * - close the database
+     * @return value from operation
      */
-    static withOpenDb<T>(args: {
-        /** The name of the database to open */
-        dbName: string;
-        /** either an object with the open parameters or just OpenMode value. */
-        openMode?: OpenMode | SQLiteDb.OpenParams;
-        /** @internal */
-        container?: SQLiteDb.CloudContainer;
-    }, operation: (db: SQLiteDb) => T): T;
+    withOpenDb<T>(args: SQLiteDb.WithOpenDbArgs, operation: () => T): T;
     /**
-     * 1. acquire the write lock on a CloudContainer
-     * 2. open a ReadWrite database in the container
-     * 3. call a function with the opened database as an argument
-     * 4. close the database
-     * 5. release the write lock and upload changes.
+     * Perform an operation on a database in a CloudContainer with the write lock held.
+     *
+     * Details:
+     * - acquire the write lock on a CloudContainer
+     * - call `withOpenDb` with openMode `ReadWrite`
+     * - upload changes
+     * - release the write lock
+     * @param args arguments to lock the container and open the database
+     * @param operation an operation performed on the database with the write lock held.
+     * @return value from operation
      * @internal
      */
-    static withLockedContainer(args: {
-        /** the name to be displayed in the event of lock collisions */
-        user: string;
-        /** the name of the database within the container */
-        dbName: string;
-        /** the CloudContainer on which the operation will be performed */
-        container: SQLiteDb.CloudContainer;
-        /** if present, function called when the write lock is currently held by another user. */
-        busyHandler?: CloudSqlite.WriteLockBusyHandler;
-    }, 
-    /** an asynchronous operation performed on the database with the write lock held. */
-    operation: (db: SQLiteDb) => Promise<void>): Promise<void>;
+    withLockedContainer<T>(args: SQLiteDb.LockAndOpenArgs, operation: () => T): Promise<T>;
     /** vacuum this database
      * @see https://www.sqlite.org/lang_vacuum.html
      */
-    vacuum(args?: {
-        /** new page size
-         * @see https://www.sqlite.org/pragma.html#pragma_page_size
-         */
-        pageSize?: number;
-        /** if present, name of new file to vacuum into */
-        into?: LocalFileName;
-    }): void;
+    vacuum(args?: SQLiteDb.VacuumDbArgs): void;
     /** Commit the outermost transaction, writing changes to the file. Then, restart the transaction. */
     saveChanges(): void;
     /** Abandon (cancel) the outermost transaction, discarding all changes since last save. Then, restart the transaction. */
@@ -109,6 +98,12 @@ export declare class SQLiteDb implements IDisposable {
      * @returns the value returned by `callback`.
      */
     withSqliteStatement<T>(sql: string, callback: (stmt: SqliteStatement) => T): T;
+    /**
+     * Perform an operation on this database within a [savepoint](https://www.sqlite.org/lang_savepoint.html). If the operation completes successfully, the
+     * changes remain in the current transaction. If the operation throws an exception, the savepoint is rolled back
+     * and all changes to the database from this method are reversed, leaving the transaction exactly as it was before this method.
+     */
+    withSavePoint(savePointName: string, operation: () => void): void;
     /** Prepare an SQL statement.
        * @param sql The SQLite SQL statement to prepare
        * @param logErrors Determine if errors are logged or not
@@ -165,10 +160,54 @@ export declare namespace SQLiteDb {
         /** use OpenMode.ReadWrite to open the file with write access */
         openMode: OpenMode;
     }
-    /** Parameters for creating a new SQLiteDb */
-    interface CreateParams extends OpenOrCreateParams {
+    /** Size of a SQLiteDb page in bytes */
+    interface PageSize {
         /** see https://www.sqlite.org/pragma.html#pragma_page_size */
         pageSize?: number;
     }
+    /** Parameters for creating a new SQLiteDb */
+    type CreateParams = OpenOrCreateParams & PageSize;
+    /** Parameters used to obtain the write lock on a cloud container
+     * @internal
+     */
+    interface ObtainLockParams {
+        /** The name of the user attempting to acquire the write lock. This name will be shown to other users while the lock is held. */
+        user?: string;
+        /** number of times to retry in the event the lock currently held by someone else.
+       * After this number of attempts, `onFailure` is called. Default is 20.
+       */
+        nRetries: number;
+        /** Delay between retries, in milliseconds. Default is 100. */
+        retryDelayMs: number;
+        /** function called if lock cannot be obtained after all retries. It is called with the name of the user currently holding the lock and
+       * generally is expected that the user will be consulted whether to wait further.
+       * If this function returns "stop", an exception will be thrown. Otherwise the retry cycle is restarted. */
+        onFailure?: CloudSqlite.WriteLockBusyHandler;
+    }
+    /** @internal */
+    interface LockAndOpenArgs {
+        /** the name to be displayed in the event of lock collisions */
+        user: string;
+        /** the name of the database within the container */
+        dbName: string;
+        /** the CloudContainer on which the operation will be performed */
+        container: SQLiteDb.CloudContainer;
+        /** if present, function called when the write lock is currently held by another user. */
+        busyHandler?: CloudSqlite.WriteLockBusyHandler;
+    }
+    /** Arguments for `SqliteDb.withOpenDb` */
+    interface WithOpenDbArgs {
+        /** The name of the database to open */
+        dbName: string;
+        /** either an object with the open parameters or just OpenMode value. */
+        openMode?: OpenMode | SQLiteDb.OpenParams;
+        /** @internal */
+        container?: SQLiteDb.CloudContainer;
+    }
+    /** Arguments for `SQLiteDb.vacuum` */
+    interface VacuumDbArgs extends PageSize {
+        /** if present, name of new file to [vacuum into](https://www.sqlite.org/lang_vacuum.html) */
+        into?: LocalFileName;
+    }
 }
 //# sourceMappingURL=SQLiteDb.d.ts.map

package/lib/cjs/SQLiteDb.d.ts.map

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

package/lib/cjs/SQLiteDb.js

@@ -12,6 +12,7 @@ const imodeljs_native_1 = require("@bentley/imodeljs-native");
 const core_bentley_1 = require("@itwin/core-bentley");
 const IModelHost_1 = require("./IModelHost");
 const SqliteStatement_1 = require("./SqliteStatement");
+// cspell:ignore savepoint
 /* eslint-disable @typescript-eslint/unified-signatures */
 /** A SQLiteDb file
  * @public
@@ -53,7 +54,7 @@ class SQLiteDb {
         this.nativeDb.openDb(dbName, openMode, container);
     }
     /** Close SQLiteDb.
-     * @param saveChanges if true, call `saveChanges` before closing db.
+     * @param saveChanges if true, call `saveChanges` before closing db. Otherwise unsaved changes are abandoned.
      */
     closeDb(saveChanges) {
         if (saveChanges && this.isOpen)
@@ -61,45 +62,53 @@ class SQLiteDb {
         this._sqliteStatementCache.clear();
         this.nativeDb.closeDb();
     }
-    /** Returns true if the SQLiteDb is open */
+    /** Returns true if this SQLiteDb is open */
     get isOpen() { return this.nativeDb.isOpen(); }
+    /** Returns true if this SQLiteDb is open readonly */
+    get isReadonly() { return this.nativeDb.isReadonly(); }
     /**
-     * 1. open a database
-     * 2. call a function supplying the open SQliteDb as argument. If it is async, await its return.
-     * 3. close the database (even if exceptions are thrown)
+     * Open a database, perform an operation, then close the database.
+     *
+     * Details:
+     * - if database is open, throw an error
+     * - open a database
+     * - call a function with the database opened. If it is async, await its return.
+     * - if function throws, abandon all changes, close database, and rethrow
+     * - save all changes
+     * - close the database
+     * @return value from operation
      */
-    static withOpenDb(args, operation) {
+    withOpenDb(args, operation) {
         var _a;
-        const db = new SQLiteDb();
-        db.openDb(args.dbName, (_a = args.openMode) !== null && _a !== void 0 ? _a : core_bentley_1.OpenMode.Readonly, args.container);
-        let fromPromise = false;
+        if (this.isOpen)
+            throw new Error("database is already open");
+        const save = () => this.closeDb(true), abandon = () => this.closeDb(false);
+        this.openDb(args.dbName, (_a = args.openMode) !== null && _a !== void 0 ? _a : core_bentley_1.OpenMode.Readonly, args.container);
         try {
-            const result = operation(db);
-            if (result instanceof Promise) {
-                fromPromise = true;
-                const doClose = () => db.closeDb();
-                result.then(doClose, doClose);
-            }
+            const result = operation();
+            result instanceof Promise ? result.then(save, abandon) : save();
             return result;
         }
-        finally {
-            if (!fromPromise)
-                db.closeDb();
+        catch (e) {
+            abandon();
+            throw e;
         }
     }
     /**
-     * 1. acquire the write lock on a CloudContainer
-     * 2. open a ReadWrite database in the container
-     * 3. call a function with the opened database as an argument
-     * 4. close the database
-     * 5. release the write lock and upload changes.
+     * Perform an operation on a database in a CloudContainer with the write lock held.
+     *
+     * Details:
+     * - acquire the write lock on a CloudContainer
+     * - call `withOpenDb` with openMode `ReadWrite`
+     * - upload changes
+     * - release the write lock
+     * @param args arguments to lock the container and open the database
+     * @param operation an operation performed on the database with the write lock held.
+     * @return value from operation
      * @internal
      */
-    static async withLockedContainer(args, 
-    /** an asynchronous operation performed on the database with the write lock held. */
-    operation) {
-        const fn = async () => SQLiteDb.withOpenDb({ ...args, openMode: core_bentley_1.OpenMode.ReadWrite }, operation);
-        await imodeljs_native_1.CloudSqlite.withWriteLock(args.user, args.container, fn, args.busyHandler);
+    async withLockedContainer(args, operation) {
+        return imodeljs_native_1.CloudSqlite.withWriteLock(args.user, args.container, () => this.withOpenDb({ ...args, openMode: core_bentley_1.OpenMode.ReadWrite }, operation), args.busyHandler);
     }
     /** vacuum this database
      * @see https://www.sqlite.org/lang_vacuum.html
@@ -131,12 +140,7 @@ class SQLiteDb {
         const release = () => this._sqliteStatementCache.addOrDispose(stmt);
         try {
             const val = callback(stmt);
-            if (val instanceof Promise) {
-                val.then(release, release);
-            }
-            else {
-                release();
-            }
+            val instanceof Promise ? val.then(release, release) : release();
             return val;
         }
         catch (err) {
@@ -157,12 +161,7 @@ class SQLiteDb {
         const release = () => stmt.dispose();
         try {
             const val = callback(stmt);
-            if (val instanceof Promise) {
-                val.then(release, release);
-            }
-            else {
-                release();
-            }
+            val instanceof Promise ? val.then(release, release) : release();
             return val;
         }
         catch (err) {
@@ -170,6 +169,24 @@ class SQLiteDb {
             throw err;
         }
     }
+    /**
+     * Perform an operation on this database within a [savepoint](https://www.sqlite.org/lang_savepoint.html). If the operation completes successfully, the
+     * changes remain in the current transaction. If the operation throws an exception, the savepoint is rolled back
+     * and all changes to the database from this method are reversed, leaving the transaction exactly as it was before this method.
+     */
+    withSavePoint(savePointName, operation) {
+        if (this.isReadonly)
+            throw new Error("database is readonly");
+        this.executeSQL(`SAVEPOINT ${savePointName}`);
+        try {
+            operation();
+            this.executeSQL(`RELEASE ${savePointName}`);
+        }
+        catch (e) {
+            this.executeSQL(`ROLLBACK TO ${savePointName}`);
+            throw e;
+        }
+    }
     /** Prepare an SQL statement.
        * @param sql The SQLite SQL statement to prepare
        * @param logErrors Determine if errors are logged or not