@adobe/uix-core 0.6.5-1 → 0.7.0

package/src/object-walker.ts

@@ -0,0 +1,92 @@
+import type { WrappedMessage } from "./message-wrapper";
+import type { DefTicket } from "./tickets";
+import {
+  Primitive,
+  isPlainObject,
+  isPrimitive,
+  isIterable,
+} from "./value-assertions";
+
+/**
+ * Extract keys of T whose values are assignable to U.
+ * @internal
+ */
+type ExtractKeys<T, U> = {
+  [P in keyof T]: T[P] extends U ? P : never;
+}[keyof T];
+
+/**
+ * Convert all functions anywhere in T to async functions.
+ * @internal
+ */
+export type Asynced<T> = T extends (...args: infer A) => infer R
+  ? (...args: A) => Promise<R>
+  : {
+      [K in ExtractKeys<
+        T,
+        Function | object | any[] | [any, any]
+      >]: T[K] extends (...args: any) => PromiseLike<any>
+        ? T[K]
+        : T[K] extends [infer U, infer V]
+        ? [Asynced<U>, Asynced<V>]
+        : T[K] extends (infer U)[]
+        ? Asynced<U>[]
+        : T[K] extends (...args: infer A) => infer R
+        ? (...args: A) => Promise<R>
+        : Asynced<T[K]>;
+    };
+
+/** @internal */
+export type Materialized<T> = T extends Primitive
+  ? T
+  : // : T extends (...args: infer A) => infer R
+  // ? (...args: A) => Promise<R>
+  T extends Simulated<infer U>
+  ? Asynced<U>
+  : Asynced<T>;
+
+/** @internal */
+export type DefMessage = WrappedMessage<DefTicket>;
+
+/** @internal */
+export type Simulated<T> = {
+  [K in ExtractKeys<T, Function | object>]: T[K] extends (
+    ...args: unknown[]
+  ) => unknown
+    ? DefMessage
+    : Simulated<T[K]>;
+};
+
+export const NOT_TRANSFORMED = Symbol.for("NOT_TRANSFORMED");
+
+export function transformRecursive<To>(
+  transform: (source: unknown) => To | typeof NOT_TRANSFORMED,
+  value: unknown
+): To {
+  if (isPrimitive(value)) {
+    return value as To;
+  }
+  const transformed = transform(value);
+  if (transformed !== NOT_TRANSFORMED) {
+    return transformed;
+  }
+  if (isIterable(value)) {
+    const outArray = [];
+    for (const item of value) {
+      outArray.push(transformRecursive(transform, item));
+    }
+    return outArray as To;
+  }
+  if (isPlainObject(value)) {
+    const outObj = {};
+    for (const key of Reflect.ownKeys(value)) {
+      Reflect.set(
+        outObj,
+        key,
+        transformRecursive(transform, Reflect.get(value, key))
+      );
+    }
+    return outObj as To;
+  }
+  throw new Error(`Bad value! ${Object.prototype.toString.call(value)}`);
+}

package/src/promises/index.ts

@@ -0,0 +1,2 @@
+export * from "./timed";
+export * from "./wait";

package/src/promises/promise-wrappers.test.ts

@@ -0,0 +1,63 @@
+import { wait } from "./wait";
+import { timeoutPromise } from "./timed";
+
+describe("promise wrappers", () => {
+  const DONE = {};
+  const finish = jest.fn().mockReturnValue(DONE);
+  beforeEach(() => {
+    finish.mockClear();
+    jest.useFakeTimers();
+  });
+  afterEach(() => {
+    jest.useRealTimers();
+  });
+  describe("wait(ms)", () => {
+    it("returns a promise that resolves after n ms", async () => {
+      const sayDone = wait(500).then(finish);
+      jest.advanceTimersByTime(300);
+      expect(finish).not.toHaveBeenCalled();
+      jest.advanceTimersByTime(300);
+      await expect(sayDone).resolves.toBe(DONE);
+      expect(finish).toHaveBeenCalled();
+    });
+  });
+  describe("timeoutPromise(promise, ms, cleanup) returns a promise", () => {
+    const cleanup = jest.fn();
+    beforeEach(() => cleanup.mockReset());
+    it("that resolves with the original promise within ms", async () => {
+      const makesIt = timeoutPromise(
+        "should not fail",
+        wait(50).then(finish),
+        100,
+        cleanup
+      );
+      jest.advanceTimersByTime(75);
+      await expect(makesIt).resolves.toBe(DONE);
+      expect(cleanup).not.toHaveBeenCalled();
+    });
+    it("that rejects if the original promise did not resolve within ms", async () => {
+      const makesIt = timeoutPromise(
+        "took too long",
+        wait(200).then(finish),
+        100,
+        cleanup
+      );
+      jest.advanceTimersByTime(200);
+      await expect(makesIt).rejects.toThrowError(
+        "took too long timed out after 100ms"
+      );
+      expect(cleanup).toHaveBeenCalled();
+    });
+    it("runs the cleanup function if the promise rejects before timeout", async () => {
+      const ngmi = timeoutPromise(
+        "not a chance",
+        Promise.reject(new Error("loool")),
+        100,
+        cleanup
+      );
+      jest.advanceTimersByTime(50);
+      await expect(ngmi).rejects.toThrowError("loool");
+      expect(cleanup).toHaveBeenCalled();
+    });
+  });
+});

