Esdeka

Communicate between <iframe> and host

Mechanism

Esdeka uses window.postMessage to communicate to iframes. It offers several helpers to make communication as easy as possible.

We stream data down to the iframe. If the iframe wants to communicate back it dispatches an action with an optional payload. We can then decide how to act on the transmitted data.

Flux flow

Creating a connection

To create a connection we need to call a client and wait for an answer.

Setting up a Host:

import { call } from "esdeka";

const iframe = document.querySelector("iframe");

call(iframe.contentWindow, "my-channel", { some: "Data" });

Setting up a Guest

import { answer, subscribe } from "esdeka";

subscribe("my-channel", event => {
  if (event.data.action.type === "call") {
    answer(event.source, "my-channel");
  }
});

Once a connection exists, we can broadcast information from the host to the guest.

Host:

import { broadcast, call, subscribe } from "esdeka";

const iframe = document.querySelector("iframe");

call(iframe.contentWindow, "my-channel", { some: "Data" });

subscribe("my-channel", event => {
  if (event.data.action.type === "answer") {
    broadcast(event.source, "my-channel", {
      question: "How are you?",
    });
  }
});

The guest subscrubes to all messages and Guest

import { answer, subscribe } from "esdeka";

const questions = [];

subscribe("my-channel", event => {
  const { type, payload } = event.data.action;
  switch (type) {
    case "broadcast":
      if (payload?.question) {
        questions.push(payload.question);
      }
      break;
    case "call":
      answer(event.source, "my-channel");
      break;
    default:
      console.error("Not implemented");
      break;
  }
});

Functions

`call`

Sends a connection request from the host to a guest. The payload can be anything that you want to send through a channel.

Argument	Type	Description
`source`	`Window`	Has to be a `Window` to use `postMessage`
`channel`	`string`	The channel on which the host and gues communicate. The host and guest have to use the same channel to communicate.
`payload`	`unknown`	The payload that of the message can contain any data. We cannot transmit functions or circular objects, therefore we recommend using a serializer.

call(window, "my-channel", {
  message: "Hello",
});

`answer`

Answer to a host to confirm the connection.

Argument	Type	Description
`source`	`Window`	Has to be a `Window` to use `postMessage`
`channel`	`string`	The channel on which the host and gues communicate. The host and guest have to use the same channel to communicate.

answer(window, "my-channel");

`disconnect`

Tell the host that the guest disconnected.

Argument	Type	Description
`source`	`Window`	Has to be a `Window` to use `postMessage`
`channel`	`string`	The channel on which the host and gues communicate. The host and guest have to use the same channel to communicate.

disconnect(window, "my-channel");

`subscribe`

Listen to all messages in a channel.

Argument	Type	Description
`source`	`Window`	Has to be a `Window` to use `postMessage`
`channel`	`string`	The channel on which the host and gues communicate. The host and guest have to use the same channel to communicate.
`callback`	`(event: MessageEvent) => void`	The callback function of the subscription

subscribe("my-channel", event => {
  console.log(event);
});

`dispatch`

Send an action to Esdeka. The host will be informed and can act un the request.

Argument	Type	Description
`source`	`Window`	Has to be a `Window` to use `postMessage`
`channel`	`string`	The channel on which the host and gues communicate. The host and guest have to use the same channel to communicate.
`action`	`Action<unknown>`	The action that is dispatched by the guest.

Without payload

dispatch(window, "my-channel", {
  type: "increment",
});

With payload

dispatch(window, "my-channel", {
  type: "greet",
  payload: {
    message: "Hello",
  },
});

`broadcast`

Send data from the host window to the guest. The payload can be anything that you want to send through a channel.

Argument	Type	Description
`source`	`Window`	Has to be a `Window` to use `postMessage`
`channel`	`string`	The channel on which the host and gues communicate. The host and guest have to use the same channel to communicate.
`payload`	`unknown`	The payload that of the message can contain any data. We cannot transmit functions or circular objects, therefore we recommend using a serializer.

boadcast(window, "my-channel", {
  message: "Hello",
});

React hooks

`useHost`

Provides curried host functions that don’t need the window and channel.

const { broadcast, call, subscribe } = useHost(ref, "my-channel");

call({
  message: "Hello",
});

boadcast({
  message: "Hello",
});

subscribe(event => {
  console.log(event);
});

`useGuest`

const { answer, disconnect, dispatch, subscribe } = useGuest(ref, "my-channel");

answer();

disconnect();

subscribe(event => {
  console.log(event);
});

dispatch({
  action: {
    type: "greet",
    payload: {
      message: "Hello",
    },
  },
});

