@itwin/core-backend/lib/esm/PropertyStore.d.ts

iTwin.js backend components

/** @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