@itwin/core-backend 5.0.0-dev.9 → 5.0.0-dev.92

package/lib/esm/PropertyStore.d.ts

@@ -0,0 +1,134 @@
+/** @packageDocumentation
+ * @module SQLiteDb
+ */
+import { BlobContainer } from "./BlobContainerService";
+import { CloudSqlite } from "./CloudSqlite";
+import { VersionedSqliteDb } from "./SQLiteDb";
+import { SettingsContainer } from "./workspace/Settings";
+/** @beta */
+export declare namespace PropertyStore {
+    /** The set of valid types for properties in a PropertyStore. */
+    type PropertyType = string | number | boolean | Uint8Array | SettingsContainer;
+    /** The case-sensitive 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 SQLite database for storing PropertyName/PropertyValue pairs.
+     */
+    class PropertyDb extends VersionedSqliteDb {
+        readonly myVersion = "3.0.0";
+        protected createDDL(): void;
+        /** 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, defaultValue: string): string;
+        /** 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): string | undefined;
+        /** 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(name: PropertyName): SettingsContainer | 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(name: PropertyName, defaultValue: SettingsContainer): SettingsContainer;
+        /** call an iteration function for each property, optionally applying a filter */
+        forAllProperties(iter: PropertyIteration, filter?: PropertyFilter): void;
+        /** 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
+         */
+        deleteProperty(propName: PropertyName): Promise<void>;
+        /** Delete an array of properties from this PropertyDb. Any value that does not exist is ignored.
+         * @note the database must be opened for write
+         */
+        deleteProperties(propNames: PropertyName[]): Promise<void>;
+        private validateName;
+        /** Save a single property in this PropertyDb. If the property already exists, its value is overwritten.
+         * @note the database must be opened for write
+         */
+        saveProperty(name: PropertyName, value: PropertyType): Promise<void>;
+        /** 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
+         */
+        saveProperties(props: PropertyArray): Promise<void>;
+    }
+    interface CreateNewContainerProps {
+        scope: BlobContainer.Scope;
+        metadata: Omit<BlobContainer.Metadata, "containerType">;
+    }
+    /**
+     * 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.DbAccess<PropertyDb> {
+        constructor(props: CloudSqlite.ContainerAccessProps);
+        /**
+         * Initialize a cloud container for use as a PropertyStore. This method is called by [[createNewContainer]].
+         * It is only necessary to convert an existing container to a PropertyStore container.
+         * @note this deletes any existing content in the container.
+         * @internal
+         */
+        static initializeDb(args: {
+            props: CloudSqlite.ContainerProps;
+        }): Promise<void>;
+        /** Create and initialize a new BlobContainer to hold a PropertyStore
+         * @note the current user must have administrator rights to create containers.
+         */
+        static createNewContainer(args: CreateNewContainerProps): Promise<CloudSqlite.ContainerProps>;
+    }
+}
+//# sourceMappingURL=PropertyStore.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"PropertyStore.d.ts","sourceRoot":"","sources":["../../src/PropertyStore.ts"],"names":[],"mappings":"AAKA;;GAEG;AAEH,OAAO,EAAE,aAAa,EAAE,MAAM,wBAAwB,CAAC;AACvD,OAAO,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAC5C,OAAO,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AAC/C,OAAO,EAAE,iBAAiB,EAAE,MAAM,sBAAsB,CAAC;AAEzD,YAAY;AACZ,yBAAiB,aAAa,CAAC;IAE7B,gEAAgE;IAChE,KAAY,YAAY,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,UAAU,GAAG,iBAAiB,CAAC;IACtF,sIAAsI;IACtI,KAAY,YAAY,GAAG,MAAM,CAAC;IAClC,mFAAmF;IACnF,KAAY,aAAa,GAAG;QAAE,IAAI,EAAE,YAAY,CAAC;QAAC,KAAK,EAAE,YAAY,CAAA;KAAE,EAAE,CAAC;IAC1E,sGAAsG;IACtG,KAAY,eAAe,GAAG,IAAI,GAAG,MAAM,CAAC;IAC5C,+GAA+G;IAC/G,KAAY,iBAAiB,GAAG,CAAC,IAAI,EAAE,MAAM,KAAK,eAAe,CAAC;IAElE,8EAA8E;IAC9E,UAAiB,cAAc;QAC7B,6EAA6E;QAC7E,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;QACxB,0DAA0D;QAC1D,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,UAAU,GAAG,UAAU,GAAG,GAAG,GAAG,IAAI,GAAG,GAAG,GAAG,GAAG,CAAC;QAC3F,kGAAkG;QAClG,QAAQ,CAAC,OAAO,CAAC,EAAE,KAAK,GAAG,MAAM,CAAC;QAClC,8JAA8J;QAC9J,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;KACjC;IAED;;OAEG;IACH,MAAa,UAAW,SAAQ,iBAAiB;QAC/C,SAAyB,SAAS,WAAW;kBAE1B,SAAS;QAI5B;;WAEG;QACI,WAAW,CAAC,IAAI,EAAE,YAAY,GAAG,YAAY,GAAG,SAAS;QAoBhE;;UAEE;QACK,SAAS,CAAC,IAAI,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,GAAG,MAAM;QAClE;;UAEE;QACK,SAAS,CAAC,IAAI,EAAE,YAAY,GAAG,MAAM,GAAG,SAAS;QAKxD;;UAEE;QACK,UAAU,CAAC,IAAI,EAAE,YAAY,GAAG,OAAO,GAAG,SAAS;QAC1D;;UAEE;QACK,UAAU,CAAC,IAAI,EAAE,YAAY,EAAE,YAAY,EAAE,OAAO,GAAG,OAAO;QAKrE;;UAEE;QACK,SAAS,CAAC,IAAI,EAAE,YAAY,GAAG,MAAM,GAAG,SAAS;QACxD;;UAEE;QACK,SAAS,CAAC,IAAI,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,GAAG,MAAM;QAKlE;;UAEE;QACK,OAAO,CAAC,IAAI,EAAE,YAAY,GAAG,UAAU,GAAG,SAAS;QAC1D;;UAEE;QACK,OAAO,CAAC,IAAI,EAAE,YAAY,EAAE,YAAY,EAAE,UAAU,GAAG,UAAU;QAKxE;;UAEE;QACK,SAAS,CAAC,IAAI,EAAE,YAAY,GAAG,iBAAiB,GAAG,SAAS;QACnE;;UAEE;QACK,SAAS,CAAC,IAAI,EAAE,YAAY,EAAE,YAAY,EAAE,iBAAiB,GAAG,iBAAiB;QAMxF,iFAAiF;QAC1E,gBAAgB,CAAC,IAAI,EAAE,iBAAiB,EAAE,MAAM,CAAC,EAAE,cAAc;QAoBxE;;WAEG;QACU,cAAc,CAAC,QAAQ,EAAE,YAAY;QAMlD;;WAEG;QACU,gBAAgB,CAAC,SAAS,EAAE,YAAY,EAAE;QAIvD,OAAO,CAAC,YAAY;QAKpB;;WAEG;QACU,YAAY,CAAC,IAAI,EAAE,YAAY,EAAE,KAAK,EAAE,YAAY;QAkCjE;;WAEG;QACU,cAAc,CAAC,KAAK,EAAE,aAAa;KAIjD;IAID,UAAiB,uBAAuB;QACtC,KAAK,EAAE,aAAa,CAAC,KAAK,CAAC;QAC3B,QAAQ,EAAE,IAAI,CAAC,aAAa,CAAC,QAAQ,EAAE,eAAe,CAAC,CAAC;KACzD;IAED;;;;;;;;OAQG;IACH,MAAa,WAAY,SAAQ,WAAW,CAAC,QAAQ,CAAC,UAAU,CAAC;oBAC5C,KAAK,EAAE,WAAW,CAAC,oBAAoB;QAI1D;;;;;WAKG;eACiB,YAAY,CAAC,IAAI,EAAE;YAAE,KAAK,EAAE,WAAW,CAAC,cAAc,CAAA;SAAE;QAI5E;;WAEG;eACiB,kBAAkB,CAAC,IAAI,EAAE,uBAAuB,GAAG,OAAO,CAAC,WAAW,CAAC,cAAc,CAAC;KAK3G;CACF"}

