jsonbird

library3.1.0jsnpmunverified

JSONBird is a Duplex stream for JSON-RPC 2.0 client/server/peer communication over any reliable transport, including WebSocket, TCP, HTTP, Web Workers, and in-process. Version 3.1.0 is stable with npm release cadence. It supports both out-of-order messaging and in-order byte streams, object mode for structured clone, and flexible readable/writable modes (json-message, json-stream, object). Unlike alternatives, it provides a single unified interface for client, server, or bidirectional use, with minimal dependencies and no transport coupling.

messaging

npm install jsonbird

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · JSONBIRD

jsonbird

messagingjavascriptv3.1.0

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

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

JSONBird

✓ import JSONBird from 'jsonbird'

✗ const { JSONBird } = require('jsonbird')

Default export only; named export does not exist. For CommonJS, use require('jsonbird').

JSONBird type (TypeScript)

✓ import type { JSONBirdOptions } from 'jsonbird' import JSONBird from 'jsonbird'

✗ import { JSONBird } from 'jsonbird'

Type imports are available; the main class is a default export.

methods()

✓ rpc.methods(new MyClass())

✗ rpc.methods(MyClass)

Pass an instance, not the class itself. Methods are bound to the instance.

Shows creating two JSONBird instances piped together for in-memory JSON-RPC, calling a registered method.

const JSONBird = require('jsonbird'); const rpc = new JSONBird({ readableMode: 'json-message', writableMode: 'json-stream', receiveErrorStack: true, sendErrorStack: true, }); rpc.method('add', (a, b) => a + b); // Simulate a peer connection const peer = new JSONBird({ readableMode: 'json-stream', writableMode: 'json-message', }); rpc.pipe(peer).pipe(rpc); peer.call('add', [2, 3]) .then(result => console.log('Result:', result)) // 5 .catch(err => console.error(err));

Debug

Known issues

gotchareadableMode and writableMode must be set correctly for the transport to avoid data loss or parsing errors.

fix

Use 'json-message' for message-based transports (e.g., WebSocket), 'json-stream' for stream-based (e.g., TCP), and 'object' for in-memory/structured clone.

affects: >=1.0.0

gotchaThe readable side emits objects; you must pipe or listen to the 'data' event to handle outgoing messages. Not reading will cause backpressure.

fix

Always attach a consumer: rpc.on('data', cb) or rpc.pipe(destination).

affects: >=1.0.0

deprecatedUsing require('jsonbird') is fine for CJS, but ESM users must use default import: import JSONBird from 'jsonbird'.

fix

Switch to ESM import syntax if using ES modules.

affects: >=3.0.0

gotchaCalling methods() with a class instead of an instance will silently fail to register methods.

fix

Instantiate the class first: rpc.methods(new MyClass())

affects: >=1.0.0

gotchaError stacks are not sent by default; set receiveErrorStack and sendErrorStack to true to include them.

fix

Pass { receiveErrorStack: true, sendErrorStack: true } in options.

affects: >=1.0.0

Errors

Common errors & fixes

TypeError: rpc.methods is not a function

Importing the module incorrectly (e.g., using named import).

fix

Correct import: const JSONBird = require('jsonbird'); or import JSONBird from 'jsonbird';

Error: Cannot find module 'jsonbird'

Package not installed or wrong import path.

fix

Run: npm install jsonbird

RangeError: Invalid return value from reader

readableMode and writableMode mismatch causing the stream to produce unexpected data types.

fix

Ensure readableMode and writableMode are set appropriately for your transport. See documentation.

Upgrade

Version history

3.1.0latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

13 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/Joris-van-der-Wel/jsonbird ↗

packagejsonbird ↗

homepagehttps://github.com/Joris-van-der-Wel/jsonbird#readme ↗