@itwin/core-backend 4.0.0-dev.1 → 4.0.0-dev.100

package/lib/cjs/PropertyStore.js

@@ -1,12 +1,180 @@
-"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 = {}));
+"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;
+/** @packageDocumentation
+ * @module SQLiteDb
+ */
+const core_bentley_1 = require("@itwin/core-bentley");
+const CloudSqlite_1 = require("./CloudSqlite");
+const SQLiteDb_1 = require("./SQLiteDb");
+/** @beta */
+var PropertyStore;
+(function (PropertyStore) {
+    /**
+     * A SQLite database for storing PropertyName/PropertyValue pairs.
+     */
+    class PropertyDb extends SQLiteDb_1.VersionedSqliteDb {
+        constructor() {
+            super(...arguments);
+            this.myVersion = "3.0.0";
+        }
+        createDDL() {
+            this.createTable({ tableName: "properties", columns: "name TEXT NOT NULL PRIMARY KEY,type,value", addTimestamp: true });
+        }
+        /** get the value of a Property by name.
+         * @returns the property's value if it exists, `undefined` otherwise.
+         */
+        getProperty(name) {
+            return this.withPreparedSqliteStatement("SELECT type,value from properties WHERE name=?", (stmt) => {
+                stmt.bindString(1, name);
+                if (!stmt.nextRow())
+                    return undefined;
+                switch (stmt.getValueString(0)) {
+                    case "string":
+                        return stmt.getValueString(1);
+                    case "boolean":
+                        return stmt.getValueInteger(1) !== 0;
+                    case "blob":
+                        return stmt.getValueBlob(1);
+                    case "number":
+                        return stmt.getValueDouble(1);
+                    case "object":
+                        return JSON.parse(stmt.getValueString(1));
+                }
+                return undefined;
+            });
+        }
+        getString(name, defaultValue) {
+            const out = this.getProperty(name);
+            return typeof out === "string" ? out : defaultValue;
+        }
+        getBoolean(name, defaultValue) {
+            const out = this.getProperty(name);
+            return typeof out === "boolean" ? out : defaultValue;
+        }
+        getNumber(name, defaultValue) {
+            const out = this.getProperty(name);
+            return typeof out === "number" ? out : defaultValue;
+        }
+        getBlob(name, defaultValue) {
+            const out = this.getProperty(name);
+            return out instanceof Uint8Array ? out : defaultValue;
+        }
+        getObject(name, defaultValue) {
+            const out = this.getProperty(name);
+            return typeof out === "object" ? out : defaultValue;
+        }
+        /** call an iteration function for each property, optionally applying a filter */
+        forAllProperties(iter, filter) {
+            let sql = "SELECT name FROM properties WHERE name IS NOT NULL";
+            if (filter?.sqlExpression)
+                sql += ` AND ${filter.sqlExpression} `;
+            if (filter?.value)
+                sql += ` AND name ${filter.valueCompare ?? "="} @val`;
+            if (filter?.orderBy)
+                sql += ` ORDER BY name ${filter.orderBy} `;
+            this.withSqliteStatement(sql, (stmt) => {
+                if (filter?.value)
+                    stmt.bindString("@val", filter.value);
+                while (stmt.nextRow()) {
+                    if (iter(stmt.getValueString(0)) === "stop")
+                        return;
+                }
+            });
+        }
+        /** Delete a single property from this PropertyDb. If the value does not exist, this method does nothing.
+         * @note the database must be opened for write
+         */
+        async deleteProperty(propName) {
+            this.withSqliteStatement("DELETE from properties WHERE name=?", (stmt) => {
+                stmt.bindString(1, propName);
+                stmt.step();
+            });
+        }
+        /** Delete an array of properties from this PropertyDb. Any value that does not exist is ignored.
+         * @note the database must be opened for write
+         */
+        async deleteProperties(propNames) {
+            propNames.forEach(async (name) => this.deleteProperty(name));
+        }
+        validateName(name) {
+            if (typeof name !== "string" || name.trim() !== name || name.length > 2 * 1024 || name.length < 2)
+                throw new Error(`illegal property name[${name}]`);
+        }
+        /** Save a single property in this PropertyDb. If the property already exists, its value is overwritten.
+         * @note the database must be opened for write
+         */
+        async saveProperty(name, value) {
+            this.validateName(name);
+            this.withSqliteStatement("INSERT OR REPLACE INTO properties(name,type,value) VALUES (?,?,?)", (stmt) => {
+                stmt.bindString(1, name);
+                switch (typeof value) {
+                    case "string":
+                        stmt.bindString(2, "string");
+                        stmt.bindString(3, value);
+                        break;
+                    case "boolean":
+                        stmt.bindString(2, "boolean");
+                        stmt.bindInteger(3, value ? 1 : 0);
+                        break;
+                    case "number":
+                        stmt.bindString(2, "number");
+                        stmt.bindDouble(3, value);
+                        break;
+                    case "object":
+                        if (value instanceof Uint8Array) {
+                            stmt.bindString(2, "blob");
+                            stmt.bindBlob(3, value);
+                        }
+                        else {
+                            stmt.bindString(2, "object");
+                            stmt.bindString(3, JSON.stringify(value));
+                        }
+                        break;
+                    default:
+                        throw new Error("illegal property value type");
+                }
+                const rc = stmt.step();
+                if (rc !== core_bentley_1.DbResult.BE_SQLITE_DONE)
+                    throw new core_bentley_1.BentleyError(rc, "error saving property");
+            });
+        }
+        /** Save an array of properties in this PropertyDb. If a property already exists, its value is overwritten.
+         * @note the database must be opened for write
+         */
+        async saveProperties(props) {
+            for (const prop of props)
+                await this.saveProperty(prop.name, prop.value);
+        }
+    }
+    PropertyStore.PropertyDb = PropertyDb;
+    const defaultDbName = "PropertyDb";
+    /**
+     * Provides access to a cloud-based `PropertyDb` to hold a set of values of type `PropertyType`, each with a unique `PropertyName`.
+     * `PropertyStore.PropertyDb`s that are stored in cloud containers 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.
+     *
+     * The database 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]]).
+     */
+    class CloudAccess extends CloudSqlite_1.CloudSqlite.DbAccess {
+        constructor(props) {
+            super({ dbType: PropertyDb, props, dbName: defaultDbName });
+        }
+        /**
+         * Initialize a cloud container for use as a PropertyStore. The container must first be created via its storage supplier api (e.g. Azure, or AWS).
+         * A valid sasToken that grants write access must be supplied. This function creates and uploads an empty PropertyDb into the container.
+         * @note this deletes any existing content in the container.
+         */
+        static async initializeDb(args) {
+            return super._initializeDb({ ...args, dbType: PropertyDb, dbName: defaultDbName });
+        }
+    }
+    PropertyStore.CloudAccess = CloudAccess;
+})(PropertyStore = exports.PropertyStore || (exports.PropertyStore = {}));
 //# sourceMappingURL=PropertyStore.js.map

