@itwin/core-backend 3.5.5 → 3.5.6

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

@@ -1,415 +1,415 @@
-/** @packageDocumentation
- * @module Workspace
- */
-import { AccessToken, BeEvent, Optional } from "@itwin/core-bentley";
-import { LocalDirName, LocalFileName } from "@itwin/core-common";
-import { CloudSqlite } from "../CloudSqlite";
-import { SQLiteDb } from "../SQLiteDb";
-import { Settings, SettingsPriority } from "./Settings";
-/** The Settings used by Workspace api
- * @beta
- */
-export declare const WorkspaceSetting: {
-    Accounts: string;
-    Containers: string;
-    Databases: string;
-};
-/** Types used to identify cloud accounts for Workspaces.
- *  @beta
- */
-export declare namespace WorkspaceAccount {
-    /** The name of a WorkspaceAccount in a "cloud/accounts" setting. */
-    type Name = string;
-    /** A member named `accountName` that specifies by an entry in a "cloud/accounts" setting */
-    interface Alias {
-        accountName: string;
-    }
-    /** The properties of a cloud account required to open containers with CloudSqlite. Usually supplied via a "cloud/accounts" setting. */
-    type Props = CloudSqlite.AccountAccessProps;
-}
-/** @beta */
-export declare namespace WorkspaceContainer {
-    /** The name of a WorkspaceContainer in a "cloud/containers" setting. */
-    type Name = string;
-    /** The unique identifier of a WorkspaceContainer. This becomes the base name for the local directory holding the WorkspaceDbs from a WorkspaceContainer.
-     * Usually supplied via the `containerId` member of a "cloud/containers" setting.
-     * `WorkspaceContainer.Id`s may:
-     *  - only contain lower case letters, numbers or dashes
-     *  - not start or end with a dash
-     *  - not be shorter than 3 or longer than 63 characters
-     */
-    type Id = string;
-    /** A member named `containerName` that specifies by an entry in a "cloud/containers" setting */
-    interface Alias {
-        containerName: string;
-    }
-    /** Properties that specify a WorkspaceContainer. */
-    interface Props extends Optional<CloudSqlite.ContainerProps, "accessToken"> {
-        /** true if the container is public (doesn't require authentication) */
-        isPublic?: boolean;
-        /** attempt to synchronize (i.e. call `checkForChanges`) this cloud container whenever it is connected to a cloud cache. Default=true */
-        syncOnConnect?: boolean;
-    }
-    /** A function to supply an [AccessToken]($bentley) for a `WorkspaceContainer`.
-     * @param props The properties of the WorkspaceContainer necessary to obtain the access token
-     * @param account The properties of the account for the container
-     * @returns a Promise that resolves to the AccessToken for the container.
-     */
-    type TokenFunc = (props: Props, account: WorkspaceAccount.Props) => Promise<AccessToken>;
-}
-/** @beta */
-export declare namespace WorkspaceDb {
-    /** The name of a WorkspaceDb in a "workspace/databases" setting. */
-    type Name = string;
-    /** The base name of a WorkspaceDb within a WorkspaceContainer (without any version identifier) */
-    type DbName = string;
-    /** The  name of a WorkspaceDb within a WorkspaceContainer, including the version identifier */
-    type DbFullName = string;
-    /** The semver-format version identifier for a WorkspaceDb. */
-    type Version = string;
-    /** The [semver range format](https://github.com/npm/node-semver) identifier for a range of acceptable versions. */
-    type VersionRange = string;
-    /** Properties that specify how to load a WorkspaceDb within a [[WorkspaceContainer]]. */
-    interface Props extends CloudSqlite.DbNameProp {
-        /** a semver version range specifier that determines the acceptable range of versions to load. If not present, use the newest version. */
-        version?: VersionRange;
-        /** if true, allow semver *prerelease* versions. By default only released version are allowed. */
-        includePrerelease?: boolean;
-    }
-    /** Scope to increment for a version number.
-     * @see semver.ReleaseType
-     */
-    type VersionIncrement = "major" | "minor" | "patch";
-}
-/** Types used to identify Workspace resources
- *  @beta
- */
-export declare namespace WorkspaceResource {
-    /**
-     * The name for identifying WorkspaceResources in a [[WorkspaceDb]].
-     * * `WorkspaceResource.Name`s may not:
-     *  - be blank or start or end with a space
-     *  - be longer than 1024 characters
-     * @note a single WorkspaceDb may hold WorkspaceResources of type 'blob', 'string' and 'file', all with the same WorkspaceResource.Name.
-     */
-    type Name = string;
-    /** Properties that specify an individual WorkspaceResource within a [[WorkspaceDb]]. */
-    interface Props {
-        /** the name of the resource within the WorkspaceDb */
-        rscName: Name;
-    }
-}
-/**
- * A WorkspaceDb holds workspace resources. `WorkspaceDb`s may just be local files, or they may be stored
- * in cloud WorkspaceContainers. Each `WorkspaceResource` in a WorkspaceDb is identified by a [[WorkspaceResource.Name]].
- * Resources of type `string` and `blob` may be loaded directly from the `WorkspaceDb`. Resources of type `file` are
- * copied from the WorkspaceDb into a temporary local file so they can be accessed by programs directly from disk.
- * @beta
- */
-export interface WorkspaceDb {
-    /** The WorkspaceContainer holding this WorkspaceDb. */
-    readonly container: WorkspaceContainer;
-    /** The base name of this WorkspaceDb, without version */
-    readonly dbName: WorkspaceDb.DbName;
-    /** event raised before this WorkspaceDb is closed. */
-    readonly onClose: BeEvent<() => void>;
-    /** Name by which a WorkspaceDb may be opened. This will be either a local file name or the name of a database in a cloud container */
-    readonly dbFileName: string;
-    /** Get a string resource from this WorkspaceDb, if present. */
-    getString(rscName: WorkspaceResource.Name): string | undefined;
-    /** Get a blob resource from this WorkspaceDb, if present. */
-    getBlob(rscName: WorkspaceResource.Name): Uint8Array | undefined;
-    /** @internal */
-    getBlobReader(rscName: WorkspaceResource.Name): SQLiteDb.BlobIO;
-    /**
-     * Extract a local copy of a file resource from this WorkspaceDb, if present.
-     * @param rscName The name of the file resource in the WorkspaceDb
-     * @param targetFileName optional name for extracted file. Some applications require files in specific locations or filenames. If
-     * you know the full path to use for the extracted file, you can supply it. Generally, it is best to *not* supply the filename and
-     * keep the extracted files in the  filesDir.
-     * @returns the full path to a file on the local filesystem.
-     * @note The file is copied from the file into the local filesystem so it may be accessed directly. This happens only
-     * as necessary, if the local file doesn't exist, or if it is out-of-date because it was updated in the file.
-     * For this reason, you should not save the local file name, and instead call this method every time you access it, so its
-     * content is always holds the correct version.
-     * @note The filename will be a hash value, not the resource name.
-     * @note Workspace resource files are set readonly as they are copied from the file.
-     * To edit them, you must first copy them to another location.
-     */
-    getFile(rscName: WorkspaceResource.Name, targetFileName?: LocalFileName): LocalFileName | undefined;
-    /**
-     * Ensure that the contents of a `WorkspaceDb` are downloaded into the local cache so that it may be accessed offline.
-     * Until the promise is resolved, the `WorkspaceDb` is not fully downloaded, but it *may* be safely accessed during the download.
-     * To determine the progress of the download, use the `localBlocks` and `totalBlocks` values returned by `CloudContainer.queryDatabase`.
-     * @returns a `CloudSqlite.CloudPrefetch` object that can be used to await and/or cancel the prefetch.
-     * @throws if this WorkspaceDb is not from a `CloudContainer`.
-     */
-    prefetch(): CloudSqlite.CloudPrefetch;
-}
-/** The properties of the CloudCache used for Workspaces.
- * @beta
- */
-export interface WorkspaceCloudCacheProps extends Optional<CloudSqlite.CacheProps, "name" | "rootDir"> {
-    /** if true, empty the cache before using it. */
-    clearContents?: boolean;
-}
-/**
- * Options for constructing a [[Workspace]].
- * @beta
- */
-export interface WorkspaceOpts {
-    /** The local directory for non-cloud-based WorkspaceDb files. The workspace api will look in this directory
-     * for files named `${containerId}/${dbId}.itwin-workspace`.
-     * @note if not supplied, defaults to `iTwin/Workspace` in the user-local folder.
-     */
-    containerDir?: LocalDirName;
-    /** the local fileName(s) of one or more settings files to load after the Workspace is first created. */
-    settingsFiles?: LocalFileName | [LocalFileName];
-    /**
-     * only for tests
-     * @internal */
-    testCloudCache?: CloudSqlite.CloudCache;
-}
-/**
- * Settings and resources that customize an application for the current session.
- * See [Workspaces]($docs/learning/backend/Workspace)
- * @beta
- */
-export interface Workspace {
-    /** The directory for local WorkspaceDb files with the name `${containerId}/${dbId}.itwin-workspace`. */
-    readonly containerDir: LocalDirName;
-    /** The [[Settings]] for this Workspace */
-    readonly settings: Settings;
-    /** The CloudCache for cloud-based WorkspaceContainers */
-    readonly cloudCache?: CloudSqlite.CloudCache;
-    /** search for a previously opened container.
-     * @param containerId the id of the container
-     * @returns the [[WorkspaceContainer]] for `containerId` if it was not previously opened with [[getContainer]]
-     */
-    findContainer(containerId: WorkspaceContainer.Id): WorkspaceContainer | undefined;
-    /** get a [[WorkspaceContainer]] by [[WorkspaceContainer.Props]]
-     * @param props the properties of the `WorkspaceContainer`. If `props.containerId` was already opened, its WorkspaceContainer is returned.
-     * Otherwise it is created.
-     * @param account If present, the properties for this container if it is to be opened from the cloud. If not present, the container is just a local directory.
-    */
-    getContainer(props: WorkspaceContainer.Props, account?: WorkspaceAccount.Props): WorkspaceContainer;
-    /** get the properties for the supplied account name by searching for an entry with that name in a `cloud/accounts` setting. */
-    resolveAccount(accountName: WorkspaceAccount.Name): WorkspaceAccount.Props;
-    /** get the properties for the supplied container name by searching for an entry with that name in a `cloud/containers` setting. */
-    resolveContainer(containerName: WorkspaceContainer.Name): WorkspaceContainer.Props & WorkspaceAccount.Alias;
-    /** get the properties for the supplied workspace database name by searching for an entry with that name in a `workspace/databases` setting. */
-    resolveDatabase(databaseAlias: WorkspaceDb.Name): WorkspaceDb.Props & WorkspaceContainer.Alias;
-    /**
-     * Get an opened [[WorkspaceDb]]. If the WorkspaceDb is present but not open, it is opened first.
-     * If `cloudProps` are supplied, a CloudContainer will be used to open the WorkspaceDb.
-     */
-    getWorkspaceDbFromProps(dbProps: WorkspaceDb.Props, containerProps: WorkspaceContainer.Props, account?: WorkspaceAccount.Props): WorkspaceDb;
-    /** Get an opened [[WorkspaceDb]] from a WorkspaceDb alias.
-     * @param dbAlias the database alias, resolved via [[resolveDatabase]].
-     * @param tokenFunc optional function to obtain an AccessToken for the resolved WorkspaceContainer. This function will only be called the first
-     * time a container is used.
-     */
-    getWorkspaceDb(dbAlias: WorkspaceDb.Name, tokenFunc?: WorkspaceContainer.TokenFunc): Promise<WorkspaceDb>;
-    /** Load a WorkspaceResource of type string, parse it, and add it to the current Settings for this Workspace.
-     * @note settingsRsc must specify a resource holding a stringified JSON representation of a [[SettingDictionary]]
-     */
-    loadSettingsDictionary(settingRsc: WorkspaceResource.Name, db: WorkspaceDb, priority: SettingsPriority): void;
-    /** Close this Workspace. All WorkspaceContainers are dropped. */
-    close(): void;
-}
-/**
- * A WorkspaceContainer holds WorkspaceDbs.
- * Access rights are administered per WorkspaceContainer. That is, if a user has rights to access a WorkspaceContainer, that right
- * applies to all WorkspaceDbs in the WorkspaceContainer.
- * @beta
- */
-export interface WorkspaceContainer {
-    /** the local directory where this WorkspaceContainer will store temporary files extracted for file-resources. */
-    readonly filesDir: LocalDirName;
-    /** The unique identifier for a WorkspaceContainer a cloud storage account. */
-    readonly id: WorkspaceContainer.Id;
-    /** Workspace holding this WorkspaceContainer. */
-    readonly workspace: Workspace;
-    /** CloudContainer for this WorkspaceContainer (`undefined` if this is a local WorkspaceContainer.)
-     * @internal
-    */
-    readonly cloudContainer?: CloudSqlite.CloudContainer;
-    /** @internal */
-    addWorkspaceDb(toAdd: ITwinWorkspaceDb): void;
-    /** @internal */
-    resolveDbFileName(props: WorkspaceDb.Props): string;
-    /** find or open a WorkspaceDb from this WorkspaceContainer. */
-    getWorkspaceDb(props: WorkspaceDb.Props): WorkspaceDb;
-    /** Close and remove a currently opened [[WorkspaceDb]] from this Workspace. */
-    dropWorkspaceDb(container: WorkspaceDb): void;
-    /** Close this WorkspaceContainer. All currently opened WorkspaceDbs are dropped. */
-    close(): void;
-}
-/** @internal */
-export declare class ITwinWorkspace implements Workspace {
-    private _containers;
-    readonly containerDir: LocalDirName;
-    readonly settings: Settings;
-    private static _sharedCloudCache?;
-    private _cloudCache?;
-    get cloudCache(): CloudSqlite.CloudCache;
-    private static getSharedCloudCache;
-    static finalize(): void;
-    constructor(settings: Settings, opts?: WorkspaceOpts);
-    addContainer(toAdd: ITwinWorkspaceContainer): void;
-    findContainer(containerId: WorkspaceContainer.Id): ITwinWorkspaceContainer | undefined;
-    getContainer(props: WorkspaceContainer.Props, account?: WorkspaceAccount.Props): WorkspaceContainer;
-    getWorkspaceDbFromProps(dbProps: WorkspaceDb.Props, containerProps: WorkspaceContainer.Props, account?: WorkspaceAccount.Props): WorkspaceDb;
-    getWorkspaceDb(dbAlias: string, tokenFunc?: WorkspaceContainer.TokenFunc): Promise<WorkspaceDb>;
-    loadSettingsDictionary(settingRsc: WorkspaceResource.Name, db: WorkspaceDb, priority: SettingsPriority): void;
-    close(): void;
-    resolveAccount(accountName: string): WorkspaceAccount.Props;
-    resolveContainer(containerName: string): WorkspaceContainer.Props & WorkspaceAccount.Alias;
-    resolveDatabase(databaseName: string): WorkspaceDb.Props & WorkspaceContainer.Alias;
-}
-/** @internal */
-export declare class ITwinWorkspaceContainer implements WorkspaceContainer {
-    readonly workspace: ITwinWorkspace;
-    readonly filesDir: LocalDirName;
-    readonly id: WorkspaceContainer.Id;
-    readonly cloudContainer?: CloudSqlite.CloudContainer | undefined;
-    private _wsDbs;
-    get dirName(): string;
-    static noLeadingOrTrailingSpaces(name: string, msg: string): void;
-    /** rules for ContainerIds (from Azure, see https://docs.microsoft.com/en-us/rest/api/storageservices/naming-and-referencing-containers--blobs--and-metadata)
-     *  - may only contain lower case letters, numbers or dashes
-     *  - may not start or end with with a dash nor have more than one dash in a row
-     *  - may not be shorter than 3 or longer than 63 characters
-     */
-    private static validateContainerId;
-    static validateDbName(dbName: WorkspaceDb.DbName): void;
-    constructor(workspace: ITwinWorkspace, props: WorkspaceContainer.Props, account?: WorkspaceAccount.Props);
-    static validateVersion(version?: WorkspaceDb.Version): string;
-    static parseDbFileName(dbFileName: WorkspaceDb.DbFullName): {
-        dbName: WorkspaceDb.DbName;
-        version: WorkspaceDb.Version;
-    };
-    static makeDbFileName(dbName: WorkspaceDb.DbName, version?: WorkspaceDb.Version): WorkspaceDb.DbName;
-    static resolveCloudFileName(cloudContainer: CloudSqlite.CloudContainer, props: WorkspaceDb.Props): WorkspaceDb.DbFullName;
-    /**
-     * Create a copy of an existing [[WorkspaceDb]] in a cloud container with a new version number.
-     * @param cloudContainer The attached cloud container holding the existing WorkspaceDb
-     * @param fromProps Properties that describe the source WorkspaceDb for the new version
-     * @param versionType The type of version increment to apply to the existing version.
-     * @note This requires that the cloudContainer is attached and the write lock on the container be held. The copy should be modified with
-     * new content before the write lock is released, and thereafter should never be modified again.
-     */
-    static makeNewVersion(cloudContainer: CloudSqlite.CloudContainer, fromProps: WorkspaceDb.Props, versionType: WorkspaceDb.VersionIncrement): Promise<{
-        oldName: string;
-        newName: string;
-    }>;
-    /**
-     * Convert a WorkspaceDb.Props specification into a DbFileName. For cloud-based containers, this resolves to the dbName, incorporating the appropriate
-     * version. For file-based containers, this returns a local filename of a WorkspaceDb file with the extension ".itwin-workspace"
-     */
-    resolveDbFileName(props: WorkspaceDb.Props): WorkspaceDb.DbFullName;
-    addWorkspaceDb(toAdd: ITwinWorkspaceDb): void;
-    getWorkspaceDb(props: WorkspaceDb.Props): WorkspaceDb;
-    dropWorkspaceDb(toDrop: WorkspaceDb): void;
-    close(): void;
-    /** Delete all local files extracted by [[WorkspaceDb.getFile]] for this container. */
-    purgeContainerFiles(): void;
-}
-/**
- * Implementation of WorkspaceDb
- * @internal
- */
-export declare class ITwinWorkspaceDb implements WorkspaceDb {
-    /** file extension for local WorkspaceDbs */
-    static readonly fileExt = "itwin-workspace";
-    /** the SQLiteDb for this WorkspaceDb*/
-    readonly sqliteDb: SQLiteDb;
-    /** the base WorkspaceDb name, without directory, extension, or version information. */
-    readonly dbName: WorkspaceDb.DbName;
-    /** The WorkspaceContainer holding this WorkspaceDb */
-    readonly container: WorkspaceContainer;
-    /** called before db is closed */
-    readonly onClose: BeEvent<() => void>;
-    /** either a local file name or the name of the file in a cloud container, including version identifier */
-    dbFileName: string;
-    /** true if this WorkspaceDb is currently open */
-    get isOpen(): boolean;
-    queryFileResource(rscName: WorkspaceResource.Name): {
-        localFileName: string;
-        info: import("@bentley/imodeljs-native").IModelJsNative.EmbedFileQuery;
-    } | undefined;
-    constructor(props: WorkspaceDb.Props, container: WorkspaceContainer);
-    open(): void;
-    close(): void;
-    getString(rscName: WorkspaceResource.Name): string | undefined;
-    /** Get a BlobIO reader for a blob WorkspaceResource.
-     * @note when finished, caller *must* call `close` on the BlobIO.
-     */
-    getBlobReader(rscName: WorkspaceResource.Name): SQLiteDb.BlobIO;
-    getBlob(rscName: WorkspaceResource.Name): Uint8Array | undefined;
-    getFile(rscName: WorkspaceResource.Name, targetFileName?: LocalFileName): LocalFileName | undefined;
-    prefetch(opts?: CloudSqlite.PrefetchProps): CloudSqlite.CloudPrefetch;
-}
-/**
- * An editable [[WorkspaceDb]]. This is used by administrators for creating and modifying `WorkspaceDb`s.
- * For cloud-backed containers, the write token must be obtained before this class may be used. Only one user at at time
- * may be editing.
- * @internal
- */
-export declare class EditableWorkspaceDb extends ITwinWorkspaceDb {
-    private static validateResourceName;
-    private validateResourceSize;
-    open(): void;
-    private getFileModifiedTime;
-    private performWriteSql;
-    createDb(version?: string): Promise<void>;
-    /** Create a new, empty, EditableWorkspaceDb for importing Workspace resources. */
-    static createEmpty(fileName: LocalFileName): void;
-    /** Add a new string resource to this WorkspaceDb.
-     * @param rscName The name of the string resource.
-     * @param val The string to save.
-     */
-    addString(rscName: WorkspaceResource.Name, val: string): void;
-    /** Update an existing string resource with a new value.
-     * @param rscName The name of the string resource.
-     * @param val The new value.
-     * @throws if rscName does not exist
-     */
-    updateString(rscName: WorkspaceResource.Name, val: string): void;
-    /** Remove a string resource. */
-    removeString(rscName: WorkspaceResource.Name): void;
-    /** Add a new blob resource to this WorkspaceDb.
-     * @param rscName The name of the blob resource.
-     * @param val The blob to save.
-     */
-    addBlob(rscName: WorkspaceResource.Name, val: Uint8Array): void;
-    /** Update an existing blob resource with a new value.
-     * @param rscName The name of the blob resource.
-     * @param val The new value.
-     * @throws if rscName does not exist
-     */
-    updateBlob(rscName: WorkspaceResource.Name, val: Uint8Array): void;
-    /** Get a BlobIO writer for a previously-added blob WorkspaceResource.
-     * @note after writing is complete, caller must call `close` on the BlobIO and must call `saveChanges` on the `db`.
-     */
-    getBlobWriter(rscName: WorkspaceResource.Name): SQLiteDb.BlobIO;
-    /** Remove a blob resource. */
-    removeBlob(rscName: WorkspaceResource.Name): void;
-    /** Copy the contents of an existing local file into this WorkspaceDb as a file resource.
-     * @param rscName The name of the file resource.
-     * @param localFileName The name of a local file to be read.
-     * @param fileExt The extension (do not include the leading ".") to be appended to the generated fileName
-     * when this WorkspaceDb is extracted from the WorkspaceDb. By default the characters after the last "." in `localFileName`
-     * are used. Pass this argument to override that.
-     */
-    addFile(rscName: WorkspaceResource.Name, localFileName: LocalFileName, fileExt?: string): void;
-    /** Replace an existing file resource with the contents of another local file.
-     * @param rscName The name of the file resource.
-     * @param localFileName The name of a local file to be read.
-     * @throws if rscName does not exist
-     */
-    updateFile(rscName: WorkspaceResource.Name, localFileName: LocalFileName): void;
-    /** Remove a file resource. */
-    removeFile(rscName: WorkspaceResource.Name): void;
-}
+/** @packageDocumentation
+ * @module Workspace
+ */
+import { AccessToken, BeEvent, Optional } from "@itwin/core-bentley";
+import { LocalDirName, LocalFileName } from "@itwin/core-common";
+import { CloudSqlite } from "../CloudSqlite";
+import { SQLiteDb } from "../SQLiteDb";
+import { Settings, SettingsPriority } from "./Settings";
+/** The Settings used by Workspace api
+ * @beta
+ */
+export declare const WorkspaceSetting: {
+    Accounts: string;
+    Containers: string;
+    Databases: string;
+};
+/** Types used to identify cloud accounts for Workspaces.
+ *  @beta
+ */
+export declare namespace WorkspaceAccount {
+    /** The name of a WorkspaceAccount in a "cloud/accounts" setting. */
+    type Name = string;
+    /** A member named `accountName` that specifies by an entry in a "cloud/accounts" setting */
+    interface Alias {
+        accountName: string;
+    }
+    /** The properties of a cloud account required to open containers with CloudSqlite. Usually supplied via a "cloud/accounts" setting. */
+    type Props = CloudSqlite.AccountAccessProps;
+}
+/** @beta */
+export declare namespace WorkspaceContainer {
+    /** The name of a WorkspaceContainer in a "cloud/containers" setting. */
+    type Name = string;
+    /** The unique identifier of a WorkspaceContainer. This becomes the base name for the local directory holding the WorkspaceDbs from a WorkspaceContainer.
+     * Usually supplied via the `containerId` member of a "cloud/containers" setting.
+     * `WorkspaceContainer.Id`s may:
+     *  - only contain lower case letters, numbers or dashes
+     *  - not start or end with a dash
+     *  - not be shorter than 3 or longer than 63 characters
+     */
+    type Id = string;
+    /** A member named `containerName` that specifies by an entry in a "cloud/containers" setting */
+    interface Alias {
+        containerName: string;
+    }
+    /** Properties that specify a WorkspaceContainer. */
+    interface Props extends Optional<CloudSqlite.ContainerProps, "accessToken"> {
+        /** true if the container is public (doesn't require authentication) */
+        isPublic?: boolean;
+        /** attempt to synchronize (i.e. call `checkForChanges`) this cloud container whenever it is connected to a cloud cache. Default=true */
+        syncOnConnect?: boolean;
+    }
+    /** A function to supply an [AccessToken]($bentley) for a `WorkspaceContainer`.
+     * @param props The properties of the WorkspaceContainer necessary to obtain the access token
+     * @param account The properties of the account for the container
+     * @returns a Promise that resolves to the AccessToken for the container.
+     */
+    type TokenFunc = (props: Props, account: WorkspaceAccount.Props) => Promise<AccessToken>;
+}
+/** @beta */
+export declare namespace WorkspaceDb {
+    /** The name of a WorkspaceDb in a "workspace/databases" setting. */
+    type Name = string;
+    /** The base name of a WorkspaceDb within a WorkspaceContainer (without any version identifier) */
+    type DbName = string;
+    /** The  name of a WorkspaceDb within a WorkspaceContainer, including the version identifier */
+    type DbFullName = string;
+    /** The semver-format version identifier for a WorkspaceDb. */
+    type Version = string;
+    /** The [semver range format](https://github.com/npm/node-semver) identifier for a range of acceptable versions. */
+    type VersionRange = string;
+    /** Properties that specify how to load a WorkspaceDb within a [[WorkspaceContainer]]. */
+    interface Props extends CloudSqlite.DbNameProp {
+        /** a semver version range specifier that determines the acceptable range of versions to load. If not present, use the newest version. */
+        version?: VersionRange;
+        /** if true, allow semver *prerelease* versions. By default only released version are allowed. */
+        includePrerelease?: boolean;
+    }
+    /** Scope to increment for a version number.
+     * @see semver.ReleaseType
+     */
+    type VersionIncrement = "major" | "minor" | "patch";
+}
+/** Types used to identify Workspace resources
+ *  @beta
+ */
+export declare namespace WorkspaceResource {
+    /**
+     * The name for identifying WorkspaceResources in a [[WorkspaceDb]].
+     * * `WorkspaceResource.Name`s may not:
+     *  - be blank or start or end with a space
+     *  - be longer than 1024 characters
+     * @note a single WorkspaceDb may hold WorkspaceResources of type 'blob', 'string' and 'file', all with the same WorkspaceResource.Name.
+     */
+    type Name = string;
+    /** Properties that specify an individual WorkspaceResource within a [[WorkspaceDb]]. */
+    interface Props {
+        /** the name of the resource within the WorkspaceDb */
+        rscName: Name;
+    }
+}
+/**
+ * A WorkspaceDb holds workspace resources. `WorkspaceDb`s may just be local files, or they may be stored
+ * in cloud WorkspaceContainers. Each `WorkspaceResource` in a WorkspaceDb is identified by a [[WorkspaceResource.Name]].
+ * Resources of type `string` and `blob` may be loaded directly from the `WorkspaceDb`. Resources of type `file` are
+ * copied from the WorkspaceDb into a temporary local file so they can be accessed by programs directly from disk.
+ * @beta
+ */
+export interface WorkspaceDb {
+    /** The WorkspaceContainer holding this WorkspaceDb. */
+    readonly container: WorkspaceContainer;
+    /** The base name of this WorkspaceDb, without version */
+    readonly dbName: WorkspaceDb.DbName;
+    /** event raised before this WorkspaceDb is closed. */
+    readonly onClose: BeEvent<() => void>;
+    /** Name by which a WorkspaceDb may be opened. This will be either a local file name or the name of a database in a cloud container */
+    readonly dbFileName: string;
+    /** Get a string resource from this WorkspaceDb, if present. */
+    getString(rscName: WorkspaceResource.Name): string | undefined;
+    /** Get a blob resource from this WorkspaceDb, if present. */
+    getBlob(rscName: WorkspaceResource.Name): Uint8Array | undefined;
+    /** @internal */
+    getBlobReader(rscName: WorkspaceResource.Name): SQLiteDb.BlobIO;
+    /**
+     * Extract a local copy of a file resource from this WorkspaceDb, if present.
+     * @param rscName The name of the file resource in the WorkspaceDb
+     * @param targetFileName optional name for extracted file. Some applications require files in specific locations or filenames. If
+     * you know the full path to use for the extracted file, you can supply it. Generally, it is best to *not* supply the filename and
+     * keep the extracted files in the  filesDir.
+     * @returns the full path to a file on the local filesystem.
+     * @note The file is copied from the file into the local filesystem so it may be accessed directly. This happens only
+     * as necessary, if the local file doesn't exist, or if it is out-of-date because it was updated in the file.
+     * For this reason, you should not save the local file name, and instead call this method every time you access it, so its
+     * content is always holds the correct version.
+     * @note The filename will be a hash value, not the resource name.
+     * @note Workspace resource files are set readonly as they are copied from the file.
+     * To edit them, you must first copy them to another location.
+     */
+    getFile(rscName: WorkspaceResource.Name, targetFileName?: LocalFileName): LocalFileName | undefined;
+    /**
+     * Ensure that the contents of a `WorkspaceDb` are downloaded into the local cache so that it may be accessed offline.
+     * Until the promise is resolved, the `WorkspaceDb` is not fully downloaded, but it *may* be safely accessed during the download.
+     * To determine the progress of the download, use the `localBlocks` and `totalBlocks` values returned by `CloudContainer.queryDatabase`.
+     * @returns a `CloudSqlite.CloudPrefetch` object that can be used to await and/or cancel the prefetch.
+     * @throws if this WorkspaceDb is not from a `CloudContainer`.
+     */
+    prefetch(): CloudSqlite.CloudPrefetch;
+}
+/** The properties of the CloudCache used for Workspaces.
+ * @beta
+ */
+export interface WorkspaceCloudCacheProps extends Optional<CloudSqlite.CacheProps, "name" | "rootDir"> {
+    /** if true, empty the cache before using it. */
+    clearContents?: boolean;
+}
+/**
+ * Options for constructing a [[Workspace]].
+ * @beta
+ */
+export interface WorkspaceOpts {
+    /** The local directory for non-cloud-based WorkspaceDb files. The workspace api will look in this directory
+     * for files named `${containerId}/${dbId}.itwin-workspace`.
+     * @note if not supplied, defaults to `iTwin/Workspace` in the user-local folder.
+     */
+    containerDir?: LocalDirName;
+    /** the local fileName(s) of one or more settings files to load after the Workspace is first created. */
+    settingsFiles?: LocalFileName | [LocalFileName];
+    /**
+     * only for tests
+     * @internal */
+    testCloudCache?: CloudSqlite.CloudCache;
+}
+/**
+ * Settings and resources that customize an application for the current session.
+ * See [Workspaces]($docs/learning/backend/Workspace)
+ * @beta
+ */
+export interface Workspace {
+    /** The directory for local WorkspaceDb files with the name `${containerId}/${dbId}.itwin-workspace`. */
+    readonly containerDir: LocalDirName;
+    /** The [[Settings]] for this Workspace */
+    readonly settings: Settings;
+    /** The CloudCache for cloud-based WorkspaceContainers */
+    readonly cloudCache?: CloudSqlite.CloudCache;
+    /** search for a previously opened container.
+     * @param containerId the id of the container
+     * @returns the [[WorkspaceContainer]] for `containerId` if it was not previously opened with [[getContainer]]
+     */
+    findContainer(containerId: WorkspaceContainer.Id): WorkspaceContainer | undefined;
+    /** get a [[WorkspaceContainer]] by [[WorkspaceContainer.Props]]
+     * @param props the properties of the `WorkspaceContainer`. If `props.containerId` was already opened, its WorkspaceContainer is returned.
+     * Otherwise it is created.
+     * @param account If present, the properties for this container if it is to be opened from the cloud. If not present, the container is just a local directory.
+    */
+    getContainer(props: WorkspaceContainer.Props, account?: WorkspaceAccount.Props): WorkspaceContainer;
+    /** get the properties for the supplied account name by searching for an entry with that name in a `cloud/accounts` setting. */
+    resolveAccount(accountName: WorkspaceAccount.Name): WorkspaceAccount.Props;
+    /** get the properties for the supplied container name by searching for an entry with that name in a `cloud/containers` setting. */
+    resolveContainer(containerName: WorkspaceContainer.Name): WorkspaceContainer.Props & WorkspaceAccount.Alias;
+    /** get the properties for the supplied workspace database name by searching for an entry with that name in a `workspace/databases` setting. */
+    resolveDatabase(databaseAlias: WorkspaceDb.Name): WorkspaceDb.Props & WorkspaceContainer.Alias;
+    /**
+     * Get an opened [[WorkspaceDb]]. If the WorkspaceDb is present but not open, it is opened first.
+     * If `cloudProps` are supplied, a CloudContainer will be used to open the WorkspaceDb.
+     */
+    getWorkspaceDbFromProps(dbProps: WorkspaceDb.Props, containerProps: WorkspaceContainer.Props, account?: WorkspaceAccount.Props): WorkspaceDb;
+    /** Get an opened [[WorkspaceDb]] from a WorkspaceDb alias.
+     * @param dbAlias the database alias, resolved via [[resolveDatabase]].
+     * @param tokenFunc optional function to obtain an AccessToken for the resolved WorkspaceContainer. This function will only be called the first
+     * time a container is used.
+     */
+    getWorkspaceDb(dbAlias: WorkspaceDb.Name, tokenFunc?: WorkspaceContainer.TokenFunc): Promise<WorkspaceDb>;
+    /** Load a WorkspaceResource of type string, parse it, and add it to the current Settings for this Workspace.
+     * @note settingsRsc must specify a resource holding a stringified JSON representation of a [[SettingDictionary]]
+     */
+    loadSettingsDictionary(settingRsc: WorkspaceResource.Name, db: WorkspaceDb, priority: SettingsPriority): void;
+    /** Close this Workspace. All WorkspaceContainers are dropped. */
+    close(): void;
+}
+/**
+ * A WorkspaceContainer holds WorkspaceDbs.
+ * Access rights are administered per WorkspaceContainer. That is, if a user has rights to access a WorkspaceContainer, that right
+ * applies to all WorkspaceDbs in the WorkspaceContainer.
+ * @beta
+ */
+export interface WorkspaceContainer {
+    /** the local directory where this WorkspaceContainer will store temporary files extracted for file-resources. */
+    readonly filesDir: LocalDirName;
+    /** The unique identifier for a WorkspaceContainer a cloud storage account. */
+    readonly id: WorkspaceContainer.Id;
+    /** Workspace holding this WorkspaceContainer. */
+    readonly workspace: Workspace;
+    /** CloudContainer for this WorkspaceContainer (`undefined` if this is a local WorkspaceContainer.)
+     * @internal
+    */
+    readonly cloudContainer?: CloudSqlite.CloudContainer;
+    /** @internal */
+    addWorkspaceDb(toAdd: ITwinWorkspaceDb): void;
+    /** @internal */
+    resolveDbFileName(props: WorkspaceDb.Props): string;
+    /** find or open a WorkspaceDb from this WorkspaceContainer. */
+    getWorkspaceDb(props: WorkspaceDb.Props): WorkspaceDb;
+    /** Close and remove a currently opened [[WorkspaceDb]] from this Workspace. */
+    dropWorkspaceDb(container: WorkspaceDb): void;
+    /** Close this WorkspaceContainer. All currently opened WorkspaceDbs are dropped. */
+    close(): void;
+}
+/** @internal */
+export declare class ITwinWorkspace implements Workspace {
+    private _containers;
+    readonly containerDir: LocalDirName;
+    readonly settings: Settings;
+    private static _sharedCloudCache?;
+    private _cloudCache?;
+    get cloudCache(): CloudSqlite.CloudCache;
+    private static getSharedCloudCache;
+    static finalize(): void;
+    constructor(settings: Settings, opts?: WorkspaceOpts);
+    addContainer(toAdd: ITwinWorkspaceContainer): void;
+    findContainer(containerId: WorkspaceContainer.Id): ITwinWorkspaceContainer | undefined;
+    getContainer(props: WorkspaceContainer.Props, account?: WorkspaceAccount.Props): WorkspaceContainer;
+    getWorkspaceDbFromProps(dbProps: WorkspaceDb.Props, containerProps: WorkspaceContainer.Props, account?: WorkspaceAccount.Props): WorkspaceDb;
+    getWorkspaceDb(dbAlias: string, tokenFunc?: WorkspaceContainer.TokenFunc): Promise<WorkspaceDb>;
+    loadSettingsDictionary(settingRsc: WorkspaceResource.Name, db: WorkspaceDb, priority: SettingsPriority): void;
+    close(): void;
+    resolveAccount(accountName: string): WorkspaceAccount.Props;
+    resolveContainer(containerName: string): WorkspaceContainer.Props & WorkspaceAccount.Alias;
+    resolveDatabase(databaseName: string): WorkspaceDb.Props & WorkspaceContainer.Alias;
+}
+/** @internal */
+export declare class ITwinWorkspaceContainer implements WorkspaceContainer {
+    readonly workspace: ITwinWorkspace;
+    readonly filesDir: LocalDirName;
+    readonly id: WorkspaceContainer.Id;
+    readonly cloudContainer?: CloudSqlite.CloudContainer | undefined;
+    private _wsDbs;
+    get dirName(): string;
+    static noLeadingOrTrailingSpaces(name: string, msg: string): void;
+    /** rules for ContainerIds (from Azure, see https://docs.microsoft.com/en-us/rest/api/storageservices/naming-and-referencing-containers--blobs--and-metadata)
+     *  - may only contain lower case letters, numbers or dashes
+     *  - may not start or end with with a dash nor have more than one dash in a row
+     *  - may not be shorter than 3 or longer than 63 characters
+     */
+    private static validateContainerId;
+    static validateDbName(dbName: WorkspaceDb.DbName): void;
+    constructor(workspace: ITwinWorkspace, props: WorkspaceContainer.Props, account?: WorkspaceAccount.Props);
+    static validateVersion(version?: WorkspaceDb.Version): string;
+    static parseDbFileName(dbFileName: WorkspaceDb.DbFullName): {
+        dbName: WorkspaceDb.DbName;
+        version: WorkspaceDb.Version;
+    };
+    static makeDbFileName(dbName: WorkspaceDb.DbName, version?: WorkspaceDb.Version): WorkspaceDb.DbName;
+    static resolveCloudFileName(cloudContainer: CloudSqlite.CloudContainer, props: WorkspaceDb.Props): WorkspaceDb.DbFullName;
+    /**
+     * Create a copy of an existing [[WorkspaceDb]] in a cloud container with a new version number.
+     * @param cloudContainer The attached cloud container holding the existing WorkspaceDb
+     * @param fromProps Properties that describe the source WorkspaceDb for the new version
+     * @param versionType The type of version increment to apply to the existing version.
+     * @note This requires that the cloudContainer is attached and the write lock on the container be held. The copy should be modified with
+     * new content before the write lock is released, and thereafter should never be modified again.
+     */
+    static makeNewVersion(cloudContainer: CloudSqlite.CloudContainer, fromProps: WorkspaceDb.Props, versionType: WorkspaceDb.VersionIncrement): Promise<{
+        oldName: string;
+        newName: string;
+    }>;
+    /**
+     * Convert a WorkspaceDb.Props specification into a DbFileName. For cloud-based containers, this resolves to the dbName, incorporating the appropriate
+     * version. For file-based containers, this returns a local filename of a WorkspaceDb file with the extension ".itwin-workspace"
+     */
+    resolveDbFileName(props: WorkspaceDb.Props): WorkspaceDb.DbFullName;
+    addWorkspaceDb(toAdd: ITwinWorkspaceDb): void;
+    getWorkspaceDb(props: WorkspaceDb.Props): WorkspaceDb;
+    dropWorkspaceDb(toDrop: WorkspaceDb): void;
+    close(): void;
+    /** Delete all local files extracted by [[WorkspaceDb.getFile]] for this container. */
+    purgeContainerFiles(): void;
+}
+/**
+ * Implementation of WorkspaceDb
+ * @internal
+ */
+export declare class ITwinWorkspaceDb implements WorkspaceDb {
+    /** file extension for local WorkspaceDbs */
+    static readonly fileExt = "itwin-workspace";
+    /** the SQLiteDb for this WorkspaceDb*/
+    readonly sqliteDb: SQLiteDb;
+    /** the base WorkspaceDb name, without directory, extension, or version information. */
+    readonly dbName: WorkspaceDb.DbName;
+    /** The WorkspaceContainer holding this WorkspaceDb */
+    readonly container: WorkspaceContainer;
+    /** called before db is closed */
+    readonly onClose: BeEvent<() => void>;
+    /** either a local file name or the name of the file in a cloud container, including version identifier */
+    dbFileName: string;
+    /** true if this WorkspaceDb is currently open */
+    get isOpen(): boolean;
+    queryFileResource(rscName: WorkspaceResource.Name): {
+        localFileName: string;
+        info: import("@bentley/imodeljs-native").IModelJsNative.EmbedFileQuery;
+    } | undefined;
+    constructor(props: WorkspaceDb.Props, container: WorkspaceContainer);
+    open(): void;
+    close(): void;
+    getString(rscName: WorkspaceResource.Name): string | undefined;
+    /** Get a BlobIO reader for a blob WorkspaceResource.
+     * @note when finished, caller *must* call `close` on the BlobIO.
+     */
+    getBlobReader(rscName: WorkspaceResource.Name): SQLiteDb.BlobIO;
+    getBlob(rscName: WorkspaceResource.Name): Uint8Array | undefined;
+    getFile(rscName: WorkspaceResource.Name, targetFileName?: LocalFileName): LocalFileName | undefined;
+    prefetch(opts?: CloudSqlite.PrefetchProps): CloudSqlite.CloudPrefetch;
+}
+/**
+ * An editable [[WorkspaceDb]]. This is used by administrators for creating and modifying `WorkspaceDb`s.
+ * For cloud-backed containers, the write token must be obtained before this class may be used. Only one user at at time
+ * may be editing.
+ * @internal
+ */
+export declare class EditableWorkspaceDb extends ITwinWorkspaceDb {
+    private static validateResourceName;
+    private validateResourceSize;
+    open(): void;
+    private getFileModifiedTime;
+    private performWriteSql;
+    createDb(version?: string): Promise<void>;
+    /** Create a new, empty, EditableWorkspaceDb for importing Workspace resources. */
+    static createEmpty(fileName: LocalFileName): void;
+    /** Add a new string resource to this WorkspaceDb.
+     * @param rscName The name of the string resource.
+     * @param val The string to save.
+     */
+    addString(rscName: WorkspaceResource.Name, val: string): void;
+    /** Update an existing string resource with a new value.
+     * @param rscName The name of the string resource.
+     * @param val The new value.
+     * @throws if rscName does not exist
+     */
+    updateString(rscName: WorkspaceResource.Name, val: string): void;
+    /** Remove a string resource. */
+    removeString(rscName: WorkspaceResource.Name): void;
+    /** Add a new blob resource to this WorkspaceDb.
+     * @param rscName The name of the blob resource.
+     * @param val The blob to save.
+     */
+    addBlob(rscName: WorkspaceResource.Name, val: Uint8Array): void;
+    /** Update an existing blob resource with a new value.
+     * @param rscName The name of the blob resource.
+     * @param val The new value.
+     * @throws if rscName does not exist
+     */
+    updateBlob(rscName: WorkspaceResource.Name, val: Uint8Array): void;
+    /** Get a BlobIO writer for a previously-added blob WorkspaceResource.
+     * @note after writing is complete, caller must call `close` on the BlobIO and must call `saveChanges` on the `db`.
+     */
+    getBlobWriter(rscName: WorkspaceResource.Name): SQLiteDb.BlobIO;
+    /** Remove a blob resource. */
+    removeBlob(rscName: WorkspaceResource.Name): void;
+    /** Copy the contents of an existing local file into this WorkspaceDb as a file resource.
+     * @param rscName The name of the file resource.
+     * @param localFileName The name of a local file to be read.
+     * @param fileExt The extension (do not include the leading ".") to be appended to the generated fileName
+     * when this WorkspaceDb is extracted from the WorkspaceDb. By default the characters after the last "." in `localFileName`
+     * are used. Pass this argument to override that.
+     */
+    addFile(rscName: WorkspaceResource.Name, localFileName: LocalFileName, fileExt?: string): void;
+    /** Replace an existing file resource with the contents of another local file.
+     * @param rscName The name of the file resource.
+     * @param localFileName The name of a local file to be read.
+     * @throws if rscName does not exist
+     */
+    updateFile(rscName: WorkspaceResource.Name, localFileName: LocalFileName): void;
+    /** Remove a file resource. */
+    removeFile(rscName: WorkspaceResource.Name): void;
+}
 //# sourceMappingURL=Workspace.d.ts.map