@adobe/uix-core 0.6.5 → 0.7.0

package/dist/tunnel/tunnel.d.ts

@@ -0,0 +1,58 @@
+import EventEmitter from "eventemitter3";
+/** @alpha */
+export interface TunnelConfig {
+    /**
+     * To ensure secure communication, target origin must be specified, so the
+     * tunnel can't connect to an unauthorized domain. Can be '*' to disable
+     * origin checks, but this is discouraged!
+     */
+    targetOrigin: string;
+    /**
+     * A Promise for a tunnel will reject if not connected within timeout (ms).
+     * @defaultValue 4000
+     */
+    timeout: number;
+}
+/**
+ * An EventEmitter across two documents. It emits events on the remote document
+ * and takes subscribers from the local document.
+ * @alpha
+ */
+export declare class Tunnel extends EventEmitter {
+    private _messagePort;
+    config: TunnelConfig;
+    constructor(config: TunnelConfig);
+    /**
+     * Create a Tunnel that connects to the page running in the provided iframe.
+     *
+     * @remarks
+     * Returns a Tunnel that listens for connection requests from the page in the
+     * provided iframe, which it will send periodically until timeout if that page
+     * has called {@link Tunnel.toParent}. If it receives one, the Tunnel will accept the
+     * connection and send an exclusive MessagePort to the xrobject on the other
+     * end. The tunnel may reconnect if the iframe reloads, in which case it will
+     * emit another "connected" event.
+     *
+     * @alpha
+     */
+    static toIframe(target: HTMLIFrameElement, options: Partial<TunnelConfig>): Tunnel;
+    /**
+     * Create a Tunnel that connects to the page running in the parent window.
+     *
+     * @remarks
+     * Returns a Tunnel that starts sending connection requests to the parent
+     * window, sending them periodically until the window responds with an accept
+     * message or the timeout passes. The parent window will accept the request if
+     * it calls {@link Tunnel.toIframe}.
+     *
+     * @alpha
+     */
+    static toParent(source: WindowProxy, opts: Partial<TunnelConfig>): Tunnel;
+    connect(remote: MessagePort): void;
+    destroy(): void;
+    emit(type: string | symbol, payload?: unknown): boolean;
+    emitLocal: (type: string | symbol, payload?: unknown) => any;
+    private static _normalizeConfig;
+    private _emitFromMessage;
+}
+//# sourceMappingURL=tunnel.d.ts.map

package/dist/tunnel/tunnel.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tunnel.d.ts","sourceRoot":"","sources":["../../src/tunnel/tunnel.ts"],"names":[],"mappings":"AAAA,OAAO,YAAY,MAAM,eAAe,CAAC;AAiCzC,aAAa;AACb,MAAM,WAAW,YAAY;IAG3B;;;;OAIG;IACH,YAAY,EAAE,MAAM,CAAC;IACrB;;;OAGG;IACH,OAAO,EAAE,MAAM,CAAC;CAGjB;AAuBD;;;;GAIG;AACH,qBAAa,MAAO,SAAQ,YAAY;IAGtC,OAAO,CAAC,YAAY,CAAc;IAElC,MAAM,EAAE,YAAY,CAAC;gBAMT,MAAM,EAAE,YAAY;IAShC;;;;;;;;;;;;OAYG;IACH,MAAM,CAAC,QAAQ,CACb,MAAM,EAAE,iBAAiB,EACzB,OAAO,EAAE,OAAO,CAAC,YAAY,CAAC,GAC7B,MAAM;IAyDT;;;;;;;;;;OAUG;IACH,MAAM,CAAC,QAAQ,CAAC,MAAM,EAAE,WAAW,EAAE,IAAI,EAAE,OAAO,CAAC,YAAY,CAAC,GAAG,MAAM;IAwDzE,OAAO,CAAC,MAAM,EAAE,WAAW;IAW3B,OAAO,IAAI,IAAI;IAUf,IAAI,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,EAAE,OAAO,CAAC,EAAE,OAAO,GAAG,OAAO;IAQvD,SAAS,SAAU,MAAM,GAAG,MAAM,YAAY,OAAO,SAEnD;IAMF,OAAO,CAAC,MAAM,CAAC,gBAAgB;IA8B/B,OAAO,CAAC,gBAAgB,CAEtB;CAGH"}

