@itwin/core-backend 5.0.0-dev.10 → 5.0.0-dev.102

package/lib/esm/SQLiteDb.js

@@ -0,0 +1,379 @@
+/*---------------------------------------------------------------------------------------------
+* Copyright (c) Bentley Systems, Incorporated. All rights reserved.
+* See LICENSE.md in the project root for license terms and full copyright notice.
+*--------------------------------------------------------------------------------------------*/
+/** @packageDocumentation
+ * @module SQLiteDb
+ */
+var __addDisposableResource = (this && this.__addDisposableResource) || function (env, value, async) {
+    if (value !== null && value !== void 0) {
+        if (typeof value !== "object" && typeof value !== "function") throw new TypeError("Object expected.");
+        var dispose, inner;
+        if (async) {
+            if (!Symbol.asyncDispose) throw new TypeError("Symbol.asyncDispose is not defined.");
+            dispose = value[Symbol.asyncDispose];
+        }
+        if (dispose === void 0) {
+            if (!Symbol.dispose) throw new TypeError("Symbol.dispose is not defined.");
+            dispose = value[Symbol.dispose];
+            if (async) inner = dispose;
+        }
+        if (typeof dispose !== "function") throw new TypeError("Object not disposable.");
+        if (inner) dispose = function() { try { inner.call(this); } catch (e) { return Promise.reject(e); } };
+        env.stack.push({ value: value, dispose: dispose, async: async });
+    }
+    else if (async) {
+        env.stack.push({ async: true });
+    }
+    return value;
+};
+var __disposeResources = (this && this.__disposeResources) || (function (SuppressedError) {
+    return function (env) {
+        function fail(e) {
+            env.error = env.hasError ? new SuppressedError(e, env.error, "An error was suppressed during disposal.") : e;
+            env.hasError = true;
+        }
+        var r, s = 0;
+        function next() {
+            while (r = env.stack.pop()) {
+                try {
+                    if (!r.async && s === 1) return s = 0, env.stack.push(r), Promise.resolve().then(next);
+                    if (r.dispose) {
+                        var result = r.dispose.call(r.value);
+                        if (r.async) return s |= 2, Promise.resolve(result).then(next, function(e) { fail(e); return next(); });
+                    }
+                    else s |= 1;
+                }
+                catch (e) {
+                    fail(e);
+                }
+            }
+            if (s === 1) return env.hasError ? Promise.reject(env.error) : Promise.resolve();
+            if (env.hasError) throw env.error;
+        }
+        return next();
+    };
+})(typeof SuppressedError === "function" ? SuppressedError : function (error, suppressed, message) {
+    var e = new Error(message);
+    return e.name = "SuppressedError", e.error = error, e.suppressed = suppressed, e;
+});
+import * as fs from "fs";
+import { dirname } from "path";
+import * as semver from "semver";
+import { OpenMode } from "@itwin/core-bentley";
+import { CloudSqlite } from "./CloudSqlite";
+import { IModelNative } from "./internal/NativePlatform";
+import { IModelJsFs } from "./IModelJsFs";
+import { SqliteStatement, StatementCache } from "./SqliteStatement";
+import { _nativeDb } from "./internal/Symbols";
+// cspell:ignore savepoint julianday rowid
+/* eslint-disable @typescript-eslint/unified-signatures */
+/**
+ * A "generic" SQLiteDb. This class may be used to access local files or databases in a cloud container.
+ * @public
+ */
+export class SQLiteDb {
+    /** @internal */
+    [_nativeDb] = new IModelNative.platform.SQLiteDb();
+    _sqliteStatementCache = new StatementCache();
+    /** @internal */
+    static createBlobIO() {
+        return new IModelNative.platform.BlobIO();
+    }
+    /** alias for closeDb.
+     * @deprecated in 4.0, use [[closeDb]]
+     */
+    dispose() {
+        this.closeDb();
+    }
+    createDb(dbName, container, params) {
+        this[_nativeDb].createDb(dbName, container, params);
+    }
+    openDb(dbName, openMode, container) {
+        this[_nativeDb].openDb(dbName, openMode, container);
+    }
+    /** Close SQLiteDb.
+     * @param saveChanges if true, call `saveChanges` before closing db. Otherwise unsaved changes are abandoned.
+     */
+    closeDb(saveChanges) {
+        if (saveChanges && this.isOpen)
+            this.saveChanges();
+        this._sqliteStatementCache.clear();
+        this[_nativeDb].closeDb();
+    }
+    /** Returns true if this SQLiteDb is open */
+    get isOpen() { return this[_nativeDb].isOpen(); }
+    /** Returns true if this SQLiteDb is open readonly */
+    get isReadonly() { return this[_nativeDb].isReadonly(); }
+    /** Create a new table in this database. */
+    createTable(args) {
+        const timestampCol = args.addTimestamp ? ",lastMod TIMESTAMP NOT NULL DEFAULT(julianday('now'))" : "";
+        const constraints = args.constraints ? `,${args.constraints}` : "";
+        this.executeSQL(`CREATE TABLE ${args.tableName}(${args.columns}${timestampCol}${constraints})`);
+        if (args.addTimestamp)
+            this.executeSQL(`CREATE TRIGGER ${args.tableName}_timestamp AFTER UPDATE ON ${args.tableName} WHEN old.lastMod=new.lastMod AND old.lastMod != julianday('now') BEGIN UPDATE ${args.tableName} SET lastMod=julianday('now') WHERE rowid=new.rowid; END`);
+    }
+    /**
+     * Get the last modified date for a row in a table of this database.
+     * @note the table must have been created with `addTimestamp: true`
+    */
+    readLastModTime(tableName, rowId) {
+        return this.withSqliteStatement(`SELECT lastMod from ${tableName} WHERE rowid=?`, (stmt) => {
+            stmt.bindInteger(1, rowId);
+            return stmt.getValueDate(0);
+        });
+    }
+    /**
+     * Open a database, perform an operation, then close the database.
+     *
+     * Details:
+     * - if database is open, throw an error
+     * - open a database
+     * - call a function with the database opened. If it is async, await its return.
+     * - if function throws, abandon all changes, close database, and rethrow
+     * - save all changes
+     * - close the database
+     * @return value from operation
+     */
+    withOpenDb(args, operation) {
+        if (this.isOpen)
+            throw new Error("database is already open");
+        const save = () => this.closeDb(true), abandon = () => this.closeDb(false);
+        this.openDb(args.dbName, args.openMode ?? OpenMode.Readonly, args.container);
+        try {
+            const result = operation();
+            result instanceof Promise ? result.then(save, abandon) : save();
+            return result;
+        }
+        catch (e) {
+            abandon();
+            throw e;
+        }
+    }
+    /** The cloud container backing this SQLite database, if any.
+     * @beta
+     */
+    get cloudContainer() {
+        return this[_nativeDb].cloudContainer;
+    }
+    /** Returns the Id of the most-recently-inserted row in this database, per [sqlite3_last_insert_rowid](https://www.sqlite.org/c3ref/last_insert_rowid.html). */
+    getLastInsertRowId() {
+        return this[_nativeDb].getLastInsertRowId();
+    }
+    /**
+     * Perform an operation on a database in a CloudContainer with the write lock held.
+     *
+     * Details:
+     * - acquire the write lock on a CloudContainer
+     * - call `withOpenDb` with openMode `ReadWrite`
+     * - upload changes
+     * - release the write lock
+     * @param args arguments to lock the container and open the database
+     * @param operation an operation performed on the database with the write lock held.
+     * @return value from operation
+     * @internal
+     */
+    async withLockedContainer(args, operation) {
+        return CloudSqlite.withWriteLock(args, async () => this.withOpenDb({ ...args, openMode: args.openMode ?? OpenMode.ReadWrite }, operation));
+    }
+    /** vacuum this database
+     * @see https://www.sqlite.org/lang_vacuum.html
+     */
+    vacuum(args) {
+        this[_nativeDb].vacuum(args);
+    }
+    /** Commit the outermost transaction, writing changes to the file. Then, restart the default transaction. */
+    saveChanges() {
+        this[_nativeDb].saveChanges();
+    }
+    /** Abandon (cancel) the outermost transaction, discarding all changes since last save. Then, restart the default transaction. */
+    abandonChanges() {
+        this[_nativeDb].abandonChanges();
+    }
+    /**
+     * Use a prepared SQL statement, potentially from the statement cache. If the requested statement doesn't exist
+     * in the statement cache, a new statement is prepared. After the callback completes, the statement is reset and saved
+     * in the statement cache so it can be reused in the future. Use this method for SQL statements that will be
+     * reused often and are expensive to prepare. The statement cache holds the most recently used statements, discarding
+     * the oldest statements as it fills. For statements you don't intend to reuse, instead use [[withSqliteStatement]].
+     * @param sql The SQLite SQL statement to execute
+     * @param callback the callback to invoke on the prepared statement
+     * @returns the value returned by `callback`.
+     */
+    withPreparedSqliteStatement(sql, callback) {
+        const stmt = this._sqliteStatementCache.findAndRemove(sql) ?? this.prepareSqliteStatement(sql);
+        const release = () => this._sqliteStatementCache.addOrDispose(stmt);
+        try {
+            const val = callback(stmt);
+            val instanceof Promise ? val.then(release, release) : release();
+            return val;
+        }
+        catch (err) {
+            release();
+            throw err;
+        }
+    }
+    /**
+     * Prepare and execute a callback on a SQL statement. After the callback completes the statement is disposed.
+     * Use this method for SQL statements are either not expected to be reused, or are not expensive to prepare.
+     * For statements that will be reused often, instead use [[withPreparedSqliteStatement]].
+     * @param sql The SQLite SQL statement to execute
+     * @param callback the callback to invoke on the prepared statement
+     * @returns the value returned by `callback`.
+     */
+    withSqliteStatement(sql, callback) {
+        const stmt = this.prepareSqliteStatement(sql);
+        const release = () => stmt[Symbol.dispose]();
+        try {
+            const val = callback(stmt);
+            val instanceof Promise ? val.then(release, release) : release();
+            return val;
+        }
+        catch (err) {
+            release();
+            throw err;
+        }
+    }
+    /**
+     * Perform an operation on this database within a [savepoint](https://www.sqlite.org/lang_savepoint.html). If the operation completes successfully, the
+     * changes remain in the current transaction. If the operation throws an exception, the savepoint is rolled back
+     * and all changes to the database from this method are reversed, leaving the transaction exactly as it was before this method.
+     */
+    withSavePoint(savePointName, operation) {
+        if (this.isReadonly)
+            throw new Error("database is readonly");
+        this.executeSQL(`SAVEPOINT ${savePointName}`);
+        try {
+            operation();
+            this.executeSQL(`RELEASE ${savePointName}`);
+        }
+        catch (e) {
+            this.executeSQL(`ROLLBACK TO ${savePointName}`);
+            throw e;
+        }
+    }
+    /** Prepare an SQL statement.
+       * @param sql The SQLite SQL statement to prepare
+       * @param logErrors Determine if errors are logged or not
+       * @internal
+       */
+    prepareSqliteStatement(sql, logErrors = true) {
+        const stmt = new SqliteStatement(sql);
+        stmt.prepare(this[_nativeDb], logErrors);
+        return stmt;
+    }
+    /** execute an SQL statement */
+    executeSQL(sql) {
+        const env_1 = { stack: [], error: void 0, hasError: false };
+        try {
+            const stmt = __addDisposableResource(env_1, this.prepareSqliteStatement(sql), false);
+            return stmt.step();
+        }
+        catch (e_1) {
+            env_1.error = e_1;
+            env_1.hasError = true;
+        }
+        finally {
+            __disposeResources(env_1);
+        }
+    }
+}
+/**
+ * Abstract base class for a SQLite database that has [[SQLiteDb.RequiredVersionRanges]] stored in it.
+ * This class provides version checking when the database is opened, to guarantee that a valid version of software is
+ * always used for access.
+ *
+ * Notes:
+ *  - This class may be used either to access a local file, or one stored in a cloud container.
+ *  - Subclasses must provide a `myVersion` member indicating the version of its software, and implement the `createDDL` member to create its
+ * tables.
+ * @beta
+ */
+export class VersionedSqliteDb extends SQLiteDb {
+    static _versionProps = { namespace: "SQLiteDb", name: "versions" };
+    /**
+     * Change the "versions required to open this database" property stored in this database. After this call,
+     * versions of software that don't meet the supplied ranges will fail.
+     * @param versions the new versions required for reading and writing this database.
+     * @note the database must be opened for write access.
+     */
+    setRequiredVersions(versions) {
+        // NOTE: It might look tempting to just stringify the supplied `versions` object, but we only include required members - there may be others.
+        this[_nativeDb].saveFileProperty(VersionedSqliteDb._versionProps, JSON.stringify({ readVersion: versions.readVersion, writeVersion: versions.writeVersion }));
+    }
+    /** Get the required version ranges necessary to open this VersionedSqliteDb. */
+    getRequiredVersions() {
+        const checkIsString = (value) => {
+            if (typeof value !== "string")
+                throw new Error(`CloudDb ${this[_nativeDb].getFilePath()} has invalid "versions" property`);
+            return value;
+        };
+        const versionJson = checkIsString(this[_nativeDb].queryFileProperty(VersionedSqliteDb._versionProps, true));
+        const versionRanges = JSON.parse(versionJson);
+        checkIsString(versionRanges.readVersion);
+        checkIsString(versionRanges.writeVersion);
+        return versionRanges;
+    }
+    /**
+     * Create a new database file for the subclass of VersionedSqliteDb.
+     * @note The required versions are saved as [[myVersion]] or newer for both read and write.
+     */
+    static createNewDb(fileName, setupArgs) {
+        const db = new this(); // "as any" necessary because VersionedSqliteDb is abstract
+        IModelJsFs.recursiveMkDirSync(dirname(fileName));
+        if (fs.existsSync(fileName))
+            fs.unlinkSync(fileName);
+        db.createDb(fileName);
+        db.createDDL(setupArgs);
+        const minVer = `^${db.myVersion}`;
+        db.setRequiredVersions({ readVersion: minVer, writeVersion: minVer });
+        db.closeDb(true);
+    }
+    /**
+     * Verify that this version of the software meets the required version range (as appropriate, read or write) stored in the database.
+     * Throws otherwise.
+     */
+    verifyVersions() {
+        const versions = this.getRequiredVersions();
+        const isReadonly = this.isReadonly; // so we can tell read/write after the file is closed.
+        const range = isReadonly ? versions.readVersion : versions.writeVersion;
+        if (semver.satisfies(this.myVersion, range))
+            return;
+        this.closeDb();
+        const tooNew = semver.gtr(this.myVersion, range);
+        throw new Error(`${this[_nativeDb].getFilePath()} requires ${tooNew ? "older" : "newer"} version of ${this.constructor.name} for ${isReadonly ? "read" : "write"}`);
+    }
+    /**
+     * Open this database and verify that this version of the software meets the required version range (as appropriate, read or write) stored in the database.
+     * Throws otherwise.
+     * @see [[SqliteDb.openDb]] for argument types
+     */
+    openDb(dbName, openMode, container) {
+        super.openDb(dbName, openMode, container);
+        this.verifyVersions();
+    }
+    async upgradeSchema(arg) {
+        // can't use "this" because it checks for version, which we don't want here
+        return (arg.lockContainer) ?
+            super.withLockedContainer({ dbName: arg.dbName, ...arg.lockContainer }, async () => arg.upgradeFn) :
+            super.withOpenDb({ ...arg, openMode: OpenMode.ReadWrite }, arg.upgradeFn);
+    }
+}
+/** @public */
+(function (SQLiteDb) {
+    /** Default transaction mode for SQLiteDbs.
+     * @see https://www.sqlite.org/lang_transaction.html
+     */
+    let DefaultTxnMode;
+    (function (DefaultTxnMode) {
+        /** no default transaction is started. You must use BEGIN/COMMIT or SQLite will use implicit transactions */
+        DefaultTxnMode[DefaultTxnMode["None"] = 0] = "None";
+        /** A deferred transaction is started when the file is first opened. This is the default. */
+        DefaultTxnMode[DefaultTxnMode["Deferred"] = 1] = "Deferred";
+        /** An immediate transaction is started when the file is first opened. */
+        DefaultTxnMode[DefaultTxnMode["Immediate"] = 2] = "Immediate";
+        /** An exclusive transaction is started when the file is first opened. */
+        DefaultTxnMode[DefaultTxnMode["Exclusive"] = 3] = "Exclusive";
+    })(DefaultTxnMode = SQLiteDb.DefaultTxnMode || (SQLiteDb.DefaultTxnMode = {}));
+})(SQLiteDb || (SQLiteDb = {}));
+//# sourceMappingURL=SQLiteDb.js.map

