JSPM

  • ESM via JSPM
  • ES Module Entrypoint
  • Export Map
  • Keywords
  • License
  • Repository URL
  • TypeScript Types
  • README
  • Created
  • Published
  • Downloads 12
  • Score
    100M100P100Q59316F
  • License AGPL-3.0-or-later

Typed RPC envelope layer over Sideband message frames: request/response/notification shapes, reserved subject helpers, JSON codec, and guards.

Package Exports

  • @sideband/rpc
  • @sideband/rpc/package.json

Readme

@sideband/rpc

Canonical RPC envelope layer over Sideband message frames: typed request/response/notification shapes, reserved subject helpers, JSON codec, and guards for safe handling.

Install

bun add @sideband/rpc

Quick use

import {
  createRpcRequest,
  createRpcSuccessResponse,
  createRpcErrorResponse,
  createRpcNotification,
  encodeRpcEnvelope,
  decodeRpcEnvelope,
  isRpcResponse,
  SUBJECT_PREFIXES,
  asRpcSubject,
} from "@sideband/rpc";
import {
  generateFrameId,
  createMessageFrame,
  encodeFrame,
  decodeFrame,
  asSubject,
  FrameKind,
} from "@sideband/protocol";

// Build an RPC request envelope
const cid = generateFrameId(); // Correlation ID = frame's frameId
const methodName = "echo";
const request = createRpcRequest(methodName, cid, { text: "hi" });
const envelopeBytes = encodeRpcEnvelope(request);

// Wrap in a MessageFrame with rpc/ subject
const subject = asSubject(`${SUBJECT_PREFIXES.RPC}${methodName}`); // "rpc/echo"
const messageFrame = createMessageFrame({ subject, data: envelopeBytes });
const frameBytes = encodeFrame(messageFrame);

// ...send frameBytes over transport...

// On receive: decode frame, extract envelope, dispatch by subject
const decodedFrame = decodeFrame(frameBytes);
if (decodedFrame.kind === FrameKind.Message) {
  const envelope = decodeRpcEnvelope(decodedFrame.data);
  if (isRpcResponse(envelope)) {
    console.log("result:", envelope.result);
  }
}

// Craft responses/notifications
const responseEnvelope = createRpcSuccessResponse(cid, { text: "hi back" });
const notifyEnvelope = createRpcNotification(
  `${SUBJECT_PREFIXES.EVENT}user.joined`,
  { userId: "123" },
);

// Validate reserved subjects for routing (rpc/, event/, stream/, app/)
const validSubject = asRpcSubject(`${SUBJECT_PREFIXES.RPC}echo`);

What it provides

  • Typed RPC envelopes with helpers and discriminated unions for requests, responses, and notifications
  • Reserved subject helpers (rpc/, event/, stream/, app/) plus validator re-export (asRpcSubject)
  • JSON encoder/decoder that handles FrameId ↔ hex, emits protocol errors on malformed input
  • Integrates with runtime correlation (@sideband/runtime) and any transport carrying MessageFrames

License

Code: AGPL-3.0-or-later. Commercial licensing available via hello@sideband.tech.