@itwin/core-common 5.12.0-dev.8 → 5.13.0-dev.1

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

@@ -0,0 +1,44 @@
+/** @packageDocumentation
+ * @module IpcSocket
+ */
+import { LoggingMetaData, PickAsyncMethods } from "@itwin/core-bentley";
+import { IpcInvokeReturn } from "./IpcSocket";
+/**
+ * Unwrap an [[IpcInvokeReturn]] produced by an Ipc handler: return its `result` on success, or rethrow the
+ * serialized `error` on failure (rebuilt via [[rebuildIpcError]]; non-object values are rethrown as-is).
+ *
+ * Shared by both Ipc directions. By default the error is rebuilt as a plain `Error` following the `ITwinError`
+ * paradigm (identify via [ITwinError.isError]($bentley)); the backend (`IpcHost`) uses this. A caller may pass
+ * `typedErrorClass` to rebuild a legacy typed error instead — the frontend (`IpcApp`) passes [BackendError]($common)
+ * to preserve `instanceof BackendError` for existing consumers.
+ * @param retVal The [[IpcInvokeReturn]] returned by the remote handler.
+ * @param typedErrorClass Optional constructor for a legacy typed error to build when the serialized error carries
+ * `BentleyError` identity (e.g. [BackendError]($common) on the frontend). Omit it for the ITwinError paradigm.
+ * @returns The handler's `result` value, typed as `T` (defaults to `unknown`, so untyped callers must narrow).
+ * @throws The reconstructed error when `retVal` carries an `error`.
+ * @internal
+ */
+export declare function unwrapIpcInvokeReturn<T = unknown>(retVal: IpcInvokeReturn, typedErrorClass?: new (errorNumber: number, name: string, message: string, getMetaData?: LoggingMetaData) => Error): T;
+/**
+ * Create a type-safe `Proxy` that routes every method access to `call`, forwarding the accessed method name and
+ * its arguments. Shared by the frontend (`IpcApp.makeIpcProxy`) and backend (`IpcHost.makeIpcProxy`) so both build
+ * their remote-interface proxies identically; each supplies a `call` bound to its own `callIpcChannel`.
+ * @param call Invoked with the accessed method name followed by the call arguments.
+ * @returns A `Proxy` exposing `K`'s async methods.
+ * @internal
+ */
+export declare function createIpcProxy<K>(call: (methodName: string, ...args: any[]) => Promise<any>): PickAsyncMethods<K>;
+/**
+ * Create the handler that an `IpcHandler` registers on its channel: it looks up `funcName` on `impl`, invokes it
+ * with `args`, and packages the outcome as an [[IpcInvokeReturn]] (`{ result }` on success, or a serialized `error`
+ * via [[serializeIpcError]] on failure). Shared by the frontend and backend `IpcHandler.register` implementations
+ * so method dispatch and error packaging behave identically in both directions.
+ * @param impl The handler instance whose methods are exposed over the channel.
+ * @param channelName The channel `impl` is registered on, used for diagnostic messages.
+ * @param includeStack Whether to include `Error.stack` in serialized errors, or a function evaluated per
+ * invocation to decide (the backend omits stacks when [[IpcHost.noStack]] is set, which can change at runtime).
+ * @returns An async dispatcher `(funcName, ...args) => Promise<IpcInvokeReturn>`.
+ * @internal
+ */
+export declare function createIpcDispatcher(impl: object, channelName: string, includeStack: boolean | (() => boolean)): (funcName: string, ...args: any[]) => Promise<IpcInvokeReturn>;
+//# sourceMappingURL=IpcInvoke.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"IpcInvoke.d.ts","sourceRoot":"","sources":["../../../src/ipc/IpcInvoke.ts"],"names":[],"mappings":"AAIA;;GAEG;AAEH,OAAO,EAA2B,eAAe,EAAE,gBAAgB,EAAE,MAAM,qBAAqB,CAAC;AAGjG,OAAO,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAE9C;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,qBAAqB,CAAC,CAAC,GAAG,OAAO,EAC/C,MAAM,EAAE,eAAe,EACvB,eAAe,CAAC,EAAE,KAAK,WAAW,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,WAAW,CAAC,EAAE,eAAe,KAAK,KAAK,GACjH,CAAC,CAUH;AAED;;;;;;;GAOG;AACH,wBAAgB,cAAc,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC,UAAU,EAAE,MAAM,EAAE,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,OAAO,CAAC,GAAG,CAAC,GAAG,gBAAgB,CAAC,CAAC,CAAC,CAMjH;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,mBAAmB,CACjC,IAAI,EAAE,MAAM,EACZ,WAAW,EAAE,MAAM,EACnB,YAAY,EAAE,OAAO,GAAG,CAAC,MAAM,OAAO,CAAC,GACtC,CAAC,QAAQ,EAAE,MAAM,EAAE,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,OAAO,CAAC,eAAe,CAAC,CAiBhE"}

