@trackunit/iris-app-runtime-core 1.17.6 → 1.17.7

package/index.cjs.js

@@ -6,40 +6,146 @@ var penpal = require('penpal');
 const doNothingByDefault = () => {
     // do nothing by default
 };
+/**
+ * Registry of handlers for the host-driven subscription methods that the host
+ * pushes through the `host-runtime` channel. Providers (e.g.
+ * `TokenProviderIrisApp`) install their real handler via
+ * {@link registerHostChangeHandler}, replacing the `doNothingByDefault`
+ * placeholder until they unmount.
+ *
+ * v6's original design used a separate penpal connection per provider on
+ * dedicated channels (`token-subscription`, `time-range-subscription`, …)
+ * which worked only because v6's multi-connection bug caused the host's
+ * single `connectToChild` to receive messages from all of them. With v7's
+ * proper channel isolation, that arrangement silently drops every push event
+ * because the host only opens the `host-runtime` channel. This registry
+ * collapses all subscription methods back onto the host-runtime channel so
+ * they fire reliably without forcing the host to open one connection per
+ * channel.
+ */
+const subscriptionHandlers = {
+    onFilterBarValuesChanged: doNothingByDefault,
+    onTokenChanged: doNothingByDefault,
+    onAssetSortingStateChanged: doNothingByDefault,
+    onAssetsFilterBarValuesChanged: doNothingByDefault,
+    onCustomersFilterBarValuesChanged: doNothingByDefault,
+    onSitesFilterBarValuesChanged: doNothingByDefault,
+    onTablePersistenceStateChanged: doNothingByDefault,
+    onTimeRangeChanged: doNothingByDefault,
+    onWidgetPollIntervalChanged: doNothingByDefault,
+};
+/**
+ * Install a handler for one of the host-driven subscription methods on the
+ * singleton `host-runtime` channel. Returns an unregister function that
+ * restores the previously installed handler (typically the
+ * `doNothingByDefault` no-op); call it from the effect's cleanup.
+ *
+ * Safe to call before the singleton's penpal handshake completes: the
+ * singleton's child-facing methods look up the current handler at call time,
+ * so handlers registered after `connect()` has resolved still receive events.
+ */
+const registerHostChangeHandler = (name, handler) => {
+    const previous = subscriptionHandlers[name];
+    subscriptionHandlers[name] = handler;
+    return () => {
+        // Only restore if we're still the active handler — a newer mount may have
+        // installed its own handler in the meantime, and we don't want this stale
+        // cleanup to clobber it.
+        if (subscriptionHandlers[name] === handler) {
+            subscriptionHandlers[name] = previous;
+        }
+    };
+};
+const dispatchToHandler = (name) => {
+    // The closure dispatches at call time so handlers registered after the
+    // singleton's connect() has resolved still receive events.
+    const dispatch = (...args) => {
+        const handler = subscriptionHandlers[name];
+        return handler(...args);
+    };
+    return dispatch;
+};
 /**
  * Setup using the subscribedMethods to subscribe to events from the host.
  *
- * @param subscribedMethods the methods to subscribe to
- * @returns { Connection<HostConnectorApi> } the connection to the host
+ * @param subscribedMethods the methods to subscribe to. Any key omitted here
+ *   dispatches through the {@link registerHostChangeHandler} registry on the
+ *   singleton connection, so internal callers can register handlers via that
+ *   path without opening a second penpal connection.
+ * @param channel the penpal channel to use; defaults to `undefined`. The
+ *   default singleton on the iris-app side intentionally omits the channel so
+ *   the host's matching `connect()` call (which also omits it) can accept
+ *   both native v7 SYNs and v6 SYNs translated by penpal's v6-compat shim
+ *   (`upgradeMessage` produces v7 messages with `channel: undefined`). External
+ *   callers can still pin a channel for isolated parallel connections; the
+ *   host won't auto-handshake those — they're for caller-managed transports.
+ * @returns { Connection<HostConnectorMethods> } the connection to the host
  */