package/src/promises/timed.ts

@@ -0,0 +1,41 @@
+/**
+ * Add a timeout to a Promise. The returned Promise will resolve to the value of
+ * the original Promise, but if it doesn't resolve within the timeout interval,
+ * it will reject with a timeout error.
+ *
+ * @param description - Job description to be used in the timeout error
+ * @param promise - Original promise to set a timeout for
+ * @param timeoutMs - Time to wait (ms) before rejecting
+ * @param onReject - Run when promise times out to clean up handles
+ * @returns - Promise that rejects with informative error after X milliseconds have passed
+ *
+ * @internal
+ */
+export function timeoutPromise<T>(
+  description: string,
+  promise: Promise<T>,
+  ms: number,
+  onReject: (e: Error) => void
+): Promise<T> {
+  return new Promise((resolve, reject) => {
+    const cleanupAndReject = async (e: Error) => {
+      try {
+        await onReject(e);
+      } finally {
+        reject(e);
+      }
+    };
+    const timeout = setTimeout(() => {
+      cleanupAndReject(new Error(`${description} timed out after ${ms}ms`));
+    }, ms);
+    promise
+      .then((result) => {
+        clearTimeout(timeout);
+        resolve(result);
+      })
+      .catch((e) => {
+        clearTimeout(timeout);
+        cleanupAndReject(e);
+      });
+  });
+}

package/src/promises/wait.ts

@@ -0,0 +1,10 @@
+/**
+ * Promise that resolves after a specific time
+ *
+ * @internal
+ */
+export function wait(ms: number) {
+  return new Promise((resolve) => {
+    setTimeout(resolve, ms);
+  });
+}

package/src/remote-subject.ts