package/lib/esm/SQLiteDb.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"SQLiteDb.js","sourceRoot":"","sources":["../../src/SQLiteDb.ts"],"names":[],"mappings":"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","sourcesContent":["/*---------------------------------------------------------------------------------------------\r\n* Copyright (c) Bentley Systems, Incorporated. All rights reserved.\r\n* See LICENSE.md in the project root for license terms and full copyright notice.\r\n*--------------------------------------------------------------------------------------------*/\r\n/** @packageDocumentation\r\n * @module SQLiteDb\r\n */\r\n\r\nimport * as fs from \"fs\";\r\nimport { dirname } from \"path\";\r\nimport * as semver from \"semver\";\r\nimport { IModelJsNative } from \"@bentley/imodeljs-native\";\r\nimport { DbResult, OpenMode } from \"@itwin/core-bentley\";\r\nimport { LocalFileName } from \"@itwin/core-common\";\r\nimport { CloudSqlite } from \"./CloudSqlite\";\r\nimport { IModelNative } from \"./internal/NativePlatform\";\r\nimport { IModelJsFs } from \"./IModelJsFs\";\r\nimport { SqliteStatement, StatementCache } from \"./SqliteStatement\";\r\nimport { _nativeDb } from \"./internal/Symbols\";\r\n\r\n// cspell:ignore savepoint julianday rowid\r\n\r\n/* eslint-disable @typescript-eslint/unified-signatures */\r\n\r\n/**\r\n * A \"generic\" SQLiteDb. This class may be used to access local files or databases in a cloud container.\r\n * @public\r\n */\r\nexport class SQLiteDb {\r\n  /** @internal */\r\n  public readonly [_nativeDb] = new IModelNative.platform.SQLiteDb();\r\n  private _sqliteStatementCache = new StatementCache<SqliteStatement>();\r\n\r\n  /** @internal */\r\n  public static createBlobIO(): SQLiteDb.BlobIO {\r\n    return new IModelNative.platform.BlobIO();\r\n  }\r\n\r\n  /** alias for closeDb.\r\n   * @deprecated in 4.0, use [[closeDb]]\r\n   */\r\n  public dispose(): void {\r\n    this.closeDb();\r\n  }\r\n\r\n  /** Create a SQLiteDb\r\n   * @param dbName The path to the SQLiteDb file to create.\r\n   */\r\n  public createDb(dbName: string): void;\r\n  /** @beta */\r\n  public createDb(dbName: string, container?: CloudSqlite.CloudContainer, params?: SQLiteDb.CreateParams): void;\r\n  public createDb(dbName: string, container?: CloudSqlite.CloudContainer, params?: SQLiteDb.CreateParams): void {\r\n    this[_nativeDb].createDb(dbName, container, params);\r\n  }\r\n\r\n  /** Open a SQLiteDb.\r\n   * @param dbName The path to the SQLiteDb file to open\r\n   */\r\n  public openDb(dbName: string, openMode: OpenMode | SQLiteDb.OpenParams): void;\r\n  /**\r\n   * @param container optional CloudContainer holding database\r\n   * @beta\r\n   */\r\n  public openDb(dbName: string, openMode: OpenMode | SQLiteDb.OpenParams, container?: CloudSqlite.CloudContainer): void;\r\n  public openDb(dbName: string, openMode: OpenMode | SQLiteDb.OpenParams, container?: CloudSqlite.CloudContainer): void {\r\n    this[_nativeDb].openDb(dbName, openMode, container);\r\n  }\r\n\r\n  /** Close SQLiteDb.\r\n   * @param saveChanges if true, call `saveChanges` before closing db. Otherwise unsaved changes are abandoned.\r\n   */\r\n  public closeDb(saveChanges?: boolean): void {\r\n    if (saveChanges && this.isOpen)\r\n      this.saveChanges();\r\n    this._sqliteStatementCache.clear();\r\n    this[_nativeDb].closeDb();\r\n  }\r\n\r\n  /** Returns true if this SQLiteDb is open */\r\n  public get isOpen(): boolean { return this[_nativeDb].isOpen(); }\r\n\r\n  /** Returns true if this SQLiteDb is open readonly */\r\n  public get isReadonly(): boolean { return this[_nativeDb].isReadonly(); }\r\n\r\n  /** Create a new table in this database. */\r\n  protected createTable(args: {\r\n    /** The name of the table to create. */\r\n    tableName: string;\r\n    /** all of the columns in the table. */\r\n    columns: string;\r\n    /** any unique or foreign key constraints */\r\n    constraints?: string;\r\n    /** if true, add a \"lastMod\" timestamp column and triggers to automatically update it. */\r\n    addTimestamp?: boolean;\r\n  }) {\r\n    const timestampCol = args.addTimestamp ? \",lastMod TIMESTAMP NOT NULL DEFAULT(julianday('now'))\" : \"\";\r\n    const constraints = args.constraints ? `,${args.constraints}` : \"\";\r\n    this.executeSQL(`CREATE TABLE ${args.tableName}(${args.columns}${timestampCol}${constraints})`);\r\n    if (args.addTimestamp)\r\n      this.executeSQL(`CREATE TRIGGER ${args.tableName}_timestamp AFTER UPDATE ON ${args.tableName} WHEN old.lastMod=new.lastMod AND old.lastMod != julianday('now') BEGIN UPDATE ${args.tableName} SET lastMod=julianday('now') WHERE rowid=new.rowid; END`);\r\n  }\r\n\r\n  /**\r\n   * Get the last modified date for a row in a table of this database.\r\n   * @note the table must have been created with `addTimestamp: true`\r\n  */\r\n  public readLastModTime(tableName: string, rowId: number): Date {\r\n    return this.withSqliteStatement(`SELECT lastMod from ${tableName} WHERE rowid=?`, (stmt) => {\r\n      stmt.bindInteger(1, rowId);\r\n      return stmt.getValueDate(0);\r\n    });\r\n  }\r\n\r\n  /**\r\n   * Open a database, perform an operation, then close the database.\r\n   *\r\n   * Details:\r\n   * - if database is open, throw an error\r\n   * - open a database\r\n   * - call a function with the database opened. If it is async, await its return.\r\n   * - if function throws, abandon all changes, close database, and rethrow\r\n   * - save all changes\r\n   * - close the database\r\n   * @return value from operation\r\n   */\r\n  public withOpenDb<T>(args: SQLiteDb.WithOpenDbArgs, operation: () => T): T {\r\n    if (this.isOpen)\r\n      throw new Error(\"database is already open\");\r\n\r\n    const save = () => this.closeDb(true), abandon = () => this.closeDb(false);\r\n    this.openDb(args.dbName, args.openMode ?? OpenMode.Readonly, args.container);\r\n    try {\r\n      const result = operation();\r\n      result instanceof Promise ? result.then(save, abandon) : save();\r\n      return result;\r\n    } catch (e) {\r\n      abandon();\r\n      throw e;\r\n    }\r\n  }\r\n\r\n  /** The cloud container backing this SQLite database, if any.\r\n   * @beta\r\n   */\r\n  public get cloudContainer(): CloudSqlite.CloudContainer | undefined {\r\n    return this[_nativeDb].cloudContainer;\r\n  }\r\n\r\n  /** Returns the Id of the most-recently-inserted row in this database, per [sqlite3_last_insert_rowid](https://www.sqlite.org/c3ref/last_insert_rowid.html). */\r\n  public getLastInsertRowId(): number {\r\n    return this[_nativeDb].getLastInsertRowId();\r\n  }\r\n\r\n  /**\r\n   * Perform an operation on a database in a CloudContainer with the write lock held.\r\n   *\r\n   * Details:\r\n   * - acquire the write lock on a CloudContainer\r\n   * - call `withOpenDb` with openMode `ReadWrite`\r\n   * - upload changes\r\n   * - release the write lock\r\n   * @param args arguments to lock the container and open the database\r\n   * @param operation an operation performed on the database with the write lock held.\r\n   * @return value from operation\r\n   * @internal\r\n   */\r\n  public async withLockedContainer<T>(args: CloudSqlite.LockAndOpenArgs, operation: () => Promise<T>) {\r\n    return CloudSqlite.withWriteLock(args, async () => this.withOpenDb({ ...args, openMode: args.openMode ?? OpenMode.ReadWrite }, operation));\r\n  }\r\n\r\n  /** vacuum this database\r\n   * @see https://www.sqlite.org/lang_vacuum.html\r\n   */\r\n  public vacuum(args?: SQLiteDb.VacuumDbArgs) {\r\n    this[_nativeDb].vacuum(args);\r\n  }\r\n\r\n  /** Commit the outermost transaction, writing changes to the file. Then, restart the default transaction. */\r\n  public saveChanges(): void {\r\n    this[_nativeDb].saveChanges();\r\n  }\r\n\r\n  /** Abandon (cancel) the outermost transaction, discarding all changes since last save. Then, restart the default transaction. */\r\n  public abandonChanges(): void {\r\n    this[_nativeDb].abandonChanges();\r\n  }\r\n\r\n  /**\r\n   * Use a prepared SQL statement, potentially from the statement cache. If the requested statement doesn't exist\r\n   * in the statement cache, a new statement is prepared. After the callback completes, the statement is reset and saved\r\n   * in the statement cache so it can be reused in the future. Use this method for SQL statements that will be\r\n   * reused often and are expensive to prepare. The statement cache holds the most recently used statements, discarding\r\n   * the oldest statements as it fills. For statements you don't intend to reuse, instead use [[withSqliteStatement]].\r\n   * @param sql The SQLite SQL statement to execute\r\n   * @param callback the callback to invoke on the prepared statement\r\n   * @returns the value returned by `callback`.\r\n   */\r\n  public withPreparedSqliteStatement<T>(sql: string, callback: (stmt: SqliteStatement) => T): T {\r\n    const stmt = this._sqliteStatementCache.findAndRemove(sql) ?? this.prepareSqliteStatement(sql);\r\n    const release = () => this._sqliteStatementCache.addOrDispose(stmt);\r\n    try {\r\n      const val = callback(stmt);\r\n      val instanceof Promise ? val.then(release, release) : release();\r\n      return val;\r\n    } catch (err) {\r\n      release();\r\n      throw err;\r\n    }\r\n  }\r\n\r\n  /**\r\n   * Prepare and execute a callback on a SQL statement. After the callback completes the statement is disposed.\r\n   * Use this method for SQL statements are either not expected to be reused, or are not expensive to prepare.\r\n   * For statements that will be reused often, instead use [[withPreparedSqliteStatement]].\r\n   * @param sql The SQLite SQL statement to execute\r\n   * @param callback the callback to invoke on the prepared statement\r\n   * @returns the value returned by `callback`.\r\n   */\r\n  public withSqliteStatement<T>(sql: string, callback: (stmt: SqliteStatement) => T): T {\r\n    const stmt = this.prepareSqliteStatement(sql);\r\n    const release = () => stmt[Symbol.dispose]();\r\n    try {\r\n      const val = callback(stmt);\r\n      val instanceof Promise ? val.then(release, release) : release();\r\n      return val;\r\n    } catch (err) {\r\n      release();\r\n      throw err;\r\n    }\r\n  }\r\n\r\n  /**\r\n   * Perform an operation on this database within a [savepoint](https://www.sqlite.org/lang_savepoint.html). If the operation completes successfully, the\r\n   * changes remain in the current transaction. If the operation throws an exception, the savepoint is rolled back\r\n   * and all changes to the database from this method are reversed, leaving the transaction exactly as it was before this method.\r\n   */\r\n  public withSavePoint(savePointName: string, operation: () => void) {\r\n    if (this.isReadonly)\r\n      throw new Error(\"database is readonly\");\r\n\r\n    this.executeSQL(`SAVEPOINT ${savePointName}`);\r\n    try {\r\n      operation();\r\n      this.executeSQL(`RELEASE ${savePointName}`);\r\n    } catch (e) {\r\n      this.executeSQL(`ROLLBACK TO ${savePointName}`);\r\n      throw e;\r\n    }\r\n  }\r\n\r\n  /** Prepare an SQL statement.\r\n     * @param sql The SQLite SQL statement to prepare\r\n     * @param logErrors Determine if errors are logged or not\r\n     * @internal\r\n     */\r\n  public prepareSqliteStatement(sql: string, logErrors = true): SqliteStatement {\r\n    const stmt = new SqliteStatement(sql);\r\n    stmt.prepare(this[_nativeDb], logErrors);\r\n    return stmt;\r\n  }\r\n\r\n  /** execute an SQL statement */\r\n  public executeSQL(sql: string): DbResult {\r\n    using stmt = this.prepareSqliteStatement(sql);\r\n    return stmt.step();\r\n  }\r\n}\r\n\r\n/**\r\n * Abstract base class for a SQLite database that has [[SQLiteDb.RequiredVersionRanges]] stored in it.\r\n * This class provides version checking when the database is opened, to guarantee that a valid version of software is\r\n * always used for access.\r\n *\r\n * Notes:\r\n *  - This class may be used either to access a local file, or one stored in a cloud container.\r\n *  - Subclasses must provide a `myVersion` member indicating the version of its software, and implement the `createDDL` member to create its\r\n * tables.\r\n * @beta\r\n */\r\nexport abstract class VersionedSqliteDb extends SQLiteDb {\r\n  protected static _versionProps = { namespace: \"SQLiteDb\", name: \"versions\" } as const;\r\n\r\n  /** The current semver \"persistence version\" of this class.\r\n   * @note This value should only be changed when logic in its code is modified in a way that affects the operation of extant copies.\r\n   * If this value is outside of the range of accepted versions of a to-be-opened VersionedSqliteDb, the operation will fail. In this manner, if\r\n   * changes are made to the format of a VersionedSqliteDb, or if bug fixes are necessary, the `requiredVersions` property in a VersionedSqliteDb may be updated\r\n   * and immediately old versions of the package will refuse to open the VersionedSqliteDb, with a message to the user that they need to upgrade their\r\n   * software. Likewise, if a new version of the package is asked to open an older VersionedSqliteDb that has not been upgraded to the lowest version\r\n   * supported by it, the user will be informed that they need to upgrade their software.\r\n   * @note this identifier is independent of versions in `package.json` files.\r\n  */\r\n  public abstract myVersion: string;\r\n\r\n  /**\r\n   * Change the \"versions required to open this database\" property stored in this database. After this call,\r\n   * versions of software that don't meet the supplied ranges will fail.\r\n   * @param versions the new versions required for reading and writing this database.\r\n   * @note the database must be opened for write access.\r\n   */\r\n  public setRequiredVersions(versions: SQLiteDb.RequiredVersionRanges) {\r\n    // NOTE: It might look tempting to just stringify the supplied `versions` object, but we only include required members - there may be others.\r\n    this[_nativeDb].saveFileProperty(VersionedSqliteDb._versionProps, JSON.stringify({ readVersion: versions.readVersion, writeVersion: versions.writeVersion }));\r\n  }\r\n\r\n  /** Get the required version ranges necessary to open this VersionedSqliteDb. */\r\n  public getRequiredVersions() {\r\n    const checkIsString = (value: any) => {\r\n      if (typeof value !== \"string\")\r\n        throw new Error(`CloudDb ${this[_nativeDb].getFilePath()} has invalid \"versions\" property`);\r\n      return value;\r\n    };\r\n    const versionJson = checkIsString(this[_nativeDb].queryFileProperty(VersionedSqliteDb._versionProps, true));\r\n    const versionRanges = JSON.parse(versionJson) as SQLiteDb.RequiredVersionRanges;\r\n    checkIsString(versionRanges.readVersion);\r\n    checkIsString(versionRanges.writeVersion);\r\n    return versionRanges;\r\n  }\r\n\r\n  /**\r\n   * Implement this method to create all tables for this subclass of `VersionedSqliteDb` when a new database file is created. Called from [[createNewDb]].\r\n   */\r\n  protected abstract createDDL(args: any): void;\r\n\r\n  /**\r\n   * Create a new database file for the subclass of VersionedSqliteDb.\r\n   * @note The required versions are saved as [[myVersion]] or newer for both read and write.\r\n   */\r\n  public static createNewDb(fileName: LocalFileName, setupArgs?: any) {\r\n    const db = new (this as any)() as VersionedSqliteDb; // \"as any\" necessary because VersionedSqliteDb is abstract\r\n    IModelJsFs.recursiveMkDirSync(dirname(fileName));\r\n    if (fs.existsSync(fileName))\r\n      fs.unlinkSync(fileName);\r\n\r\n    db.createDb(fileName);\r\n    db.createDDL(setupArgs);\r\n    const minVer = `^${db.myVersion}`;\r\n    db.setRequiredVersions({ readVersion: minVer, writeVersion: minVer });\r\n    db.closeDb(true);\r\n  }\r\n\r\n  /**\r\n   * Verify that this version of the software meets the required version range (as appropriate, read or write) stored in the database.\r\n   * Throws otherwise.\r\n   */\r\n  protected verifyVersions() {\r\n    const versions = this.getRequiredVersions();\r\n    const isReadonly = this.isReadonly; // so we can tell read/write after the file is closed.\r\n    const range = isReadonly ? versions.readVersion : versions.writeVersion;\r\n    if (semver.satisfies(this.myVersion, range))\r\n      return;\r\n\r\n    this.closeDb();\r\n    const tooNew = semver.gtr(this.myVersion, range);\r\n    throw new Error(`${this[_nativeDb].getFilePath()} requires ${tooNew ? \"older\" : \"newer\"} version of ${this.constructor.name} for ${isReadonly ? \"read\" : \"write\"}`);\r\n\r\n  }\r\n\r\n  /**\r\n   * Open this database and verify that this version of the software meets the required version range (as appropriate, read or write) stored in the database.\r\n   * Throws otherwise.\r\n   * @see [[SqliteDb.openDb]] for argument types\r\n   */\r\n  public override openDb(dbName: string, openMode: OpenMode | SQLiteDb.OpenParams, container?: CloudSqlite.CloudContainer) {\r\n    super.openDb(dbName, openMode, container);\r\n    this.verifyVersions();\r\n  }\r\n\r\n  public async upgradeSchema(arg: { dbName: string, lockContainer?: { container: CloudSqlite.CloudContainer, user: string }, upgradeFn: () => void }) {\r\n    // can't use \"this\" because it checks for version, which we don't want here\r\n    return (arg.lockContainer) ?\r\n      super.withLockedContainer({ dbName: arg.dbName, ...arg.lockContainer }, async () => arg.upgradeFn) :\r\n      super.withOpenDb({ ...arg, openMode: OpenMode.ReadWrite }, arg.upgradeFn);\r\n  }\r\n}\r\n\r\n/** @public */\r\nexport namespace SQLiteDb {\r\n  /** A semver version range.\r\n   * @see https://docs.npmjs.com/cli/v6/using-npm/semver\r\n   */\r\n  export type VersionRange = string;\r\n\r\n  /**\r\n   * A pair of semver [[SQLiteDb.VersionRange]]s, one for read and one for write, required to access a [[VersionedSqliteDb]].\r\n   * If the version of the software attempting to read or write the database does not satisfy the range, access is denied.\r\n   */\r\n  export interface RequiredVersionRanges {\r\n    /** a range of acceptable persistence versions for reading from a VersionedSqliteDb. */\r\n    readonly readVersion: VersionRange;\r\n    /** a range of acceptable persistence versions for writing to a VersionedSqliteDb. */\r\n    readonly writeVersion: VersionRange;\r\n  }\r\n\r\n  /** interface for reading and writing to a blob in a SQLiteDb\r\n   * @internal\r\n   */\r\n  export interface BlobIO {\r\n    /** Close this BlobIO if it is opened.\r\n       * @note this BlobIO *may* be reused after this call by calling `open` again.\r\n      */\r\n    close(): void;\r\n    /** get the total number of bytes in the blob */\r\n    getNumBytes(): number;\r\n    /** @return true if this BlobIO was successfully opened and may be use to read or write the blob */\r\n    isValid(): boolean;\r\n    /** Open this BlobIO against a table/row/column in a Db */\r\n    open(\r\n      /** The database for the blob */\r\n      db: IModelJsNative.AnyDb,\r\n      args: {\r\n        /** the name of the table for the blob*/\r\n        tableName: string;\r\n        /** the name of the column for the blob */\r\n        columnName: string;\r\n        /** The rowId of the blob */\r\n        row: number;\r\n        /** If true, open this BlobIO for write access */\r\n        writeable?: boolean;\r\n      }): void;\r\n    /** Read from a blob\r\n       * @returns the contents of the requested byte range\r\n       */\r\n    read(args: {\r\n      /** The number of bytes to read */\r\n      numBytes: number;\r\n      /** starting offset within the blob to read */\r\n      offset: number;\r\n      /** If present and of sufficient size, use this ArrayBuffer for the value. */\r\n      blob?: ArrayBuffer;\r\n    }): Uint8Array;\r\n    /** Reposition this BlobIO to a new rowId\r\n       * @note this BlobIO must be valid when this methods is called.\r\n       */\r\n    changeRow(row: number): void;\r\n    /** Write to a blob */\r\n    write(args: {\r\n      /** The number of bytes to write  */\r\n      numBytes: number;\r\n      /** starting offset within the blob to write */\r\n      offset: number;\r\n      /** the value to write */\r\n      blob: ArrayBuffer;\r\n    }): void;\r\n  }\r\n\r\n  /** Default transaction mode for SQLiteDbs.\r\n   * @see https://www.sqlite.org/lang_transaction.html\r\n   */\r\n  export enum DefaultTxnMode {\r\n    /** no default transaction is started. You must use BEGIN/COMMIT or SQLite will use implicit transactions */\r\n    None = 0,\r\n    /** A deferred transaction is started when the file is first opened. This is the default. */\r\n    Deferred = 1,\r\n    /** An immediate transaction is started when the file is first opened. */\r\n    Immediate = 2,\r\n    /** An exclusive transaction is started when the file is first opened. */\r\n    Exclusive = 3\r\n  }\r\n\r\n  /** parameters common to opening or creating a new SQLiteDb */\r\n  export interface OpenOrCreateParams {\r\n    /** If true, do not require that the `be_Prop` table exist */\r\n    rawSQLite?: boolean;\r\n    /** @see immutable option at https://www.sqlite.org/c3ref/open.html */\r\n    immutable?: boolean;\r\n    /** Do not attempt to verify that the file is a valid sQLite file before opening. */\r\n    skipFileCheck?: boolean;\r\n    /** the default transaction mode\r\n   * @see [[SQLiteDb.DefaultTxnMode]]\r\n  */\r\n    defaultTxn?: 0 | 1 | 2 | 3;\r\n    /** see query parameters from 'URI Filenames' in  https://www.sqlite.org/c3ref/open.html */\r\n    queryParam?: string;\r\n  }\r\n\r\n  /** Parameters for opening an existing SQLiteDb */\r\n  export interface OpenParams extends OpenOrCreateParams {\r\n    /** use OpenMode.ReadWrite to open the file with write access */\r\n    openMode: OpenMode;\r\n  }\r\n\r\n  /** Size of a SQLiteDb page in bytes */\r\n  export interface PageSize {\r\n    /** see https://www.sqlite.org/pragma.html#pragma_page_size */\r\n    pageSize?: number;\r\n  }\r\n\r\n  /** Parameters for creating a new SQLiteDb */\r\n  export type CreateParams = OpenOrCreateParams & PageSize;\r\n\r\n  /** Arguments for `SqliteDb.withOpenDb` */\r\n  export interface WithOpenDbArgs {\r\n    /** The name of the database to open */\r\n    dbName: string;\r\n    /** either an object with the open parameters or just OpenMode value. */\r\n    openMode?: OpenMode | SQLiteDb.OpenParams;\r\n    /** @internal */\r\n    container?: CloudSqlite.CloudContainer;\r\n  }\r\n\r\n  /** Arguments for `SQLiteDb.vacuum` */\r\n  export interface VacuumDbArgs extends PageSize {\r\n    /** if present, name of new file to [vacuum into](https://www.sqlite.org/lang_vacuum.html) */\r\n    into?: LocalFileName;\r\n  }\r\n}\r\n"]}