package/lib/esm/PropertyStore.js

@@ -0,0 +1,177 @@
+/*---------------------------------------------------------------------------------------------
+* Copyright (c) Bentley Systems, Incorporated. All rights reserved.
+* See LICENSE.md in the project root for license terms and full copyright notice.
+*--------------------------------------------------------------------------------------------*/
+import { CloudSqlite } from "./CloudSqlite";
+import { VersionedSqliteDb } from "./SQLiteDb";
+/** @beta */
+export var PropertyStore;
+(function (PropertyStore) {
+    /**
+     * A SQLite database for storing PropertyName/PropertyValue pairs.
+     */
+    class PropertyDb extends VersionedSqliteDb {
+        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.stepForWrite();
+            });
+        }
+        /** 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");
+                }
+                stmt.stepForWrite();
+            });
+        }
+        /** 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.DbAccess {
+        constructor(props) {
+            super({ dbType: PropertyDb, props, dbName: defaultDbName });
+        }
+        /**
+         * Initialize a cloud container for use as a PropertyStore. This method is called by [[createNewContainer]].
+         * It is only necessary to convert an existing container to a PropertyStore container.
+         * @note this deletes any existing content in the container.
+         * @internal
+         */
+        static async initializeDb(args) {
+            return super._initializeDb({ ...args, dbType: PropertyDb, dbName: defaultDbName });
+        }
+        /** Create and initialize a new BlobContainer to hold a PropertyStore
+         * @note the current user must have administrator rights to create containers.
+         */
+        static async createNewContainer(args) {
+            const props = await this.createBlobContainer({ scope: args.scope, metadata: { ...args.metadata, containerType: "property-store" } });
+            await this.initializeDb({ props });
+            return props;
+        }
+    }
+    PropertyStore.CloudAccess = CloudAccess;
+})(PropertyStore || (PropertyStore = {}));
+//# sourceMappingURL=PropertyStore.js.map