@@ -0,0 +1,185 @@
+import type {
+  CallArgsTicket,
+  CallTicket,
+  DefTicket,
+  RejectTicket,
+  ResolveTicket,
+  RespondTicket,
+  CleanupTicket,
+} from "./tickets";
+import type { Materialized, Simulated } from "./object-walker";
+import EventEmitter from "eventemitter3";
+
+type EvTypeDef = `${string}_f`;
+type EvTypeGC = `${string}_g`;
+type EvTypeCall = `${string}_c`;
+type EvTypeRespond = `${string}_r`;
+type EvTypeDestroyed = "destroyed";
+type EvTypeConnected = "connected";
+type EvTypeError = "error";
+
+type RemoteDefEvent = {
+  type: EvTypeDef;
+  payload: DefTicket;
+};
+type RemoteCallEvent = {
+  type: EvTypeCall;
+  payload: CallArgsTicket;
+};
+type RemoteResolveEvent = {
+  type: EvTypeRespond;
+  payload: ResolveTicket;
+};
+type RemoteRejectEvent = {
+  type: EvTypeRespond;
+  payload: RejectTicket;
+};
+type RemoteCleanupEvent = {
+  type: EvTypeGC;
+  payload: CleanupTicket;
+};
+type RemoteReconnectedEvent = {
+  type: EvTypeConnected;
+  payload: void;
+};
+type RemoteDestroyedEvent = {
+  type: EvTypeDestroyed;
+  payload: void;
+};
+type RemoteErrorEvent = {
+  type: EvTypeError;
+  payload: Error;
+};
+
+export type RemoteEvents =
+  | RemoteDefEvent
+  | RemoteCallEvent
+  | RemoteResolveEvent
+  | RemoteRejectEvent
+  | RemoteCleanupEvent
+  | RemoteReconnectedEvent
+  | RemoteDestroyedEvent
+  | RemoteErrorEvent;
+
+type Simulates = <T>(localObject: T) => Simulated<T>;
+type Materializes = <T>(simulatedObject: T) => Materialized<T>;
+
+export interface Simulator {
+  // #region Properties
+
+  materialize: Materializes;
+  simulate: Simulates;
+
+  // #endregion Properties
+}
+
+type Mapper = Simulates | Materializes;
+
+export class RemoteSubject {
+  // #region Properties
+
+  private emitter: EventEmitter;
+  private simulator: Simulator;
+
+  // #endregion Properties
+
+  // #region Constructors
+
+  constructor(emitter: EventEmitter, simulator: Simulator) {
+    this.emitter = emitter;
+    this.simulator = simulator;
+  }
+
+  // #endregion Constructors
+
+  // #region Public Methods
+
+  notifyCleanup(ticket: DefTicket) {
+    return this.emitter.emit(`${ticket.fnId}_g`, {});
+  }
+
+  notifyConnect() {
+    return this.emitter.emit("connected");
+  }
+
+  notifyDestroy() {
+    return this.emitter.emit("destroyed");
+  }
+
+  onCall(ticket: DefTicket, handler: (ticket: CallArgsTicket) => void) {
+    return this.subscribe(`${ticket.fnId}_c`, (ticket: CallArgsTicket) =>
+      handler(this.processCallTicket(ticket, this.simulator.materialize))
+    );
+  }
+
+  onConnected(handler: () => void) {
+    return this.subscribe("connected", handler);
+  }
+
+  onDestroyed(handler: () => void) {
+    return this.subscribe("destroyed", handler);
+  }
+
+  onOutOfScope(ticket: DefTicket, handler: () => void) {
+    return this.subscribeOnce(`${ticket.fnId}_g`, handler);
+  }
+
+  onRespond(ticket: CallTicket, handler: (ticket: RespondTicket) => void) {
+    const fnAndCall = `${ticket.fnId}${ticket.callId}`;
+    return this.subscribeOnce(`${fnAndCall}_r`, (ticket: RespondTicket) =>
+      handler(this.processResponseTicket(ticket, this.simulator.materialize))
+    );
+  }
+
+  respond(ticket: RespondTicket) {
+    const fnAndCall = `${ticket.fnId}${ticket.callId}`;
+    return this.emitter.emit(
+      `${fnAndCall}_r`,
+      this.processResponseTicket(ticket, this.simulator.simulate)
+    );
+  }
+
+  send(ticket: CallArgsTicket) {
+    return this.emitter.emit(
+      `${ticket.fnId}_c`,
+      this.processCallTicket(ticket, this.simulator.simulate)
+    );
+  }
+
+  // #endregion Public Methods
+
+  // #region Private Methods
+
+  private processCallTicket(
+    { args, ...ticket }: CallArgsTicket,
+    mapper: Mapper
+  ) {
+    return {
+      ...ticket,
+      args: args.map(mapper),
+    };
+  }
+
+  private processResponseTicket(ticket: RespondTicket, mapper: Mapper) {
+    return ticket.status === "resolve"
+      ? { ...ticket, value: mapper(ticket.value) }
+      : ticket;
+  }
+
+  private subscribe(type: string, handler: (arg: unknown) => void) {
+    this.emitter.on(type, handler);
+    return () => {
+      this.emitter.off(type, handler);
+    };
+  }
+
+  private subscribeOnce(type: string, handler: (arg: unknown) => void) {
+    const once = (arg: unknown) => {
+      this.emitter.off(type, once);
+      handler(arg);
+    };
+    return this.subscribe(type, once);
+  }
+
+  // #endregion Private Methods
+}

package/src/rpc/call-receiver.test.ts

