@itwin/core-backend 4.5.0-dev.8 → 4.5.0

package/lib/cjs/workspace/Workspace.js

@@ -7,7 +7,7 @@
  * @module Workspace
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.EditableWorkspaceDb = exports.ITwinWorkspaceDb = exports.ITwinWorkspaceContainer = exports.ITwinWorkspace = exports.WorkspaceSetting = void 0;
+exports.EditableWorkspaceDb = exports.Workspace = exports.WorkspaceDb = exports.WorkspaceContainer = exports.WorkspaceSetting = void 0;
 const crypto_1 = require("crypto");
 const fs = require("fs-extra");
 const path_1 = require("path");
@@ -22,16 +22,116 @@ const Settings_1 = require("./Settings");
 const SettingsSchemas_1 = require("./SettingsSchemas");
 /* eslint-disable @typescript-eslint/naming-convention */
 // cspell:ignore rowid primarykey julianday
+function noLeadingOrTrailingSpaces(name, msg) {
+    if (name.trim() !== name)
+        throw new Error(`${msg} [${name}] may not have leading or tailing spaces`);
+}
 /** The Settings used by Workspace api
  * @beta
  */
 exports.WorkspaceSetting = {
-    Accounts: "cloud/accounts",
     Containers: "cloud/containers",
     Databases: "workspace/databases",
 };