package/lib/esm/ipc/IpcInvoke.js

@@ -0,0 +1,78 @@
+/*---------------------------------------------------------------------------------------------
+* Copyright (c) Bentley Systems, Incorporated. All rights reserved.
+* See LICENSE.md in the project root for license terms and full copyright notice.
+*--------------------------------------------------------------------------------------------*/
+/** @packageDocumentation
+ * @module IpcSocket
+ */
+import { IModelStatus, JsonUtils } from "@itwin/core-bentley";
+import { IModelError } from "../IModelError";
+import { rebuildIpcError, serializeIpcError } from "./IpcErrors";
+/**
+ * Unwrap an [[IpcInvokeReturn]] produced by an Ipc handler: return its `result` on success, or rethrow the
+ * serialized `error` on failure (rebuilt via [[rebuildIpcError]]; non-object values are rethrown as-is).
+ *
+ * Shared by both Ipc directions. By default the error is rebuilt as a plain `Error` following the `ITwinError`
+ * paradigm (identify via [ITwinError.isError]($bentley)); the backend (`IpcHost`) uses this. A caller may pass
+ * `typedErrorClass` to rebuild a legacy typed error instead — the frontend (`IpcApp`) passes [BackendError]($common)
+ * to preserve `instanceof BackendError` for existing consumers.
+ * @param retVal The [[IpcInvokeReturn]] returned by the remote handler.
+ * @param typedErrorClass Optional constructor for a legacy typed error to build when the serialized error carries
+ * `BentleyError` identity (e.g. [BackendError]($common) on the frontend). Omit it for the ITwinError paradigm.
+ * @returns The handler's `result` value, typed as `T` (defaults to `unknown`, so untyped callers must narrow).
+ * @throws The reconstructed error when `retVal` carries an `error`.
+ * @internal
+ */
+export function unwrapIpcInvokeReturn(retVal, typedErrorClass) {
+    if (retVal.error === undefined)
+        return retVal.result; // method was successful
+    // remote handler threw an exception, rethrow one on this side
+    const err = retVal.error;
+    if (!JsonUtils.isObject(err)) // exception wasn't an object?
+        throw retVal.error; // eslint-disable-line @typescript-eslint/only-throw-error
+    throw rebuildIpcError(err, typedErrorClass);
+}
+/**
+ * Create a type-safe `Proxy` that routes every method access to `call`, forwarding the accessed method name and
+ * its arguments. Shared by the frontend (`IpcApp.makeIpcProxy`) and backend (`IpcHost.makeIpcProxy`) so both build
+ * their remote-interface proxies identically; each supplies a `call` bound to its own `callIpcChannel`.
+ * @param call Invoked with the accessed method name followed by the call arguments.
+ * @returns A `Proxy` exposing `K`'s async methods.
+ * @internal
+ */
+export function createIpcProxy(call) {
+    return new Proxy({}, {
+        get(_target, methodName) {
+            return async (...args) => call(methodName, ...args);
+        },
+    });
+}
+/**
+ * Create the handler that an `IpcHandler` registers on its channel: it looks up `funcName` on `impl`, invokes it
+ * with `args`, and packages the outcome as an [[IpcInvokeReturn]] (`{ result }` on success, or a serialized `error`
+ * via [[serializeIpcError]] on failure). Shared by the frontend and backend `IpcHandler.register` implementations
+ * so method dispatch and error packaging behave identically in both directions.
+ * @param impl The handler instance whose methods are exposed over the channel.
+ * @param channelName The channel `impl` is registered on, used for diagnostic messages.
+ * @param includeStack Whether to include `Error.stack` in serialized errors, or a function evaluated per
+ * invocation to decide (the backend omits stacks when [[IpcHost.noStack]] is set, which can change at runtime).
+ * @returns An async dispatcher `(funcName, ...args) => Promise<IpcInvokeReturn>`.
+ * @internal
+ */
+export function createIpcDispatcher(impl, channelName, includeStack) {
+    const prohibitedFunctions = Object.getOwnPropertyNames(Object.getPrototypeOf({}));
+    return async (funcName, ...args) => {
+        try {
+            if (prohibitedFunctions.includes(funcName))
+                throw new Error(`Method "${funcName}" not available for channel: ${channelName}`);
+            const func = impl[funcName];
+            if (typeof func !== "function")
+                throw new IModelError(IModelStatus.FunctionNotFound, `Method "${impl.constructor.name}.${funcName}" not found on IpcHandler registered for channel: ${channelName}`);
+            return { result: await func.call(impl, ...args) };
+        }
+        catch (err) {
+            return serializeIpcError(err, typeof includeStack === "function" ? includeStack() : includeStack);
+        }
+    };
+}
+//# sourceMappingURL=IpcInvoke.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"IpcInvoke.js","sourceRoot":"","sources":["../../../src/ipc/IpcInvoke.ts"],"names":[],"mappings":"AAAA;;;+FAG+F;AAC/F;;GAEG;AAEH,OAAO,EAAE,YAAY,EAAE,SAAS,EAAqC,MAAM,qBAAqB,CAAC;AACjG,OAAO,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAC7C,OAAO,EAAE,eAAe,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AAGjE;;;;;;;;;;;;;;GAcG;AACH,MAAM,UAAU,qBAAqB,CACnC,MAAuB,EACvB,eAAkH;IAElH,IAAI,MAAM,CAAC,KAAK,KAAK,SAAS;QAC5B,OAAO,MAAM,CAAC,MAAW,CAAC,CAAC,wBAAwB;IAErD,8DAA8D;IAC9D,MAAM,GAAG,GAAG,MAAM,CAAC,KAAK,CAAC;IACzB,IAAI,CAAC,SAAS,CAAC,QAAQ,CAAC,GAAG,CAAC,EAAE,8BAA8B;QAC1D,MAAM,MAAM,CAAC,KAAK,CAAC,CAAC,0DAA0D;IAEhF,MAAM,eAAe,CAAC,GAAG,EAAE,eAAe,CAAC,CAAC;AAC9C,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,cAAc,CAAI,IAA0D;IAC1F,OAAO,IAAI,KAAK,CAAC,EAAyB,EAAE;QAC1C,GAAG,CAAC,OAAO,EAAE,UAAkB;YAC7B,OAAO,KAAK,EAAE,GAAG,IAAW,EAAE,EAAE,CAAC,IAAI,CAAC,UAAU,EAAE,GAAG,IAAI,CAAC,CAAC;QAC7D,CAAC;KACF,CAAC,CAAC;AACL,CAAC;AAED;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,mBAAmB,CACjC,IAAY,EACZ,WAAmB,EACnB,YAAuC;IAEvC,MAAM,mBAAmB,GAAG,MAAM,CAAC,mBAAmB,CAAC,MAAM,CAAC,cAAc,CAAC,EAAE,CAAC,CAAC,CAAC;IAElF,OAAO,KAAK,EAAE,QAAgB,EAAE,GAAG,IAAW,EAA4B,EAAE;QAC1E,IAAI,CAAC;YACH,IAAI,mBAAmB,CAAC,QAAQ,CAAC,QAAQ,CAAC;gBACxC,MAAM,IAAI,KAAK,CAAC,WAAW,QAAQ,gCAAgC,WAAW,EAAE,CAAC,CAAC;YAEpF,MAAM,IAAI,GAAI,IAAY,CAAC,QAAQ,CAAC,CAAC;YACrC,IAAI,OAAO,IAAI,KAAK,UAAU;gBAC5B,MAAM,IAAI,WAAW,CAAC,YAAY,CAAC,gBAAgB,EAAE,WAAW,IAAI,CAAC,WAAW,CAAC,IAAI,IAAI,QAAQ,qDAAqD,WAAW,EAAE,CAAC,CAAC;YAEvK,OAAO,EAAE,MAAM,EAAE,MAAM,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,GAAG,IAAI,CAAC,EAAE,CAAC;QACpD,CAAC;QAAC,OAAO,GAAY,EAAE,CAAC;YACtB,OAAO,iBAAiB,CAAC,GAAG,EAAE,OAAO,YAAY,KAAK,UAAU,CAAC,CAAC,CAAC,YAAY,EAAE,CAAC,CAAC,CAAC,YAAY,CAAC,CAAC;QACpG,CAAC;IACH,CAAC,CAAC;AACJ,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 { IModelStatus, JsonUtils, LoggingMetaData, PickAsyncMethods } from \"@itwin/core-bentley\";\nimport { IModelError } from \"../IModelError\";\nimport { rebuildIpcError, serializeIpcError } from \"./IpcErrors\";\nimport { IpcInvokeReturn } from \"./IpcSocket\";\n\n/**\n * Unwrap an [[IpcInvokeReturn]] produced by an Ipc handler: return its `result` on success, or rethrow the\n * serialized `error` on failure (rebuilt via [[rebuildIpcError]]; non-object values are rethrown as-is).\n *\n * Shared by both Ipc directions. By default the error is rebuilt as a plain `Error` following the `ITwinError`\n * paradigm (identify via [ITwinError.isError]($bentley)); the backend (`IpcHost`) uses this. A caller may pass\n * `typedErrorClass` to rebuild a legacy typed error instead — the frontend (`IpcApp`) passes [BackendError]($common)\n * to preserve `instanceof BackendError` for existing consumers.\n * @param retVal The [[IpcInvokeReturn]] returned by the remote handler.\n * @param typedErrorClass Optional constructor for a legacy typed error to build when the serialized error carries\n * `BentleyError` identity (e.g. [BackendError]($common) on the frontend). Omit it for the ITwinError paradigm.\n * @returns The handler's `result` value, typed as `T` (defaults to `unknown`, so untyped callers must narrow).\n * @throws The reconstructed error when `retVal` carries an `error`.\n * @internal\n */\nexport function unwrapIpcInvokeReturn<T = unknown>(\n  retVal: IpcInvokeReturn,\n  typedErrorClass?: new (errorNumber: number, name: string, message: string, getMetaData?: LoggingMetaData) => Error,\n): T {\n  if (retVal.error === undefined)\n    return retVal.result as T; // method was successful\n\n  // remote handler threw an exception, rethrow one on this side\n  const err = retVal.error;\n  if (!JsonUtils.isObject(err)) // exception wasn't an object?\n    throw retVal.error; // eslint-disable-line @typescript-eslint/only-throw-error\n\n  throw rebuildIpcError(err, typedErrorClass);\n}\n\n/**\n * Create a type-safe `Proxy` that routes every method access to `call`, forwarding the accessed method name and\n * its arguments. Shared by the frontend (`IpcApp.makeIpcProxy`) and backend (`IpcHost.makeIpcProxy`) so both build\n * their remote-interface proxies identically; each supplies a `call` bound to its own `callIpcChannel`.\n * @param call Invoked with the accessed method name followed by the call arguments.\n * @returns A `Proxy` exposing `K`'s async methods.\n * @internal\n */\nexport function createIpcProxy<K>(call: (methodName: string, ...args: any[]) => Promise<any>): PickAsyncMethods<K> {\n  return new Proxy({} as PickAsyncMethods<K>, {\n    get(_target, methodName: string) {\n      return async (...args: any[]) => call(methodName, ...args);\n    },\n  });\n}\n\n/**\n * Create the handler that an `IpcHandler` registers on its channel: it looks up `funcName` on `impl`, invokes it\n * with `args`, and packages the outcome as an [[IpcInvokeReturn]] (`{ result }` on success, or a serialized `error`\n * via [[serializeIpcError]] on failure). Shared by the frontend and backend `IpcHandler.register` implementations\n * so method dispatch and error packaging behave identically in both directions.\n * @param impl The handler instance whose methods are exposed over the channel.\n * @param channelName The channel `impl` is registered on, used for diagnostic messages.\n * @param includeStack Whether to include `Error.stack` in serialized errors, or a function evaluated per\n * invocation to decide (the backend omits stacks when [[IpcHost.noStack]] is set, which can change at runtime).\n * @returns An async dispatcher `(funcName, ...args) => Promise<IpcInvokeReturn>`.\n * @internal\n */\nexport function createIpcDispatcher(\n  impl: object,\n  channelName: string,\n  includeStack: boolean | (() => boolean),\n): (funcName: string, ...args: any[]) => Promise<IpcInvokeReturn> {\n  const prohibitedFunctions = Object.getOwnPropertyNames(Object.getPrototypeOf({}));\n\n  return async (funcName: string, ...args: any[]): Promise<IpcInvokeReturn> => {\n    try {\n      if (prohibitedFunctions.includes(funcName))\n        throw new Error(`Method \"${funcName}\" not available for channel: ${channelName}`);\n\n      const func = (impl as any)[funcName];\n      if (typeof func !== \"function\")\n        throw new IModelError(IModelStatus.FunctionNotFound, `Method \"${impl.constructor.name}.${funcName}\" not found on IpcHandler registered for channel: ${channelName}`);\n\n      return { result: await func.call(impl, ...args) };\n    } catch (err: unknown) {\n      return serializeIpcError(err, typeof includeStack === \"function\" ? includeStack() : includeStack);\n    }\n  };\n}\n"]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@itwin/core-common",
-  "version": "5.12.0-dev.8",
+  "version": "5.13.0-dev.1",
   "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.12.0-dev.8",
