Bidirectional Channel for JavaScript

Common errors

• TypeError: createChannel is not a function

  cause Attempting to use CommonJS `require` syntax with an ESM-only package or a misconfigured bundler.
  fix Use ESM import syntax: `import { createChannel } from 'bidc'`. Ensure your project's `package.json` specifies `"type": "module"` or your build system correctly handles ESM.

• Uncaught (in promise) DOMException: Failed to execute 'postMessage' on 'Window': An object could not be cloned.

  cause While BIDC generally handles complex types, certain non-clonable or non-transferable objects (e.g., DOM elements, functions not wrapped by BIDC's async support) might still fail if directly sent in a payload without proper serialization or remote execution context.
  fix Ensure that the data being sent directly as a payload consists of clonable JavaScript primitives or objects that BIDC explicitly supports for serialization. For DOM elements or functions, consider an RPC pattern where the function is executed remotely or only send serializable identifiers.

Warnings

• breaking As of version 0.0.4, BIDC is in early development. While the core API (`createChannel`, `send`, `receive`) is stable, minor versions may introduce breaking changes to less common features or internal protocols. Major version 1.0.0 is expected to stabilize the API.
  Fix: Monitor releases and review changelogs for new minor versions before upgrading in production environments. Pin exact versions for critical applications.
• gotcha When using `createChannel()` without specifying a target, it defaults to `window.parent`. This behavior is useful for iframes/workers communicating with their creators but can lead to unexpected connections if used in a top-level window without explicit targeting.
  Fix: Always explicitly provide a target (e.g., `iframe.contentWindow`, `worker`, `otherWindow`) to `createChannel(target)` unless you specifically intend to connect to `window.parent`.
• gotcha Ensure both ends of the channel are calling either `send` or `receive` (or both) to establish and maintain communication. If only one side attempts to `send` without a `receive` handler on the other, messages will be buffered but never processed.
  Fix: For every message you intend to send, ensure there's a corresponding `receive` handler on the other side of the channel to process it and, if desired, return a response.

Install

• npm install bidc npm
• yarn add bidc yarn
• pnpm add bidc pnpm

Imports

• createChannel
  wrong:

  const { createChannel } = require('bidc')

  correct:

  import { createChannel } from 'bidc'

  BIDC is primarily an ESM-first library. While some bundlers might transpile CommonJS 'require', using ESM 'import' is the recommended and native approach for modern JavaScript environments.
• Channel
  wrong:

  import { Channel } from 'bidc'

  correct:

  import type { Channel } from 'bidc'

  The 'Channel' type refers to the interface returned by 'createChannel'. It should be imported as a type for TypeScript, not as a runtime value.
• Payload

  import type { Payload } from 'bidc'

  While 'Payload' is not directly exported for consumption in the same way 'createChannel' is, understanding and defining custom payload types for your channel messages is crucial for robust communication. You would typically define your specific message interfaces that extend or align with BIDC's internal 'Payload' structure for type safety in your `send` and `receive` handlers.

Quickstart

This quickstart demonstrates basic one-way data transfer and response handling between a parent window and an iframe using `createChannel`, showing both sending and receiving sides.

import { createChannel } from 'bidc';

// --- Parent window code ---
async function parentContext() {
  const iframe = document.createElement('iframe');
  document.body.appendChild(iframe);

  // Wait for iframe to load for contentWindow to be available
  await new Promise(resolve => iframe.onload = resolve);

  const { send } = createChannel(iframe.contentWindow);

  // Send a simple message to the iframe and await its response
  const result = await send({ value: 'Hello, iframe from parent!' });
  console.log('Parent received:', result);
  console.assert(result === 'HELLO, IFRAME FROM PARENT!');
}

// --- Inside the iframe (hypothetical, or simulated for demo) ---
// In a real scenario, this would be in the iframe's HTML or JS file.
function iframeContext() {
  // Omitting the target here will create a channel to the parent window by default
  const { receive } = createChannel(); // Equivalent to createChannel(window.parent)

  // Handle incoming messages from the parent and return a response
  receive((payload) => {
    console.log('Iframe received:', payload);
    if (typeof payload.value === 'string') {
      return payload.value.toUpperCase();
    }
    return 'Invalid payload';
  });
}

// For demonstration, call both, but in reality they run in separate contexts.
parentContext();
iframeContext(); // This would typically be loaded by the iframe itself.