@itwin/core-common 5.0.0-dev.82 → 5.0.0-dev.84

package/lib/cjs/ITwinError.d.ts

@@ -3,6 +3,7 @@
  */
 import { LoggingMetaData } from "@itwin/core-bentley";
 import { LockState } from "./IModelError";
+import { BriefcaseId } from "./BriefcaseTypes";
 /**
  * Detailed information about a particular object Lock that is causing the Lock update conflict.
  * An example of a lock update conflict would be attempting to use [LockControl.acquireLocks]($backend) on an object that is already locked by another Briefcase.
@@ -17,20 +18,34 @@ export interface InUseLock {
      */
     state: LockState;
     /** An array of Briefcase ids that hold this lock. */
-    briefcaseIds: number[];
+    briefcaseIds: BriefcaseId[];
 }
+/**
+ * iTwinjs Core namespace namespace for a developer/application.
+ * @beta
+ */
+export declare const iTwinjsCoreNamespace = "itwinjs-core";
+/**
+ * error keys object used to describe an error keys for a developer/application.
+ * @beta
+ */
+export declare const iTwinErrorKeys: {
+    readonly inUseLocks: "in-use-locks";
+    readonly channelNest: "channel-may-not-nest";
+    readonly channelNotAllowed: "channel-not-allowed";
+    readonly channelRootExists: "channel-root-exists";
+};
+/**
+ * Record for all itwin error messages.
+ * @beta
+ */
+export declare const iTwinErrorMessages: Record<keyof typeof iTwinErrorKeys, (...args: any[]) => string>;
 /**
  * An interface used to describe an error for a developer/application. The message is not intended to be displayed to an end user.
  * This error interface should be extended when needing to throw errors with extra properties defined on them. See [[InUseLocksError]] for an example.
- * When extending ITwinError, one should typically add a type guard function and a function to throw the error either to a namespace for their error or as standalone functions.
- * See [[InUseLocksError.throwInUseLocksError]] and [[InUseLocksError.isInUseLocksError]] for examples of how to throw and check that an error is of type InUseLocksError.
- * * Example of catching a ITwinError:
- * ``` ts
- * [[include:ITwinError.catchAndHandleITwinError]]
- * ```
  * @beta
  */
