corpc

coRPC: Cross-Origin Remote Procedure Call

A package for promisifying cross-origin messaging (e.g. window.postMessage).

Install

npm install corpc

yarn add corpc

pnpm add corpc

Usage

import { defineProcedures } from "corpc";
import type { RemoteProcedures } from "./remote-procedures";

const localProcedures = defineProcedures({
  procedures,
  postMessage,
  listener,
  addMessageEventListener,
  removeMessageEventListener,
  timeout,
  logger,
}): {
  createRPC,
  cleanUp,
  ...procedures
};

export type LocalProcedures = typeof localProcedures;

const remoteRPC = procedures.createRPC<RemoteProcedures>();

Parameter:

Property	Type	Default	Description
procedures	{ [procedureName: string]: (...args: unknown) => any }	undefined	The local functions to be called remotely.
postMessage	(message: unknown) => void	(message: unknown) => { window.parent.postMessage(message, "*"); }	Define the function that sends messages to the other origin. message is what is sent by coRPC and needs to be received by the other origin via the listener prop.
listener	(handler: (message: unknown) => void) => Listener	(handler) => (event: MessageEvent) => { handler(event.data); }	Define the listener handler. This is used in addMessageEventListener and removeMessageEventListener. handler expects the message argument from postMessage.
addMessageEventListener	(listener: Listener) => void	(listener: (event: MessageEvent) => void) => { window.addEventListener("message", listener); }	The local "add message event listener" implementation.
removeMessageEventListener	(listener: Listener) => void	(listener: (event: MessageEvent) => void) => { window.removeEventListener("message", listener); }	The local "remove message event listener" implementation.
timeout	number	5000	RPC timeout. Function will throw if it takes longer than the timeout.
logger	(...args: any) => void	undefined	Log function for debug logging.

Returns:

Property	Type	Description
createRPC	<RemoteProcedures extends Procedures>() => RemoteProcedureProxy<RemoteProcedures>	Creates the proxy for calling remote procedures.
cleanUp	() => void	Remove message event listener.

Examples

iFrame example

// parent.ts

import { defineProcedures } from "corpc";
import type { IFrameProcedures } from "./iframe";

const iframe: HTMLIFrameElement = new HTMLIFrameElement();

const parentProcedures = defineProcedures({
  procedures: {
    getDataFromParent: (id: string) => {
      return "parent data";
    },
  },
  postMessage: (message) => iframe.contentWindow?.postMessage(message, "*"),
});

export type ParentProcedures = typeof parentProcedures;

const iframeRPC = parentProcedures.createRPC<IFrameProcedures>();
/**
 * ^? const iframeRPC: {
 *      getDataFromIFrame: (id: number) => Promise<string>;
 *    }
 */

const result = await iframeRPC.getDataFromIFrame(10);
// ^? const result: string

// iframe.ts

import { defineProcedures } from "corpc";
import type { ParentProcedures } from "./parent";

const iframeProcedures = defineProcedures({
  procedures: {
    getDataFromIFrame: (id: number) => {
      return "iframe data";
    },
  },
  postMessage: (message: any) => window.top?.postMessage(message, "*"),
});

export type IFrameProcedures = typeof iframeEvents;

const parentRPC = iframeProcedures.createRPC<ParentProcedures>();
/**
 * ^? const parentRPC: {
 *      getDataFromParent: (id: string) => Promise<string>;
 *    }
 */

const result = await parentRPC.getDataFromParent("10");
// ^? const result: string

Figma plugin example

// main.ts

import { defineProcedures } from "corpc";
import type { UiProcedures } from "./ui";

const listeners = Set<(message: unknown) => void>();

const addFigmaEventListener = (listener: (message: unknown) => void) => {
  listeners.add(listener);
};

const removeFigmaEventListener = (listener: (message: unknown) => void) => {
  listeners.delete(listener);
};

figma.ui.onmessage = (message: unknown): void => {
  for (const listener of listeners) {
    listener(message);
  }
};

const mainProcedures = defineProcedures({
  procedures: {
    getCurrentUser: () => figma.currentUser,
    getState: (key: string) => figma.clientStorage.getAsync(key),
    updateState: (key: string, value: any) =>
      figma.clientStorage.setAsync(key, value),
    close: () => figma.ui.close(),
  },
  postMessage: (message) => {
    figma.ui.postMessage(message);
  },
  listener: (handler) => (message: unknown) => {
    handler(message);
  },
  addMessageEventListener: (listener) => {
    addFigmaEventListener(listener);
  },
  removeMessageEventListener: (listener) => {
    removeFigmaEventListener(listener);
  },
});

export type MainProcedures = typeof mainProcedures;

const uiRPC = mainProcedures.createRPC<UiProcedures>();
/**
 * ^? const uiRPC: {}
 */

// ui.ts

import { defineProcedures } from "corpc";
import type { MainProcedures } from "./main";

const uiProcedures = defineProcedures({
  postMessage: (message) => {
    window.parent.postMessage(
      {
        pluginMessage: message,
      },
      "*",
    );
  },
  listener: (handler) => (event: MessageEvent) => {
    handler(event.data.pluginMessage);
  },
});

export type UiProcedures = typeof uiProcedures;

export const mainRPC = uiProcedures.createRPC<MainProcedures>();
/**
 * ^? const mainRPC: {
 *      getCurrentUser: () => Promise<User | null>;
 *      getState: (key: string) => Promise<unknown>;
 *      updateState: (key: string, value: any) => Promise<void>;
 *      close: () => Promise<void>;
 *    }
 */

const user = await mainRPC.getCurrentUser();
// ^? const user: User | null