-const setupHostConnector = (subscribedMethods) => {
+const setupHostConnector = (subscribedMethods, channel) => {
     const methods = {
-        onFilterBarValuesChanged: doNothingByDefault,
-        onTokenChanged: doNothingByDefault,
-        onAssetSortingStateChanged: doNothingByDefault,
-        onAssetsFilterBarValuesChanged: doNothingByDefault,
-        onCustomersFilterBarValuesChanged: doNothingByDefault,
-        onSitesFilterBarValuesChanged: doNothingByDefault,
-        onTablePersistenceStateChanged: doNothingByDefault,
-        onTimeRangeChanged: doNothingByDefault,
-        onWidgetPollIntervalChanged: doNothingByDefault,
+        onFilterBarValuesChanged: dispatchToHandler("onFilterBarValuesChanged"),
+        onTokenChanged: dispatchToHandler("onTokenChanged"),
+        onAssetSortingStateChanged: dispatchToHandler("onAssetSortingStateChanged"),
+        onAssetsFilterBarValuesChanged: dispatchToHandler("onAssetsFilterBarValuesChanged"),
+        onCustomersFilterBarValuesChanged: dispatchToHandler("onCustomersFilterBarValuesChanged"),
+        onSitesFilterBarValuesChanged: dispatchToHandler("onSitesFilterBarValuesChanged"),
+        onTablePersistenceStateChanged: dispatchToHandler("onTablePersistenceStateChanged"),
+        onTimeRangeChanged: dispatchToHandler("onTimeRangeChanged"),
+        onWidgetPollIntervalChanged: dispatchToHandler("onWidgetPollIntervalChanged"),
         ...subscribedMethods,
     };
-    const connection = penpal.connectToParent({ methods });
-    connection.promise.catch(err => {
-        // TODO consider how to handle this catch
-        // eslint-disable-next-line no-console
-        console.log(err);
+    const connection = penpal.connect({
+        messenger: new penpal.WindowMessenger({ remoteWindow: window.parent, allowedOrigins: ["*"] }),
+        methods,
+        channel,
+        timeout: 10000,
+    });
+    // Subscription-channel connections (e.g. token-subscription, time-range-subscription)
+    // are routinely destroyed by `useSubscribeToHostChanges`' cleanup before the host
+    // opens its matching channel and the handshake can complete; without a swallowing
+    // .catch here, every unmount emits an unhandled-promise rejection.
+    connection.promise.catch(() => {
+        // intentionally swallowed; consumers that need the resolved proxy go through
+        // `getHostConnector()` which propagates the rejection on its own path.
     });
     return connection;
 };
-const hostConnector = setupHostConnector({});
+/**
+ * The module-level singleton connector to the host's runtime bridge.
+ *
+ * Lazy-initialised on the first {@link getHostConnector} call (rather than at
+ * module evaluation time) so that simply importing this module from the host
+ * bundle does not open an unwanted self-talking penpal connection. In the host
+ * window `window.parent === window`, which would make penpal post SYN messages
+ * back to itself and time out after 10s — see `PENPAL-V7-MIGRATION.md` §2.
+ *
+ * Iris-app bundles (which always run inside an iframe and have a real parent
+ * window) reach this lazily via `getHostConnector()` from runtime classes such
+ * as `TokenRuntime`, `RestRuntime`, etc.
+ */
+let hostConnector = null;
 /**
  * Gets the host connector.
  *
- * @returns { Promise<Connection<HostConnectorApi>> } the connection to the host
+ * Returns penpal v7's {@link RemoteProxy} directly. The proxy is a JavaScript
+ * `Proxy` that intercepts every method access via a `get` trap and routes the
+ * call to the host through the underlying `MessagePort`. Attempting to spread
+ * or `Object.assign` it produces an empty object — the proxy has no own
+ * enumerable properties, only the `get` trap.
+ *
+ * The return is type-cast to `HostConnectorApi` because v7's `RemoteProxy<T>`
+ * is a mapped type that erases method-level generics (e.g. `exportData`'s
+ * `<TData, TVariables>` is widened to `<unknown, unknown>`). At runtime the
+ * proxy serializes whatever data the caller hands it across `postMessage`, so
+ * the original generics are honoured by the host on the other end — the
+ * widening is purely a TypeScript artefact at this library boundary.
+ *
+ * @returns { Promise<HostConnectorApi> } the connection to the host
  */
 const getHostConnector = () => {
+    if (!hostConnector) {
+        hostConnector = setupHostConnector({});
+    }
     return hostConnector.promise;
 };
 
@@ -689,6 +795,7 @@ exports.getDateValue = getDateValue;
 exports.getHostConnector = getHostConnector;
 exports.getStringValue = getStringValue;
 exports.isValidCustomFieldValue = isValidCustomFieldValue;
+exports.registerHostChangeHandler = registerHostChangeHandler;
 exports.setupHostConnector = setupHostConnector;
 Object.keys(irisAppRuntimeCoreApi).forEach(function (k) {
     if (k !== 'default' && !Object.prototype.hasOwnProperty.call(exports, k)) Object.defineProperty(exports, k, {

package/index.esm.js

@@ -1,43 +1,149 @@
 export * from '@trackunit/iris-app-runtime-core-api';
-import { connectToParent } from 'penpal';
+import { connect, WindowMessenger } from 'penpal';
 
 const doNothingByDefault = () => {
     // do nothing by default
 };
+/**
+ * Registry of handlers for the host-driven subscription methods that the host
+ * pushes through the `host-runtime` channel. Providers (e.g.
+ * `TokenProviderIrisApp`) install their real handler via
+ * {@link registerHostChangeHandler}, replacing the `doNothingByDefault`
+ * placeholder until they unmount.
+ *
+ * v6's original design used a separate penpal connection per provider on
+ * dedicated channels (`token-subscription`, `time-range-subscription`, …)
+ * which worked only because v6's multi-connection bug caused the host's
+ * single `connectToChild` to receive messages from all of them. With v7's
+ * proper channel isolation, that arrangement silently drops every push event
+ * because the host only opens the `host-runtime` channel. This registry
+ * collapses all subscription methods back onto the host-runtime channel so
+ * they fire reliably without forcing the host to open one connection per
+ * channel.
+ */
+const subscriptionHandlers = {
+    onFilterBarValuesChanged: doNothingByDefault,
+    onTokenChanged: doNothingByDefault,
+    onAssetSortingStateChanged: doNothingByDefault,
+    onAssetsFilterBarValuesChanged: doNothingByDefault,
+    onCustomersFilterBarValuesChanged: doNothingByDefault,
+    onSitesFilterBarValuesChanged: doNothingByDefault,
+    onTablePersistenceStateChanged: doNothingByDefault,
+    onTimeRangeChanged: doNothingByDefault,
+    onWidgetPollIntervalChanged: doNothingByDefault,
+};
+/**
+ * Install a handler for one of the host-driven subscription methods on the
+ * singleton `host-runtime` channel. Returns an unregister function that
+ * restores the previously installed handler (typically the
+ * `doNothingByDefault` no-op); call it from the effect's cleanup.
+ *
+ * Safe to call before the singleton's penpal handshake completes: the
+ * singleton's child-facing methods look up the current handler at call time,
+ * so handlers registered after `connect()` has resolved still receive events.
+ */
+const registerHostChangeHandler = (name, handler) => {
+    const previous = subscriptionHandlers[name];
+    subscriptionHandlers[name] = handler;
+    return () => {
+        // Only restore if we're still the active handler — a newer mount may have
+        // installed its own handler in the meantime, and we don't want this stale
+        // cleanup to clobber it.
+        if (subscriptionHandlers[name] === handler) {
+            subscriptionHandlers[name] = previous;
+        }
+    };
+};
+const dispatchToHandler = (name) => {
+    // The closure dispatches at call time so handlers registered after the
+    // singleton's connect() has resolved still receive events.
+    const dispatch = (...args) => {
+        const handler = subscriptionHandlers[name];
+        return handler(...args);
+    };
+    return dispatch;
+};
 /**
  * Setup using the subscribedMethods to subscribe to events from the host.
  *
- * @param subscribedMethods the methods to subscribe to
- * @returns { Connection<HostConnectorApi> } the connection to the host
+ * @param subscribedMethods the methods to subscribe to. Any key omitted here
+ *   dispatches through the {@link registerHostChangeHandler} registry on the
+ *   singleton connection, so internal callers can register handlers via that
+ *   path without opening a second penpal connection.
+ * @param channel the penpal channel to use; defaults to `undefined`. The
+ *   default singleton on the iris-app side intentionally omits the channel so
+ *   the host's matching `connect()` call (which also omits it) can accept
+ *   both native v7 SYNs and v6 SYNs translated by penpal's v6-compat shim
+ *   (`upgradeMessage` produces v7 messages with `channel: undefined`). External
+ *   callers can still pin a channel for isolated parallel connections; the
+ *   host won't auto-handshake those — they're for caller-managed transports.
+ * @returns { Connection<HostConnectorMethods> } the connection to the host
  */
-const setupHostConnector = (subscribedMethods) => {
+const setupHostConnector = (subscribedMethods, channel) => {
     const methods = {
-        onFilterBarValuesChanged: doNothingByDefault,
-        onTokenChanged: doNothingByDefault,
-        onAssetSortingStateChanged: doNothingByDefault,
-        onAssetsFilterBarValuesChanged: doNothingByDefault,
-        onCustomersFilterBarValuesChanged: doNothingByDefault,
-        onSitesFilterBarValuesChanged: doNothingByDefault,
-        onTablePersistenceStateChanged: doNothingByDefault,
-        onTimeRangeChanged: doNothingByDefault,
-        onWidgetPollIntervalChanged: doNothingByDefault,
+        onFilterBarValuesChanged: dispatchToHandler("onFilterBarValuesChanged"),
+        onTokenChanged: dispatchToHandler("onTokenChanged"),
+        onAssetSortingStateChanged: dispatchToHandler("onAssetSortingStateChanged"),
+        onAssetsFilterBarValuesChanged: dispatchToHandler("onAssetsFilterBarValuesChanged"),
+        onCustomersFilterBarValuesChanged: dispatchToHandler("onCustomersFilterBarValuesChanged"),
+        onSitesFilterBarValuesChanged: dispatchToHandler("onSitesFilterBarValuesChanged"),
+        onTablePersistenceStateChanged: dispatchToHandler("onTablePersistenceStateChanged"),
+        onTimeRangeChanged: dispatchToHandler("onTimeRangeChanged"),
+        onWidgetPollIntervalChanged: dispatchToHandler("onWidgetPollIntervalChanged"),
         ...subscribedMethods,
     };
-    const connection = connectToParent({ methods });
-    connection.promise.catch(err => {
-        // TODO consider how to handle this catch
-        // eslint-disable-next-line no-console
-        console.log(err);
+    const connection = connect({
+        messenger: new WindowMessenger({ remoteWindow: window.parent, allowedOrigins: ["*"] }),
+        methods,
+        channel,
+        timeout: 10000,
+    });
+    // Subscription-channel connections (e.g. token-subscription, time-range-subscription)
+    // are routinely destroyed by `useSubscribeToHostChanges`' cleanup before the host
+    // opens its matching channel and the handshake can complete; without a swallowing
+    // .catch here, every unmount emits an unhandled-promise rejection.
+    connection.promise.catch(() => {
+        // intentionally swallowed; consumers that need the resolved proxy go through
+        // `getHostConnector()` which propagates the rejection on its own path.
     });
     return connection;
 };
-const hostConnector = setupHostConnector({});
+/**
+ * The module-level singleton connector to the host's runtime bridge.
+ *
+ * Lazy-initialised on the first {@link getHostConnector} call (rather than at
+ * module evaluation time) so that simply importing this module from the host
+ * bundle does not open an unwanted self-talking penpal connection. In the host
+ * window `window.parent === window`, which would make penpal post SYN messages
+ * back to itself and time out after 10s — see `PENPAL-V7-MIGRATION.md` §2.
+ *
+ * Iris-app bundles (which always run inside an iframe and have a real parent
+ * window) reach this lazily via `getHostConnector()` from runtime classes such
+ * as `TokenRuntime`, `RestRuntime`, etc.
+ */
+let hostConnector = null;
 /**
  * Gets the host connector.
  *
- * @returns { Promise<Connection<HostConnectorApi>> } the connection to the host
+ * Returns penpal v7's {@link RemoteProxy} directly. The proxy is a JavaScript
+ * `Proxy` that intercepts every method access via a `get` trap and routes the
+ * call to the host through the underlying `MessagePort`. Attempting to spread
+ * or `Object.assign` it produces an empty object — the proxy has no own
+ * enumerable properties, only the `get` trap.
+ *
+ * The return is type-cast to `HostConnectorApi` because v7's `RemoteProxy<T>`
+ * is a mapped type that erases method-level generics (e.g. `exportData`'s
+ * `<TData, TVariables>` is widened to `<unknown, unknown>`). At runtime the
+ * proxy serializes whatever data the caller hands it across `postMessage`, so
+ * the original generics are honoured by the host on the other end — the
+ * widening is purely a TypeScript artefact at this library boundary.
+ *
+ * @returns { Promise<HostConnectorApi> } the connection to the host
  */
 const getHostConnector = () => {
+    if (!hostConnector) {
+        hostConnector = setupHostConnector({});
+    }
     return hostConnector.promise;
 };
 
@@ -653,4 +759,4 @@ const WidgetConfigRuntime = {
     },
 };
 
-export { AnalyticsRuntime, AssetRuntime, AssetSortingRuntime, AssetsFilterBarRuntime, ConfirmationDialogRuntime, CurrentUserPreferenceRuntime, CurrentUserRuntime, CustomerRuntime, CustomersFilterBarRuntime, EnvironmentRuntime, EventRuntime, ExportDataRuntime, FeatureFlagRuntime, GeolocationRuntime, ModalDialogRuntime, NavigationRuntime, OemBrandingRuntime, ParamsRuntime, RestRuntime, RouterRuntime, SiteRuntime, SitesFilterBarRuntime, ThemeCssRuntime, TimeRangeRuntime, ToastRuntime, TokenRuntime, UserSubscriptionRuntime, WidgetConfigRuntime, getCustomFieldValueForDisplayInUI, getCustomFieldValueToSaveFromRawValue, getDateValue, getHostConnector, getStringValue, isValidCustomFieldValue, setupHostConnector };
+export { AnalyticsRuntime, AssetRuntime, AssetSortingRuntime, AssetsFilterBarRuntime, ConfirmationDialogRuntime, CurrentUserPreferenceRuntime, CurrentUserRuntime, CustomerRuntime, CustomersFilterBarRuntime, EnvironmentRuntime, EventRuntime, ExportDataRuntime, FeatureFlagRuntime, GeolocationRuntime, ModalDialogRuntime, NavigationRuntime, OemBrandingRuntime, ParamsRuntime, RestRuntime, RouterRuntime, SiteRuntime, SitesFilterBarRuntime, ThemeCssRuntime, TimeRangeRuntime, ToastRuntime, TokenRuntime, UserSubscriptionRuntime, WidgetConfigRuntime, getCustomFieldValueForDisplayInUI, getCustomFieldValueToSaveFromRawValue, getDateValue, getHostConnector, getStringValue, isValidCustomFieldValue, registerHostChangeHandler, setupHostConnector };

package/package.json

@@ -1,14 +1,14 @@
 {
   "name": "@trackunit/iris-app-runtime-core",
-  "version": "1.17.6",
+  "version": "1.17.7",
   "repository": "https://github.com/Trackunit/manager",
   "license": "SEE LICENSE IN LICENSE.txt",
   "engines": {
     "node": ">=24.x"
   },
   "dependencies": {
-    "penpal": "^6.2.2",
-    "@trackunit/iris-app-runtime-core-api": "1.16.6"
+    "penpal": "^7.0.6",
+    "@trackunit/iris-app-runtime-core-api": "1.16.7"
   },
   "module": "./index.esm.js",
   "main": "./index.cjs.js",

package/src/HostConnector.d.ts

@@ -1,15 +1,51 @@
 import { ChildConnectorApi, HostConnectorApi } from "@trackunit/iris-app-runtime-core-api";
-import { AsyncMethodReturns, Connection, Methods } from "penpal";
+import { Connection, Methods } from "penpal";
+type HostConnectorMethods = HostConnectorApi & Methods;
+/**
+ * Install a handler for one of the host-driven subscription methods on the
+ * singleton `host-runtime` channel. Returns an unregister function that
+ * restores the previously installed handler (typically the
+ * `doNothingByDefault` no-op); call it from the effect's cleanup.
+ *
+ * Safe to call before the singleton's penpal handshake completes: the
+ * singleton's child-facing methods look up the current handler at call time,
+ * so handlers registered after `connect()` has resolved still receive events.
+ */
+export declare const registerHostChangeHandler: <TKey extends keyof ChildConnectorApi>(name: TKey, handler: ChildConnectorApi[TKey]) => (() => void);
 /**
  * Setup using the subscribedMethods to subscribe to events from the host.
  *
- * @param subscribedMethods the methods to subscribe to
- * @returns { Connection<HostConnectorApi> } the connection to the host
+ * @param subscribedMethods the methods to subscribe to. Any key omitted here
+ *   dispatches through the {@link registerHostChangeHandler} registry on the
+ *   singleton connection, so internal callers can register handlers via that
+ *   path without opening a second penpal connection.
+ * @param channel the penpal channel to use; defaults to `undefined`. The
+ *   default singleton on the iris-app side intentionally omits the channel so
+ *   the host's matching `connect()` call (which also omits it) can accept
+ *   both native v7 SYNs and v6 SYNs translated by penpal's v6-compat shim
+ *   (`upgradeMessage` produces v7 messages with `channel: undefined`). External
+ *   callers can still pin a channel for isolated parallel connections; the
+ *   host won't auto-handshake those — they're for caller-managed transports.
+ * @returns { Connection<HostConnectorMethods> } the connection to the host
  */
-export declare const setupHostConnector: (subscribedMethods: Partial<ChildConnectorApi> & Methods) => Connection<HostConnectorApi>;
+export declare const setupHostConnector: (subscribedMethods: Partial<ChildConnectorApi> & Methods, channel?: string) => Connection<HostConnectorMethods>;
 /**
  * Gets the host connector.
  *
- * @returns { Promise<Connection<HostConnectorApi>> } the connection to the host
+ * Returns penpal v7's {@link RemoteProxy} directly. The proxy is a JavaScript
+ * `Proxy` that intercepts every method access via a `get` trap and routes the
+ * call to the host through the underlying `MessagePort`. Attempting to spread
+ * or `Object.assign` it produces an empty object — the proxy has no own
+ * enumerable properties, only the `get` trap.
+ *
+ * The return is type-cast to `HostConnectorApi` because v7's `RemoteProxy<T>`
+ * is a mapped type that erases method-level generics (e.g. `exportData`'s
+ * `<TData, TVariables>` is widened to `<unknown, unknown>`). At runtime the
+ * proxy serializes whatever data the caller hands it across `postMessage`, so
+ * the original generics are honoured by the host on the other end — the
+ * widening is purely a TypeScript artefact at this library boundary.
+ *
+ * @returns { Promise<HostConnectorApi> } the connection to the host
  */
-export declare const getHostConnector: () => Promise<AsyncMethodReturns<HostConnectorApi>>;
+export declare const getHostConnector: () => Promise<HostConnectorApi>;
+export {};