-export interface ITwinError {
+export interface ITwinError extends Error {
     /** namespace for the error. This is a unique qualifier for the errorKey. */
     namespace: string;
     /** unique key for error, within namespace. All errorKeys within the same namespace must be unique. */
@@ -48,25 +63,46 @@ export interface ITwinError {
  * @beta
 */
 export interface InUseLocksError extends ITwinError {
-    namespace: "itwinjs-core";
-    errorKey: "in-use-locks";
     inUseLocks: InUseLock[];
 }
-/** @beta */
-export declare namespace InUseLocksError {
-    /**
-     * type guard function that returns whether or not the passed in parameter is an [[InUseLocksError]].
-     * it first checks [[ITwinError.isITwinError]] and then checks that the namespace property is "itwinjs-core" and the errorKey property is "in-use-locks".
-     */
-    function isInUseLocksError(error: unknown): error is InUseLocksError;
-    /** throws an error which passes the [[InUseLocksError.isInUseLocksError]] type guard function */
-    function throwInUseLocksError(inUseLocks: InUseLock[], message?: string, metadata?: LoggingMetaData): never;
-}
-/** @beta */
-export declare namespace ITwinError {
-    /** type guard function that returns whether or not the passed in parameter is an [[ITwinError]] */
-    function isITwinError(error: unknown): error is ITwinError;
-    /** get the meta data associated with this ITwinError, if any. */
-    function getMetaData(err: ITwinError): object | undefined;
-}
+/**
+* A function which will be used to construct an [[ITwinError]].
+* @param namespace The namespace associated with the error.
+* @param errorKey The errorKey associated with the error.
+* @param message The message associated with the error.
+* @param metadata Metadata associated with the error.
+* @beta
+*/
+export declare function constructITwinError(namespace: string, errorKey: string, message?: string, metadata?: LoggingMetaData): ITwinError;
+/**
+* A function which constructs a detailed error for example [[ InUseLocksError ]] above.
+* @param namespace The namespace associated with the error.
+* @param errorKey The errorKey associated with the error.
+* @param details Other details associated with the error.
+* @param message The message associated with the error.
+* @param metadata Metadata associated with the error.
+* @beta
+*/
+export declare function constructDetailedError<T extends ITwinError>(namespace: string, errorKey: string, details: Omit<T, keyof ITwinError>, message?: string, metadata?: LoggingMetaData): T;
+/**
+ * a high level function that returns a type asserter function which would return whether or not the passed in parameter is an [[ITwinError]]
+ * @param namespace The namespace associated with the error.
+ * @param errorKey The errorKey associated with the error.
+ * @beta
+*/
+export declare function createITwinErrorTypeAsserter<T extends ITwinError>(namespace: string, errorKey: string): (error: unknown) => error is T;
+/**
+ * get the meta data associated with this ITwinError, if any.
+ * @param error The error for which metadata is required.
+ * @beta
+*/
+export declare function getITwinErrorMetaData(error: ITwinError): object | undefined;
+/**
+ * type guard function that returns whether or not the passed in parameter is an [[ITwinError]]
+ * @param error The error which is to ve verified.
+ * @param namespace The namespace associated with the error.
+ * @param errorKey The errorKey associated with the error.
+ * @beta
+*/
+export declare function isITwinError(error: unknown, namespace?: string, errorKey?: string): error is ITwinError;
 //# sourceMappingURL=ITwinError.d.ts.map

package/lib/cjs/ITwinError.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ITwinError.d.ts","sourceRoot":"","sources":["../../src/ITwinError.ts"],"names":[],"mappings":"AAIA;;GAEG;AAEH,OAAO,EAAgB,eAAe,EAAE,MAAM,qBAAqB,CAAC;AACpE,OAAO,EAAE,SAAS,EAAE,MAAM,eAAe,CAAC;AAE1C;;;;GAIG;AACH,MAAM,WAAW,SAAS;IACxB,iDAAiD;IACjD,QAAQ,EAAE,MAAM,CAAC;IACjB;;;OAGG;IACH,KAAK,EAAE,SAAS,CAAC;IACjB,qDAAqD;IACrD,YAAY,EAAE,MAAM,EAAE,CAAC;CACxB;AAED;;;;;;;;;;GAUG;AACH,MAAM,WAAW,UAAU;IACzB,4EAA4E;IAC5E,SAAS,EAAE,MAAM,CAAC;IAClB,sGAAsG;IACtG,QAAQ,EAAE,MAAM,CAAC;IACjB,0EAA0E;IAC1E,OAAO,EAAE,MAAM,CAAC;IAChB,gCAAgC;IAChC,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,oCAAoC;IACpC,QAAQ,CAAC,EAAE,eAAe,CAAC;CAC5B;AAED;;;;EAIE;AACF,MAAM,WAAW,eAAgB,SAAQ,UAAU;IACjD,SAAS,EAAE,cAAc,CAAC;IAC1B,QAAQ,EAAE,cAAc,CAAC;IACzB,UAAU,EAAE,SAAS,EAAE,CAAC;CACzB;AAED,YAAY;AACZ,yBAAiB,eAAe,CAAC;IAE/B;;;OAGG;IACH,SAAgB,iBAAiB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,eAAe,CAE1E;IAED,iGAAiG;IACjG,SAAgB,oBAAoB,CAAC,UAAU,EAAE,SAAS,EAAE,EAAE,OAAO,CAAC,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,eAAe,GAAG,KAAK,CAajH;CAEF;AACD,YAAY;AACZ,yBAAiB,UAAU,CAAC;IAC1B,mGAAmG;IACnG,SAAgB,YAAY,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,UAAU,CAEhE;IAED,iEAAiE;IACjE,SAAgB,WAAW,CAAC,GAAG,EAAE,UAAU,GAAG,MAAM,GAAG,SAAS,CAE/D;CAEF"}
+{"version":3,"file":"ITwinError.d.ts","sourceRoot":"","sources":["../../src/ITwinError.ts"],"names":[],"mappings":"AAIA;;GAEG;AAEH,OAAO,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC;AACtD,OAAO,EAAE,SAAS,EAAE,MAAM,eAAe,CAAC;AAC1C,OAAO,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAE/C;;;;GAIG;AACH,MAAM,WAAW,SAAS;IACxB,iDAAiD;IACjD,QAAQ,EAAE,MAAM,CAAC;IACjB;;;OAGG;IACH,KAAK,EAAE,SAAS,CAAC;IACjB,qDAAqD;IACrD,YAAY,EAAE,WAAW,EAAE,CAAC;CAC7B;AAED;;;GAGG;AACH,eAAO,MAAM,oBAAoB,iBAAiB,CAAC;AAEnD;;;GAGG;AACH,eAAO,MAAM,cAAc;;;;;CAKjB,CAAC;AAEX;;;GAGG;AACH,eAAO,MAAM,kBAAkB,EAAE,MAAM,CAAC,MAAM,OAAO,cAAc,EAAE,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,MAAM,CAK9F,CAAC;AAGF;;;;GAIG;AACH,MAAM,WAAW,UAAW,SAAQ,KAAK;IACvC,4EAA4E;IAC5E,SAAS,EAAE,MAAM,CAAC;IAClB,sGAAsG;IACtG,QAAQ,EAAE,MAAM,CAAC;IACjB,0EAA0E;IAC1E,OAAO,EAAE,MAAM,CAAC;IAChB,gCAAgC;IAChC,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,oCAAoC;IACpC,QAAQ,CAAC,EAAE,eAAe,CAAC;CAC5B;AAED;;;;EAIE;AACF,MAAM,WAAW,eAAgB,SAAQ,UAAU;IACjD,UAAU,EAAE,SAAS,EAAE,CAAC;CACzB;AAED;;;;;;;EAOE;AACF,wBAAgB,mBAAmB,CAAC,SAAS,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,eAAe,GAAG,UAAU,CAWjI;AAED;;;;;;;;EAQE;AACF,wBAAgB,sBAAsB,CAAC,CAAC,SAAS,UAAU,EAAE,SAAS,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,IAAI,CAAC,CAAC,EAAE,MAAM,UAAU,CAAC,EAAE,OAAO,CAAC,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,eAAe,GAAG,CAAC,CAKrL;AAED;;;;;EAKE;AACF,wBAAgB,4BAA4B,CAAC,CAAC,SAAS,UAAU,EAAE,SAAS,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,WACrF,OAAO,KAAG,KAAK,IAAI,CAAC,CACpC;AAED;;;;EAIE;AACF,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,UAAU,GAAG,MAAM,GAAG,SAAS,CAE3E;AAED;;;;;;EAME;AACF,wBAAgB,YAAY,CAAC,KAAK,EAAE,OAAO,EAAE,SAAS,CAAC,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,MAAM,GAAG,KAAK,IAAI,UAAU,CAKvG"}

package/lib/cjs/ITwinError.js

@@ -7,49 +7,97 @@
  * @module iModels
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.ITwinError = exports.InUseLocksError = void 0;
-const core_bentley_1 = require("@itwin/core-bentley");
-/** @beta */
-var InUseLocksError;
-(function (InUseLocksError) {
-    /**
-     * type guard function that returns whether or not the passed in parameter is an [[InUseLocksError]].
-     * it first checks [[ITwinError.isITwinError]] and then checks that the namespace property is "itwinjs-core" and the errorKey property is "in-use-locks".
-     */
-    function isInUseLocksError(error) {
-        return ITwinError.isITwinError(error) && error.namespace === "itwinjs-core" && error.errorKey === "in-use-locks";
-    }
-    InUseLocksError.isInUseLocksError = isInUseLocksError;
-    /** throws an error which passes the [[InUseLocksError.isInUseLocksError]] type guard function */
-    function throwInUseLocksError(inUseLocks, message, metadata) {
-        const errorObject = new Error();
-        errorObject.name = "InUseLocksError"; // optional but makes it so that when the error is thrown and not caught we see InUseLocksError: 'message' instead of Error: 'message'
-        Error.captureStackTrace(errorObject, throwInUseLocksError); // optional: whether we want to hide throwInUseLocksError or not from the stack. not super important
-        const lockError = {
-            namespace: "itwinjs-core",
-            errorKey: "in-use-locks",
-            message: message ?? "One or more objects are already locked by another briefcase.",
-            metadata,
-            inUseLocks,
-        };
-        Object.assign(errorObject, lockError);
-        throw errorObject;
-    }
-    InUseLocksError.throwInUseLocksError = throwInUseLocksError;
-})(InUseLocksError || (exports.InUseLocksError = InUseLocksError = {}));
-/** @beta */
-var ITwinError;
-(function (ITwinError) {
-    /** type guard function that returns whether or not the passed in parameter is an [[ITwinError]] */
-    function isITwinError(error) {
-        return error !== undefined && error !== null && typeof error === "object" && "namespace" in error && "errorKey" in error && "message" in error;
-    }
-    ITwinError.isITwinError = isITwinError;
-    /** get the meta data associated with this ITwinError, if any. */
-    function getMetaData(err) {
-        return core_bentley_1.BentleyError.getMetaData(err.metadata);
-    }
-    ITwinError.getMetaData = getMetaData;
-})(ITwinError || (exports.ITwinError = ITwinError = {}));
-;
+exports.iTwinErrorMessages = exports.iTwinErrorKeys = exports.iTwinjsCoreNamespace = void 0;
+exports.constructITwinError = constructITwinError;
+exports.constructDetailedError = constructDetailedError;
+exports.createITwinErrorTypeAsserter = createITwinErrorTypeAsserter;
+exports.getITwinErrorMetaData = getITwinErrorMetaData;
+exports.isITwinError = isITwinError;
+/**
+ * iTwinjs Core namespace namespace for a developer/application.
+ * @beta
+ */
+exports.iTwinjsCoreNamespace = "itwinjs-core";
+/**
+ * error keys object used to describe an error keys for a developer/application.
+ * @beta
+ */
+exports.iTwinErrorKeys = {
+    inUseLocks: "in-use-locks",
+    channelNest: "channel-may-not-nest",
+    channelNotAllowed: "channel-not-allowed",
+    channelRootExists: "channel-root-exists"
+};
+/**
+ * Record for all itwin error messages.
+ * @beta
+ */
+exports.iTwinErrorMessages = {
+    "inUseLocks": () => 'Objects are locked by another briefcase',
+    "channelNest": (id) => `Channel ${id} may not nest`,
+    "channelNotAllowed": (id) => `Channel ${id} is not allowed`,
+    "channelRootExists": (id) => `Channel ${id} root already exist`,
+};
+/**
+* A function which will be used to construct an [[ITwinError]].
+* @param namespace The namespace associated with the error.
+* @param errorKey The errorKey associated with the error.
+* @param message The message associated with the error.
+* @param metadata Metadata associated with the error.
+* @beta
+*/
+function constructITwinError(namespace, errorKey, message, metadata) {
+    const error = new Error();
+    error.message = message ?? `${errorKey} occurred`;
+    error.name = `${namespace}:${errorKey}`;
+    error.namespace = namespace;
+    error.errorKey = errorKey;
+    error.metadata = metadata;
+    Error.captureStackTrace(error, constructITwinError); // Optional, but this would hide constructITwinError from stack.
+    return error;
+}
+/**
+* A function which constructs a detailed error for example [[ InUseLocksError ]] above.
+* @param namespace The namespace associated with the error.
+* @param errorKey The errorKey associated with the error.
+* @param details Other details associated with the error.
+* @param message The message associated with the error.
+* @param metadata Metadata associated with the error.
+* @beta
+*/
+function constructDetailedError(namespace, errorKey, details, message, metadata) {
+    const baseError = constructITwinError(namespace, errorKey, message, metadata);
+    Error.captureStackTrace(baseError, constructDetailedError); // Optional, but this would hide constructDetailedError from stack.
+    return Object.assign(baseError, details);
+}
+/**
+ * a high level function that returns a type asserter function which would return whether or not the passed in parameter is an [[ITwinError]]
+ * @param namespace The namespace associated with the error.
+ * @param errorKey The errorKey associated with the error.
+ * @beta
+*/
+function createITwinErrorTypeAsserter(namespace, errorKey) {
+    return (error) => isITwinError(error, namespace, errorKey);
+}
+/**
+ * get the meta data associated with this ITwinError, if any.
+ * @param error The error for which metadata is required.
+ * @beta
+*/
+function getITwinErrorMetaData(error) {
+    return (typeof error.metadata === "function") ? error.metadata() : error.metadata;
+}
+/**
+ * type guard function that returns whether or not the passed in parameter is an [[ITwinError]]
+ * @param error The error which is to ve verified.
+ * @param namespace The namespace associated with the error.
+ * @param errorKey The errorKey associated with the error.
+ * @beta
+*/
+function isITwinError(error, namespace, errorKey) {
+    return error !== undefined && error !== null && typeof error === "object"
+        && "namespace" in error && "errorKey" in error && "message" in error
+        && (namespace === undefined || error.namespace === namespace)
+        && (errorKey === undefined || error.errorKey === errorKey);
+}
 //# sourceMappingURL=ITwinError.js.map

package/lib/cjs/ITwinError.js.map

@@ -1 +1 @@
-{"version":3,"file":"ITwinError.js","sourceRoot":"","sources":["../../src/ITwinError.ts"],"names":[],"mappings":";AAAA;;;+FAG+F;AAC/F;;GAEG;;;AAEH,sDAAoE;AAuDpE,YAAY;AACZ,IAAiB,eAAe,CA0B/B;AA1BD,WAAiB,eAAe;IAE9B;;;OAGG;IACH,SAAgB,iBAAiB,CAAC,KAAc;QAC9C,OAAO,UAAU,CAAC,YAAY,CAAC,KAAK,CAAC,IAAI,KAAK,CAAC,SAAS,KAAK,cAAc,IAAI,KAAK,CAAC,QAAQ,KAAK,cAAc,CAAC;IACnH,CAAC;IAFe,iCAAiB,oBAEhC,CAAA;IAED,iGAAiG;IACjG,SAAgB,oBAAoB,CAAC,UAAuB,EAAE,OAAgB,EAAE,QAA0B;QACxG,MAAM,WAAW,GAAG,IAAI,KAAK,EAAE,CAAC;QAChC,WAAW,CAAC,IAAI,GAAG,iBAAiB,CAAC,CAAC,sIAAsI;QAC5K,KAAK,CAAC,iBAAiB,CAAC,WAAW,EAAE,oBAAoB,CAAC,CAAC,CAAC,oGAAoG;QAChK,MAAM,SAAS,GAAoB;YACjC,SAAS,EAAE,cAAc;YACzB,QAAQ,EAAE,cAAc;YACxB,OAAO,EAAE,OAAO,IAAI,8DAA8D;YAClF,QAAQ;YACR,UAAU;SACX,CAAC;QACF,MAAM,CAAC,MAAM,CAAC,WAAW,EAAE,SAAS,CAAC,CAAC;QACtC,MAAM,WAAW,CAAC;IACpB,CAAC;IAbe,oCAAoB,uBAanC,CAAA;AAEH,CAAC,EA1BgB,eAAe,+BAAf,eAAe,QA0B/B;AACD,YAAY;AACZ,IAAiB,UAAU,CAW1B;AAXD,WAAiB,UAAU;IACzB,mGAAmG;IACnG,SAAgB,YAAY,CAAC,KAAc;QACzC,OAAO,KAAK,KAAK,SAAS,IAAI,KAAK,KAAK,IAAI,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,WAAW,IAAI,KAAK,IAAI,UAAU,IAAI,KAAK,IAAI,SAAS,IAAI,KAAK,CAAC;IACjJ,CAAC;IAFe,uBAAY,eAE3B,CAAA;IAED,iEAAiE;IACjE,SAAgB,WAAW,CAAC,GAAe;QACzC,OAAO,2BAAY,CAAC,WAAW,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;IAChD,CAAC;IAFe,sBAAW,cAE1B,CAAA;AAEH,CAAC,EAXgB,UAAU,0BAAV,UAAU,QAW1B;AAAA,CAAC","sourcesContent":["/*---------------------------------------------------------------------------------------------\n* Copyright (c) Bentley Systems, Incorporated. All rights reserved.\n* See LICENSE.md in the project root for license terms and full copyright notice.\n*--------------------------------------------------------------------------------------------*/\n/** @packageDocumentation\n * @module iModels\n */\n\nimport { BentleyError, LoggingMetaData } from \"@itwin/core-bentley\";\nimport { LockState } from \"./IModelError\";\n\n/**\n * Detailed information about a particular object Lock that is causing the Lock update conflict.\n * An example of a lock update conflict would be attempting to use [LockControl.acquireLocks]($backend) on an object that is already locked by another Briefcase.\n * @beta\n */\nexport interface InUseLock {\n  /** Id of the object that is causing conflict. */\n  objectId: string;\n  /**\n   * The level of conflicting lock. Possible values are {@link LockState.Shared}, {@link LockState.Exclusive}.\n   * See {@link LockState}.\n   */\n  state: LockState;\n  /** An array of Briefcase ids that hold this lock. */\n  briefcaseIds: number[];\n}\n\n/**\n * An interface used to describe an error for a developer/application. The message is not intended to be displayed to an end user.\n * This error interface should be extended when needing to throw errors with extra properties defined on them. See [[InUseLocksError]] for an example.\n * When extending ITwinError, one should typically add a type guard function and a function to throw the error either to a namespace for their error or as standalone functions.\n * See [[InUseLocksError.throwInUseLocksError]] and [[InUseLocksError.isInUseLocksError]] for examples of how to throw and check that an error is of type InUseLocksError.\n * * Example of catching a ITwinError:\n * ``` ts\n * [[include:ITwinError.catchAndHandleITwinError]]\n * ```\n * @beta\n */\nexport interface ITwinError {\n  /** namespace for the error. This is a unique qualifier for the errorKey. */\n  namespace: string;\n  /** unique key for error, within namespace. All errorKeys within the same namespace must be unique. */\n  errorKey: string;\n  /** explanation of what went wrong. Intended to be read by a developer. */\n  message: string;\n  /** stack trace of the error. */\n  stack?: string;\n  /** metadata about the exception. */\n  metadata?: LoggingMetaData;\n}\n\n/**\n * An error raised when there is a lock conflict detected.\n * Typically this error would be thrown by [LockControl.acquireLocks]($backend) when you are requesting a lock on an element that is already held by another briefcase.\n * @beta\n*/\nexport interface InUseLocksError extends ITwinError {\n  namespace: \"itwinjs-core\";\n  errorKey: \"in-use-locks\";\n  inUseLocks: InUseLock[];\n}\n\n/** @beta */\nexport namespace InUseLocksError {\n\n  /**\n   * type guard function that returns whether or not the passed in parameter is an [[InUseLocksError]].\n   * it first checks [[ITwinError.isITwinError]] and then checks that the namespace property is \"itwinjs-core\" and the errorKey property is \"in-use-locks\".\n   */\n  export function isInUseLocksError(error: unknown): error is InUseLocksError {\n    return ITwinError.isITwinError(error) && error.namespace === \"itwinjs-core\" && error.errorKey === \"in-use-locks\";\n  }\n\n  /** throws an error which passes the [[InUseLocksError.isInUseLocksError]] type guard function */\n  export function throwInUseLocksError(inUseLocks: InUseLock[], message?: string, metadata?: LoggingMetaData): never {\n    const errorObject = new Error();\n    errorObject.name = \"InUseLocksError\"; // optional but makes it so that when the error is thrown and not caught we see InUseLocksError: 'message' instead of Error: 'message'\n    Error.captureStackTrace(errorObject, throwInUseLocksError); // optional: whether we want to hide throwInUseLocksError or not from the stack. not super important\n    const lockError: InUseLocksError = {\n      namespace: \"itwinjs-core\",\n      errorKey: \"in-use-locks\",\n      message: message ?? \"One or more objects are already locked by another briefcase.\",\n      metadata,\n      inUseLocks,\n    };\n    Object.assign(errorObject, lockError);\n    throw errorObject;\n  }\n\n}\n/** @beta */\nexport namespace ITwinError {\n  /** type guard function that returns whether or not the passed in parameter is an [[ITwinError]] */\n  export function isITwinError(error: unknown): error is ITwinError {\n    return error !== undefined && error !== null && typeof error === \"object\" && \"namespace\" in error && \"errorKey\" in error && \"message\" in error;\n  }\n\n  /** get the meta data associated with this ITwinError, if any. */\n  export function getMetaData(err: ITwinError): object | undefined {\n    return BentleyError.getMetaData(err.metadata);\n  }\n\n};\n"]}
+{"version":3,"file":"ITwinError.js","sourceRoot":"","sources":["../../src/ITwinError.ts"],"names":[],"mappings":";AAAA;;;+FAG+F;AAC/F;;GAEG;;;AAuFH,kDAWC;AAWD,wDAKC;AAQD,oEAEC;AAOD,sDAEC;AASD,oCAKC;AA5HD;;;GAGG;AACU,QAAA,oBAAoB,GAAG,cAAc,CAAC;AAEnD;;;GAGG;AACU,QAAA,cAAc,GAAG;IAC5B,UAAU,EAAE,cAAc;IAC1B,WAAW,EAAE,sBAAsB;IACnC,iBAAiB,EAAE,qBAAqB;IACxC,iBAAiB,EAAE,qBAAqB;CAChC,CAAC;AAEX;;;GAGG;AACU,QAAA,kBAAkB,GAAoE;IACjG,YAAY,EAAE,GAAG,EAAE,CAAC,yCAAyC;IAC7D,aAAa,EAAE,CAAC,EAAE,EAAE,EAAE,CAAC,WAAW,EAAE,eAAe;IACnD,mBAAmB,EAAE,CAAC,EAAE,EAAE,EAAE,CAAC,WAAW,EAAE,iBAAiB;IAC3D,mBAAmB,EAAE,CAAC,EAAE,EAAE,EAAE,CAAC,WAAW,EAAE,qBAAqB;CAChE,CAAC;AA8BF;;;;;;;EAOE;AACF,SAAgB,mBAAmB,CAAC,SAAiB,EAAE,QAAgB,EAAE,OAAgB,EAAE,QAA0B;IAEnH,MAAM,KAAK,GAAG,IAAI,KAAK,EAAgB,CAAC;IACxC,KAAK,CAAC,OAAO,GAAG,OAAO,IAAI,GAAG,QAAQ,WAAW,CAAC;IAClD,KAAK,CAAC,IAAI,GAAG,GAAG,SAAS,IAAI,QAAQ,EAAE,CAAC;IACxC,KAAK,CAAC,SAAS,GAAG,SAAS,CAAC;IAC5B,KAAK,CAAC,QAAQ,GAAG,QAAQ,CAAC;IAC1B,KAAK,CAAC,QAAQ,GAAG,QAAQ,CAAC;IAE1B,KAAK,CAAC,iBAAiB,CAAC,KAAK,EAAE,mBAAmB,CAAC,CAAC,CAAC,gEAAgE;IACrH,OAAO,KAAK,CAAC;AACf,CAAC;AAED;;;;;;;;EAQE;AACF,SAAgB,sBAAsB,CAAuB,SAAiB,EAAE,QAAgB,EAAE,OAAkC,EAAE,OAAgB,EAAE,QAA0B;IAChL,MAAM,SAAS,GAAG,mBAAmB,CAAC,SAAS,EAAE,QAAQ,EAAE,OAAO,EAAE,QAAQ,CAAC,CAAC;IAE9E,KAAK,CAAC,iBAAiB,CAAC,SAAS,EAAE,sBAAsB,CAAC,CAAC,CAAC,mEAAmE;IAC/H,OAAO,MAAM,CAAC,MAAM,CAAC,SAAS,EAAE,OAAO,CAAM,CAAC;AAChD,CAAC;AAED;;;;;EAKE;AACF,SAAgB,4BAA4B,CAAuB,SAAiB,EAAE,QAAgB;IACpG,OAAO,CAAC,KAAc,EAAc,EAAE,CAAC,YAAY,CAAC,KAAK,EAAE,SAAS,EAAE,QAAQ,CAAC,CAAC;AAClF,CAAC;AAED;;;;EAIE;AACF,SAAgB,qBAAqB,CAAC,KAAiB;IACrD,OAAO,CAAC,OAAO,KAAK,CAAC,QAAQ,KAAK,UAAU,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,QAAQ,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC,QAAQ,CAAC;AACpF,CAAC;AAED;;;;;;EAME;AACF,SAAgB,YAAY,CAAC,KAAc,EAAE,SAAkB,EAAE,QAAiB;IAChF,OAAO,KAAK,KAAK,SAAS,IAAI,KAAK,KAAK,IAAI,IAAI,OAAO,KAAK,KAAK,QAAQ;WACpE,WAAW,IAAI,KAAK,IAAI,UAAU,IAAI,KAAK,IAAI,SAAS,IAAI,KAAK;WACjE,CAAC,SAAS,KAAK,SAAS,IAAK,KAAoB,CAAC,SAAS,KAAK,SAAS,CAAC;WAC1E,CAAC,QAAQ,KAAK,SAAS,IAAK,KAAoB,CAAC,QAAQ,KAAK,QAAQ,CAAC,CAAC;AAC/E,CAAC","sourcesContent":["/*---------------------------------------------------------------------------------------------\n* Copyright (c) Bentley Systems, Incorporated. All rights reserved.\n* See LICENSE.md in the project root for license terms and full copyright notice.\n*--------------------------------------------------------------------------------------------*/\n/** @packageDocumentation\n * @module iModels\n */\n\nimport { LoggingMetaData } from \"@itwin/core-bentley\";\nimport { LockState } from \"./IModelError\";\nimport { BriefcaseId } from \"./BriefcaseTypes\";\n\n/**\n * Detailed information about a particular object Lock that is causing the Lock update conflict.\n * An example of a lock update conflict would be attempting to use [LockControl.acquireLocks]($backend) on an object that is already locked by another Briefcase.\n * @beta\n */\nexport interface InUseLock {\n  /** Id of the object that is causing conflict. */\n  objectId: string;\n  /**\n   * The level of conflicting lock. Possible values are {@link LockState.Shared}, {@link LockState.Exclusive}.\n   * See {@link LockState}.\n   */\n  state: LockState;\n  /** An array of Briefcase ids that hold this lock. */\n  briefcaseIds: BriefcaseId[];\n}\n\n/**\n * iTwinjs Core namespace namespace for a developer/application.\n * @beta\n */\nexport const iTwinjsCoreNamespace = \"itwinjs-core\";\n\n/**\n * error keys object used to describe an error keys for a developer/application.\n * @beta\n */\nexport const iTwinErrorKeys = {\n  inUseLocks: \"in-use-locks\",\n  channelNest: \"channel-may-not-nest\",\n  channelNotAllowed: \"channel-not-allowed\",\n  channelRootExists: \"channel-root-exists\"\n} as const;\n\n/**\n * Record for all itwin error messages.\n * @beta\n */\nexport const iTwinErrorMessages: Record<keyof typeof iTwinErrorKeys, (...args: any[]) => string> = {\n  \"inUseLocks\": () => 'Objects are locked by another briefcase',\n  \"channelNest\": (id) => `Channel ${id} may not nest`,\n  \"channelNotAllowed\": (id) => `Channel ${id} is not allowed`,\n  \"channelRootExists\": (id) => `Channel ${id} root already exist`,\n};\n\n\n/**\n * An interface used to describe an error for a developer/application. The message is not intended to be displayed to an end user.\n * This error interface should be extended when needing to throw errors with extra properties defined on them. See [[InUseLocksError]] for an example.\n * @beta\n */\nexport interface ITwinError extends Error {\n  /** namespace for the error. This is a unique qualifier for the errorKey. */\n  namespace: string;\n  /** unique key for error, within namespace. All errorKeys within the same namespace must be unique. */\n  errorKey: string;\n  /** explanation of what went wrong. Intended to be read by a developer. */\n  message: string;\n  /** stack trace of the error. */\n  stack?: string;\n  /** metadata about the exception. */\n  metadata?: LoggingMetaData;\n}\n\n/**\n * An error raised when there is a lock conflict detected.\n * Typically this error would be thrown by [LockControl.acquireLocks]($backend) when you are requesting a lock on an element that is already held by another briefcase.\n * @beta\n*/\nexport interface InUseLocksError extends ITwinError {\n  inUseLocks: InUseLock[];\n}\n\n/**\n* A function which will be used to construct an [[ITwinError]].\n* @param namespace The namespace associated with the error.\n* @param errorKey The errorKey associated with the error.\n* @param message The message associated with the error.\n* @param metadata Metadata associated with the error.\n* @beta\n*/\nexport function constructITwinError(namespace: string, errorKey: string, message?: string, metadata?: LoggingMetaData): ITwinError {\n\n  const error = new Error() as ITwinError;\n  error.message = message ?? `${errorKey} occurred`;\n  error.name = `${namespace}:${errorKey}`;\n  error.namespace = namespace;\n  error.errorKey = errorKey;\n  error.metadata = metadata;\n\n  Error.captureStackTrace(error, constructITwinError); // Optional, but this would hide constructITwinError from stack.\n  return error;\n}\n\n/**\n* A function which constructs a detailed error for example [[ InUseLocksError ]] above.\n* @param namespace The namespace associated with the error.\n* @param errorKey The errorKey associated with the error.\n* @param details Other details associated with the error.\n* @param message The message associated with the error.\n* @param metadata Metadata associated with the error.\n* @beta\n*/\nexport function constructDetailedError<T extends ITwinError>(namespace: string, errorKey: string, details: Omit<T, keyof ITwinError>, message?: string, metadata?: LoggingMetaData): T {\n  const baseError = constructITwinError(namespace, errorKey, message, metadata);\n\n  Error.captureStackTrace(baseError, constructDetailedError); // Optional, but this would hide constructDetailedError from stack.\n  return Object.assign(baseError, details) as T;\n}\n\n/**\n * a high level function that returns a type asserter function which would return whether or not the passed in parameter is an [[ITwinError]]\n * @param namespace The namespace associated with the error.\n * @param errorKey The errorKey associated with the error.\n * @beta\n*/\nexport function createITwinErrorTypeAsserter<T extends ITwinError>(namespace: string, errorKey: string) {\n  return (error: unknown): error is T => isITwinError(error, namespace, errorKey);\n}\n\n/**\n * get the meta data associated with this ITwinError, if any.\n * @param error The error for which metadata is required.\n * @beta\n*/\nexport function getITwinErrorMetaData(error: ITwinError): object | undefined {\n  return (typeof error.metadata === \"function\") ? error.metadata() : error.metadata;\n}\n\n/**\n * type guard function that returns whether or not the passed in parameter is an [[ITwinError]]\n * @param error The error which is to ve verified.\n * @param namespace The namespace associated with the error.\n * @param errorKey The errorKey associated with the error.\n * @beta\n*/\nexport function isITwinError(error: unknown, namespace?: string, errorKey?: string): error is ITwinError {\n  return error !== undefined && error !== null && typeof error === \"object\"\n    && \"namespace\" in error && \"errorKey\" in error && \"message\" in error\n    && (namespace === undefined || (error as ITwinError).namespace === namespace)\n    && (errorKey === undefined || (error as ITwinError).errorKey === errorKey);\n}\n"]}

package/lib/cjs/ipc/IpcSocket.d.ts

@@ -36,6 +36,7 @@ export type IpcInvokeReturn = {
         message: string;
         errorNumber: number;
         stack?: string;
+        metadata?: LoggingMetaData;
     };
 } | {
     result?: never;

package/lib/cjs/ipc/IpcSocket.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"IpcSocket.d.ts","sourceRoot":"","sources":["../../../src/ipc/IpcSocket.ts"],"names":[],"mappings":"AAIA;;GAEG;AAEH,OAAO,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC;AAEtD;;;KAGK;AACL,eAAO,MAAM,YAAY,YAAa,MAAM,WAAuB,CAAC;AAEpE;;;GAGG;AACH,MAAM,MAAM,WAAW,GAAG,CAAC,GAAG,EAAE,KAAK,EAAE,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,IAAI,CAAC;AAE/D;;;;GAIG;AACH,MAAM,MAAM,cAAc,GAAG,MAAM,IAAI,CAAC;AAExC;;;;;eAKe;AACf,MAAM,MAAM,eAAe,GAAG;IAAE,MAAM,EAAE,GAAG,CAAC;IAAC,KAAK,CAAC,EAAE,KAAK,CAAC;IAAC,UAAU,CAAC,EAAE,KAAK,CAAA;CAAE,GAAG;IAAE,MAAM,CAAC,EAAE,KAAK,CAAC;IAAC,UAAU,CAAC,EAAE,KAAK,CAAC;IAAC,KAAK,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAC;QAAC,WAAW,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAA;KAAE,CAAA;CAAE,GACxM;IAAE,MAAM,CAAC,EAAE,KAAK,CAAC;IAAC,KAAK,CAAC,EAAE,KAAK,CAAC;IAAC,UAAU,EAAE;QAAC,SAAS,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,EAAE,eAAe,CAAC;QAAC,CAAC,GAAG,EAAE,MAAM,GAAG,GAAG,CAAA;KAAE,CAAA;CAAE,CAAC;AACvK;;;;;EAKE;AACF,MAAM,WAAW,SAAS;IACxB;;;;;;OAMG;IACH,IAAI,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,IAAI,CAAC;IAChD;;;;;OAKG;IACH,WAAW,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,WAAW,KAAK,cAAc,CAAC;IACxE;;;;OAIG;IACH,cAAc,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,WAAW,KAAK,IAAI,CAAC;CAClE;AAED;;;GAGG;AACH,MAAM,WAAW,iBAAkB,SAAQ,SAAS;IAClD;;;;;;;;;OASG;IACH,MAAM,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,OAAO,CAAC,GAAG,CAAC,CAAC;CAC3D;AAED;;;;GAIG;AACH,MAAM,WAAW,gBAAiB,SAAQ,SAAS;IACjD;;;;;OAKG;IACH,MAAM,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,OAAO,CAAC,GAAG,CAAC,KAAK,cAAc,CAAC;CACxF"}
+{"version":3,"file":"IpcSocket.d.ts","sourceRoot":"","sources":["../../../src/ipc/IpcSocket.ts"],"names":[],"mappings":"AAIA;;GAEG;AAEH,OAAO,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC;AAEtD;;;KAGK;AACL,eAAO,MAAM,YAAY,YAAa,MAAM,WAAuB,CAAC;AAEpE;;;GAGG;AACH,MAAM,MAAM,WAAW,GAAG,CAAC,GAAG,EAAE,KAAK,EAAE,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,IAAI,CAAC;AAE/D;;;;GAIG;AACH,MAAM,MAAM,cAAc,GAAG,MAAM,IAAI,CAAC;AAExC;;;;;eAKe;AACf,MAAM,MAAM,eAAe,GAAG;IAAE,MAAM,EAAE,GAAG,CAAC;IAAC,KAAK,CAAC,EAAE,KAAK,CAAC;IAAC,UAAU,CAAC,EAAE,KAAK,CAAA;CAAE,GAAG;IAAE,MAAM,CAAC,EAAE,KAAK,CAAC;IAAC,UAAU,CAAC,EAAE,KAAK,CAAC;IAAC,KAAK,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAC;QAAC,WAAW,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,EAAE,eAAe,CAAA;KAAE,CAAA;CAAE,GACpO;IAAE,MAAM,CAAC,EAAE,KAAK,CAAC;IAAC,KAAK,CAAC,EAAE,KAAK,CAAC;IAAC,UAAU,EAAE;QAAE,SAAS,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,EAAE,eAAe,CAAC;QAAC,CAAC,GAAG,EAAE,MAAM,GAAG,GAAG,CAAA;KAAE,CAAA;CAAE,CAAC;AACxK;;;;;EAKE;AACF,MAAM,WAAW,SAAS;IACxB;;;;;;OAMG;IACH,IAAI,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,IAAI,CAAC;IAChD;;;;;OAKG;IACH,WAAW,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,WAAW,KAAK,cAAc,CAAC;IACxE;;;;OAIG;IACH,cAAc,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,WAAW,KAAK,IAAI,CAAC;CAClE;AAED;;;GAGG;AACH,MAAM,WAAW,iBAAkB,SAAQ,SAAS;IAClD;;;;;;;;;OASG;IACH,MAAM,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,OAAO,CAAC,GAAG,CAAC,CAAC;CAC3D;AAED;;;;GAIG;AACH,MAAM,WAAW,gBAAiB,SAAQ,SAAS;IACjD;;;;;OAKG;IACH,MAAM,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,OAAO,CAAC,GAAG,CAAC,KAAK,cAAc,CAAC;CACxF"}

package/lib/cjs/ipc/IpcSocket.js.map

@@ -1 +1 @@
-{"version":3,"file":"IpcSocket.js","sourceRoot":"","sources":["../../../src/ipc/IpcSocket.ts"],"names":[],"mappings":";AAAA;;;+FAG+F;AAC/F;;GAEG;;;AAIH;;;KAGK;AACE,MAAM,YAAY,GAAG,CAAC,OAAe,EAAE,EAAE,CAAC,SAAS,OAAO,EAAE,CAAC;AAAvD,QAAA,YAAY,gBAA2C","sourcesContent":["/*---------------------------------------------------------------------------------------------\n* Copyright (c) Bentley Systems, Incorporated. All rights reserved.\n* See LICENSE.md in the project root for license terms and full copyright notice.\n*--------------------------------------------------------------------------------------------*/\n/** @packageDocumentation\n * @module IpcSocket\n */\n\nimport { LoggingMetaData } from \"@itwin/core-bentley\";\n\n/**\n * The prefix for all IpcSocket channels to disambiguate from system channels.\n * @internal\n * */\nexport const iTwinChannel = (channel: string) => `itwin.${channel}`;\n\n/**\n * A function to handle an Ipc message.\n * @public\n */\nexport type IpcListener = (evt: Event, ...args: any[]) => void;\n\n/**\n * Function returned when establishing an Ipc `receive` listener or `invoke` handler. Call this method to remove the listener/handler.\n * @public\n * @extensions\n */\nexport type RemoveFunction = () => void;\n\n/**\n * Payload of an IpcInvoke response. The presence of `error` indicates that the backend threw an exception and the\n * frontend will re-throw a [BackendError]$(frontend) with the `errorNumber` and `message` values.\n * The presence of iTwinError indicates that the backend threw an exception of type [[ITwinError]] and the frontend will re-throw that same error.\n * Otherwise the `result` member holds the response.\n * @internal */\nexport type IpcInvokeReturn = { result: any, error?: never, iTwinError?: never } | { result?: never, iTwinError?: never, error: { name: string, message: string, errorNumber: number, stack?: string } } |\n{ result?: never, error?: never, iTwinError: {namespace: string, errorKey: string, message: string, stack?: string, metadata?: LoggingMetaData, [key: string]: any } };\n/**\n * An inter-process socket connection between a single [IModelHost]($backend) on the backend (the node process), and an [IModelApp]($frontend) on\n * the frontend (the browser process.) Each side will implement this interface to form a two way connection. The frontend and backend\n * processes connected through an IpcSocket don't necessarily have to be on the same computer, but often are.\n * @public\n*/\nexport interface IpcSocket {\n  /**\n   * Send a message over the socket.\n   * @param channel The name of the channel for the message. Must begin with the [[iTwinChannel]] prefix.\n   * @param data The optional data of the message.\n   * @note `data` is serialized with the [Structured Clone Algorithm](https://developer.mozilla.org/en-US/docs/Web/API/Web_Workers_API/Structured_clone_algorithm), so only\n   * primitive types and `ArrayBuffers` are allowed.\n   */\n  send: (channel: string, ...data: any[]) => void;\n  /**\n   * Establish a handler to receive messages for a channel through a socket.\n   * @param channel The name of the channel for the messages. Must begin with the [[iTwinChannel]] prefix.\n   * @param listener A function called when messages are sent over `channel`\n   * @note returns A function to call to remove the listener.\n   */\n  addListener: (channel: string, listener: IpcListener) => RemoveFunction;\n  /**\n   * Remove a previously registered listener\n   * @param channel The name of the channel for the listener previously registered with [[addListener]]\n   * @param listener The function passed to [[addListener]]\n   */\n  removeListener: (channel: string, listener: IpcListener) => void;\n}\n\n/**\n * Interface for the frontend (browser) side of a socket connection. Frontends may invoke methods implemented on the backend.\n * @public\n */\nexport interface IpcSocketFrontend extends IpcSocket {\n  /**\n   * Send a message to the backend via `channel` and expect a result asynchronously.\n   * @param channel The name of the channel for the method.  Must begin with the [[iTwinChannel]] prefix.\n   * @see Electron [ipcRenderer.invoke](https://www.electronjs.org/docs/api/ipc-renderer) documentation for details.\n   * Note that this interface *may* be implemented via Electron for desktop apps, or via\n   * [WebSockets](https://developer.mozilla.org/en-US/docs/Web/API/WebSockets_API) for mobile or web-based\n   * Ipc connections. In either case, the Electron documentation provides the specifications for how it works.\n   * @note `args` are serialized with the [Structured Clone Algorithm](https://developer.mozilla.org/en-US/docs/Web/API/Web_Workers_API/Structured_clone_algorithm), so only\n   * primitive types and `ArrayBuffers` are allowed.\n   */\n  invoke: (channel: string, ...args: any[]) => Promise<any>;\n}\n\n/**\n * Interface for the backend (Node.js) side of a socket connection. Backends provide the implementation\n * of methods that are invoked from the frontend.\n * @public\n */\nexport interface IpcSocketBackend extends IpcSocket {\n  /**\n   * Establish a backend implementation of an Ipc interface for a channel.\n   * @param channel The name of the channel for this handler. Must begin with the [[iTwinChannel]] prefix.\n   * @param handler A function that supplies the implementation for methods invoked over `channel` via [[IpcSocketFrontend.invoke]]\n   * @note returns A function to call to remove the handler.\n   */\n  handle: (channel: string, handler: (...args: any[]) => Promise<any>) => RemoveFunction;\n}\n\n"]}
+{"version":3,"file":"IpcSocket.js","sourceRoot":"","sources":["../../../src/ipc/IpcSocket.ts"],"names":[],"mappings":";AAAA;;;+FAG+F;AAC/F;;GAEG;;;AAIH;;;KAGK;AACE,MAAM,YAAY,GAAG,CAAC,OAAe,EAAE,EAAE,CAAC,SAAS,OAAO,EAAE,CAAC;AAAvD,QAAA,YAAY,gBAA2C","sourcesContent":["/*---------------------------------------------------------------------------------------------\n* Copyright (c) Bentley Systems, Incorporated. All rights reserved.\n* See LICENSE.md in the project root for license terms and full copyright notice.\n*--------------------------------------------------------------------------------------------*/\n/** @packageDocumentation\n * @module IpcSocket\n */\n\nimport { LoggingMetaData } from \"@itwin/core-bentley\";\n\n/**\n * The prefix for all IpcSocket channels to disambiguate from system channels.\n * @internal\n * */\nexport const iTwinChannel = (channel: string) => `itwin.${channel}`;\n\n/**\n * A function to handle an Ipc message.\n * @public\n */\nexport type IpcListener = (evt: Event, ...args: any[]) => void;\n\n/**\n * Function returned when establishing an Ipc `receive` listener or `invoke` handler. Call this method to remove the listener/handler.\n * @public\n * @extensions\n */\nexport type RemoveFunction = () => void;\n\n/**\n * Payload of an IpcInvoke response. The presence of `error` indicates that the backend threw an exception and the\n * frontend will re-throw a [BackendError]$(frontend) with the `errorNumber` and `message` values.\n * The presence of iTwinError indicates that the backend threw an exception of type [[ITwinError]] and the frontend will re-throw that same error.\n * Otherwise the `result` member holds the response.\n * @internal */\nexport type IpcInvokeReturn = { result: any, error?: never, iTwinError?: never } | { result?: never, iTwinError?: never, error: { name: string, message: string, errorNumber: number, stack?: string, metadata?: LoggingMetaData } } |\n{ result?: never, error?: never, iTwinError: { namespace: string, errorKey: string, message: string, stack?: string, metadata?: LoggingMetaData, [key: string]: any } };\n/**\n * An inter-process socket connection between a single [IModelHost]($backend) on the backend (the node process), and an [IModelApp]($frontend) on\n * the frontend (the browser process.) Each side will implement this interface to form a two way connection. The frontend and backend\n * processes connected through an IpcSocket don't necessarily have to be on the same computer, but often are.\n * @public\n*/\nexport interface IpcSocket {\n  /**\n   * Send a message over the socket.\n   * @param channel The name of the channel for the message. Must begin with the [[iTwinChannel]] prefix.\n   * @param data The optional data of the message.\n   * @note `data` is serialized with the [Structured Clone Algorithm](https://developer.mozilla.org/en-US/docs/Web/API/Web_Workers_API/Structured_clone_algorithm), so only\n   * primitive types and `ArrayBuffers` are allowed.\n   */\n  send: (channel: string, ...data: any[]) => void;\n  /**\n   * Establish a handler to receive messages for a channel through a socket.\n   * @param channel The name of the channel for the messages. Must begin with the [[iTwinChannel]] prefix.\n   * @param listener A function called when messages are sent over `channel`\n   * @note returns A function to call to remove the listener.\n   */\n  addListener: (channel: string, listener: IpcListener) => RemoveFunction;\n  /**\n   * Remove a previously registered listener\n   * @param channel The name of the channel for the listener previously registered with [[addListener]]\n   * @param listener The function passed to [[addListener]]\n   */\n  removeListener: (channel: string, listener: IpcListener) => void;\n}\n\n/**\n * Interface for the frontend (browser) side of a socket connection. Frontends may invoke methods implemented on the backend.\n * @public\n */\nexport interface IpcSocketFrontend extends IpcSocket {\n  /**\n   * Send a message to the backend via `channel` and expect a result asynchronously.\n   * @param channel The name of the channel for the method.  Must begin with the [[iTwinChannel]] prefix.\n   * @see Electron [ipcRenderer.invoke](https://www.electronjs.org/docs/api/ipc-renderer) documentation for details.\n   * Note that this interface *may* be implemented via Electron for desktop apps, or via\n   * [WebSockets](https://developer.mozilla.org/en-US/docs/Web/API/WebSockets_API) for mobile or web-based\n   * Ipc connections. In either case, the Electron documentation provides the specifications for how it works.\n   * @note `args` are serialized with the [Structured Clone Algorithm](https://developer.mozilla.org/en-US/docs/Web/API/Web_Workers_API/Structured_clone_algorithm), so only\n   * primitive types and `ArrayBuffers` are allowed.\n   */\n  invoke: (channel: string, ...args: any[]) => Promise<any>;\n}\n\n/**\n * Interface for the backend (Node.js) side of a socket connection. Backends provide the implementation\n * of methods that are invoked from the frontend.\n * @public\n */\nexport interface IpcSocketBackend extends IpcSocket {\n  /**\n   * Establish a backend implementation of an Ipc interface for a channel.\n   * @param channel The name of the channel for this handler. Must begin with the [[iTwinChannel]] prefix.\n   * @param handler A function that supplies the implementation for methods invoked over `channel` via [[IpcSocketFrontend.invoke]]\n   * @note returns A function to call to remove the handler.\n   */\n  handle: (channel: string, handler: (...args: any[]) => Promise<any>) => RemoveFunction;\n}\n\n"]}

package/lib/esm/ITwinError.d.ts

@@ -3,6 +3,7 @@
  */
 import { LoggingMetaData } from "@itwin/core-bentley";
 import { LockState } from "./IModelError";
+import { BriefcaseId } from "./BriefcaseTypes";
 /**
  * Detailed information about a particular object Lock that is causing the Lock update conflict.
  * An example of a lock update conflict would be attempting to use [LockControl.acquireLocks]($backend) on an object that is already locked by another Briefcase.
@@ -17,20 +18,34 @@ export interface InUseLock {
      */
     state: LockState;
     /** An array of Briefcase ids that hold this lock. */
-    briefcaseIds: number[];
+    briefcaseIds: BriefcaseId[];
 }
+/**
+ * iTwinjs Core namespace namespace for a developer/application.
+ * @beta
+ */
+export declare const iTwinjsCoreNamespace = "itwinjs-core";
+/**
+ * error keys object used to describe an error keys for a developer/application.
+ * @beta
+ */
+export declare const iTwinErrorKeys: {
+    readonly inUseLocks: "in-use-locks";
+    readonly channelNest: "channel-may-not-nest";
+    readonly channelNotAllowed: "channel-not-allowed";
+    readonly channelRootExists: "channel-root-exists";
+};
+/**
+ * Record for all itwin error messages.
+ * @beta
+ */
+export declare const iTwinErrorMessages: Record<keyof typeof iTwinErrorKeys, (...args: any[]) => string>;
 /**
  * An interface used to describe an error for a developer/application. The message is not intended to be displayed to an end user.
  * This error interface should be extended when needing to throw errors with extra properties defined on them. See [[InUseLocksError]] for an example.
- * When extending ITwinError, one should typically add a type guard function and a function to throw the error either to a namespace for their error or as standalone functions.
- * See [[InUseLocksError.throwInUseLocksError]] and [[InUseLocksError.isInUseLocksError]] for examples of how to throw and check that an error is of type InUseLocksError.
- * * Example of catching a ITwinError:
- * ``` ts
- * [[include:ITwinError.catchAndHandleITwinError]]
- * ```
  * @beta
  */
-export interface ITwinError {
+export interface ITwinError extends Error {
     /** namespace for the error. This is a unique qualifier for the errorKey. */
     namespace: string;
     /** unique key for error, within namespace. All errorKeys within the same namespace must be unique. */
@@ -48,25 +63,46 @@ export interface ITwinError {
  * @beta
 */
 export interface InUseLocksError extends ITwinError {
-    namespace: "itwinjs-core";
-    errorKey: "in-use-locks";
     inUseLocks: InUseLock[];
 }
-/** @beta */
-export declare namespace InUseLocksError {
-    /**
-     * type guard function that returns whether or not the passed in parameter is an [[InUseLocksError]].
-     * it first checks [[ITwinError.isITwinError]] and then checks that the namespace property is "itwinjs-core" and the errorKey property is "in-use-locks".
-     */
-    function isInUseLocksError(error: unknown): error is InUseLocksError;
-    /** throws an error which passes the [[InUseLocksError.isInUseLocksError]] type guard function */
-    function throwInUseLocksError(inUseLocks: InUseLock[], message?: string, metadata?: LoggingMetaData): never;
-}
-/** @beta */
-export declare namespace ITwinError {
-    /** type guard function that returns whether or not the passed in parameter is an [[ITwinError]] */
-    function isITwinError(error: unknown): error is ITwinError;
-    /** get the meta data associated with this ITwinError, if any. */
-    function getMetaData(err: ITwinError): object | undefined;
-}
+/**
+* A function which will be used to construct an [[ITwinError]].
+* @param namespace The namespace associated with the error.
+* @param errorKey The errorKey associated with the error.
+* @param message The message associated with the error.
+* @param metadata Metadata associated with the error.
+* @beta
+*/
+export declare function constructITwinError(namespace: string, errorKey: string, message?: string, metadata?: LoggingMetaData): ITwinError;
+/**
+* A function which constructs a detailed error for example [[ InUseLocksError ]] above.
+* @param namespace The namespace associated with the error.
+* @param errorKey The errorKey associated with the error.
+* @param details Other details associated with the error.
+* @param message The message associated with the error.
+* @param metadata Metadata associated with the error.
+* @beta
+*/
+export declare function constructDetailedError<T extends ITwinError>(namespace: string, errorKey: string, details: Omit<T, keyof ITwinError>, message?: string, metadata?: LoggingMetaData): T;
+/**
+ * a high level function that returns a type asserter function which would return whether or not the passed in parameter is an [[ITwinError]]
+ * @param namespace The namespace associated with the error.
+ * @param errorKey The errorKey associated with the error.
+ * @beta
+*/
+export declare function createITwinErrorTypeAsserter<T extends ITwinError>(namespace: string, errorKey: string): (error: unknown) => error is T;
+/**
+ * get the meta data associated with this ITwinError, if any.
+ * @param error The error for which metadata is required.
+ * @beta
+*/
+export declare function getITwinErrorMetaData(error: ITwinError): object | undefined;
+/**
+ * type guard function that returns whether or not the passed in parameter is an [[ITwinError]]
+ * @param error The error which is to ve verified.
+ * @param namespace The namespace associated with the error.
+ * @param errorKey The errorKey associated with the error.
+ * @beta
+*/
+export declare function isITwinError(error: unknown, namespace?: string, errorKey?: string): error is ITwinError;
 //# sourceMappingURL=ITwinError.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"ITwinError.d.ts","sourceRoot":"","sources":["../../src/ITwinError.ts"],"names":[],"mappings":"AAIA;;GAEG;AAEH,OAAO,EAAgB,eAAe,EAAE,MAAM,qBAAqB,CAAC;AACpE,OAAO,EAAE,SAAS,EAAE,MAAM,eAAe,CAAC;AAE1C;;;;GAIG;AACH,MAAM,WAAW,SAAS;IACxB,iDAAiD;IACjD,QAAQ,EAAE,MAAM,CAAC;IACjB;;;OAGG;IACH,KAAK,EAAE,SAAS,CAAC;IACjB,qDAAqD;IACrD,YAAY,EAAE,MAAM,EAAE,CAAC;CACxB;AAED;;;;;;;;;;GAUG;AACH,MAAM,WAAW,UAAU;IACzB,4EAA4E;IAC5E,SAAS,EAAE,MAAM,CAAC;IAClB,sGAAsG;IACtG,QAAQ,EAAE,MAAM,CAAC;IACjB,0EAA0E;IAC1E,OAAO,EAAE,MAAM,CAAC;IAChB,gCAAgC;IAChC,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,oCAAoC;IACpC,QAAQ,CAAC,EAAE,eAAe,CAAC;CAC5B;AAED;;;;EAIE;AACF,MAAM,WAAW,eAAgB,SAAQ,UAAU;IACjD,SAAS,EAAE,cAAc,CAAC;IAC1B,QAAQ,EAAE,cAAc,CAAC;IACzB,UAAU,EAAE,SAAS,EAAE,CAAC;CACzB;AAED,YAAY;AACZ,yBAAiB,eAAe,CAAC;IAE/B;;;OAGG;IACH,SAAgB,iBAAiB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,eAAe,CAE1E;IAED,iGAAiG;IACjG,SAAgB,oBAAoB,CAAC,UAAU,EAAE,SAAS,EAAE,EAAE,OAAO,CAAC,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,eAAe,GAAG,KAAK,CAajH;CAEF;AACD,YAAY;AACZ,yBAAiB,UAAU,CAAC;IAC1B,mGAAmG;IACnG,SAAgB,YAAY,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,UAAU,CAEhE;IAED,iEAAiE;IACjE,SAAgB,WAAW,CAAC,GAAG,EAAE,UAAU,GAAG,MAAM,GAAG,SAAS,CAE/D;CAEF"}
+{"version":3,"file":"ITwinError.d.ts","sourceRoot":"","sources":["../../src/ITwinError.ts"],"names":[],"mappings":"AAIA;;GAEG;AAEH,OAAO,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC;AACtD,OAAO,EAAE,SAAS,EAAE,MAAM,eAAe,CAAC;AAC1C,OAAO,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAE/C;;;;GAIG;AACH,MAAM,WAAW,SAAS;IACxB,iDAAiD;IACjD,QAAQ,EAAE,MAAM,CAAC;IACjB;;;OAGG;IACH,KAAK,EAAE,SAAS,CAAC;IACjB,qDAAqD;IACrD,YAAY,EAAE,WAAW,EAAE,CAAC;CAC7B;AAED;;;GAGG;AACH,eAAO,MAAM,oBAAoB,iBAAiB,CAAC;AAEnD;;;GAGG;AACH,eAAO,MAAM,cAAc;;;;;CAKjB,CAAC;AAEX;;;GAGG;AACH,eAAO,MAAM,kBAAkB,EAAE,MAAM,CAAC,MAAM,OAAO,cAAc,EAAE,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,MAAM,CAK9F,CAAC;AAGF;;;;GAIG;AACH,MAAM,WAAW,UAAW,SAAQ,KAAK;IACvC,4EAA4E;IAC5E,SAAS,EAAE,MAAM,CAAC;IAClB,sGAAsG;IACtG,QAAQ,EAAE,MAAM,CAAC;IACjB,0EAA0E;IAC1E,OAAO,EAAE,MAAM,CAAC;IAChB,gCAAgC;IAChC,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,oCAAoC;IACpC,QAAQ,CAAC,EAAE,eAAe,CAAC;CAC5B;AAED;;;;EAIE;AACF,MAAM,WAAW,eAAgB,SAAQ,UAAU;IACjD,UAAU,EAAE,SAAS,EAAE,CAAC;CACzB;AAED;;;;;;;EAOE;AACF,wBAAgB,mBAAmB,CAAC,SAAS,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,eAAe,GAAG,UAAU,CAWjI;AAED;;;;;;;;EAQE;AACF,wBAAgB,sBAAsB,CAAC,CAAC,SAAS,UAAU,EAAE,SAAS,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,IAAI,CAAC,CAAC,EAAE,MAAM,UAAU,CAAC,EAAE,OAAO,CAAC,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,eAAe,GAAG,CAAC,CAKrL;AAED;;;;;EAKE;AACF,wBAAgB,4BAA4B,CAAC,CAAC,SAAS,UAAU,EAAE,SAAS,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,WACrF,OAAO,KAAG,KAAK,IAAI,CAAC,CACpC;AAED;;;;EAIE;AACF,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,UAAU,GAAG,MAAM,GAAG,SAAS,CAE3E;AAED;;;;;;EAME;AACF,wBAAgB,YAAY,CAAC,KAAK,EAAE,OAAO,EAAE,SAAS,CAAC,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,MAAM,GAAG,KAAK,IAAI,UAAU,CAKvG"}

package/lib/esm/ITwinError.js

@@ -5,48 +5,91 @@
 /** @packageDocumentation
  * @module iModels
  */
-import { BentleyError } from "@itwin/core-bentley";
-/** @beta */
-export var InUseLocksError;
-(function (InUseLocksError) {
-    /**
-     * type guard function that returns whether or not the passed in parameter is an [[InUseLocksError]].
-     * it first checks [[ITwinError.isITwinError]] and then checks that the namespace property is "itwinjs-core" and the errorKey property is "in-use-locks".
-     */
-    function isInUseLocksError(error) {
-        return ITwinError.isITwinError(error) && error.namespace === "itwinjs-core" && error.errorKey === "in-use-locks";
-    }
-    InUseLocksError.isInUseLocksError = isInUseLocksError;
-    /** throws an error which passes the [[InUseLocksError.isInUseLocksError]] type guard function */
-    function throwInUseLocksError(inUseLocks, message, metadata) {
-        const errorObject = new Error();
-        errorObject.name = "InUseLocksError"; // optional but makes it so that when the error is thrown and not caught we see InUseLocksError: 'message' instead of Error: 'message'
-        Error.captureStackTrace(errorObject, throwInUseLocksError); // optional: whether we want to hide throwInUseLocksError or not from the stack. not super important
-        const lockError = {
-            namespace: "itwinjs-core",
-            errorKey: "in-use-locks",
-            message: message ?? "One or more objects are already locked by another briefcase.",
-            metadata,
-            inUseLocks,
-        };
-        Object.assign(errorObject, lockError);
-        throw errorObject;
-    }
-    InUseLocksError.throwInUseLocksError = throwInUseLocksError;
-})(InUseLocksError || (InUseLocksError = {}));
-/** @beta */
-export var ITwinError;
-(function (ITwinError) {
-    /** type guard function that returns whether or not the passed in parameter is an [[ITwinError]] */
-    function isITwinError(error) {
-        return error !== undefined && error !== null && typeof error === "object" && "namespace" in error && "errorKey" in error && "message" in error;
-    }
-    ITwinError.isITwinError = isITwinError;
-    /** get the meta data associated with this ITwinError, if any. */
-    function getMetaData(err) {
-        return BentleyError.getMetaData(err.metadata);
-    }
-    ITwinError.getMetaData = getMetaData;
-})(ITwinError || (ITwinError = {}));
-;
+/**
+ * iTwinjs Core namespace namespace for a developer/application.
+ * @beta
+ */
+export const iTwinjsCoreNamespace = "itwinjs-core";
+/**
+ * error keys object used to describe an error keys for a developer/application.
+ * @beta
+ */
+export const iTwinErrorKeys = {
+    inUseLocks: "in-use-locks",
+    channelNest: "channel-may-not-nest",
+    channelNotAllowed: "channel-not-allowed",
+    channelRootExists: "channel-root-exists"
+};
+/**
+ * Record for all itwin error messages.
+ * @beta
+ */
+export const iTwinErrorMessages = {
+    "inUseLocks": () => 'Objects are locked by another briefcase',
+    "channelNest": (id) => `Channel ${id} may not nest`,
+    "channelNotAllowed": (id) => `Channel ${id} is not allowed`,
+    "channelRootExists": (id) => `Channel ${id} root already exist`,
+};
+/**
+* A function which will be used to construct an [[ITwinError]].
+* @param namespace The namespace associated with the error.
+* @param errorKey The errorKey associated with the error.
+* @param message The message associated with the error.
+* @param metadata Metadata associated with the error.
+* @beta
+*/
+export function constructITwinError(namespace, errorKey, message, metadata) {
+    const error = new Error();
+    error.message = message ?? `${errorKey} occurred`;
+    error.name = `${namespace}:${errorKey}`;
+    error.namespace = namespace;
+    error.errorKey = errorKey;
+    error.metadata = metadata;
+    Error.captureStackTrace(error, constructITwinError); // Optional, but this would hide constructITwinError from stack.
+    return error;
+}
+/**
+* A function which constructs a detailed error for example [[ InUseLocksError ]] above.
+* @param namespace The namespace associated with the error.
+* @param errorKey The errorKey associated with the error.
+* @param details Other details associated with the error.
+* @param message The message associated with the error.
+* @param metadata Metadata associated with the error.
+* @beta
+*/
+export function constructDetailedError(namespace, errorKey, details, message, metadata) {
+    const baseError = constructITwinError(namespace, errorKey, message, metadata);
+    Error.captureStackTrace(baseError, constructDetailedError); // Optional, but this would hide constructDetailedError from stack.
+    return Object.assign(baseError, details);
+}
+/**
+ * a high level function that returns a type asserter function which would return whether or not the passed in parameter is an [[ITwinError]]
+ * @param namespace The namespace associated with the error.
+ * @param errorKey The errorKey associated with the error.
+ * @beta
+*/
+export function createITwinErrorTypeAsserter(namespace, errorKey) {
+    return (error) => isITwinError(error, namespace, errorKey);
+}
+/**
+ * get the meta data associated with this ITwinError, if any.
+ * @param error The error for which metadata is required.
+ * @beta
+*/
+export function getITwinErrorMetaData(error) {
+    return (typeof error.metadata === "function") ? error.metadata() : error.metadata;
+}
+/**
+ * type guard function that returns whether or not the passed in parameter is an [[ITwinError]]
+ * @param error The error which is to ve verified.
+ * @param namespace The namespace associated with the error.
+ * @param errorKey The errorKey associated with the error.
+ * @beta
+*/
+export function isITwinError(error, namespace, errorKey) {
+    return error !== undefined && error !== null && typeof error === "object"
+        && "namespace" in error && "errorKey" in error && "message" in error
+        && (namespace === undefined || error.namespace === namespace)
+        && (errorKey === undefined || error.errorKey === errorKey);
+}
 //# sourceMappingURL=ITwinError.js.map

package/lib/esm/ITwinError.js.map

@@ -1 +1 @@
-{"version":3,"file":"ITwinError.js","sourceRoot":"","sources":["../../src/ITwinError.ts"],"names":[],"mappings":"AAAA;;;+FAG+F;AAC/F;;GAEG;AAEH,OAAO,EAAE,YAAY,EAAmB,MAAM,qBAAqB,CAAC;AAuDpE,YAAY;AACZ,MAAM,KAAW,eAAe,CA0B/B;AA1BD,WAAiB,eAAe;IAE9B;;;OAGG;IACH,SAAgB,iBAAiB,CAAC,KAAc;QAC9C,OAAO,UAAU,CAAC,YAAY,CAAC,KAAK,CAAC,IAAI,KAAK,CAAC,SAAS,KAAK,cAAc,IAAI,KAAK,CAAC,QAAQ,KAAK,cAAc,CAAC;IACnH,CAAC;IAFe,iCAAiB,oBAEhC,CAAA;IAED,iGAAiG;IACjG,SAAgB,oBAAoB,CAAC,UAAuB,EAAE,OAAgB,EAAE,QAA0B;QACxG,MAAM,WAAW,GAAG,IAAI,KAAK,EAAE,CAAC;QAChC,WAAW,CAAC,IAAI,GAAG,iBAAiB,CAAC,CAAC,sIAAsI;QAC5K,KAAK,CAAC,iBAAiB,CAAC,WAAW,EAAE,oBAAoB,CAAC,CAAC,CAAC,oGAAoG;QAChK,MAAM,SAAS,GAAoB;YACjC,SAAS,EAAE,cAAc;YACzB,QAAQ,EAAE,cAAc;YACxB,OAAO,EAAE,OAAO,IAAI,8DAA8D;YAClF,QAAQ;YACR,UAAU;SACX,CAAC;QACF,MAAM,CAAC,MAAM,CAAC,WAAW,EAAE,SAAS,CAAC,CAAC;QACtC,MAAM,WAAW,CAAC;IACpB,CAAC;IAbe,oCAAoB,uBAanC,CAAA;AAEH,CAAC,EA1BgB,eAAe,KAAf,eAAe,QA0B/B;AACD,YAAY;AACZ,MAAM,KAAW,UAAU,CAW1B;AAXD,WAAiB,UAAU;IACzB,mGAAmG;IACnG,SAAgB,YAAY,CAAC,KAAc;QACzC,OAAO,KAAK,KAAK,SAAS,IAAI,KAAK,KAAK,IAAI,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,WAAW,IAAI,KAAK,IAAI,UAAU,IAAI,KAAK,IAAI,SAAS,IAAI,KAAK,CAAC;IACjJ,CAAC;IAFe,uBAAY,eAE3B,CAAA;IAED,iEAAiE;IACjE,SAAgB,WAAW,CAAC,GAAe;QACzC,OAAO,YAAY,CAAC,WAAW,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;IAChD,CAAC;IAFe,sBAAW,cAE1B,CAAA;AAEH,CAAC,EAXgB,UAAU,KAAV,UAAU,QAW1B;AAAA,CAAC","sourcesContent":["/*---------------------------------------------------------------------------------------------\n* Copyright (c) Bentley Systems, Incorporated. All rights reserved.\n* See LICENSE.md in the project root for license terms and full copyright notice.\n*--------------------------------------------------------------------------------------------*/\n/** @packageDocumentation\n * @module iModels\n */\n\nimport { BentleyError, LoggingMetaData } from \"@itwin/core-bentley\";\nimport { LockState } from \"./IModelError\";\n\n/**\n * Detailed information about a particular object Lock that is causing the Lock update conflict.\n * An example of a lock update conflict would be attempting to use [LockControl.acquireLocks]($backend) on an object that is already locked by another Briefcase.\n * @beta\n */\nexport interface InUseLock {\n  /** Id of the object that is causing conflict. */\n  objectId: string;\n  /**\n   * The level of conflicting lock. Possible values are {@link LockState.Shared}, {@link LockState.Exclusive}.\n   * See {@link LockState}.\n   */\n  state: LockState;\n  /** An array of Briefcase ids that hold this lock. */\n  briefcaseIds: number[];\n}\n\n/**\n * An interface used to describe an error for a developer/application. The message is not intended to be displayed to an end user.\n * This error interface should be extended when needing to throw errors with extra properties defined on them. See [[InUseLocksError]] for an example.\n * When extending ITwinError, one should typically add a type guard function and a function to throw the error either to a namespace for their error or as standalone functions.\n * See [[InUseLocksError.throwInUseLocksError]] and [[InUseLocksError.isInUseLocksError]] for examples of how to throw and check that an error is of type InUseLocksError.\n * * Example of catching a ITwinError:\n * ``` ts\n * [[include:ITwinError.catchAndHandleITwinError]]\n * ```\n * @beta\n */\nexport interface ITwinError {\n  /** namespace for the error. This is a unique qualifier for the errorKey. */\n  namespace: string;\n  /** unique key for error, within namespace. All errorKeys within the same namespace must be unique. */\n  errorKey: string;\n  /** explanation of what went wrong. Intended to be read by a developer. */\n  message: string;\n  /** stack trace of the error. */\n  stack?: string;\n  /** metadata about the exception. */\n  metadata?: LoggingMetaData;\n}\n\n/**\n * An error raised when there is a lock conflict detected.\n * Typically this error would be thrown by [LockControl.acquireLocks]($backend) when you are requesting a lock on an element that is already held by another briefcase.\n * @beta\n*/\nexport interface InUseLocksError extends ITwinError {\n  namespace: \"itwinjs-core\";\n  errorKey: \"in-use-locks\";\n  inUseLocks: InUseLock[];\n}\n\n/** @beta */\nexport namespace InUseLocksError {\n\n  /**\n   * type guard function that returns whether or not the passed in parameter is an [[InUseLocksError]].\n   * it first checks [[ITwinError.isITwinError]] and then checks that the namespace property is \"itwinjs-core\" and the errorKey property is \"in-use-locks\".\n   */\n  export function isInUseLocksError(error: unknown): error is InUseLocksError {\n    return ITwinError.isITwinError(error) && error.namespace === \"itwinjs-core\" && error.errorKey === \"in-use-locks\";\n  }\n\n  /** throws an error which passes the [[InUseLocksError.isInUseLocksError]] type guard function */\n  export function throwInUseLocksError(inUseLocks: InUseLock[], message?: string, metadata?: LoggingMetaData): never {\n    const errorObject = new Error();\n    errorObject.name = \"InUseLocksError\"; // optional but makes it so that when the error is thrown and not caught we see InUseLocksError: 'message' instead of Error: 'message'\n    Error.captureStackTrace(errorObject, throwInUseLocksError); // optional: whether we want to hide throwInUseLocksError or not from the stack. not super important\n    const lockError: InUseLocksError = {\n      namespace: \"itwinjs-core\",\n      errorKey: \"in-use-locks\",\n      message: message ?? \"One or more objects are already locked by another briefcase.\",\n      metadata,\n      inUseLocks,\n    };\n    Object.assign(errorObject, lockError);\n    throw errorObject;\n  }\n\n}\n/** @beta */\nexport namespace ITwinError {\n  /** type guard function that returns whether or not the passed in parameter is an [[ITwinError]] */\n  export function isITwinError(error: unknown): error is ITwinError {\n    return error !== undefined && error !== null && typeof error === \"object\" && \"namespace\" in error && \"errorKey\" in error && \"message\" in error;\n  }\n\n  /** get the meta data associated with this ITwinError, if any. */\n  export function getMetaData(err: ITwinError): object | undefined {\n    return BentleyError.getMetaData(err.metadata);\n  }\n\n};\n"]}
+{"version":3,"file":"ITwinError.js","sourceRoot":"","sources":["../../src/ITwinError.ts"],"names":[],"mappings":"AAAA;;;+FAG+F;AAC/F;;GAEG;AAuBH;;;GAGG;AACH,MAAM,CAAC,MAAM,oBAAoB,GAAG,cAAc,CAAC;AAEnD;;;GAGG;AACH,MAAM,CAAC,MAAM,cAAc,GAAG;IAC5B,UAAU,EAAE,cAAc;IAC1B,WAAW,EAAE,sBAAsB;IACnC,iBAAiB,EAAE,qBAAqB;IACxC,iBAAiB,EAAE,qBAAqB;CAChC,CAAC;AAEX;;;GAGG;AACH,MAAM,CAAC,MAAM,kBAAkB,GAAoE;IACjG,YAAY,EAAE,GAAG,EAAE,CAAC,yCAAyC;IAC7D,aAAa,EAAE,CAAC,EAAE,EAAE,EAAE,CAAC,WAAW,EAAE,eAAe;IACnD,mBAAmB,EAAE,CAAC,EAAE,EAAE,EAAE,CAAC,WAAW,EAAE,iBAAiB;IAC3D,mBAAmB,EAAE,CAAC,EAAE,EAAE,EAAE,CAAC,WAAW,EAAE,qBAAqB;CAChE,CAAC;AA8BF;;;;;;;EAOE;AACF,MAAM,UAAU,mBAAmB,CAAC,SAAiB,EAAE,QAAgB,EAAE,OAAgB,EAAE,QAA0B;IAEnH,MAAM,KAAK,GAAG,IAAI,KAAK,EAAgB,CAAC;IACxC,KAAK,CAAC,OAAO,GAAG,OAAO,IAAI,GAAG,QAAQ,WAAW,CAAC;IAClD,KAAK,CAAC,IAAI,GAAG,GAAG,SAAS,IAAI,QAAQ,EAAE,CAAC;IACxC,KAAK,CAAC,SAAS,GAAG,SAAS,CAAC;IAC5B,KAAK,CAAC,QAAQ,GAAG,QAAQ,CAAC;IAC1B,KAAK,CAAC,QAAQ,GAAG,QAAQ,CAAC;IAE1B,KAAK,CAAC,iBAAiB,CAAC,KAAK,EAAE,mBAAmB,CAAC,CAAC,CAAC,gEAAgE;IACrH,OAAO,KAAK,CAAC;AACf,CAAC;AAED;;;;;;;;EAQE;AACF,MAAM,UAAU,sBAAsB,CAAuB,SAAiB,EAAE,QAAgB,EAAE,OAAkC,EAAE,OAAgB,EAAE,QAA0B;IAChL,MAAM,SAAS,GAAG,mBAAmB,CAAC,SAAS,EAAE,QAAQ,EAAE,OAAO,EAAE,QAAQ,CAAC,CAAC;IAE9E,KAAK,CAAC,iBAAiB,CAAC,SAAS,EAAE,sBAAsB,CAAC,CAAC,CAAC,mEAAmE;IAC/H,OAAO,MAAM,CAAC,MAAM,CAAC,SAAS,EAAE,OAAO,CAAM,CAAC;AAChD,CAAC;AAED;;;;;EAKE;AACF,MAAM,UAAU,4BAA4B,CAAuB,SAAiB,EAAE,QAAgB;IACpG,OAAO,CAAC,KAAc,EAAc,EAAE,CAAC,YAAY,CAAC,KAAK,EAAE,SAAS,EAAE,QAAQ,CAAC,CAAC;AAClF,CAAC;AAED;;;;EAIE;AACF,MAAM,UAAU,qBAAqB,CAAC,KAAiB;IACrD,OAAO,CAAC,OAAO,KAAK,CAAC,QAAQ,KAAK,UAAU,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,QAAQ,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC,QAAQ,CAAC;AACpF,CAAC;AAED;;;;;;EAME;AACF,MAAM,UAAU,YAAY,CAAC,KAAc,EAAE,SAAkB,EAAE,QAAiB;IAChF,OAAO,KAAK,KAAK,SAAS,IAAI,KAAK,KAAK,IAAI,IAAI,OAAO,KAAK,KAAK,QAAQ;WACpE,WAAW,IAAI,KAAK,IAAI,UAAU,IAAI,KAAK,IAAI,SAAS,IAAI,KAAK;WACjE,CAAC,SAAS,KAAK,SAAS,IAAK,KAAoB,CAAC,SAAS,KAAK,SAAS,CAAC;WAC1E,CAAC,QAAQ,KAAK,SAAS,IAAK,KAAoB,CAAC,QAAQ,KAAK,QAAQ,CAAC,CAAC;AAC/E,CAAC","sourcesContent":["/*---------------------------------------------------------------------------------------------\n* Copyright (c) Bentley Systems, Incorporated. All rights reserved.\n* See LICENSE.md in the project root for license terms and full copyright notice.\n*--------------------------------------------------------------------------------------------*/\n/** @packageDocumentation\n * @module iModels\n */\n\nimport { LoggingMetaData } from \"@itwin/core-bentley\";\nimport { LockState } from \"./IModelError\";\nimport { BriefcaseId } from \"./BriefcaseTypes\";\n\n/**\n * Detailed information about a particular object Lock that is causing the Lock update conflict.\n * An example of a lock update conflict would be attempting to use [LockControl.acquireLocks]($backend) on an object that is already locked by another Briefcase.\n * @beta\n */\nexport interface InUseLock {\n  /** Id of the object that is causing conflict. */\n  objectId: string;\n  /**\n   * The level of conflicting lock. Possible values are {@link LockState.Shared}, {@link LockState.Exclusive}.\n   * See {@link LockState}.\n   */\n  state: LockState;\n  /** An array of Briefcase ids that hold this lock. */\n  briefcaseIds: BriefcaseId[];\n}\n\n/**\n * iTwinjs Core namespace namespace for a developer/application.\n * @beta\n */\nexport const iTwinjsCoreNamespace = \"itwinjs-core\";\n\n/**\n * error keys object used to describe an error keys for a developer/application.\n * @beta\n */\nexport const iTwinErrorKeys = {\n  inUseLocks: \"in-use-locks\",\n  channelNest: \"channel-may-not-nest\",\n  channelNotAllowed: \"channel-not-allowed\",\n  channelRootExists: \"channel-root-exists\"\n} as const;\n\n/**\n * Record for all itwin error messages.\n * @beta\n */\nexport const iTwinErrorMessages: Record<keyof typeof iTwinErrorKeys, (...args: any[]) => string> = {\n  \"inUseLocks\": () => 'Objects are locked by another briefcase',\n  \"channelNest\": (id) => `Channel ${id} may not nest`,\n  \"channelNotAllowed\": (id) => `Channel ${id} is not allowed`,\n  \"channelRootExists\": (id) => `Channel ${id} root already exist`,\n};\n\n\n/**\n * An interface used to describe an error for a developer/application. The message is not intended to be displayed to an end user.\n * This error interface should be extended when needing to throw errors with extra properties defined on them. See [[InUseLocksError]] for an example.\n * @beta\n */\nexport interface ITwinError extends Error {\n  /** namespace for the error. This is a unique qualifier for the errorKey. */\n  namespace: string;\n  /** unique key for error, within namespace. All errorKeys within the same namespace must be unique. */\n  errorKey: string;\n  /** explanation of what went wrong. Intended to be read by a developer. */\n  message: string;\n  /** stack trace of the error. */\n  stack?: string;\n  /** metadata about the exception. */\n  metadata?: LoggingMetaData;\n}\n\n/**\n * An error raised when there is a lock conflict detected.\n * Typically this error would be thrown by [LockControl.acquireLocks]($backend) when you are requesting a lock on an element that is already held by another briefcase.\n * @beta\n*/\nexport interface InUseLocksError extends ITwinError {\n  inUseLocks: InUseLock[];\n}\n\n/**\n* A function which will be used to construct an [[ITwinError]].\n* @param namespace The namespace associated with the error.\n* @param errorKey The errorKey associated with the error.\n* @param message The message associated with the error.\n* @param metadata Metadata associated with the error.\n* @beta\n*/\nexport function constructITwinError(namespace: string, errorKey: string, message?: string, metadata?: LoggingMetaData): ITwinError {\n\n  const error = new Error() as ITwinError;\n  error.message = message ?? `${errorKey} occurred`;\n  error.name = `${namespace}:${errorKey}`;\n  error.namespace = namespace;\n  error.errorKey = errorKey;\n  error.metadata = metadata;\n\n  Error.captureStackTrace(error, constructITwinError); // Optional, but this would hide constructITwinError from stack.\n  return error;\n}\n\n/**\n* A function which constructs a detailed error for example [[ InUseLocksError ]] above.\n* @param namespace The namespace associated with the error.\n* @param errorKey The errorKey associated with the error.\n* @param details Other details associated with the error.\n* @param message The message associated with the error.\n* @param metadata Metadata associated with the error.\n* @beta\n*/\nexport function constructDetailedError<T extends ITwinError>(namespace: string, errorKey: string, details: Omit<T, keyof ITwinError>, message?: string, metadata?: LoggingMetaData): T {\n  const baseError = constructITwinError(namespace, errorKey, message, metadata);\n\n  Error.captureStackTrace(baseError, constructDetailedError); // Optional, but this would hide constructDetailedError from stack.\n  return Object.assign(baseError, details) as T;\n}\n\n/**\n * a high level function that returns a type asserter function which would return whether or not the passed in parameter is an [[ITwinError]]\n * @param namespace The namespace associated with the error.\n * @param errorKey The errorKey associated with the error.\n * @beta\n*/\nexport function createITwinErrorTypeAsserter<T extends ITwinError>(namespace: string, errorKey: string) {\n  return (error: unknown): error is T => isITwinError(error, namespace, errorKey);\n}\n\n/**\n * get the meta data associated with this ITwinError, if any.\n * @param error The error for which metadata is required.\n * @beta\n*/\nexport function getITwinErrorMetaData(error: ITwinError): object | undefined {\n  return (typeof error.metadata === \"function\") ? error.metadata() : error.metadata;\n}\n\n/**\n * type guard function that returns whether or not the passed in parameter is an [[ITwinError]]\n * @param error The error which is to ve verified.\n * @param namespace The namespace associated with the error.\n * @param errorKey The errorKey associated with the error.\n * @beta\n*/\nexport function isITwinError(error: unknown, namespace?: string, errorKey?: string): error is ITwinError {\n  return error !== undefined && error !== null && typeof error === \"object\"\n    && \"namespace\" in error && \"errorKey\" in error && \"message\" in error\n    && (namespace === undefined || (error as ITwinError).namespace === namespace)\n    && (errorKey === undefined || (error as ITwinError).errorKey === errorKey);\n}\n"]}

package/lib/esm/ipc/IpcSocket.d.ts

@@ -36,6 +36,7 @@ export type IpcInvokeReturn = {
         message: string;
         errorNumber: number;
         stack?: string;
+        metadata?: LoggingMetaData;
     };
 } | {
     result?: never;

package/lib/esm/ipc/IpcSocket.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"IpcSocket.d.ts","sourceRoot":"","sources":["../../../src/ipc/IpcSocket.ts"],"names":[],"mappings":"AAIA;;GAEG;AAEH,OAAO,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC;AAEtD;;;KAGK;AACL,eAAO,MAAM,YAAY,YAAa,MAAM,WAAuB,CAAC;AAEpE;;;GAGG;AACH,MAAM,MAAM,WAAW,GAAG,CAAC,GAAG,EAAE,KAAK,EAAE,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,IAAI,CAAC;AAE/D;;;;GAIG;AACH,MAAM,MAAM,cAAc,GAAG,MAAM,IAAI,CAAC;AAExC;;;;;eAKe;AACf,MAAM,MAAM,eAAe,GAAG;IAAE,MAAM,EAAE,GAAG,CAAC;IAAC,KAAK,CAAC,EAAE,KAAK,CAAC;IAAC,UAAU,CAAC,EAAE,KAAK,CAAA;CAAE,GAAG;IAAE,MAAM,CAAC,EAAE,KAAK,CAAC;IAAC,UAAU,CAAC,EAAE,KAAK,CAAC;IAAC,KAAK,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAC;QAAC,WAAW,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAA;KAAE,CAAA;CAAE,GACxM;IAAE,MAAM,CAAC,EAAE,KAAK,CAAC;IAAC,KAAK,CAAC,EAAE,KAAK,CAAC;IAAC,UAAU,EAAE;QAAC,SAAS,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,EAAE,eAAe,CAAC;QAAC,CAAC,GAAG,EAAE,MAAM,GAAG,GAAG,CAAA;KAAE,CAAA;CAAE,CAAC;AACvK;;;;;EAKE;AACF,MAAM,WAAW,SAAS;IACxB;;;;;;OAMG;IACH,IAAI,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,IAAI,CAAC;IAChD;;;;;OAKG;IACH,WAAW,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,WAAW,KAAK,cAAc,CAAC;IACxE;;;;OAIG;IACH,cAAc,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,WAAW,KAAK,IAAI,CAAC;CAClE;AAED;;;GAGG;AACH,MAAM,WAAW,iBAAkB,SAAQ,SAAS;IAClD;;;;;;;;;OASG;IACH,MAAM,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,OAAO,CAAC,GAAG,CAAC,CAAC;CAC3D;AAED;;;;GAIG;AACH,MAAM,WAAW,gBAAiB,SAAQ,SAAS;IACjD;;;;;OAKG;IACH,MAAM,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,OAAO,CAAC,GAAG,CAAC,KAAK,cAAc,CAAC;CACxF"}
+{"version":3,"file":"IpcSocket.d.ts","sourceRoot":"","sources":["../../../src/ipc/IpcSocket.ts"],"names":[],"mappings":"AAIA;;GAEG;AAEH,OAAO,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC;AAEtD;;;KAGK;AACL,eAAO,MAAM,YAAY,YAAa,MAAM,WAAuB,CAAC;AAEpE;;;GAGG;AACH,MAAM,MAAM,WAAW,GAAG,CAAC,GAAG,EAAE,KAAK,EAAE,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,IAAI,CAAC;AAE/D;;;;GAIG;AACH,MAAM,MAAM,cAAc,GAAG,MAAM,IAAI,CAAC;AAExC;;;;;eAKe;AACf,MAAM,MAAM,eAAe,GAAG;IAAE,MAAM,EAAE,GAAG,CAAC;IAAC,KAAK,CAAC,EAAE,KAAK,CAAC;IAAC,UAAU,CAAC,EAAE,KAAK,CAAA;CAAE,GAAG;IAAE,MAAM,CAAC,EAAE,KAAK,CAAC;IAAC,UAAU,CAAC,EAAE,KAAK,CAAC;IAAC,KAAK,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAC;QAAC,WAAW,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,EAAE,eAAe,CAAA;KAAE,CAAA;CAAE,GACpO;IAAE,MAAM,CAAC,EAAE,KAAK,CAAC;IAAC,KAAK,CAAC,EAAE,KAAK,CAAC;IAAC,UAAU,EAAE;QAAE,SAAS,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,EAAE,eAAe,CAAC;QAAC,CAAC,GAAG,EAAE,MAAM,GAAG,GAAG,CAAA;KAAE,CAAA;CAAE,CAAC;AACxK;;;;;EAKE;AACF,MAAM,WAAW,SAAS;IACxB;;;;;;OAMG;IACH,IAAI,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,IAAI,CAAC;IAChD;;;;;OAKG;IACH,WAAW,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,WAAW,KAAK,cAAc,CAAC;IACxE;;;;OAIG;IACH,cAAc,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,WAAW,KAAK,IAAI,CAAC;CAClE;AAED;;;GAGG;AACH,MAAM,WAAW,iBAAkB,SAAQ,SAAS;IAClD;;;;;;;;;OASG;IACH,MAAM,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,OAAO,CAAC,GAAG,CAAC,CAAC;CAC3D;AAED;;;;GAIG;AACH,MAAM,WAAW,gBAAiB,SAAQ,SAAS;IACjD;;;;;OAKG;IACH,MAAM,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,OAAO,CAAC,GAAG,CAAC,KAAK,cAAc,CAAC;CACxF"}

package/lib/esm/ipc/IpcSocket.js.map

@@ -1 +1 @@
-{"version":3,"file":"IpcSocket.js","sourceRoot":"","sources":["../../../src/ipc/IpcSocket.ts"],"names":[],"mappings":"AAAA;;;+FAG+F;AAC/F;;GAEG;AAIH;;;KAGK;AACL,MAAM,CAAC,MAAM,YAAY,GAAG,CAAC,OAAe,EAAE,EAAE,CAAC,SAAS,OAAO,EAAE,CAAC","sourcesContent":["/*---------------------------------------------------------------------------------------------\n* Copyright (c) Bentley Systems, Incorporated. All rights reserved.\n* See LICENSE.md in the project root for license terms and full copyright notice.\n*--------------------------------------------------------------------------------------------*/\n/** @packageDocumentation\n * @module IpcSocket\n */\n\nimport { LoggingMetaData } from \"@itwin/core-bentley\";\n\n/**\n * The prefix for all IpcSocket channels to disambiguate from system channels.\n * @internal\n * */\nexport const iTwinChannel = (channel: string) => `itwin.${channel}`;\n\n/**\n * A function to handle an Ipc message.\n * @public\n */\nexport type IpcListener = (evt: Event, ...args: any[]) => void;\n\n/**\n * Function returned when establishing an Ipc `receive` listener or `invoke` handler. Call this method to remove the listener/handler.\n * @public\n * @extensions\n */\nexport type RemoveFunction = () => void;\n\n/**\n * Payload of an IpcInvoke response. The presence of `error` indicates that the backend threw an exception and the\n * frontend will re-throw a [BackendError]$(frontend) with the `errorNumber` and `message` values.\n * The presence of iTwinError indicates that the backend threw an exception of type [[ITwinError]] and the frontend will re-throw that same error.\n * Otherwise the `result` member holds the response.\n * @internal */\nexport type IpcInvokeReturn = { result: any, error?: never, iTwinError?: never } | { result?: never, iTwinError?: never, error: { name: string, message: string, errorNumber: number, stack?: string } } |\n{ result?: never, error?: never, iTwinError: {namespace: string, errorKey: string, message: string, stack?: string, metadata?: LoggingMetaData, [key: string]: any } };\n/**\n * An inter-process socket connection between a single [IModelHost]($backend) on the backend (the node process), and an [IModelApp]($frontend) on\n * the frontend (the browser process.) Each side will implement this interface to form a two way connection. The frontend and backend\n * processes connected through an IpcSocket don't necessarily have to be on the same computer, but often are.\n * @public\n*/\nexport interface IpcSocket {\n  /**\n   * Send a message over the socket.\n   * @param channel The name of the channel for the message. Must begin with the [[iTwinChannel]] prefix.\n   * @param data The optional data of the message.\n   * @note `data` is serialized with the [Structured Clone Algorithm](https://developer.mozilla.org/en-US/docs/Web/API/Web_Workers_API/Structured_clone_algorithm), so only\n   * primitive types and `ArrayBuffers` are allowed.\n   */\n  send: (channel: string, ...data: any[]) => void;\n  /**\n   * Establish a handler to receive messages for a channel through a socket.\n   * @param channel The name of the channel for the messages. Must begin with the [[iTwinChannel]] prefix.\n   * @param listener A function called when messages are sent over `channel`\n   * @note returns A function to call to remove the listener.\n   */\n  addListener: (channel: string, listener: IpcListener) => RemoveFunction;\n  /**\n   * Remove a previously registered listener\n   * @param channel The name of the channel for the listener previously registered with [[addListener]]\n   * @param listener The function passed to [[addListener]]\n   */\n  removeListener: (channel: string, listener: IpcListener) => void;\n}\n\n/**\n * Interface for the frontend (browser) side of a socket connection. Frontends may invoke methods implemented on the backend.\n * @public\n */\nexport interface IpcSocketFrontend extends IpcSocket {\n  /**\n   * Send a message to the backend via `channel` and expect a result asynchronously.\n   * @param channel The name of the channel for the method.  Must begin with the [[iTwinChannel]] prefix.\n   * @see Electron [ipcRenderer.invoke](https://www.electronjs.org/docs/api/ipc-renderer) documentation for details.\n   * Note that this interface *may* be implemented via Electron for desktop apps, or via\n   * [WebSockets](https://developer.mozilla.org/en-US/docs/Web/API/WebSockets_API) for mobile or web-based\n   * Ipc connections. In either case, the Electron documentation provides the specifications for how it works.\n   * @note `args` are serialized with the [Structured Clone Algorithm](https://developer.mozilla.org/en-US/docs/Web/API/Web_Workers_API/Structured_clone_algorithm), so only\n   * primitive types and `ArrayBuffers` are allowed.\n   */\n  invoke: (channel: string, ...args: any[]) => Promise<any>;\n}\n\n/**\n * Interface for the backend (Node.js) side of a socket connection. Backends provide the implementation\n * of methods that are invoked from the frontend.\n * @public\n */\nexport interface IpcSocketBackend extends IpcSocket {\n  /**\n   * Establish a backend implementation of an Ipc interface for a channel.\n   * @param channel The name of the channel for this handler. Must begin with the [[iTwinChannel]] prefix.\n   * @param handler A function that supplies the implementation for methods invoked over `channel` via [[IpcSocketFrontend.invoke]]\n   * @note returns A function to call to remove the handler.\n   */\n  handle: (channel: string, handler: (...args: any[]) => Promise<any>) => RemoveFunction;\n}\n\n"]}
+{"version":3,"file":"IpcSocket.js","sourceRoot":"","sources":["../../../src/ipc/IpcSocket.ts"],"names":[],"mappings":"AAAA;;;+FAG+F;AAC/F;;GAEG;AAIH;;;KAGK;AACL,MAAM,CAAC,MAAM,YAAY,GAAG,CAAC,OAAe,EAAE,EAAE,CAAC,SAAS,OAAO,EAAE,CAAC","sourcesContent":["/*---------------------------------------------------------------------------------------------\n* Copyright (c) Bentley Systems, Incorporated. All rights reserved.\n* See LICENSE.md in the project root for license terms and full copyright notice.\n*--------------------------------------------------------------------------------------------*/\n/** @packageDocumentation\n * @module IpcSocket\n */\n\nimport { LoggingMetaData } from \"@itwin/core-bentley\";\n\n/**\n * The prefix for all IpcSocket channels to disambiguate from system channels.\n * @internal\n * */\nexport const iTwinChannel = (channel: string) => `itwin.${channel}`;\n\n/**\n * A function to handle an Ipc message.\n * @public\n */\nexport type IpcListener = (evt: Event, ...args: any[]) => void;\n\n/**\n * Function returned when establishing an Ipc `receive` listener or `invoke` handler. Call this method to remove the listener/handler.\n * @public\n * @extensions\n */\nexport type RemoveFunction = () => void;\n\n/**\n * Payload of an IpcInvoke response. The presence of `error` indicates that the backend threw an exception and the\n * frontend will re-throw a [BackendError]$(frontend) with the `errorNumber` and `message` values.\n * The presence of iTwinError indicates that the backend threw an exception of type [[ITwinError]] and the frontend will re-throw that same error.\n * Otherwise the `result` member holds the response.\n * @internal */\nexport type IpcInvokeReturn = { result: any, error?: never, iTwinError?: never } | { result?: never, iTwinError?: never, error: { name: string, message: string, errorNumber: number, stack?: string, metadata?: LoggingMetaData } } |\n{ result?: never, error?: never, iTwinError: { namespace: string, errorKey: string, message: string, stack?: string, metadata?: LoggingMetaData, [key: string]: any } };\n/**\n * An inter-process socket connection between a single [IModelHost]($backend) on the backend (the node process), and an [IModelApp]($frontend) on\n * the frontend (the browser process.) Each side will implement this interface to form a two way connection. The frontend and backend\n * processes connected through an IpcSocket don't necessarily have to be on the same computer, but often are.\n * @public\n*/\nexport interface IpcSocket {\n  /**\n   * Send a message over the socket.\n   * @param channel The name of the channel for the message. Must begin with the [[iTwinChannel]] prefix.\n   * @param data The optional data of the message.\n   * @note `data` is serialized with the [Structured Clone Algorithm](https://developer.mozilla.org/en-US/docs/Web/API/Web_Workers_API/Structured_clone_algorithm), so only\n   * primitive types and `ArrayBuffers` are allowed.\n   */\n  send: (channel: string, ...data: any[]) => void;\n  /**\n   * Establish a handler to receive messages for a channel through a socket.\n   * @param channel The name of the channel for the messages. Must begin with the [[iTwinChannel]] prefix.\n   * @param listener A function called when messages are sent over `channel`\n   * @note returns A function to call to remove the listener.\n   */\n  addListener: (channel: string, listener: IpcListener) => RemoveFunction;\n  /**\n   * Remove a previously registered listener\n   * @param channel The name of the channel for the listener previously registered with [[addListener]]\n   * @param listener The function passed to [[addListener]]\n   */\n  removeListener: (channel: string, listener: IpcListener) => void;\n}\n\n/**\n * Interface for the frontend (browser) side of a socket connection. Frontends may invoke methods implemented on the backend.\n * @public\n */\nexport interface IpcSocketFrontend extends IpcSocket {\n  /**\n   * Send a message to the backend via `channel` and expect a result asynchronously.\n   * @param channel The name of the channel for the method.  Must begin with the [[iTwinChannel]] prefix.\n   * @see Electron [ipcRenderer.invoke](https://www.electronjs.org/docs/api/ipc-renderer) documentation for details.\n   * Note that this interface *may* be implemented via Electron for desktop apps, or via\n   * [WebSockets](https://developer.mozilla.org/en-US/docs/Web/API/WebSockets_API) for mobile or web-based\n   * Ipc connections. In either case, the Electron documentation provides the specifications for how it works.\n   * @note `args` are serialized with the [Structured Clone Algorithm](https://developer.mozilla.org/en-US/docs/Web/API/Web_Workers_API/Structured_clone_algorithm), so only\n   * primitive types and `ArrayBuffers` are allowed.\n   */\n  invoke: (channel: string, ...args: any[]) => Promise<any>;\n}\n\n/**\n * Interface for the backend (Node.js) side of a socket connection. Backends provide the implementation\n * of methods that are invoked from the frontend.\n * @public\n */\nexport interface IpcSocketBackend extends IpcSocket {\n  /**\n   * Establish a backend implementation of an Ipc interface for a channel.\n   * @param channel The name of the channel for this handler. Must begin with the [[iTwinChannel]] prefix.\n   * @param handler A function that supplies the implementation for methods invoked over `channel` via [[IpcSocketFrontend.invoke]]\n   * @note returns A function to call to remove the handler.\n   */\n  handle: (channel: string, handler: (...args: any[]) => Promise<any>) => RemoveFunction;\n}\n\n"]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@itwin/core-common",
-  "version": "5.0.0-dev.82",
+  "version": "5.0.0-dev.84",
   "description": "iTwin.js components common to frontend and backend",
   "main": "lib/cjs/core-common.js",
   "module": "lib/esm/core-common.js",
@@ -27,8 +27,8 @@
     "js-base64": "^3.6.1"
   },
   "peerDependencies": {
-    "@itwin/core-bentley": "5.0.0-dev.82",
-    "@itwin/core-geometry": "5.0.0-dev.82"
+    "@itwin/core-bentley": "5.0.0-dev.84",
+    "@itwin/core-geometry": "5.0.0-dev.84"
   },
   "devDependencies": {
     "@itwin/eslint-plugin": "5.0.0-dev.1",
@@ -42,9 +42,9 @@
     "rimraf": "^6.0.1",
     "typescript": "~5.6.2",
     "vitest": "^3.0.6",
-    "@itwin/build-tools": "5.0.0-dev.82",
-    "@itwin/core-bentley": "5.0.0-dev.82",
-    "@itwin/core-geometry": "5.0.0-dev.82"
+    "@itwin/build-tools": "5.0.0-dev.84",
+    "@itwin/core-bentley": "5.0.0-dev.84",
+    "@itwin/core-geometry": "5.0.0-dev.84"
   },
   "nyc": {
     "extends": "./node_modules/@itwin/build-tools/.nycrc",