-    "@itwin/core-geometry": "5.12.0-dev.8"
+    "@itwin/core-bentley": "5.13.0-dev.1",
+    "@itwin/core-geometry": "5.13.0-dev.1"
   },
   "devDependencies": {
     "@itwin/eslint-plugin": "^6.0.0",
@@ -36,15 +36,15 @@
     "@types/chai": "4.3.1",
     "@types/flatbuffers": "~1.10.0",
     "@types/node": "~20.17.0",
-    "@vitest/coverage-v8": "^4.1.8",
+    "@vitest/coverage-v8": "^4.1.10",
     "eslint": "^9.31.0",
     "nyc": "^17.1.0",
     "rimraf": "^6.0.1",
     "typescript": "~5.6.2",
-    "vitest": "^4.1.8",
-    "@itwin/build-tools": "5.12.0-dev.8",
-    "@itwin/core-bentley": "5.12.0-dev.8",
-    "@itwin/core-geometry": "5.12.0-dev.8"
+    "vitest": "^4.1.10",
+    "@itwin/build-tools": "5.13.0-dev.1",
+    "@itwin/core-geometry": "5.13.0-dev.1",
+    "@itwin/core-bentley": "5.13.0-dev.1"
   },
   "nyc": {
     "extends": "./node_modules/@itwin/build-tools/.nycrc",