@@ -0,0 +1,90 @@
+import { wait } from "../promises/wait";
+import EventEmitter from "eventemitter3";
+import { RemoteSubject } from "../remote-subject";
+import { receiveCalls } from "./call-receiver";
+import { FakeFinalizationRegistry } from "../__mocks__/mock-finalization-registry";
+import { FakeWeakRef } from "../__mocks__/mock-weak-ref";
+import { ObjectSimulator } from "../object-simulator";
+
+describe("a listener for remote calls to a local function", () => {
+  const MURMURS = ["baa", "moo", "ahoy"];
+  const FARAWAY_SOUND = "(distant) riiiiicolaaaa";
+  const ECHOES = "(echoes) riiiiicolaaaa";
+  const village = jest.fn().mockReturnValue(MURMURS);
+  const villageId = "village_1";
+  const villageTicket = { fnId: villageId };
+  let emitter: EventEmitter;
+  let subject: RemoteSubject;
+  let simulator: ObjectSimulator;
+  beforeEach(() => {
+    village.mockClear();
+    jest.spyOn(console, "error").mockImplementation(() => {});
+    emitter = new EventEmitter();
+    simulator = ObjectSimulator.create(emitter, FakeFinalizationRegistry);
+    subject = simulator.subject;
+    receiveCalls(village, villageTicket, new FakeWeakRef(subject));
+  });
+  it("turns fn_call events into calls to local function", async () => {
+    const responder = jest.fn();
+    const call4Ticket = {
+      ...villageTicket,
+      callId: 4,
+    };
+    subject.onRespond(call4Ticket, responder);
+    subject.send({
+      ...call4Ticket,
+      args: [FARAWAY_SOUND, ECHOES],
+    });
+    await expect(village).toHaveBeenCalledWith(FARAWAY_SOUND, ECHOES);
+    expect(responder).toHaveBeenCalledWith(
+      expect.objectContaining({
+        ...call4Ticket,
+        status: "resolve",
+        value: expect.arrayContaining(["baa", "moo", "ahoy"]),
+      })
+    );
+  });
+  it("sends events notifying of rejections", async () => {
+    const responder = jest.fn();
+    const call500Ticket = {
+      ...villageTicket,
+      callId: 500,
+    };
+    subject.onRespond(call500Ticket, responder);
+    village.mockRejectedValueOnce(new Error("what is that infernal noise"));
+    subject.send({
+      ...call500Ticket,
+      args: [FARAWAY_SOUND],
+    });
+    await expect(village).toHaveBeenCalledWith(FARAWAY_SOUND);
+    await wait(100);
+    expect(responder).toHaveBeenCalledWith(
+      expect.objectContaining({
+        ...call500Ticket,
+        status: "reject",
+        error: expect.any(Error),
+      })
+    );
+  });
+  it.skip("unsubscribes itself when receiving a cleanup event", async () => {
+    const responder = jest.fn();
+    const call76Ticket = {
+      ...villageTicket,
+      callId: 76,
+    };
+    subject.onRespond(call76Ticket, responder);
+    village.mockRejectedValueOnce(new Error("what is that infernal noise"));
+
+    subject.notifyCleanup(call76Ticket);
+
+    await wait(100);
+
+    subject.send({
+      ...call76Ticket,
+      args: [FARAWAY_SOUND],
+    });
+
+    await wait(100);
+    expect(responder).not.toHaveBeenCalled();
+  });
+});

package/src/rpc/call-receiver.ts

@@ -0,0 +1,29 @@
+import type { CallArgsTicket, DefTicket } from "../tickets";
+import type { RemoteSubject } from "../remote-subject";
+
+export function receiveCalls(
+  fn: CallableFunction,
+  ticket: DefTicket,
+  remote: WeakRef<RemoteSubject>
+) {
+  const responder = async ({ fnId, callId, args }: CallArgsTicket) => {
+    /* istanbul ignore next: should never happen */
+    try {
+      const value = await fn(...args);
+      remote.deref().respond({
+        fnId,
+        callId,
+        value,
+        status: "resolve",
+      });
+    } catch (error) {
+      remote.deref().respond({
+        fnId,
+        callId,
+        status: "reject",
+        error,
+      });
+    }
+  };
+  return remote.deref().onCall(ticket, responder);
+}

package/src/rpc/call-sender.test.ts