package/lib/esm/PropertyStore.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"PropertyStore.js","sourceRoot":"","sources":["../../src/PropertyStore.ts"],"names":[],"mappings":"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","sourcesContent":["/*---------------------------------------------------------------------------------------------\n* Copyright (c) Bentley Systems, Incorporated. All rights reserved.\n* See LICENSE.md in the project root for license terms and full copyright notice.\n*--------------------------------------------------------------------------------------------*/\n\n/** @packageDocumentation\n * @module SQLiteDb\n */\n\nimport { BlobContainer } from \"./BlobContainerService\";\nimport { CloudSqlite } from \"./CloudSqlite\";\nimport { VersionedSqliteDb } from \"./SQLiteDb\";\nimport { SettingsContainer } from \"./workspace/Settings\";\n\n/** @beta */\nexport namespace PropertyStore {\n\n  /** The set of valid types for properties in a PropertyStore. */\n  export type PropertyType = string | number | boolean | Uint8Array | SettingsContainer;\n  /** The case-sensitive name of a Property. May not have leading or trailing spaces, and must be between 3 and 2048 characters long. */\n  export type PropertyName = string;\n  /** An array of PropertyName/PropertyType pairs to be stored in a PropertyStore. */\n  export type PropertyArray = { name: PropertyName, value: PropertyType }[];\n  /** The return status of an iteration function. The value \"stop\" causes the iteration to terminate. */\n  export type IterationReturn = void | \"stop\";\n  /** An iteration function over Properties in a PropertyStore. It is called with the name of a each Property. */\n  export type PropertyIteration = (name: string) => IterationReturn;\n\n  /** A filter used to limit and/or sort the values returned by an iteration. */\n  export interface PropertyFilter {\n    /** A value filter. May include wild cards when used with `GLOB` or `LIKE` */\n    readonly value?: string;\n    /** The comparison operator for `value`. Default is `=` */\n    readonly valueCompare?: \"GLOB\" | \"LIKE\" | \"NOT GLOB\" | \"NOT LIKE\" | \"=\" | \"!=\" | \"<\" | \">\";\n    /** Order results ascending or descending. If not supplied, the results are unordered (random). */\n    readonly orderBy?: \"ASC\" | \"DESC\";\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) */\n    readonly sqlExpression?: string;\n  }\n\n  /**\n   * A SQLite database for storing PropertyName/PropertyValue pairs.\n   */\n  export class PropertyDb extends VersionedSqliteDb {\n    public override readonly myVersion = \"3.0.0\";\n\n    protected override createDDL() {\n      this.createTable({ tableName: \"properties\", columns: \"name TEXT NOT NULL PRIMARY KEY,type,value\", addTimestamp: true });\n    }\n\n    /** get the value of a Property by name.\n     * @returns the property's value if it exists, `undefined` otherwise.\n     */\n    public getProperty(name: PropertyName): PropertyType | undefined {\n      return this.withPreparedSqliteStatement(\"SELECT type,value from properties WHERE name=?\", (stmt) => {\n        stmt.bindString(1, name);\n        if (!stmt.nextRow())\n          return undefined;\n        switch (stmt.getValueString(0)) {\n          case \"string\":\n            return stmt.getValueString(1);\n          case \"boolean\":\n            return stmt.getValueInteger(1) !== 0;\n          case \"blob\":\n            return stmt.getValueBlob(1);\n          case \"number\":\n            return stmt.getValueDouble(1);\n          case \"object\":\n            return JSON.parse(stmt.getValueString(1)) as SettingsContainer;\n        }\n        return undefined;\n      });\n    }\n    /** Get the value of a string property by name.\n    * @returns the property's value if it exists and is a string, `undefined` otherwise.\n    */\n    public getString(name: PropertyName, defaultValue: string): string;\n    /** Get the value of a string property by name.\n    * @returns the property's value if it exists and is a string, otherwise the supplied default value.\n    */\n    public getString(name: PropertyName): string | undefined;\n    public getString(name: PropertyName, defaultValue?: string): string | undefined {\n      const out = this.getProperty(name);\n      return typeof out === \"string\" ? out : defaultValue;\n    }\n    /** Get the value of a boolean property by name.\n    * @returns the property's value if it exists and is a boolean, `undefined` otherwise.\n    */\n    public getBoolean(name: PropertyName): boolean | undefined;\n    /** Get the value of a boolean property by name.\n    * @returns the property's value if it exists and is a boolean, otherwise the supplied default value.\n    */\n    public getBoolean(name: PropertyName, defaultValue: boolean): boolean;\n    public getBoolean(name: PropertyName, defaultValue?: boolean): boolean | undefined {\n      const out = this.getProperty(name);\n      return typeof out === \"boolean\" ? out : defaultValue;\n    }\n    /** Get the value of a number property by name.\n    * @returns the property's value if it exists and is a number, `undefined` otherwise.\n    */\n    public getNumber(name: PropertyName): number | undefined;\n    /** Get the value of a number property by name.\n    * @returns the property's value if it exists and is a number, otherwise the supplied default value.\n    */\n    public getNumber(name: PropertyName, defaultValue: number): number;\n    public getNumber(name: PropertyName, defaultValue?: number): number | undefined {\n      const out = this.getProperty(name);\n      return typeof out === \"number\" ? out : defaultValue;\n    }\n    /** Get the value of a blob property by name.\n    * @returns the property's value if it exists and is a blob, `undefined` otherwise.\n    */\n    public getBlob(name: PropertyName): Uint8Array | undefined;\n    /** Get the value of a blob property by name.\n    * @returns the property's value if it exists and is a blob, otherwise the supplied default value.\n    */\n    public getBlob(name: PropertyName, defaultValue: Uint8Array): Uint8Array;\n    public getBlob(name: PropertyName, defaultValue?: Uint8Array): Uint8Array | undefined {\n      const out = this.getProperty(name);\n      return out instanceof Uint8Array ? out : defaultValue;\n    }\n    /** Get the value of an object property by name.\n    * @returns the property's value if it exists and is an object, `undefined` otherwise.\n    */\n    public getObject(name: PropertyName): SettingsContainer | undefined;\n    /** Get the value of an object property by name.\n    * @returns the property's value if it exists and is an object, otherwise the supplied default value.\n    */\n    public getObject(name: PropertyName, defaultValue: SettingsContainer): SettingsContainer;\n    public getObject(name: PropertyName, defaultValue?: SettingsContainer): SettingsContainer | undefined {\n      const out = this.getProperty(name);\n      return typeof out === \"object\" ? out as SettingsContainer : defaultValue;\n    }\n\n    /** call an iteration function for each property, optionally applying a filter */\n    public forAllProperties(iter: PropertyIteration, filter?: PropertyFilter) {\n      let sql = \"SELECT name FROM properties WHERE name IS NOT NULL\";\n      if (filter?.sqlExpression)\n        sql += ` AND ${filter.sqlExpression} `;\n      if (filter?.value)\n        sql += ` AND name ${filter.valueCompare ?? \"=\"} @val`;\n      if (filter?.orderBy)\n        sql += ` ORDER BY name ${filter.orderBy} `;\n\n      this.withSqliteStatement(sql, (stmt) => {\n        if (filter?.value)\n          stmt.bindString(\"@val\", filter.value);\n\n        while (stmt.nextRow()) {\n          if (iter(stmt.getValueString(0)) === \"stop\")\n            return;\n        }\n      });\n    }\n\n    /** Delete a single property from this PropertyDb. If the value does not exist, this method does nothing.\n     * @note the database must be opened for write\n     */\n    public async deleteProperty(propName: PropertyName) {\n      this.withSqliteStatement(\"DELETE from properties WHERE name=?\", (stmt) => {\n        stmt.bindString(1, propName);\n        stmt.stepForWrite();\n      });\n    }\n    /** Delete an array of properties from this PropertyDb. Any value that does not exist is ignored.\n     * @note the database must be opened for write\n     */\n    public async deleteProperties(propNames: PropertyName[]) {\n      propNames.forEach(async (name) => this.deleteProperty(name));\n    }\n\n    private validateName(name: PropertyName) {\n      if (typeof name !== \"string\" || name.trim() !== name || name.length > 2 * 1024 || name.length < 2)\n        throw new Error(`illegal property name[${name}]`);\n    }\n\n    /** Save a single property in this PropertyDb. If the property already exists, its value is overwritten.\n     * @note the database must be opened for write\n     */\n    public async saveProperty(name: PropertyName, value: PropertyType) {\n      this.validateName(name);\n      this.withSqliteStatement(\"INSERT OR REPLACE INTO properties(name,type,value) VALUES (?,?,?)\", (stmt) => {\n        stmt.bindString(1, name);\n        switch (typeof value) {\n          case \"string\":\n            stmt.bindString(2, \"string\");\n            stmt.bindString(3, value);\n            break;\n          case \"boolean\":\n            stmt.bindString(2, \"boolean\");\n            stmt.bindInteger(3, value ? 1 : 0);\n            break;\n          case \"number\":\n            stmt.bindString(2, \"number\");\n            stmt.bindDouble(3, value);\n            break;\n          case \"object\":\n            if (value instanceof Uint8Array) {\n              stmt.bindString(2, \"blob\");\n              stmt.bindBlob(3, value);\n            } else {\n              stmt.bindString(2, \"object\");\n              stmt.bindString(3, JSON.stringify(value));\n            }\n            break;\n          default:\n            throw new Error(\"illegal property value type\");\n        }\n\n        stmt.stepForWrite();\n      });\n    }\n\n    /** Save an array of properties in this PropertyDb. If a property already exists, its value is overwritten.\n     * @note the database must be opened for write\n     */\n    public async saveProperties(props: PropertyArray) {\n      for (const prop of props)\n        await this.saveProperty(prop.name, prop.value);\n    }\n  }\n\n  const defaultDbName = \"PropertyDb\";\n\n  export interface CreateNewContainerProps {\n    scope: BlobContainer.Scope;\n    metadata: Omit<BlobContainer.Metadata, \"containerType\">;\n  }\n\n  /**\n   * Provides access to a cloud-based `PropertyDb` to hold a set of values of type `PropertyType`, each with a unique `PropertyName`.\n   * `PropertyStore.PropertyDb`s that are stored in cloud containers require an access token that grants permission to read and/or write them.\n   * All write operations will fail without an access token that grants write permission.\n   *\n   * The database is cached on a local drive so reads are fast and inexpensive, and may even be done offline after a prefetch.\n   * However, that means that callers are responsible for synchronizing the local cache to ensure it includes changes\n   * made by others, as appropriate (see [[synchronizeWithCloud]]).\n   */\n  export class CloudAccess extends CloudSqlite.DbAccess<PropertyDb> {\n    public constructor(props: CloudSqlite.ContainerAccessProps) {\n      super({ dbType: PropertyDb, props, dbName: defaultDbName });\n    }\n\n    /**\n     * Initialize a cloud container for use as a PropertyStore. This method is called by [[createNewContainer]].\n     * It is only necessary to convert an existing container to a PropertyStore container.\n     * @note this deletes any existing content in the container.\n     * @internal\n     */\n    public static async initializeDb(args: { props: CloudSqlite.ContainerProps }) {\n      return super._initializeDb({ ...args, dbType: PropertyDb, dbName: defaultDbName });\n    }\n\n    /** Create and initialize a new BlobContainer to hold a PropertyStore\n     * @note the current user must have administrator rights to create containers.\n     */\n    public static async createNewContainer(args: CreateNewContainerProps): Promise<CloudSqlite.ContainerProps> {\n      const props = await this.createBlobContainer({ scope: args.scope, metadata: { ...args.metadata, containerType: \"property-store\" } });\n      await this.initializeDb({ props });\n      return props;\n    }\n  }\n}\n"]}