Bundle size

All bundles are smaller than 1KB

 PASS  ./dist/index.js: 554B < maxSize 1KB (gzip)

 PASS  ./dist/index.mjs: 511B < maxSize 1KB (gzip)

 PASS  ./dist/react.js: 696B < maxSize 1KB (gzip)

 PASS  ./dist/react.mjs: 673B < maxSize 1KB (gzip)

Full React example (using Zustand)

Host

http://localhost:3000/

import { serialize, useHost } from "esdeka/react";
import { DetailedHTMLProps, IframeHTMLAttributes, useEffect, useRef, useState } from "react";
import create from "zustand";

export interface StoreModel {
  counter: number;
  increment(): void;
  decrement(): void;
}

export const useStore = create<StoreModel>(set => ({
  counter: 0,
  increment() {
    set(state => ({ counter: state.counter + 1 }));
  },
  decrement() {
    set(state => ({ counter: state.counter - 1 }));
  },
}));

export interface EsdekaHostProps
  extends DetailedHTMLProps<IframeHTMLAttributes<HTMLIFrameElement>, HTMLIFrameElement> {
  channel: string;
  maxTries?: number;
  interval?: number;
}

export function EsdekaHost({ channel, maxTries = 30, interval = 30, ...props }: EsdekaHostProps) {
  const ref = useRef<HTMLIFrameElement>(null);
  const connection = useRef(false);
  const [tries, setTries] = useState(maxTries);

  const { broadcast, call, subscribe } = useHost(ref, channel);

  // Send a connection request
  useEffect(() => {
    if (connection.current || tries <= 0) {
      return () => {
        /* Consistency */
      };
    }

    call(serialize(useStore.getState()));
    const timeout = setTimeout(() => {
      call(serialize(useStore.getState()));
      setTries(tries - 1);
    }, interval);

    return () => {
      clearTimeout(timeout);
    };
  }, [call, tries, interval]);

  useEffect(() => {
    if (!connection.current) {
      const unsubscribe = subscribe(event => {
        const store = useStore.getState();
        const { action } = event.data;
        switch (action.type) {
          case "answer":
            connection.current = true;
            break;
          default:
            if (typeof store[action.type] === "function") {
              store[action.type](action.payload.store);
            }
            break;
        }
      });
      return () => {
        unsubscribe();
      };
    }
    return () => {
      /* Consistency */
    };
  }, [subscribe]);

  // Broadcast store to guest
  useEffect(() => {
    if (connection.current) {
      const unsubscribe = useStore.subscribe(newState => {
        broadcast(serialize(newState));
      });
      return () => {
        unsubscribe();
      };
    }
    return () => {
      /* Consistency */
    };
  }, [broadcast]);

  return <iframe ref={ref} {...props} />;
}

export default function App() {
  const increment = useStore(state => state.increment);
  const decrement = useStore(state => state.decrement);
  const counter = useStore(state => state.counter);
  return (
    <div>
      <button onClick={increment}>Up</button>
      <span>{counter}</span>
      <button onClick={decrement}>Down</button>
      <EsdekaHost channel="esdeka-test" src="http://localhost:3001" />
    </div>
  );
}

Guest

http://localhost:3001

import { useGuest } from "esdeka/react";
import { useEffect, useState } from "react";
import create from "zustand";

export interface StoreModel {
  [key: string]: any;
  // eslint-disable-next-line no-unused-vars
  set(state: Omit<StoreModel, "set">): void;
}

export const useStore = create<StoreModel>(set => ({
  set(state) {
    set(state);
  },
}));

export function EsdekaGuest({ channel }: { channel: string }) {
  const counter = useStore(state => state.counter);
  const host = useRef<Window | null>(null);
  const { answer, dispatch, subscribe } = useGuest();

  useEffect(() => {
    const unsubscribe = subscribe<Except<StoreModel, "set">>(event => {
      const { action } = event.data;
      switch (action.type) {
        case "call":
          host.current = event.source as Window;
          answer(host.current);
          break;
        case "broadcast":
          useStore.getState().set(action.payload);
          break;
        default:
          break;
      }
    });
    return () => {
      unsubscribe();
    };
  }, [answer, subscribe]);

  return (
    <div>
      <h1>Current Count: {counter}</h1>
      <button
        onClick={() => {
          dispatch({ type: "decrement" });
        }}
      >
        Down
      </button>
      <button
        onClick={() => {
          dispatch({ type: "increment" });
        }}
      >
        Up
      </button>
    </div>
  );
}

export default function Page() {
  return <EsdekaGuest channel="esdeka-test" />;
}

GitHub

View Github