esdeka-node18

v0.1.18

Published

a year ago

Communicate between iframe and host

Downloads

0High
0Medium
0Low

timpietrusky

react vanilla hooks sdk iframe state widget app communicate

Esdeka

Communicate between <iframe> and host

Mechanism

Esdeka is a small and lightweight library that provides a simple mechanism for communication between a host window and one or more guest iframes. It uses window.postMessage to transmit data between the two, and offers several helper functions to make the process as easy as possible.

With Esdeka, you can stream data down to the iframe, and if the iframe needs to communicate back, it can dispatch an action with an optional payload. You can then choose how to respond to the transmitted data.

Esdeka is easy to use and offers a range of functions to create and manage connections, including call, answer, broadcast, and subscribe. It also includes a set of React hooks for even simpler integration with your React projects.

With all bundles smaller than 1KB, Esdeka is a great choice for lightweight communication between your web pages and iframes.

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 subscribes to all messages and act accordingly.

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. | | targetOrigin? | string | Optional origin to prevent insecure communication. |

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. | | targetOrigin? | string | Optional origin to prevent insecure communication. |

answer(window, "my-channel");

`disconnect`

Tell the host that the guest disconnected.

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 | | targetOrigin? | string | Optional origin to prevent insecure communication. |

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. | | targetOrigin? | string | Optional origin to prevent insecure communication. |

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.

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

React hooks

`useHost`

Curried host functions that don't need the window and channel.

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

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

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

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

`useGuest`

Curried guest functions that don't need the window and channel.

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

answer();

disconnect();

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

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

Bundle size

All bundles are smaller than 1KB


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

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

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

 PASS  ./dist/react.mjs: 729B < 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, useRef } 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();
          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" />;
}

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

Esdeka

Table of Contents

Mechanism

Creating a connection

Functions

call

answer

disconnect

subscribe

dispatch

broadcast