package/lib/esm/Schema.d.ts

@@ -0,0 +1,79 @@
+/** @packageDocumentation
+ * @module Schema
+ */
+import { SchemaKey } from "@itwin/ecschema-metadata";
+/** Base class for all schema classes - see [working with schemas and elements in TypeScript]($docs/learning/backend/SchemasAndElementsInTypeScript.md).
+ * @public
+ */
+export declare class Schema {
+    /** The name of the BIS schema handled by this Schema.
+     * @note Every subclass of Schema ** MUST ** override this method to identify its BIS schema.
+     * Failure to do so will ordinarily result in an error when the schema is registered, since there may only
+     * be one JavaScript class for a given BIS schema (usually the errant schema will collide with its superclass.)
+     */
+    static get schemaName(): string;
+    /** Unique identifier for this schema, typed variant of [[schemaName]].
+     * @internal
+     */
+    static get schemaKey(): SchemaKey;
+    /** if true, this Schema is a proxy for a missing Domain marked with the `BisCore.SchemaHasBehavior` customAttribute.
+     * Classes generated for this Schema will disallow protected operations.
+     * @internal
+     */
+    static get missingRequiredBehavior(): boolean;
+    /** Get a semver-compatible string from a padded version string.
+     * works on unpadded version strings as well
+     * if there is no write version, it will be added
+     * @example Schema.toSemverString("1.02.03") === "1.2.3"
+     * @example Schema.toSemverString("1.01") === "1.0.1" // write version was added
+     * @beta
+     */
+    static toSemverString(paddedVersion: string): string;
+    /** Schemas may not be instantiated. The method is not private only because that precludes subclassing. It throws an
+     * error if it is ever called.
+     * @internal
+     */
+    protected constructor();
+}
+/**
+ * Holds a map of registered schemas.
+ * @public
+ */
+export declare class SchemaMap {
+    private readonly _schemas;
+    /** @internal */
+    get(schemaName: string): typeof Schema | undefined;
+    /** @internal */
+    set(schemaName: string, schema: typeof Schema): void;
+    /** @internal */
+    delete(schemaName: string): boolean;
+    /** Register a schema prior to using it.
+     * @throws [[IModelError]] if a schema of the same name is already registered.
+     * @public
+     */
+    registerSchema(schema: typeof Schema): void;
+}
+/** Manages registered schemas
+ * @public
+ */
+export declare class Schemas {
+    private static readonly _globalSchemas;
+    private constructor();
+    /** Register a schema prior to using it.
+     * This method registers the schema globally, to register a schema within the scope of a single iModel, use `IModelDb.schemaMap`.
+     * @throws [[IModelError]] if a schema of the same name is already registered.
+     */
+    static registerSchema(schema: typeof Schema): void;
+    /** Unregister a schema, by name, if one is already registered.
+     * This function is not normally needed, but is useful for cases where a generated *proxy* schema needs to be replaced by the *real* schema.
+     * @param schemaName Name of the schema to unregister
+     * @return true if the schema was unregistered
+     */
+    static unregisterSchema(schemaName: string): boolean;
+    /** Look up a previously registered schema
+     * @param schemaName The name of the schema
+     * @returns the previously registered schema or undefined if not registered.
+     */
+    static getRegisteredSchema(schemaName: string): typeof Schema | undefined;
+}
+//# sourceMappingURL=Schema.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"Schema.d.ts","sourceRoot":"","sources":["../../src/Schema.ts"],"names":[],"mappings":"AAIA;;GAEG;AAKH,OAAO,EAAa,SAAS,EAAE,MAAM,0BAA0B,CAAC;AAEhE;;GAEG;AACH,qBAAa,MAAM;IACjB;;;;OAIG;IACH,WAAkB,UAAU,IAAI,MAAM,CAA4E;IAElH;;OAEG;IACH,WAAkB,SAAS,IAAI,SAAS,CAGvC;IAED;;;OAGG;IACH,WAAkB,uBAAuB,IAAI,OAAO,CAAkB;IAEtE;;;;;;OAMG;WACW,cAAc,CAAC,aAAa,EAAE,MAAM,GAAG,MAAM;IAQ3D;;;OAGG;IACH,SAAS;CACV;AAED;;;GAGG;AACH,qBAAa,SAAS;IACpB,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAoC;IAE3D,gBAAgB;IACT,GAAG,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,MAAM,GAAG,SAAS;IAIzD,gBAAgB;IACT,GAAG,CAAC,UAAU,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,MAAM,GAAG,IAAI;IAI3D,gBAAgB;IACT,MAAM,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO;IAI5C;;;OAGG;IACI,cAAc,CAAC,MAAM,EAAE,OAAO,MAAM;CAM5C;AAED;;GAEG;AACH,qBAAa,OAAO;IAClB,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,cAAc,CAAmB;IACzD,OAAO;IAEP;;;OAGG;WACW,cAAc,CAAC,MAAM,EAAE,OAAO,MAAM;IAIlD;;;;OAIG;WACW,gBAAgB,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO;IAQ3D;;;OAGG;WACW,mBAAmB,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,MAAM,GAAG,SAAS;CACjF"}