package/lib/cjs/PropertyStore.js.map

@@ -1 +1 @@
-{"version":3,"file":"PropertyStore.js","sourceRoot":"","sources":["../../src/PropertyStore.ts"],"names":[],"mappings":";AAAA;;;+FAG+F;;;AA6D/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 { AccessToken } from \"@itwin/core-bentley\";\r\nimport { CloudSqlite } from \"./CloudSqlite\";\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  /** Parameters for obtaining the write lock on the container for a PropertyStore.*/\r\n  readonly lockParams: CloudSqlite.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(): CloudSqlite.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"]}
+{"version":3,"file":"PropertyStore.js","sourceRoot":"","sources":["../../src/PropertyStore.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\r\n/** @packageDocumentation\r\n * @module SQLiteDb\r\n */\r\n\r\nimport { BentleyError, DbResult } from \"@itwin/core-bentley\";\r\nimport { CloudSqlite } from \"./CloudSqlite\";\r\nimport { VersionedSqliteDb } from \"./SQLiteDb\";\r\nimport { SettingObject } from \"./workspace/Settings\";\r\n\r\n/** @beta */\r\nexport namespace PropertyStore {\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 case-sensitive 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 SQLite database for storing PropertyName/PropertyValue pairs.\r\n   */\r\n  export class PropertyDb extends VersionedSqliteDb {\r\n    public override readonly myVersion = \"3.0.0\";\r\n\r\n    protected override createDDL() {\r\n      this.createTable({ tableName: \"properties\", columns: \"name TEXT NOT NULL PRIMARY KEY,type,value\", addTimestamp: true });\r\n    }\r\n\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    public getProperty(name: PropertyName): PropertyType | undefined {\r\n      return this.withPreparedSqliteStatement(\"SELECT type,value from properties WHERE name=?\", (stmt) => {\r\n        stmt.bindString(1, name);\r\n        if (!stmt.nextRow())\r\n          return undefined;\r\n        switch (stmt.getValueString(0)) {\r\n          case \"string\":\r\n            return stmt.getValueString(1);\r\n          case \"boolean\":\r\n            return stmt.getValueInteger(1) !== 0;\r\n          case \"blob\":\r\n            return stmt.getValueBlob(1);\r\n          case \"number\":\r\n            return stmt.getValueDouble(1);\r\n          case \"object\":\r\n            return JSON.parse(stmt.getValueString(1)) as SettingObject;\r\n        }\r\n        return undefined;\r\n      });\r\n    }\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    public getString(name: PropertyName, defaultValue: string): string;\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    public getString(name: PropertyName): string | undefined;\r\n    public getString(name: PropertyName, defaultValue?: string): string | undefined {\r\n      const out = this.getProperty(name);\r\n      return typeof out === \"string\" ? out : defaultValue;\r\n    }\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    public 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    public getBoolean(name: PropertyName, defaultValue: boolean): boolean;\r\n    public getBoolean(name: PropertyName, defaultValue?: boolean): boolean | undefined {\r\n      const out = this.getProperty(name);\r\n      return typeof out === \"boolean\" ? out : defaultValue;\r\n    }\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    public 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    public getNumber(name: PropertyName, defaultValue: number): number;\r\n    public getNumber(name: PropertyName, defaultValue?: number): number | undefined {\r\n      const out = this.getProperty(name);\r\n      return typeof out === \"number\" ? out : defaultValue;\r\n    }\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    public 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    public getBlob(name: PropertyName, defaultValue: Uint8Array): Uint8Array;\r\n    public getBlob(name: PropertyName, defaultValue?: Uint8Array): Uint8Array | undefined {\r\n      const out = this.getProperty(name);\r\n      return out instanceof Uint8Array ? out : defaultValue;\r\n    }\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    public getObject(name: PropertyName): SettingObject | 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    public getObject(name: PropertyName, defaultValue: SettingObject): SettingObject;\r\n    public getObject(name: PropertyName, defaultValue?: SettingObject): SettingObject | undefined {\r\n      const out = this.getProperty(name);\r\n      return typeof out === \"object\" ? out as SettingObject : defaultValue;\r\n    }\r\n\r\n    /** call an iteration function for each property, optionally applying a filter */\r\n    public forAllProperties(iter: PropertyIteration, filter?: PropertyFilter) {\r\n      let sql = \"SELECT name FROM properties WHERE name IS NOT NULL\";\r\n      if (filter?.sqlExpression)\r\n        sql += ` AND ${filter.sqlExpression} `;\r\n      if (filter?.value)\r\n        sql += ` AND name ${filter.valueCompare ?? \"=\"} @val`;\r\n      if (filter?.orderBy)\r\n        sql += ` ORDER BY name ${filter.orderBy} `;\r\n\r\n      this.withSqliteStatement(sql, (stmt) => {\r\n        if (filter?.value)\r\n          stmt.bindString(\"@val\", filter.value);\r\n\r\n        while (stmt.nextRow()) {\r\n          if (iter(stmt.getValueString(0)) === \"stop\")\r\n            return;\r\n        }\r\n      });\r\n    }\r\n\r\n    /** Delete a single property from this PropertyDb. If the value does not exist, this method does nothing.\r\n     * @note the database must be opened for write\r\n     */\r\n    public async deleteProperty(propName: PropertyName) {\r\n      this.withSqliteStatement(\"DELETE from properties WHERE name=?\", (stmt) => {\r\n        stmt.bindString(1, propName);\r\n        stmt.step();\r\n      });\r\n    }\r\n    /** Delete an array of properties from this PropertyDb. Any value that does not exist is ignored.\r\n     * @note the database must be opened for write\r\n     */\r\n    public async deleteProperties(propNames: PropertyName[]) {\r\n      propNames.forEach(async (name) => this.deleteProperty(name));\r\n    }\r\n\r\n    private validateName(name: PropertyName) {\r\n      if (typeof name !== \"string\" || name.trim() !== name || name.length > 2 * 1024 || name.length < 2)\r\n        throw new Error(`illegal property name[${name}]`);\r\n    }\r\n\r\n    /** Save a single property in this PropertyDb. If the property already exists, its value is overwritten.\r\n     * @note the database must be opened for write\r\n     */\r\n    public async saveProperty(name: PropertyName, value: PropertyType) {\r\n      this.validateName(name);\r\n      this.withSqliteStatement(\"INSERT OR REPLACE INTO properties(name,type,value) VALUES (?,?,?)\", (stmt) => {\r\n        stmt.bindString(1, name);\r\n        switch (typeof value) {\r\n          case \"string\":\r\n            stmt.bindString(2, \"string\");\r\n            stmt.bindString(3, value);\r\n            break;\r\n          case \"boolean\":\r\n            stmt.bindString(2, \"boolean\");\r\n            stmt.bindInteger(3, value ? 1 : 0);\r\n            break;\r\n          case \"number\":\r\n            stmt.bindString(2, \"number\");\r\n            stmt.bindDouble(3, value);\r\n            break;\r\n          case \"object\":\r\n            if (value instanceof Uint8Array) {\r\n              stmt.bindString(2, \"blob\");\r\n              stmt.bindBlob(3, value);\r\n            } else {\r\n              stmt.bindString(2, \"object\");\r\n              stmt.bindString(3, JSON.stringify(value));\r\n            }\r\n            break;\r\n          default:\r\n            throw new Error(\"illegal property value type\");\r\n        }\r\n\r\n        const rc = stmt.step();\r\n        if (rc !== DbResult.BE_SQLITE_DONE)\r\n          throw new BentleyError(rc, \"error saving property\");\r\n      });\r\n    }\r\n\r\n    /** Save an array of properties in this PropertyDb. If a property already exists, its value is overwritten.\r\n     * @note the database must be opened for write\r\n     */\r\n    public async saveProperties(props: PropertyArray) {\r\n      for (const prop of props)\r\n        await this.saveProperty(prop.name, prop.value);\r\n    }\r\n  }\r\n\r\n  const defaultDbName = \"PropertyDb\" as const;\r\n\r\n  /**\r\n   * Provides access to a cloud-based `PropertyDb` to hold a set of values of type `PropertyType`, each with a unique `PropertyName`.\r\n   * `PropertyStore.PropertyDb`s that are stored in cloud containers 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   *\r\n   * The database 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   */\r\n  export class CloudAccess extends CloudSqlite.DbAccess<PropertyDb> {\r\n    public constructor(props: CloudSqlite.ContainerAccessProps) {\r\n      super({ dbType: PropertyDb, props, dbName: defaultDbName });\r\n    }\r\n\r\n    /**\r\n     * Initialize a cloud container for use as a PropertyStore. The container must first be created via its storage supplier api (e.g. Azure, or AWS).\r\n     * A valid sasToken that grants write access must be supplied. This function creates and uploads an empty PropertyDb into the container.\r\n     * @note this deletes any existing content in the container.\r\n     */\r\n    public static async initializeDb(args: { props: CloudSqlite.ContainerAccessProps, initContainer?: { blockSize?: number } }) {\r\n      return super._initializeDb({ ...args, dbType: PropertyDb, dbName: defaultDbName });\r\n    }\r\n  }\r\n}\r\n"]}