JSPM

  • ESM via JSPM
  • ES Module Entrypoint
  • Export Map
  • Keywords
  • License
  • Repository URL
  • TypeScript Types
  • README
  • Created
  • Published
  • Downloads 12
  • Score
    100M100P100Q59396F
  • License Apache-2.0

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_CHANNELS,
  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` channel subject
// Method name lives in the envelope, not the subject
const subject = asSubject(SUBJECT_CHANNELS.RPC); // "rpc"
const messageFrame = createMessageFrame(subject, envelopeBytes);
const frameBytes = encodeFrame(messageFrame);

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

// On receive: decode frame, extract envelope, dispatch by envelope.m
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" });
// Notifications use `event` channel; event name lives in envelope.e
const notifyEnvelope = createRpcNotification("user.joined", { userId: "123" });

// Validate reserved subjects for routing
const validRpcSubject = asRpcSubject(SUBJECT_CHANNELS.RPC); // "rpc"
const validAppSubject = asRpcSubject("app/custom"); // custom sub-path

What it provides

  • Typed RPC envelopes with helpers and discriminated unions for requests, responses, and notifications
  • Channel subjects (rpc, event, stream) and app/ prefix constants, 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

Specification

See the RPC protocol specification for envelope format details.

License

Apache-2.0