Transports

A transport is the channel expose() talks over. osra accepts the platform objects below directly; anything else can be wrapped in a plain { emit, receive } pair.

Transports are either structured-clone (Worker, Window, MessagePort, SharedWorker) or JSON (WebSocket, web extension messaging, custom transports with isJson: true). JSON mode forces JSON-safe boxing: values that depend on structured clone (RegExp, SharedArrayBuffer, ImageBitmap, …) are rejected at the type level, while everything with a dedicated revivable module (Date, Map, ArrayBuffer via base64, functions, streams, …) still works. osra only stringifies envelopes itself on WebSocket; custom function emitters handle their own serialization. See JSON vs clone for exactly what degrades, and supported types for the full matrix.

Overview

Transport	Mode	Notes
Window	clone	origin applies (inbound filter + outbound targetOrigin).
Worker	clone
DedicatedWorkerGlobalScope	clone	Pass globalThis (or self) inside the worker.
SharedWorker	clone	Page side. Messages ride .port (handled internally).
MessagePort	clone	.start() is called internally on receive.
WebSocket	JSON	Envelopes are JSON.stringifyed; sends while CONNECTING queue until open.
ServiceWorker	clone	Emit only.
ServiceWorkerContainer	clone	Receive only. Combine: { emit: registration.active, receive: navigator.serviceWorker }.
WebExtension runtime / Port / onConnect / onMessage	JSON	runtime/onConnect are identity-matched against the browser/chrome global; Port/onMessage are detected purely structurally and work without the global (lookalike objects can misclassify as these).
Custom { emit?, receive?, isJson? }	per isJson / probed	See Custom transports.

Worker

Pass the Worker on the page side and globalThis (the DedicatedWorkerGlobalScope) inside the worker — the worker scope isn’t part of the Transport type union, so cast it:

// worker.ts
expose(api, { transport: globalThis as unknown as Transport })

// main.ts
const worker = new Worker(new URL('./worker.ts', import.meta.url), { type: 'module' })
const remote = await expose<Api>({}, { transport: worker })

The full worker walkthrough lives in getting started.

Window ↔ iframe

message events fire on the window that receives them, so each side pairs the other window for emit with its own window for receive. origin is applied in both directions: outbound it is the postMessage targetOrigin, inbound it drops events whose event.origin differs. Set it whenever you talk across origins — see security for the trust model and the one announce-beacon exception.

// parent
const iframe = document.querySelector('iframe')!
const remote = await expose<IframeApi>(parentApi, {
  transport: { emit: iframe.contentWindow!, receive: window },
  origin: 'https://app.example.com',
})

// iframe
const remote = await expose<ParentApi>(iframeApi, {
  transport: { emit: window.parent, receive: window },
  origin: 'https://host.example.com',
})

SharedWorker

Pass the SharedWorker instance directly on the page side; osra rides its .port internally. Inside the worker, expose per connected port:

// page
const sharedWorker = new SharedWorker(new URL('./shared.ts', import.meta.url), { type: 'module' })
const remote = await expose<Api>({}, { transport: sharedWorker })

shared.ts

import { expose } from 'osra'

const api = { add: async (a: number, b: number) => a + b }

globalThis.addEventListener('connect', event => {
  for (const port of (event as MessageEvent).ports) expose(api, { transport: port })
})

Per-port expose() gives each connecting page its own connection; multi-peer connections explains why this is the recommended pattern.

WebSocket

JSON mode. You can expose() while the socket is still CONNECTING; outbound envelopes queue until open. The other end is anything that relays frames to a peer also running osra:

const socket = new WebSocket('wss://relay.example.com')
const remote = await expose<PeerApi>(localApi, { transport: socket })

Service worker

A ServiceWorker can only emit and a ServiceWorkerContainer can only receive, so combine them as a custom pair:

const registration = await navigator.serviceWorker.ready
const remote = await expose<SwApi>(pageApi, {
  transport: { emit: registration.active!, receive: navigator.serviceWorker },
})

Web extension

JSON mode. runtime.Port, the runtime itself (sendMessage/onMessage), onConnect, and onMessage are all accepted:

// content script
const port = browser.runtime.connect()
const background = await expose<BackgroundApi>(contentApi, { transport: port })

// background
browser.runtime.onConnect.addListener(port => {
  expose(backgroundApi, { transport: port })
})

Caution

If you accept onConnectExternal/onMessageExternal, validate senders yourself; osra does no sender validation. The MessageContext passed to custom receive listeners exposes sender. See security.

Anything else

Any plain object with emit and receive works as a transport — a BroadcastChannel, a native bridge, a text protocol of your own. See custom transports.