package/lib/esm/Schema.js

@@ -0,0 +1,113 @@
+/*---------------------------------------------------------------------------------------------
+* Copyright (c) Bentley Systems, Incorporated. All rights reserved.
+* See LICENSE.md in the project root for license terms and full copyright notice.
+*--------------------------------------------------------------------------------------------*/
+/** @packageDocumentation
+ * @module Schema
+ */
+import { IModelStatus } from "@itwin/core-bentley";
+import { IModelError } from "@itwin/core-common";
+import { ClassRegistry } from "./ClassRegistry";
+import { ECVersion, SchemaKey } from "@itwin/ecschema-metadata";
+/** Base class for all schema classes - see [working with schemas and elements in TypeScript]($docs/learning/backend/SchemasAndElementsInTypeScript.md).
+ * @public
+ */
+export class Schema {
+    /** The name of the BIS schema handled by this Schema.
+     * @note Every subclass of Schema ** MUST ** override this method to identify its BIS schema.
+     * Failure to do so will ordinarily result in an error when the schema is registered, since there may only
+     * be one JavaScript class for a given BIS schema (usually the errant schema will collide with its superclass.)
+     */
+    static get schemaName() { throw new Error(`you must override static schemaName in ${this.name}`); }
+    /** Unique identifier for this schema, typed variant of [[schemaName]].
+     * @internal
+     */
+    static get schemaKey() {
+        // We cannot cache this here because the schemaName may be overridden without this being overridden
+        return new SchemaKey(this.schemaName, ECVersion.NO_VERSION); // backend cares little for versions right now, as only one version can exist in an imodel
+    }
+    /** if true, this Schema is a proxy for a missing Domain marked with the `BisCore.SchemaHasBehavior` customAttribute.
+     * Classes generated for this Schema will disallow protected operations.
+     * @internal
+     */
+    static get missingRequiredBehavior() { return false; }
+    /** Get a semver-compatible string from a padded version string.
+     * works on unpadded version strings as well
+     * if there is no write version, it will be added
+     * @example Schema.toSemverString("1.02.03") === "1.2.3"
+     * @example Schema.toSemverString("1.01") === "1.0.1" // write version was added
+     * @beta
+     */
+    static toSemverString(paddedVersion) {
+        const tuple = paddedVersion.split(".").map(Number);
+        const noWriteVersion = tuple.length === 2;
+        if (noWriteVersion)
+            tuple.splice(1, 0, 0); // insert 0 before the second element
+        return tuple.join(".");
+    }
+    /** Schemas may not be instantiated. The method is not private only because that precludes subclassing. It throws an
+     * error if it is ever called.
+     * @internal
+     */
+    constructor() { throw new Error(`cannot create an instance of a Schema ${this.constructor.name}`); }
+}
+/**
+ * Holds a map of registered schemas.
+ * @public
+ */
+export class SchemaMap {
+    _schemas = new Map();
+    /** @internal */
+    get(schemaName) {
+        return this._schemas.get(schemaName.toLowerCase());
+    }
+    /** @internal */
+    set(schemaName, schema) {
+        this._schemas.set(schemaName.toLowerCase(), schema);
+    }
+    /** @internal */
+    delete(schemaName) {
+        return this._schemas.delete(schemaName.toLowerCase());
+    }
+    /** Register a schema prior to using it.
+     * @throws [[IModelError]] if a schema of the same name is already registered.
+     * @public
+     */
+    registerSchema(schema) {
+        const key = schema.schemaName.toLowerCase();
+        if (this.get(key))
+            throw new IModelError(IModelStatus.DuplicateName, `Schema "${schema.schemaName}" is already registered`);
+        this.set(key, schema);
+    }
+}
+/** Manages registered schemas
+ * @public
+ */
+export class Schemas {
+    static _globalSchemas = new SchemaMap();
+    constructor() { } // this is a singleton
+    /** Register a schema prior to using it.
+     * This method registers the schema globally, to register a schema within the scope of a single iModel, use `IModelDb.schemaMap`.
+     * @throws [[IModelError]] if a schema of the same name is already registered.
+     */
+    static registerSchema(schema) {
+        this._globalSchemas.registerSchema(schema);
+    }
+    /** Unregister a schema, by name, if one is already registered.
+     * This function is not normally needed, but is useful for cases where a generated *proxy* schema needs to be replaced by the *real* schema.
+     * @param schemaName Name of the schema to unregister
+     * @return true if the schema was unregistered
+     */
+    static unregisterSchema(schemaName) {
+        const schema = this.getRegisteredSchema(schemaName);
+        if (undefined !== schema)
+            ClassRegistry.unregisterClassesFrom(schema);
+        return this._globalSchemas.delete(schemaName.toLowerCase());
+    }
+    /** Look up a previously registered schema
+     * @param schemaName The name of the schema
+     * @returns the previously registered schema or undefined if not registered.
+     */
+    static getRegisteredSchema(schemaName) { return this._globalSchemas.get(schemaName.toLowerCase()); }
+}
+//# sourceMappingURL=Schema.js.map