-/** @internal */
-class ITwinWorkspace {
+/** @beta */
+var WorkspaceContainer;
+(function (WorkspaceContainer) {
+    function validateDbName(dbName) {
+        if (dbName === "" || dbName.length > 255 || /[#\.<>:"/\\"`'|?*\u0000-\u001F]/g.test(dbName) || /^(con|prn|aux|nul|com\d|lpt\d)$/i.test(dbName))
+            throw new Error(`invalid dbName: [${dbName}]`);
+        noLeadingOrTrailingSpaces(dbName, "dbName");
+    }
+    WorkspaceContainer.validateDbName = validateDbName;
+    /**
+     * Validate that a WorkspaceContainer.Id is valid.
+     * The 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
+     */
+    function validateContainerId(id) {
+        if (!/^(?=.{3,63}$)[a-z0-9]+(-[a-z0-9]+)*$/g.test(id))
+            throw new Error(`invalid containerId: [${id}]`);
+    }
+    WorkspaceContainer.validateContainerId = validateContainerId;
+    /** @internal */
+    function validateVersion(version) {
+        version = version ?? "1.0.0";
+        if (version) {
+            const opts = { loose: true, includePrerelease: true };
+            // clean allows prerelease, so try it first. If that fails attempt to coerce it (coerce strips prerelease even if you say not to.)
+            const semVersion = semver.clean(version, opts) ?? semver.coerce(version, opts)?.version;
+            if (!semVersion)
+                throw new Error("invalid version specification");
+            version = semVersion;
+        }
+        return version;
+    }
+    WorkspaceContainer.validateVersion = validateVersion;
+    /**
+     * Parse the name stored in a WorkspaceContainer into the dbName and version number. A single WorkspaceContainer may hold
+     * many versions of the same WorkspaceDb. The name of the Db in the WorkspaceContainer is in the format "name:version". This
+     * function splits them into separate strings.
+     */
+    function parseDbFileName(dbFileName) {
+        const parts = dbFileName.split(":");
+        return { dbName: parts[0], version: parts[1] };
+    }
+    WorkspaceContainer.parseDbFileName = parseDbFileName;
+    /** Create a dbName for a WorkspaceDb from its base name and version. This will be in the format "name:version" */
+    function makeDbFileName(dbName, version) {
+        return `${dbName}:${WorkspaceContainer.validateVersion(version)}`;
+    }
+    WorkspaceContainer.makeDbFileName = makeDbFileName;
+})(WorkspaceContainer = exports.WorkspaceContainer || (exports.WorkspaceContainer = {}));
+/** @beta */
+var WorkspaceDb;
+(function (WorkspaceDb) {
+    /** file extension for local WorkspaceDbs
+     * @internal
+     */
+    WorkspaceDb.fileExt = "itwin-workspace";
+    /** construct a new instance of a WorkspaceDb */
+    function construct(props, container) {
+        return new WorkspaceDbImpl(props, container);
+    }
+    WorkspaceDb.construct = construct;
+})(WorkspaceDb = exports.WorkspaceDb || (exports.WorkspaceDb = {}));
+/** @beta */
+var Workspace;
+(function (Workspace) {
+    /** @internal */
+    function construct(settings, opts) {
+        return new WorkspaceImpl(settings, opts);
+    }
+    Workspace.construct = construct;
+})(Workspace = exports.Workspace || (exports.Workspace = {}));
+/** @beta */
+var EditableWorkspaceDb;
+(function (EditableWorkspaceDb) {
+    /** construct a new instance of an EditableWorkspaceDb */
+    function construct(props, container) {
+        return new EditableWorkspaceDbImpl(props, container);
+    }
+    EditableWorkspaceDb.construct = construct;
+    /** Create a new, empty, EditableWorkspaceDb file on the local filesystem for importing Workspace resources. */
+    function createEmpty(fileName) {
+        const db = new SQLiteDb_1.SQLiteDb();
+        IModelJsFs_1.IModelJsFs.recursiveMkDirSync((0, path_1.dirname)(fileName));
+        db.createDb(fileName);
+        const timeStampCol = "lastMod TIMESTAMP NOT NULL DEFAULT(julianday('now'))";
+        db.executeSQL(`CREATE TABLE strings(id TEXT PRIMARY KEY NOT NULL,value TEXT,${timeStampCol})`);
+        db.executeSQL(`CREATE TABLE blobs(id TEXT PRIMARY KEY NOT NULL,value BLOB,${timeStampCol})`);
+        const createTrigger = (tableName) => {
+            db.executeSQL(`CREATE TRIGGER ${tableName}_timeStamp AFTER UPDATE ON ${tableName} WHEN old.lastMod=new.lastMod AND old.lastMod != julianday('now') BEGIN UPDATE ${tableName} SET lastMod=julianday('now') WHERE id=new.id; END`);
+        };
+        createTrigger("strings");
+        createTrigger("blobs");
+        db.closeDb(true);
+    }
+    EditableWorkspaceDb.createEmpty = createEmpty;
+})(EditableWorkspaceDb = exports.EditableWorkspaceDb || (exports.EditableWorkspaceDb = {}));
+class WorkspaceImpl {
     getCloudCache() {
         return this._cloudCache ??= CloudSqlite_1.CloudSqlite.CloudCaches.getCache({ cacheName: "Workspace", cacheSize: "20G" });
     }
@@ -56,7 +156,7 @@ class ITwinWorkspace {
         return this._containers.get(containerId);
     }
     getContainer(props) {
-        return this.findContainer(props.containerId) ?? new ITwinWorkspaceContainer(this, props);
+        return this.findContainer(props.containerId) ?? new WorkspaceContainerImpl(this, props);
     }
     getWorkspaceDbFromProps(dbProps, containerProps) {
         return this.getContainer(containerProps).getWorkspaceDb(dbProps);
@@ -112,31 +212,11 @@ class ITwinWorkspace {
         return resolved;
     }
 }
-exports.ITwinWorkspace = ITwinWorkspace;
-/** @internal */
-class ITwinWorkspaceContainer {
+class WorkspaceContainerImpl {
     get dirName() { return (0, path_1.join)(this.workspace.containerDir, this.id); }
-    static noLeadingOrTrailingSpaces(name, msg) {
-        if (name.trim() !== name)
-            throw new Error(`${msg} [${name}] may not have leading or tailing spaces`);
-    }
-    /** 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
-     */
-    static validateContainerId(id) {
-        if (!/^(?=.{3,63}$)[a-z0-9]+(-[a-z0-9]+)*$/g.test(id))
-            throw new Error(`invalid containerId: [${id}]`);
-    }
-    static validateDbName(dbName) {
-        if (dbName === "" || dbName.length > 255 || /[#\.<>:"/\\"`'|?*\u0000-\u001F]/g.test(dbName) || /^(con|prn|aux|nul|com\d|lpt\d)$/i.test(dbName))
-            throw new Error(`invalid dbName: [${dbName}]`);
-        this.noLeadingOrTrailingSpaces(dbName, "dbName");
-    }
     constructor(workspace, props) {
         this._wsDbs = new Map();
-        ITwinWorkspaceContainer.validateContainerId(props.containerId);
+        WorkspaceContainer.validateContainerId(props.containerId);
         this.workspace = workspace;
         this.id = props.containerId;
         if (props.baseUri !== "")
@@ -156,31 +236,15 @@ class ITwinWorkspaceContainer {
             }
         }
     }
-    static validateVersion(version) {
-        version = version ?? "1.0.0";
-        if (version) {
-            const opts = { loose: true, includePrerelease: true };
-            // clean allows prerelease, so try it first. If that fails attempt to coerce it (coerce strips prerelease even if you say not to.)
-            const semVersion = semver.clean(version, opts) ?? semver.coerce(version, opts)?.version;
-            if (!semVersion)
-                throw new Error("invalid version specification");
-            version = semVersion;
-        }
-        return version;
-    }
-    static parseDbFileName(dbFileName) {
-        const parts = dbFileName.split(":");
-        return { dbName: parts[0], version: parts[1] };
-    }
-    static makeDbFileName(dbName, version) {
-        return `${dbName}:${this.validateVersion(version)}`;
-    }
-    static resolveCloudFileName(cloudContainer, props) {
+    resolveDbFileName(props) {
+        const cloudContainer = this.cloudContainer;
+        if (undefined === cloudContainer)
+            return (0, path_1.join)(this.dirName, `${props.dbName}.${WorkspaceDb.fileExt}`); // local file, versions not allowed
         const dbName = props.dbName;
         const dbs = cloudContainer.queryDatabases(`${dbName}*`); // get all databases that start with dbName
         const versions = [];
         for (const db of dbs) {
-            const thisDb = ITwinWorkspaceContainer.parseDbFileName(db);
+            const thisDb = WorkspaceContainer.parseDbFileName(db);
             if (thisDb.dbName === dbName && "string" === typeof thisDb.version && thisDb.version.length > 0)
                 versions.push(thisDb.version);
         }
@@ -196,46 +260,31 @@ class ITwinWorkspaceContainer {
         }
         throw new Error(`No version of [${dbName}] available for "${range}"`);
     }
-    /**
-     * 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 async makeNewVersion(cloudContainer, fromProps, versionType) {
-        const oldName = this.resolveCloudFileName(cloudContainer, fromProps);
-        const oldDb = this.parseDbFileName(oldName);
+    async makeNewVersion(fromProps, versionType) {
+        const cloudContainer = this.cloudContainer;
+        if (undefined === cloudContainer)
+            throw new Error("versions require cloud containers");
+        const oldName = this.resolveDbFileName(fromProps);
+        const oldDb = WorkspaceContainer.parseDbFileName(oldName);
         const newVersion = semver.inc(oldDb.version, versionType);
         if (!newVersion)
             throw new Error("invalid version");
-        const newName = this.makeDbFileName(oldDb.dbName, newVersion);
+        const newName = WorkspaceContainer.makeDbFileName(oldDb.dbName, newVersion);
         await cloudContainer.copyDatabase(oldName, newName);
         return { oldName, newName };
     }
-    /**
-     * 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) {
-        const cloudContainer = this.cloudContainer;
-        if (undefined === cloudContainer)
-            return (0, path_1.join)(this.dirName, `${props.dbName}.${ITwinWorkspaceDb.fileExt}`); // local file, versions not allowed
-        return ITwinWorkspaceContainer.resolveCloudFileName(cloudContainer, props);
-    }
     addWorkspaceDb(toAdd) {
         if (undefined !== this._wsDbs.get(toAdd.dbName))
             throw new Error(`workspaceDb ${toAdd.dbName} already exists in workspace`);
         this._wsDbs.set(toAdd.dbName, toAdd);
     }
     getWorkspaceDb(props) {
-        const db = this._wsDbs.get(props.dbName) ?? new ITwinWorkspaceDb(props, this);
+        const db = this._wsDbs.get(props.dbName) ?? new WorkspaceDbImpl(props, this);
         if (!db.isOpen)
             db.open();
         return db;
     }
-    dropWorkspaceDb(toDrop) {
+    closeWorkspaceDb(toDrop) {
         const name = toDrop.dbName;
         const wsDb = this._wsDbs.get(name);
         if (wsDb === toDrop) {
@@ -249,17 +298,9 @@ class ITwinWorkspaceContainer {
         this._wsDbs.clear();
         this.cloudContainer?.disconnect();
     }
-    /** Delete all local files extracted by [[WorkspaceDb.getFile]] for this container. */
-    purgeContainerFiles() {
-        IModelJsFs_1.IModelJsFs.purgeDirSync(this.filesDir);
-    }
 }
-exports.ITwinWorkspaceContainer = ITwinWorkspaceContainer;
-/**
- * Implementation of WorkspaceDb
- * @internal
- */
-class ITwinWorkspaceDb {
+/** Implementation of WorkspaceDb */
+class WorkspaceDbImpl {
     /** true if this WorkspaceDb is currently open */
     get isOpen() { return this.sqliteDb.isOpen; }
     queryFileResource(rscName) {
@@ -273,11 +314,9 @@ class ITwinWorkspaceDb {
         return { localFileName, info };
     }
     constructor(props, container) {
-        /** the SQLiteDb for this WorkspaceDb*/
         this.sqliteDb = new SQLiteDb_1.SQLiteDb();
-        /** called before db is closed */
         this.onClose = new core_bentley_1.BeEvent();
-        ITwinWorkspaceContainer.validateDbName(props.dbName);
+        WorkspaceContainer.validateDbName(props.dbName);
         this.dbName = props.dbName;
         this.container = container;
         this.dbFileName = container.resolveDbFileName(props);
@@ -290,7 +329,7 @@ class ITwinWorkspaceDb {
         if (this.isOpen) {
             this.onClose.raiseEvent();
             this.sqliteDb.closeDb();
-            this.container.dropWorkspaceDb(this);
+            this.container.closeWorkspaceDb(this);
         }
     }
     getString(rscName) {
@@ -299,9 +338,6 @@ class ITwinWorkspaceDb {
             return core_bentley_1.DbResult.BE_SQLITE_ROW === stmt.step() ? stmt.getValueString(0) : undefined;
         });
     }
-    /** Get a BlobIO reader for a blob WorkspaceResource.
-     * @note when finished, caller *must* call `close` on the BlobIO.
-     */
     getBlobReader(rscName) {
         return this.sqliteDb.withSqliteStatement("SELECT rowid from blobs WHERE id=?", (stmt) => {
             stmt.bindString(1, rscName);
@@ -344,18 +380,9 @@ class ITwinWorkspaceDb {
         return CloudSqlite_1.CloudSqlite.startCloudPrefetch(cloudContainer, this.dbFileName, opts);
     }
 }
-/** file extension for local WorkspaceDbs */
-ITwinWorkspaceDb.fileExt = "itwin-workspace";
-exports.ITwinWorkspaceDb = ITwinWorkspaceDb;
-/**
- * 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
- */
-class EditableWorkspaceDb extends ITwinWorkspaceDb {
+class EditableWorkspaceDbImpl extends WorkspaceDbImpl {
     static validateResourceName(name) {
-        ITwinWorkspaceContainer.noLeadingOrTrailingSpaces(name, "resource name");
+        noLeadingOrTrailingSpaces(name, "resource name");
         if (name.length > 1024)
             throw new Error("resource name too long");
     }
@@ -389,72 +416,37 @@ class EditableWorkspaceDb extends ITwinWorkspaceDb {
         }
         else {
             // currently the only way to create a workspaceDb in a cloud container is to create a temporary workspaceDb and upload it.
-            const tempDbFile = (0, path_1.join)(IModelHost_1.KnownLocations.tmpdir, `empty.${ITwinWorkspaceDb.fileExt}`);
+            const tempDbFile = (0, path_1.join)(IModelHost_1.KnownLocations.tmpdir, `empty.${WorkspaceDb.fileExt}`);
             if (fs.existsSync(tempDbFile))
                 IModelJsFs_1.IModelJsFs.removeSync(tempDbFile);
             EditableWorkspaceDb.createEmpty(tempDbFile);
-            this.dbFileName = ITwinWorkspaceContainer.makeDbFileName(this.dbName, version);
+            this.dbFileName = WorkspaceContainer.makeDbFileName(this.dbName, version);
             await CloudSqlite_1.CloudSqlite.uploadDb(this.container.cloudContainer, { localFileName: tempDbFile, dbName: this.dbFileName });
             IModelJsFs_1.IModelJsFs.removeSync(tempDbFile);
         }
         this.open();
     }
-    /** Create a new, empty, EditableWorkspaceDb for importing Workspace resources. */
-    static createEmpty(fileName) {
-        const db = new SQLiteDb_1.SQLiteDb();
-        IModelJsFs_1.IModelJsFs.recursiveMkDirSync((0, path_1.dirname)(fileName));
-        db.createDb(fileName);
-        const timeStampCol = "lastMod TIMESTAMP NOT NULL DEFAULT(julianday('now'))";
-        db.executeSQL(`CREATE TABLE strings(id TEXT PRIMARY KEY NOT NULL,value TEXT,${timeStampCol})`);
-        db.executeSQL(`CREATE TABLE blobs(id TEXT PRIMARY KEY NOT NULL,value BLOB,${timeStampCol})`);
-        const createTrigger = (tableName) => {
-            db.executeSQL(`CREATE TRIGGER ${tableName}_timeStamp AFTER UPDATE ON ${tableName} WHEN old.lastMod=new.lastMod AND old.lastMod != julianday('now') BEGIN UPDATE ${tableName} SET lastMod=julianday('now') WHERE id=new.id; END`);
-        };
-        createTrigger("strings");
-        createTrigger("blobs");
-        db.closeDb(true);
-    }
-    /** Add a new string resource to this WorkspaceDb.
-     * @param rscName The name of the string resource.
-     * @param val The string to save.
-     */
     addString(rscName, val) {
-        EditableWorkspaceDb.validateResourceName(rscName);
+        EditableWorkspaceDbImpl.validateResourceName(rscName);
         this.validateResourceSize(val);
         this.performWriteSql(rscName, "INSERT INTO strings(id,value) VALUES(?,?)", (stmt) => stmt.bindString(2, val));
     }
-    /** Update an existing string resource with a new value, or add it if it does not exist.
-     * @param rscName The name of the string resource.
-     * @param val The new value.
-     */
     updateString(rscName, val) {
         this.validateResourceSize(val);
         this.performWriteSql(rscName, "INSERT INTO strings(id,value) VALUES(?,?) ON CONFLICT(id) DO UPDATE SET value=excluded.value WHERE value!=excluded.value", (stmt) => stmt.bindString(2, val));
     }
-    /** Remove a string resource. */
     removeString(rscName) {
         this.performWriteSql(rscName, "DELETE FROM strings WHERE id=?");
     }
-    /** Add a new blob resource to this WorkspaceDb.
-     * @param rscName The name of the blob resource.
-     * @param val The blob to save.
-     */
     addBlob(rscName, val) {
-        EditableWorkspaceDb.validateResourceName(rscName);
+        EditableWorkspaceDbImpl.validateResourceName(rscName);
         this.validateResourceSize(val);
         this.performWriteSql(rscName, "INSERT INTO blobs(id,value) VALUES(?,?)", (stmt) => stmt.bindBlob(2, val));
     }
-    /** Update an existing blob resource with a new value, or add it if it does not exist.
-     * @param rscName The name of the blob resource.
-     * @param val The new value.
-     */
     updateBlob(rscName, val) {
         this.validateResourceSize(val);
         this.performWriteSql(rscName, "INSERT INTO blobs(id,value) VALUES(?,?) ON CONFLICT(id) DO UPDATE SET value=excluded.value WHERE value!=excluded.value", (stmt) => stmt.bindBlob(2, val));
     }
-    /** 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) {
         return this.sqliteDb.withSqliteStatement("SELECT rowid from blobs WHERE id=?", (stmt) => {
             stmt.bindString(1, rscName);
@@ -463,34 +455,20 @@ class EditableWorkspaceDb extends ITwinWorkspaceDb {
             return blobWriter;
         });
     }
-    /** Remove a blob resource. */
     removeBlob(rscName) {
         this.performWriteSql(rscName, "DELETE FROM blobs WHERE id=?");
     }
-    /** 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, localFileName, fileExt) {
-        EditableWorkspaceDb.validateResourceName(rscName);
+        EditableWorkspaceDbImpl.validateResourceName(rscName);
         fileExt = fileExt ?? (0, path_1.extname)(localFileName);
         if (fileExt?.[0] === ".")
             fileExt = fileExt.slice(1);
         this.sqliteDb.nativeDb.embedFile({ name: rscName, localFileName, date: this.getFileModifiedTime(localFileName), fileExt });
     }
-    /** 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, localFileName) {
         this.queryFileResource(rscName); // throws if not present
         this.sqliteDb.nativeDb.replaceEmbeddedFile({ name: rscName, localFileName, date: this.getFileModifiedTime(localFileName) });
     }
-    /** Remove a file resource. */
     removeFile(rscName) {
         const file = this.queryFileResource(rscName);
         if (undefined === file)
@@ -500,5 +478,4 @@ class EditableWorkspaceDb extends ITwinWorkspaceDb {
         this.sqliteDb.nativeDb.removeEmbeddedFile(rscName);
     }
 }
-exports.EditableWorkspaceDb = EditableWorkspaceDb;
 //# sourceMappingURL=Workspace.js.map