Registry / http-networking / bidc
library0.0.4jsnpmunverified

BIDC is a JavaScript library designed for establishing robust, asynchronous, bidirectional communication channels between different JavaScript execution contexts, such as web workers, iframes, and service workers. Unlike traditional `postMessage` APIs, BIDC abstracts away the complexities of message passing, providing full support for promises, async functions, and a wide range of complex data types (e.g., Date, RegExp, Map, Set, ArrayBuffer). It features an automatic handshake mechanism to establish and re-establish connections seamlessly, even if one side reloads, and buffers messages until the recipient is ready. Currently at version 0.0.4, the library is in an early development stage, focusing on foundational features for secure and efficient cross-context communication. Its primary differentiators are automatic connection management, comprehensive data type serialization, and first-class async/await support, streamlining RPC-style interactions. It ships with TypeScript types, enhancing developer experience and type safety.

npm install bidc
INSTALL
IMPORT
SIG · BIDC
B
bidc
http-networkingjavascriptv0.0.4
Install
Import
Disk
Pass rate
0/ 6
Env Coverage0 / 6
glibc
1822
musl
1822
Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
node 18226 runs
build_error
glibc
node 18226 runs
build_error
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

createChannel
import { createChannel } from 'bidc'
const { createChannel } = require('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
import type { Channel } from 'bidc'
import { 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.

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.
Debug
Known issues
breakingAs 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.
affects: <1.0.0
gotchaWhen 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`.
affects: >=0.0.1
gotchaEnsure 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.
affects: >=0.0.1
Errors
Common errors & fixes
TypeError: createChannel is not a function
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.
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.
Upgrade
Version history
0.0.4latest on npm
Audit
Dependencies

No dependency data recorded yet.

Agent activity
20 hits · last 30 days
node
18
OpenAI (training)
1
Resources
bidc — npm install bidc · libregistry