Transports

Transports are the channels osra uses to communicate between the different expose() calls. As previously explained in Transport Modes, transports support different modes of communication depending on which you use.

The following table contains osra’s natively supported transports, with their corresponding mode and notes related to them:

Transport	Mode	Notes
Window	structured
DedicatedWorkerGlobalScope	structured
MessagePort	structured	Osra automatically calls .start() on the port
SharedWorker	structured
ServiceWorker	structured
WebSocket	JSON
WebExtension Port	JSON
WebExtension runtime.onMessage	JSON	Receive only, pair it with a sendMessage emit
Node.js MessagePort, parentPort	structured	See Node.js below
{ emit, receive }	either	See custom transports

Examples

The following examples demonstrate how osra can be used with each transport.

Worker

worker.ts

import { expose } from 'osra'

export const { mult } = await expose<Payload>(
  { add: (a: number, b: number) => a + b },
  { transport: globalThis }
)

await mult(3, 7) // 21

main.ts

import { expose } from 'osra'

const worker = new Worker('/worker.ts', { type: 'module' })

export const { add } = await expose<Payload>(
  { mult: (a: number, b: number) => a * b  },
  { transport: worker }
)

await add(40, 2) // 42

Iframe

iframe.ts

import { expose } from 'osra'

export const { mult } = await expose<Payload>(
  { add: (a: number, b: number) => a + b },
  {
    transport: { emit: window.parent, receive: window },
    origin: 'https://host.example.com'
  }
)

await mult(3, 7) // 21

main.ts

import { expose } from 'osra'

const iframe = document.querySelector('iframe')!

export const { add } = await expose<Payload>(
  { mult: (a: number, b: number) => a * b  },
  {
    transport: { emit: iframe.contentWindow!, receive: window },
    origin: 'https://app.example.com'
  }
)

await add(40, 2) // 42

MessagePort

import { expose } from 'osra'
const { port1, port2 } = new MessageChannel()

export const { mult } = await expose<{ mult: (a: number, b: number) => number }>(
  { add: (a: number, b: number) => a + b },
  {
    transport: port1,
    origin: 'https://host.example.com'
  }
)

export const { add } = await expose<{ add: (a: number, b: number) => number }>(
  { mult: (a: number, b: number) => a * b  },
  {
    transport: port2,
    origin: 'https://iframe.example.com'
  }
)

await add(40, 2) // 42
await mult(3, 7) // 21

SharedWorker

shared-worker.ts

import { expose } from 'osra'

globalThis.addEventListener('connect', event => {
  for (const port of (event as MessageEvent).ports) {
    expose(
      { add: (a: number, b: number) => a + b },
      { transport: port }
    )
  }
})

main.ts

import { expose } from 'osra'

const sharedWorker = new SharedWorker('/shared.ts', { type: 'module' })

const { add } = await expose<Payload>({}, { transport: sharedWorker })

await add(40, 2) // 42

Service worker

service-worker.ts

import { expose } from 'osra'

addEventListener("message", async (event) => {
  const { add } = await expose<Payload>(
    { mult: (a: number, b: number) => a * b },
    { transport: event.ports[0] }
  )

  await add(40, 2) // 42
})

main.ts

import { expose } from 'osra'

const { port1, port2 } = new MessageChannel()
const registration = await navigator.serviceWorker.ready
registration.active!.postMessage(port1, [port1])

const { mult } = await expose<Payload>(
  { add: (a: number, b: number) => a + b },
  { transport: port2 }
)

await mult(3, 7) // 21

WebSocket

server.ts

import { WebSocketServer } from 'ws'
import { expose } from 'osra'

const wss = new WebSocketServer({ port: 8080 })

wss.on('connection', async ws => {
  const { add } = await expose<Payload>(
    { mult: (a: number, b: number) => a * b },
    {
      transport: {
        isJson: true,
        emit: (data) => ws.send(data.toString()),
        receive: (listener) => {
          ws.on('message', data => {
            listener(JSON.parse(data.toString()), {})
          })
        }
      }
    }
  )

  await add(40, 2) // 42
})

client.ts

import { expose } from 'osra'

