BIDC (Bidirectional Channels for JavaScript)

BIDC supports a wide range of JavaScript types, including Date, RegExp, Map, Set, ArrayBuffer, TypedArray, and most importantly, Promise and Async Function.

When you transfer a Promise, the receiving side can await it. When you transfer an Async Function, the receiving side can call it as if it were local, and the execution will occur in the original context.

// Sending side
const response = await send({
  date: new Date(),
  map: new Map([['key', 'value']]),
  set: new Set([1, 2, 3]),
  arrayBuffer: new Uint8Array([1, 2, 3]).buffer,
  promise: Promise.resolve('resolved value'),
  function: async (x) => {
    await sleep(1000)
    return x * 2
  }
})

// Receiving side
receive(async (payload) => {
  const resolvedValue = await payload.promise
  const result = await payload.function(5)
  return { status: 'success' }
})

BIDC supports sending asynchronous data and complex JavaScript types across the channel.

Promise Serialization

Promises are serialized and sent as separate chunks when they resolve. This allows you to send data that isn't immediately available.

// This promise will be sent when it resolves
delayedResponse: new Promise(resolve => 
  setTimeout(() => resolve(`Delayed response: "${message}"`), 2000)
)

Supported Complex Types

The following serializable types are supported seamlessly:

• Map
• Set
• BigInt
• Date
• Nested objects and arrays
• Resolved Promises (Promise.resolve(...))

data: {
  map: new Map([['key1', 'value1']]),
  set: new Set([1, 2, 3]),
  bigInt: BigInt(12345),
  date: new Date(),
  asyncData: Promise.resolve({ success: true })
}

To use BIDC with a Web Worker, pass the worker instance to createChannel in the main thread. Inside the worker, calling createChannel() without arguments will automatically establish the channel back to the parent context.

// Main Thread
import { createChannel } from 'bidc'
const worker = new Worker('./worker.js')
const { send, receive } = createChannel(worker)

// Inside worker.js
import { createChannel } from 'bidc'
const { send, receive } = createChannel()

Install the bidc package using pnpm to enable bidirectional asynchronous communication between JavaScript contexts.

pnpm i bidc

BIDC uses createChannel to establish bidirectional communication. The way you initialize the channel depends on whether the code is running in the parent window or within an iframe.

• In the Parent Page: You must provide the target window (e.g., the iframe's contentWindow) to establish the connection. createChannel('channel-name', iframe.contentWindow)

• In the Iframe Page: The library automatically detects the iframe context and uses window.parent for communication. You only need to provide the channel name. createChannel('channel-name')

To run the BIDC Next.js demonstration application, follow these steps to install dependencies, build the core library, and start the development server.

1. Install dependencies in the example directory:

   cd example
   npm install
   # or
   pnpm install

2. Build the parent BIDC library from the repository root:

   cd ..
   pnpm build

3. Run the development server in the example directory:

   cd example
   npm run dev
   # or
   pnpm dev

4. Open the demo at http://localhost:3000.

A SerializableValue is any data type that can be safely encoded and transmitted across the BIDC channel. This includes standard primitives, complex objects, and even promises and functions.

Supported types include:

• Primitives: string, number, boolean, null, undefined, bigint
• Objects/Arrays: SerializableObject, SerializableArray, Map, Set
• Specialized: RegExp, Date, ArrayBuffer, TypedArray (e.g., Uint8Array)
• Async: Promise<SerializableValue>
• Functions: SerializableFunction (can be invoked remotely)

BIDC supports passing functions through the channel. When a function is sent, it is assigned a unique ID. When the receiver attempts to call this function, BIDC intercepts the call and sends a special message (bidc-fn:<id>) back to the sender. The sender executes the local function and returns the result via a response message (bidc-res:<id>).

Note: Sending many anonymous or inline functions is discouraged as they cannot be cached and may increase the size of the internal function reference store.

You can send a message from a parent window to an iframe and await a response. The send method returns the value returned by the receive handler on the target side.

Parent Window:

import { createChannel } from 'bidc'
const { send } = createChannel(iframe.contentWindow)
const result = await send({ value: 'Hello, iframe!' })

Inside the Iframe:

import { createChannel } from 'bidc'
const { receive } = createChannel()
receive(payload => {
  return payload.value.toUpperCase()
})

// Parent
import { createChannel } from 'bidc'
const { send } = createChannel(iframe.contentWindow)
const result = await send({ value: 'Hello, iframe!' })

// Iframe
import { createChannel } from 'bidc'
const { receive } = createChannel()
receive(payload => {
  return payload.value.toUpperCase()
})

Both sides of a BIDC channel can implement both send and receive to create a full duplex communication loop.

// Parent
import { createChannel } from 'bidc'
const { send, receive } = createChannel(iframe.contentWindow)

receive((payload) => {
  return { response: 'Message received!' }
})

const responseFromIframe = await send({ value: 'Hello, iframe!' })

// Iframe
import { createChannel } from 'bidc'
const { send, receive } = createChannel()

receive((payload) => {
  return { response: 'Hello, parent!' }
})

const responseFromParent = await send({ value: 'Hello, parent!' })