package/dist/tunnel/tunnel.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=tunnel.test.d.ts.map

package/dist/tunnel/tunnel.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tunnel.test.d.ts","sourceRoot":"","sources":["../../src/tunnel/tunnel.test.ts"],"names":[],"mappings":""}

package/dist/types.d.ts

@@ -133,10 +133,7 @@ export interface HostConnection<T = unknown> {
 export interface GuestConnection {
     id: string;
     url: URL;
-    attachUI(frame: HTMLIFrameElement, privateMethods?: RemoteHostApis): {
-        promise: Promise<unknown>;
-        destroy: Function;
-    };
+    attachUI(frame: HTMLIFrameElement, privateMethods?: RemoteHostApis): Promise<unknown>;
     load(): Promise<unknown>;
     error?: Error;
     hasCapabilities(capabilities: unknown): boolean;

package/dist/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}

package/dist/value-assertions.d.ts

@@ -0,0 +1,10 @@
+/** @internal */
+export declare type Primitive = string | number | boolean;
+export declare function isPlainObject<T>(value: unknown): value is T & object;
+export declare function isPrimitive(value: unknown): value is Primitive;
+export declare function isIterable<T>(value: unknown): value is T[];
+export declare function isFunction(value: unknown): value is CallableFunction;
+export declare function hasProp(value: unknown, prop: string): boolean;
+export declare function isTunnelSource(value: unknown): value is Window | ServiceWorker;
+export declare function isIframe(value: unknown): value is HTMLIFrameElement;
+//# sourceMappingURL=value-assertions.d.ts.map

package/dist/value-assertions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"value-assertions.d.ts","sourceRoot":"","sources":["../src/value-assertions.ts"],"names":[],"mappings":"AAAA,gBAAgB;AAChB,oBAAY,SAAS,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC;AAElD,wBAAgB,aAAa,CAAC,CAAC,EAAE,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,CAAC,GAAG,MAAM,CAMpE;AAED,wBAAgB,WAAW,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,SAAS,CAM9D;AAED,wBAAgB,UAAU,CAAC,CAAC,EAAE,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,CAAC,EAAE,CAE1D;AAED,wBAAgB,UAAU,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,gBAAgB,CAEpE;AAED,wBAAgB,OAAO,CAAC,KAAK,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,WAEnD;AAED,wBAAgB,cAAc,CAC5B,KAAK,EAAE,OAAO,GACb,KAAK,IAAI,MAAM,GAAG,aAAa,CAMjC;AAED,wBAAgB,QAAQ,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,iBAAiB,CAMnE"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adobe/uix-core",
-  "version": "0.6.5",
+  "version": "0.7.0",
   "publishConfig": {
     "access": "public"
   },

package/src/__helpers__/jest.messagechannel.cjs

@@ -0,0 +1,3 @@
+const { MessageChannel, MessagePort } = require("node:worker_threads");
+window.MessageChannel = MessageChannel;
+window.MessagePort = MessagePort;

package/src/__mocks__/mock-finalization-registry.ts

@@ -0,0 +1,13 @@
+type CleanupHandler = (heldValue: any) => void;
+const register = jest.fn();
+const unregister = jest.fn();
+export class FakeFinalizationRegistry {
+  static mock: FakeFinalizationRegistry;
+  register = register;
+  unregister = unregister;
+  cleanupHandler: jest.MockedFunction<CleanupHandler>;
+  constructor(handler: CleanupHandler) {
+    this.cleanupHandler = jest.fn(handler);
+    FakeFinalizationRegistry.mock = this;
+  }
+}

package/src/__mocks__/mock-weak-ref.ts

@@ -0,0 +1,10 @@
+export class FakeWeakRef<T> {
+  ref: T;
+  constructor(ref: T) {
+    this.ref = ref;
+  }
+  deref(): T {
+    return this.ref;
+  }
+  readonly [Symbol.toStringTag]: "WeakRef";
+}

package/src/constants.ts

@@ -0,0 +1,6 @@
+/** @internal */
+export const NS_ROOT = "_$pg";
+export const VERSION = "0.0.1";
+export const SYM_CLEANUP = Symbol(`${NS_ROOT}_cleanup`);
+export const SYM_INTERNAL = Symbol(`${NS_ROOT}_internal`);
+export const INIT_CALLBACK = `${NS_ROOT}_init_cb`;

package/src/cross-realm-object.ts

@@ -0,0 +1,117 @@
+import type { WrappedMessage } from "./message-wrapper";
+import { wrap } from "./message-wrapper";
+import { ObjectSimulator } from "./object-simulator";
+import type { Asynced } from "./object-walker";
+import { timeoutPromise } from "./promises/timed";
+import { receiveCalls } from "./rpc";
+import type { InitTicket } from "./tickets";
+import { INIT_TICKET } from "./tickets";
+import type { TunnelConfig } from "./tunnel";
+import { Tunnel } from "./tunnel";
+
+const INIT_MESSAGE: WrappedMessage<InitTicket> = wrap(INIT_TICKET);
+
+/**
+ * Representation of an object on the other side of an iframe/window divide
+ * between JS runtimes.
+ *
+ * @remarks
+ * At first, xrobject simply returned the proxy to the remote object and did
+ * not expose any of the underlying event handling. However, there was no way
+ * for a consumer to handle the case where the remote iframe reloaded, which
+ * would invalidate all of the simulated objects.
+ *
+ * This new manager object exposes the {@link Tunnel} object so that consumers
+ * can subscribe to the "api" event.
+ * @alpha
+ */
+export interface CrossRealmObject<ExpectedApi> {
+  /**
+   * The event emitter that transmits RPC events between remotes. Can be used to
+   * listen to "api" events, which re-emit the initial remote API after an
+   * unexpected reload. Can also be used to manually destroy the xrobject.
+   * @internal
+   */
+  tunnel: Tunnel;
+  /**
+   * Accessor for the simulated object. Putting the object behind an accessor is
+   * a way (we hope) to subtly discourage hanging on to a reference to the
+   * object, which will invalidate without the holder of the reference knowing.
+   * @internal
+   */
+  getRemoteApi(): Asynced<ExpectedApi>;
+}
+
+async function setupApiExchange<T>(
+  tunnel: Tunnel,
+  apiToSend: unknown
+): Promise<CrossRealmObject<T>> {
+  let done = false;
+  let remoteApi!: Asynced<T>;
+  const xrObject: CrossRealmObject<T> = {
+    tunnel,
+    getRemoteApi(): Asynced<T> {
+      return remoteApi;
+    },
+  };
+  return timeoutPromise(
+    "Initial API exchange",
+    new Promise((resolve, reject) => {
+      const simulator = ObjectSimulator.create(tunnel, FinalizationRegistry);
+
+      const sendApi = simulator.makeSender(INIT_MESSAGE);
+      const apiCallback = (api: Asynced<T>) => {
+        remoteApi = api;
+        if (!done) {
+          done = true;
+          resolve(xrObject);
+        }
+      };
+      tunnel.on("api", apiCallback);
+
+      const unsubscribe = receiveCalls(
+        (api: Asynced<T>) => tunnel.emitLocal("api", api),
+        INIT_TICKET,
+        new WeakRef(simulator.subject)
+      );
+      const destroy = (e: Error) => {
+        unsubscribe();
+        if (!done) {
+          done = true;
+          reject(e);
+        }
+      };
+      tunnel.on("destroyed", destroy);
+      tunnel.on("connected", () =>
+        (sendApi as Function)(apiToSend).catch(destroy)
+      );
+    }),
+    tunnel.config.timeout,
+    () => tunnel.destroy()
+  );
+}
+
+/**
+ * Create a CrossRealmObject in an iframe, simulating objects from the parent window.
+ * @alpha
+ */
+export async function connectParentWindow<Expected>(
+  tunnelOptions: Partial<TunnelConfig>,
+  apiToSend: unknown
+): Promise<CrossRealmObject<Expected>> {
+  const tunnel = Tunnel.toParent(window.parent, tunnelOptions);
+  return setupApiExchange<Expected>(tunnel, apiToSend);
+}
+
+/**
+ * Create a CrossRealmObject simulating objects from the provided iframe runtime.
+ * @alpha
+ */
+export async function connectIframe<Expected>(
+  frame: HTMLIFrameElement,
+  tunnelOptions: Partial<TunnelConfig>,
+  apiToSend: unknown
+): Promise<CrossRealmObject<Expected>> {
+  const tunnel = Tunnel.toIframe(frame, tunnelOptions);
+  return setupApiExchange<Expected>(tunnel, apiToSend);
+}

package/src/debuglog.ts

@@ -1,4 +1,4 @@
-/*
+/**
 Copyright 2022 Adobe. All rights reserved.
 This file is licensed to you under the Apache License, Version 2.0 (the "License");
 you may not use this file except in compliance with the License. You may obtain a copy

package/src/index.ts

@@ -19,5 +19,8 @@ export * from "./debug-emitter";
 export * from "./debuglog";
 export * from "./emitter";
 export * from "./namespace-proxy";
-export * from "./timeout-promise";
 export * from "./types";
+export * from "./cross-realm-object";
+export * from "./promises";
+export * from "./tunnel";
+export type { Asynced } from "./object-walker";

package/src/message-wrapper.ts

@@ -0,0 +1,35 @@
+import { NS_ROOT } from "./constants";
+import { isPlainObject } from "./value-assertions";
+
+/** @internal */
+export type WrappedMessage<Message extends object> = { [NS_ROOT]: Message };
+
+export function wrap<Message extends object = object>(
+  message: Message
+): WrappedMessage<Message> {
+  return { [NS_ROOT]: message };
+}
+
+export function unwrap<Message extends object>(
+  wrappedMessage: WrappedMessage<Message>
+): Message {
+  return wrappedMessage[NS_ROOT];
+}
+
+export function isWrapped<Message extends object = object>(
+  item: unknown
+): item is WrappedMessage<Message> {
+  if (!isPlainObject(item)) {
+    return false;
+  }
+  const keys = Object.keys(item);
+  const hasRoot = keys.includes(NS_ROOT);
+  if (hasRoot && keys.length != 1) {
+    console.error(
+      `malformed tunnel message, should have one prop "${NS_ROOT}" at root`,
+      item
+    );
+    return false;
+  }
+  return hasRoot;
+}

package/src/object-simulator.test.ts

@@ -0,0 +1,135 @@
+import { NS_ROOT } from "./constants";
+import { EventEmitter } from "eventemitter3";
+import { ObjectSimulator } from "./object-simulator";
+import { FakeFinalizationRegistry } from "./__mocks__/mock-finalization-registry";
+import { wait } from "./promises/wait";
+import { DefMessage } from "./object-walker";
+
+describe("function simulator exchanges functions and tickets", () => {
+  let objectSimulator: ObjectSimulator;
+  beforeEach(() => {
+    jest.spyOn(console, "error").mockImplementation(() => {});
+    const emitter = new EventEmitter();
+    objectSimulator = ObjectSimulator.create(emitter, FakeFinalizationRegistry);
+  });
+  it("turns an object with functions into an object with tickets", async () => {
+    const invokeIt = (blorp: CallableFunction) => blorp();
+    const gnorf = {
+      slorf: {
+        blorf: (x: number) => x + 1,
+      },
+    };
+    const toBeTicketed = {
+      list: [
+        {
+          what: 8,
+          doa: invokeIt,
+        },
+      ],
+      gnorf,
+      harbl: 3,
+    };
+    const ticketed = objectSimulator.simulate(toBeTicketed);
+    expect(ticketed).toMatchInlineSnapshot(`
+      {
+        "gnorf": {
+          "slorf": {
+            "blorf": {
+              "_\$pg": {
+                "fnId": "blorf_2",
+              },
+            },
+          },
+        },
+        "harbl": 3,
+        "list": [
+          {
+            "doa": {
+              "_\$pg": {
+                "fnId": "invokeIt_1",
+              },
+            },
+            "what": 8,
+          },
+        ],
+      }
+    `);
+    const unticketed = objectSimulator.materialize(ticketed);
+    expect(unticketed).toMatchInlineSnapshot(`
+      {
+        "gnorf": {
+          "slorf": {
+            "blorf": [Function],
+          },
+        },
+        "harbl": 3,
+        "list": [
+          {
+            "doa": [Function],
+            "what": 8,
+          },
+        ],
+      }
+    `);
+    const remoteInvokeIt = unticketed.list[0].doa;
+    await expect(remoteInvokeIt(() => "oh noes")).resolves.toBe("oh noes");
+    await expect(unticketed.gnorf.slorf.blorf(9)).resolves.toBe(10);
+  });
+  it("dies when an object has an unrecognizable value", () => {
+    expect(() =>
+      objectSimulator.simulate({
+        lol: Symbol("lol"),
+      })
+    ).toThrowError("Bad value");
+  });
+  it("passes through tickets when unexpected", () => {
+    const hasTicket = {
+      [NS_ROOT]: {
+        some: "ticket",
+      },
+    };
+    const doTicket = () => objectSimulator.simulate({ hasTicket });
+    expect(doTicket).not.toThrowError();
+    expect(doTicket()).toMatchObject({ hasTicket });
+  });
+  it("strips unserializable props, but throws on unserializable values", () => {
+    expect(() =>
+      objectSimulator.simulate({
+        lol: Symbol("lol"),
+      })
+    ).toThrowError("Bad value");
+    expect(() =>
+      objectSimulator.simulate({
+        [Symbol("lol")]: "lol",
+      })
+    ).not.toThrowError();
+  });
+  it("can handle root functions", async () => {
+    let called = false;
+    const ticketedLoneFn = objectSimulator.simulate(() => {
+      called = true;
+    });
+    expect(ticketedLoneFn).toMatchInlineSnapshot(`
+      {
+        "_$pg": {
+          "fnId": "<anonymous>_1",
+        },
+      }
+    `);
+    const loneFn = objectSimulator.materialize(ticketedLoneFn);
+    await expect(loneFn()).resolves.not.toThrowError();
+    expect(called).toBe(true);
+  });
+  it("notifies remote when FinalizationRegistry calls cleanup handler", async () => {
+    const willBeGCed = objectSimulator.simulate(() => {}) as DefMessage;
+    objectSimulator.materialize(willBeGCed);
+    const { subject } = objectSimulator;
+    const fakeTicket = willBeGCed[NS_ROOT];
+    const gcHandler = jest.fn();
+    subject.onOutOfScope(fakeTicket, gcHandler);
+    const lastCleanupHandler = FakeFinalizationRegistry.mock.cleanupHandler;
+    lastCleanupHandler(fakeTicket.fnId);
+    await wait(100);
+    expect(gcHandler).toHaveBeenCalled();
+  });
+});

package/src/object-simulator.ts

@@ -0,0 +1,136 @@
+import { isWrapped, unwrap, wrap } from "./message-wrapper";
+import EventEmitter from "eventemitter3";
+import type { DefMessage, Materialized, Simulated } from "./object-walker";
+import { NOT_TRANSFORMED, transformRecursive } from "./object-walker";
+import { makeCallSender, receiveCalls } from "./rpc";
+import type { Simulator } from "./remote-subject";
+import { RemoteSubject } from "./remote-subject";
+import type { DefTicket } from "./tickets";
+import { hasProp } from "./value-assertions";
+
+function isDefMessage(value: unknown): value is DefMessage {
+  return isWrapped(value) && hasProp(unwrap(value), "fnId");
+}
+
+const bindAll = <T>(inst: T, methods: (keyof T)[]) => {
+  for (const methodName of methods) {
+    const method = inst[methodName];
+    if (typeof method === "function") {
+      inst[methodName] = method.bind(inst);
+    }
+  }
+};
+
+interface CleanupNotifier {
+  // #region Public Methods
+
+  register(obj: any, heldValue: string, ref?: any): void;
+  unregister(ref: any): void;
+
+  // #endregion Public Methods
+}
+
+interface CleanupNotifierConstructor {
+  new (callback: (heldValue: unknown) => void): CleanupNotifier;
+}
+
+export class ObjectSimulator implements Simulator {
+  // #region Properties
+
+  private cleanupNotifier: CleanupNotifier;
+  private fnCounter = 0;
+  private receiverTicketCache: WeakMap<CallableFunction, DefTicket> =
+    new WeakMap();
+  private senderCache: WeakMap<DefTicket, CallableFunction> = new WeakMap();
+
+  subject: RemoteSubject;
+
+  // #endregion Properties
+
+  // #region Constructors
+
+  constructor(subject: RemoteSubject, cleanupNotifier: CleanupNotifier) {
+    this.cleanupNotifier = cleanupNotifier;
+    this.subject = subject;
+
+    bindAll(this, ["makeSender", "makeReceiver", "simulate", "materialize"]);
+  }
+
+  // #endregion Constructors
+
+  // #region Public Static Methods
+
+  static create(
+    emitter: EventEmitter,
+    Cleanup: CleanupNotifierConstructor
+  ): ObjectSimulator {
+    let simulator: Simulator;
+    // proxy simulator, so as not to have cyclic dependency
+    const simulatorInterface: Simulator = {
+      simulate: (x) => simulator.simulate(x),
+      materialize: (x) => simulator.materialize(x),
+    };
+
+    const subject = new RemoteSubject(emitter, simulatorInterface);
+
+    const cleanupNotifier = new Cleanup((fnId: string) => {
+      return subject.notifyCleanup({ fnId });
+    });
+
+    simulator = new ObjectSimulator(subject, cleanupNotifier);
+
+    return simulator as ObjectSimulator;
+  }
+
+  // #endregion Public Static Methods
+
+  // #region Public Methods
+
+  makeReceiver(fn: CallableFunction) {
+    if (typeof fn !== "function") {
+      return NOT_TRANSFORMED;
+    }
+    let fnTicket = this.receiverTicketCache.get(fn);
+    if (!fnTicket) {
+      fnTicket = {
+        fnId: `${fn.name || "<anonymous>"}_${++this.fnCounter}`,
+      };
+      const cleanup = receiveCalls(fn, fnTicket, new WeakRef(this.subject));
+      this.subject.onOutOfScope(fnTicket, cleanup);
+      this.receiverTicketCache.set(fn, fnTicket);
+    }
+    return wrap(fnTicket);
+  }
+
+  makeSender(message: unknown) {
+    if (!isDefMessage(message)) {
+      return NOT_TRANSFORMED;
+    }
+    const ticket = unwrap(message);
+    /* istanbul ignore else: preopt */
+    if (!this.senderCache.has(ticket)) {
+      const sender = makeCallSender(ticket, new WeakRef(this.subject));
+      this.cleanupNotifier.register(sender, ticket.fnId, sender);
+      this.senderCache.set(ticket, sender);
+      return sender;
+    } else {
+      return this.senderCache.get(ticket) as CallableFunction;
+    }
+  }
+
+  materialize<T>(simulated: T) {
+    return transformRecursive<CallableFunction>(
+      this.makeSender,
+      simulated
+    ) as Materialized<T>;
+  }
+
+  simulate<T>(localObject: T) {
+    return transformRecursive<DefMessage>(
+      this.makeReceiver,
+      localObject
+    ) as Simulated<T>;
+  }
+
+  // #endregion Public Methods
+}