const socket = new WebSocket('wss://example.com')
const { mult } = await expose<Payload>(
  { add: (a: number, b: number) => a + b },
  { transport: socket }
)

await mult(3, 7) // 21

WebExtension

Osra natively supports WebExtension transports, but there is an important thing to know about WebExtensions; if communicating with a MV3 service-worker, that service-worker might be unloaded and cause issues with the osra connection.

This means that if you have long lived promises, if the SW unloads during these, the promise will never resolve.

MV3 service-worker connection

Per the spec, service-workers are unloaded after 5 minutes of inactivity even if connections are open, in practice, this means that if you are communicating with a MV3 service-worker, you should reconnect when you receive a disconnect event.

content-script.ts

import { expose } from 'osra'

const port = runtime.connect()
const { add } = await expose<Payload>(
  { mult: (a: number, b: number) => a * b },
  { transport: port }
)

await add(40, 2) // 42

background.ts

import { expose } from 'osra'

const backgroundApi = { fetchData: async (url: string) => (await fetch(url)).text() }
export type BackgroundApi = typeof backgroundApi

runtime.onConnect.addListener(async port => {
  const { mult } = await expose<Payload>(
    { add: (a: number, b: number) => a + b },
    { transport: port }
  )

  await mult(3, 7) // 21
})

connectionless

You can also communicate to service-workers via runtime.sendMessage and runtime.onMessage, which makes them connectionless.

With the same caveat of the connection based communication, if the service-worker unloads, any in-flight requests will fail and you need to re-expose() to make a new connection.

content-script.ts

import { expose } from 'osra'

const { add } = await expose<Payload>(
  { mult: (a: number, b: number) => a * b },
  {
    transport: {
      isJson: true,
      emit: message => runtime.sendMessage(message),
      receive: runtime.onMessage
    }
  }
)

await add(40, 2) // 42

background.ts

import type { ReceiveHandler } from 'osra'

import { expose, checkOsraMessageKey, OSRA_DEFAULT_KEY } from 'osra'

type Listener = Parameters<ReceiveHandler>[0]

const peers = new Map<number, Promise<Listener>>()

const peer = (tabId: number) => {
  const existing = peers.get(tabId)
  if (existing) return existing
  const { promise, resolve } = Promise.withResolvers<Listener>()
  peers.set(tabId, promise)
  expose<Payload>(
    { add: (a: number, b: number) => a + b },
    {
      transport: {
        isJson: true,
        receive: listener => resolve(listener),
        emit: message => { tabs.sendMessage(tabId, message) }
      }
    }
  )
  return promise
}

runtime.onMessage.addListener((message: unknown, sender: Runtime.MessageSender) => {
  const tabId = sender.tab?.id
  if (tabId === undefined) return
  if (!checkOsraMessageKey(message, OSRA_DEFAULT_KEY)) return
  peer(tabId).then(listener => listener(message, { sender }))
})

Node.js

Osra runs in Node.js as well, MessageChannel, MessagePort and WebSocket are the same platform objects there.

One thing to note is that a worker_threads worker has no global postMessage, so on the worker side you expose on parentPort, which is a real MessagePort.
On the main side, the Worker object is an event emitter rather than an event target, so wrap it in a small custom transport:

worker.ts

import { parentPort } from 'node:worker_threads'
import { expose } from 'osra'

export const { mult } = await expose<Payload>(
  { add: (a: number, b: number) => a + b },
  { transport: parentPort! }
)

await mult(3, 7) // 21

main.ts

import type { TransferListItem } from 'node:worker_threads'
import { Worker } from 'node:worker_threads'
import { expose } from 'osra'

const worker = new Worker(new URL('./worker.ts', import.meta.url))

export const { add } = await expose<Payload>(
  { mult: (a: number, b: number) => a * b },
  {
    transport: {
      emit: (message, transferables) =>
        worker.postMessage(message, transferables as TransferListItem[]),
      receive: listener => {
        worker.on('message', message => listener(message, {}))
      }
    }
  }
)

await add(40, 2) // 42

Keep in mind that on Node.js 22 and 24 the JSON transports base64 their binary data through a fallback, since those versions don’t ship Uint8Array.prototype.toBase64 yet. Nothing changes for you, it’s just slower than the native path.