@@ -0,0 +1,73 @@
+import { RemoteSubject } from "../remote-subject";
+import { makeCallSender } from "./call-sender";
+import { ObjectSimulator } from "../object-simulator";
+import { FakeFinalizationRegistry } from "../__mocks__/mock-finalization-registry";
+import { FakeWeakRef } from "../__mocks__/mock-weak-ref";
+import { wait } from "../promises/wait";
+import EventEmitter from "eventemitter3";
+
+describe("an proxy representing a function in the other realm", () => {
+  const SOUND = "RIIIICOLAAAA";
+  const FARAWAY_SOUND = "(distant) riiiiicolaaaa";
+  const alpenhorn = jest.fn().mockReturnValue(SOUND);
+  const alpenhornId = "alpenhorn_1";
+  let simulator: ObjectSimulator;
+  let emitter;
+  let subject: RemoteSubject;
+  let remoteAlpenhorn: ((...args: any[]) => Promise<unknown>) | (() => any);
+  beforeEach(() => {
+    alpenhorn.mockClear();
+    emitter = new EventEmitter();
+    simulator = ObjectSimulator.create(emitter, FakeFinalizationRegistry);
+    subject = simulator.subject;
+    remoteAlpenhorn = makeCallSender(
+      { fnId: alpenhornId },
+      new FakeWeakRef(subject)
+    );
+    jest.spyOn(console, "error").mockImplementation(() => {});
+  });
+  it("resolves through the emitter", async () => {
+    subject.onCall(
+      {
+        fnId: alpenhornId,
+      },
+      (callTicket) => {
+        const { callId, fnId } = callTicket;
+        subject.respond({
+          callId,
+          fnId,
+          status: "resolve",
+          value: FARAWAY_SOUND,
+        });
+      }
+    );
+    await expect(remoteAlpenhorn()).resolves.toBe(FARAWAY_SOUND);
+  });
+  it("rejects through the emitter", async () => {
+    subject.onCall({ fnId: alpenhornId }, (callTicket) => {
+      const { callId, fnId } = callTicket;
+      subject.respond({
+        callId,
+        fnId,
+        status: "reject",
+        error: new Error("bonk"),
+      });
+    });
+    await expect(remoteAlpenhorn()).rejects.toThrowError("bonk");
+  });
+  it("destroys itself on disconnect", async () => {
+    subject.onCall({ fnId: alpenhornId }, async (callTicket) => {
+      const { callId, fnId } = callTicket;
+      subject.notifyDestroy();
+      await wait(100);
+      subject.respond({
+        callId,
+        fnId,
+        status: "reject",
+        error: new Error("bonk"),
+      });
+    });
+    await expect(remoteAlpenhorn()).rejects.toThrowError("destroyed");
+    await expect(remoteAlpenhorn()).rejects.toThrowError("destroyed");
+  });
+});

package/src/rpc/call-sender.ts

@@ -0,0 +1,72 @@
+import type { CallArgsTicket, DefTicket } from "../tickets";
+import type { RemoteSubject } from "../remote-subject";
+
+type RejectionPool = Set<(e: Error) => unknown>;
+
+class DisconnectionError extends Error {
+  constructor() {
+    super(
+      "Function belongs to a simulated remote object which has been disconnected! The tunnel may have been destroyed by page navigation or reload."
+    );
+  }
+}
+
+function dispatch(
+  subject: RemoteSubject,
+  callTicket: CallArgsTicket,
+  rejectionPool: RejectionPool,
+  resolve: { (value: unknown): void; (arg0: any): void },
+  reject: { (reason?: string): void; (arg0: any): void }
+) {
+  subject.onRespond(callTicket, (responseTicket) => {
+    rejectionPool.delete(reject);
+    if (responseTicket.status === "resolve") {
+      resolve(responseTicket.value);
+    } else {
+      reject(responseTicket.error);
+    }
+  });
+  subject.send(callTicket);
+}
+
+export function makeCallSender(
+  { fnId }: DefTicket,
+  subjectRef: WeakRef<RemoteSubject>
+) {
+  let callCounter = 0;
+  const rejectionPool: RejectionPool = new Set();
+  let sender = function (...args: unknown[]) {
+    return new Promise((resolve, reject) => {
+      rejectionPool.add(reject);
+      const callId = ++callCounter;
+      const callTicket: CallArgsTicket = {
+        fnId,
+        callId,
+        args,
+      };
+      return dispatch(
+        subjectRef.deref(),
+        callTicket,
+        rejectionPool,
+        resolve,
+        reject
+      );
+    });
+  };
+  const destroy = () => {
+    subjectRef = null;
+    sender = () => {
+      throw new DisconnectionError();
+    };
+    for (const reject of rejectionPool) {
+      reject(new DisconnectionError());
+    }
+    rejectionPool.clear();
+  };
+  subjectRef.deref().onDestroyed(destroy);
+  const facade = async function (...args: unknown[]) {
+    return sender(...args);
+  };
+  Object.defineProperty(facade, "name", { value: fnId });
+  return facade;
+}

package/src/rpc/index.ts

@@ -0,0 +1,2 @@
+export * from "./call-receiver";
+export * from "./call-sender";