Connections
Functions
Section titled “Functions”context()
Section titled “context()”Guide: Connections
function context<TValue>(make: (ctx: Context) => TValue): Contextual<TValue>Defined in: connections/utils.ts:262
Build the exposed value once per connection, from that connection’s context, rather than sharing one value across every realm that connects. It runs BEFORE the value is boxed and sent, which is what lets one server answer each realm differently:
expose( context(({ origin }) => resolvers(idFor(origin))), { transport },)A wrapper rather than “pass a function”, because osra exposes functions as endpoints, so a bare
typeof value === 'function' cannot tell a per-peer factory from a plain function value.
What the read side needs is not declared here: connection: sees the same context and derives its
own.
Type Parameters
Section titled “Type Parameters”TValue
Section titled “TValue”TValue
Parameters
Section titled “Parameters”(ctx: Context) => TValue
Returns
Section titled “Returns”Contextual<TValue>
relay()
Section titled “relay()”Guide: Low-level API
function relay(transportA: Transport, transportB: Transport, __namedParameters?: RelayOptions): voidDefined in: connections/relay.ts:22
Parameters
Section titled “Parameters”transportA
Section titled “transportA”transportB
Section titled “transportB”__namedParameters?
Section titled “__namedParameters?”RelayOptions = {}
Returns
Section titled “Returns”void
startConnections()
Section titled “startConnections()”function startConnections<T, TModules, TResult>( value: Capable<TModules> | Contextual<Capable<TModules>>, __namedParameters: StartConnectionsOptions<TModules>,): Exposed<TResult>Defined in: connections/index.ts:74
Type Parameters
Section titled “Type Parameters”T = unknown
TModules
Section titled “TModules”TModules extends readonly RevivableModule[] = readonly [__module, __module, __module, __module, __module, __module, __module, __module, __module, __module, __module, __module, __module, __module, __module, __module, __module, __module, __module, __module, __module, {
box: (value: number, context: RevivableContext<any>) => number | BoxedNonFiniteNumber;
isType: (value: unknown) => value is number;
revive: (value: BoxedNonFiniteNumber, _context: RevivableContext<any>) => number;
type: "nonFiniteNumber";
}, {
box: (value: undefined, context: RevivableContext<any>) => BoxedUndefined | undefined;
isType: (value: unknown) => value is undefined;
revive: (_value: BoxedUndefined, _context: RevivableContext<any>) => undefined;
type: "undefined";
}, {
box: (value: Clonable, _context: RevivableContext<any>) => Clonable;
capableOnly: true;
isType: (value: unknown) => value is Clonable;
objectsOnly: true;
revive: (value: BoxedClonable, _context: RevivableContext<any>) => Clonable;
type: "clonable";
}, {
box: (value: Transferable, _context: RevivableContext<any>) => Transferable;
capableOnly: true;
isType: (value: unknown) => value is Transferable;
objectsOnly: true;
revive: (value: BoxedTransferable, _context: RevivableContext<any>) => Transferable;
type: "transferable";
}, {
box: (value: Blob, context: RevivableContext<any>) => Blob;
capableOnly: true;
isType: (value: unknown) => value is Blob;
objectsOnly: true;
revive: (value: BoxedBlob, _context: RevivableContext<any>) => Blob;
type: "blob";
}, __module, {
box: (_value: never, _context: RevivableContext<any>) => BoxedUnclonable;
isType: (value: unknown) => value is never;
objectsOnly: true;
revive: (_value: BoxedUnclonable, _context: RevivableContext<any>) => Record<string, never>;
type: "unclonable";
}]
TResult
Section titled “TResult”TResult = T
Parameters
Section titled “Parameters”| Capable<TModules>
| Contextual<Capable<TModules>>
__namedParameters
Section titled “__namedParameters”StartConnectionsOptions<TModules>
Returns
Section titled “Returns”Exposed<TResult>
Type Aliases
Section titled “Type Aliases”BidirectionalConnection
Section titled “BidirectionalConnection”type BidirectionalConnection<TModules> = { remoteValue: Promise<Capable> revivableContext: ConnectionRevivableContext<TModules>}Defined in: connections/bidirectional.ts:102
Type Parameters
Section titled “Type Parameters”TModules
Section titled “TModules”TModules extends readonly RevivableModule[] = DefaultRevivableModules
Properties
Section titled “Properties”remoteValue
Section titled “remoteValue”remoteValue: Promise<Capable>Defined in: connections/bidirectional.ts:106
revivableContext
Section titled “revivableContext”revivableContext: ConnectionRevivableContext<TModules>Defined in: connections/bidirectional.ts:105
Connected
Section titled “Connected”Guide: TypeScript
type Connected<TValue> = { context: Context value: TValue}Defined in: connections/utils.ts:122
An established connection: the value that realm exposed, and what this side knows about the realm
it came from. context is whatever the transport observed, plus an abort that drops this one
peer. Anything derived from it is the caller’s to compute, in the value factory or in
connection:, rather than something to declare up front.
Type Parameters
Section titled “Type Parameters”TValue
Section titled “TValue”TValue
Properties
Section titled “Properties”context
Section titled “context”context: ContextDefined in: connections/utils.ts:124
value: TValueDefined in: connections/utils.ts:123
ConnectionContext
Section titled “ConnectionContext”type ConnectionContext<TModules> = BidirectionalConnectionContext<TModules>Defined in: connections/index.ts:69
Type Parameters
Section titled “Type Parameters”TModules
Section titled “TModules”TModules extends readonly RevivableModule[] = DefaultRevivableModules
ConnectionMessage
Section titled “ConnectionMessage”type ConnectionMessage<TModules, T> = DefaultConnectionModule extends { Messages: (modules: TModules, value: T) => infer R} ? R : neverDefined in: connections/index.ts:59
Type Parameters
Section titled “Type Parameters”TModules
Section titled “TModules”TModules extends readonly RevivableModule[] = DefaultRevivableModules
T extends Capable<TModules> = Capable<TModules>
ConnectionModule
Section titled “ConnectionModule”type ConnectionModule<T> = { init: (ctx: ProtocolContext<any>) => void Messages?: T type: string}Defined in: connections/index.ts:44
Type Parameters
Section titled “Type Parameters”T
Properties
Section titled “Properties”readonly init: (ctx: ProtocolContext<any>) => void;Defined in: connections/index.ts:47
Parameters
Section titled “Parameters”ProtocolContext<any>
Returns
Section titled “Returns”void
Messages?
Section titled “Messages?”readonly optional Messages?: T;Defined in: connections/index.ts:48
readonly type: string;Defined in: connections/index.ts:45
ConnectionQueue
Section titled “ConnectionQueue”type ConnectionQueue<TRemote> = { close: () => void iterate: () => AsyncIterableIterator<Connected<TRemote>> push: (connection: Connected<TRemote>) => void}Defined in: connections/utils.ts:134
Type Parameters
Section titled “Type Parameters”TRemote
Section titled “TRemote”TRemote
Properties
Section titled “Properties”close: () => void;Defined in: connections/utils.ts:136
Returns
Section titled “Returns”void
iterate
Section titled “iterate”iterate: () => AsyncIterableIterator<Connected<TRemote>>Defined in: connections/utils.ts:137
Returns
Section titled “Returns”AsyncIterableIterator<Connected<TRemote>>
push: (connection: Connected<TRemote>) => void;Defined in: connections/utils.ts:135
Parameters
Section titled “Parameters”connection
Section titled “connection”Connected<TRemote>
Returns
Section titled “Returns”void
ConnectionRevivableContext
Section titled “ConnectionRevivableContext”type ConnectionRevivableContext<TModules> = { eventTarget: MessageEventTarget<TModules> remoteUuid: Uuid revivableModules: TModules sendMessage: (message: MessageFields & Record<string, unknown>) => void transport: Transport}Defined in: connections/bidirectional.ts:44
Type Parameters
Section titled “Type Parameters”TModules
Section titled “TModules”TModules extends readonly RevivableModule[] = DefaultRevivableModules
Properties
Section titled “Properties”eventTarget
Section titled “eventTarget”eventTarget: MessageEventTarget<TModules>Defined in: connections/bidirectional.ts:51
remoteUuid
Section titled “remoteUuid”remoteUuid: UuidDefined in: connections/bidirectional.ts:48
revivableModules
Section titled “revivableModules”revivableModules: TModulesDefined in: connections/bidirectional.ts:50
sendMessage
Section titled “sendMessage”sendMessage: (message: MessageFields & Record<string, unknown>) => void;Defined in: connections/bidirectional.ts:49
Parameters
Section titled “Parameters”message
Section titled “message”MessageFields & Record<string, unknown>
Returns
Section titled “Returns”void
transport
Section titled “transport”transport: TransportDefined in: connections/bidirectional.ts:47
Contextual
Section titled “Contextual”Guide: Connections
type Contextual<TValue> = { [CONTEXT]: (ctx: Context) => TValue}Defined in: connections/utils.ts:245
Type Parameters
Section titled “Type Parameters”TValue
Section titled “TValue”TValue
Properties
Section titled “Properties”[CONTEXT]
Section titled “[CONTEXT]”[CONTEXT]: (ctx: Context) => TValue;Defined in: connections/utils.ts:246
Parameters
Section titled “Parameters”Returns
Section titled “Returns”TValue
DefaultConnectionModule
Section titled “DefaultConnectionModule”type DefaultConnectionModule = DefaultConnectionModules[number]Defined in: connections/index.ts:57
DefaultConnectionModules
Section titled “DefaultConnectionModules”type DefaultConnectionModules = typeof connectionsDefined in: connections/index.ts:56
Exposed
Section titled “Exposed”Guide: TypeScript
type Exposed<TResult> = Promise<TResult> & AsyncIterable<TResult>Defined in: connections/utils.ts:132
The result of expose. Awaiting it gives the first peer, iterating it gives every peer as it
connects, and both hand back the same thing: one shape, read once or read repeatedly.
What that shape IS comes from the connection: option. Without one it is the peer’s value, which
is what expose has always resolved to. With one it is whatever that function returns.
Type Parameters
Section titled “Type Parameters”TResult
Section titled “TResult”TResult
InitMessage
Section titled “InitMessage”type InitMessage<TModules, T> = { data: DeepReplaceWithBox<T, TModules[number]> remoteUuid: Uuid type: 'init'}Defined in: connections/bidirectional.ts:16
Type Parameters
Section titled “Type Parameters”TModules
Section titled “TModules”TModules extends readonly RevivableModule[] = DefaultRevivableModules
T extends Capable<TModules> = Capable<TModules>
Properties
Section titled “Properties”data: DeepReplaceWithBox<T, TModules[number]>Defined in: connections/bidirectional.ts:22
remoteUuid
Section titled “remoteUuid”remoteUuid: UuidDefined in: connections/bidirectional.ts:21
type: 'init'Defined in: connections/bidirectional.ts:20
Messages
Section titled “Messages”type Messages = <TModules, T>(modules: TModules, value: T) => InitMessage<TModules, T>Defined in: connections/bidirectional.ts:25
Type Parameters
Section titled “Type Parameters”TModules
Section titled “TModules”TModules extends readonly RevivableModule[] = readonly [__module, __module, __module, __module, __module, __module, __module, __module, __module, __module, __module, __module, __module, __module, __module, __module, __module, __module, __module, __module, __module, {
box: (value: number, context: RevivableContext<any>) => number | BoxedNonFiniteNumber;
isType: (value: unknown) => value is number;
revive: (value: BoxedNonFiniteNumber, _context: RevivableContext<any>) => number;
type: "nonFiniteNumber";
}, {
box: (value: undefined, context: RevivableContext<any>) => BoxedUndefined | undefined;
isType: (value: unknown) => value is undefined;
revive: (_value: BoxedUndefined, _context: RevivableContext<any>) => undefined;
type: "undefined";
}, {
box: (value: Clonable, _context: RevivableContext<any>) => Clonable;
capableOnly: true;
isType: (value: unknown) => value is Clonable;
objectsOnly: true;
revive: (value: BoxedClonable, _context: RevivableContext<any>) => Clonable;
type: "clonable";
}, {
box: (value: Transferable, _context: RevivableContext<any>) => Transferable;
capableOnly: true;
isType: (value: unknown) => value is Transferable;
objectsOnly: true;
revive: (value: BoxedTransferable, _context: RevivableContext<any>) => Transferable;
type: "transferable";
}, {
box: (value: Blob, context: RevivableContext<any>) => Blob;
capableOnly: true;
isType: (value: unknown) => value is Blob;
objectsOnly: true;
revive: (value: BoxedBlob, _context: RevivableContext<any>) => Blob;
type: "blob";
}, __module, {
box: (_value: never, _context: RevivableContext<any>) => BoxedUnclonable;
isType: (value: unknown) => value is never;
objectsOnly: true;
revive: (_value: BoxedUnclonable, _context: RevivableContext<any>) => Record<string, never>;
type: "unclonable";
}]
T extends any = Capable<TModules>
Parameters
Section titled “Parameters”modules
Section titled “modules”TModules
T
Returns
Section titled “Returns”InitMessage<TModules, T>
Messages
Section titled “Messages”type Messages<TModules, T> = ReturnType<typeof Messages>Defined in: connections/bidirectional.ts:25
Type Parameters
Section titled “Type Parameters”TModules
Section titled “TModules”TModules extends readonly RevivableModule[] = DefaultRevivableModules
T extends Capable<TModules> = Capable<TModules>
ProtocolContext
Section titled “ProtocolContext”type ProtocolContext<TModules> = { abortConnection: (remoteUuid: Uuid) => void addConnection: (ctx: Context, value: Capable<TModules>) => void claimPendingAbort: (remoteUuid: Uuid) => boolean connectionContexts: Map<string, ConnectionContext<TModules>> createConnectionEventTarget: () => TypedEventTarget<MessageEventMap<TModules>> getUuid: () => Uuid presetRemoteUuid?: Uuid protocolEventTarget: ProtocolEventTarget<TModules> rejectRemoteValue: (error: unknown) => void revivableModules: TModules sendMessage: (message: MessageVariant, targetOrigin?: string) => void transport: Transport unregisterSignal?: AbortSignal valueFor: (peer: Context) => Capable<TModules>}Defined in: connections/utils.ts:54
Type Parameters
Section titled “Type Parameters”TModules
Section titled “TModules”TModules extends readonly RevivableModule[] = DefaultRevivableModules
Properties
Section titled “Properties”abortConnection
Section titled “abortConnection”abortConnection: (remoteUuid: Uuid) => void;Defined in: connections/utils.ts:74
tears down one connection: close to the peer, teardown locally, drop it from tracking
Parameters
Section titled “Parameters”remoteUuid
Section titled “remoteUuid”Returns
Section titled “Returns”void
addConnection
Section titled “addConnection”addConnection: (ctx: Context, value: Capable<TModules>) => void;Defined in: connections/utils.ts:72
reports an established connection: settles the first-connection promise and feeds iteration, so a caller sees every realm rather than only the one that happened to connect first
Parameters
Section titled “Parameters”Capable<TModules>
Returns
Section titled “Returns”void
claimPendingAbort
Section titled “claimPendingAbort”claimPendingAbort: (remoteUuid: Uuid) => booleanDefined in: connections/utils.ts:76
true when this uuid was aborted before it was registered, which means refuse the registration
Parameters
Section titled “Parameters”remoteUuid
Section titled “remoteUuid”Returns
Section titled “Returns”boolean
connectionContexts
Section titled “connectionContexts”connectionContexts: Map<string, ConnectionContext<TModules>>Defined in: connections/utils.ts:62
createConnectionEventTarget
Section titled “createConnectionEventTarget”createConnectionEventTarget: () => TypedEventTarget<MessageEventMap<TModules>>Defined in: connections/utils.ts:77
Returns
Section titled “Returns”TypedEventTarget<MessageEventMap<TModules>>
getUuid
Section titled “getUuid”getUuid: () => UuidDefined in: connections/utils.ts:63
Returns
Section titled “Returns”presetRemoteUuid?
Section titled “presetRemoteUuid?”optional presetRemoteUuid?: Uuid;Defined in: connections/utils.ts:64
protocolEventTarget
Section titled “protocolEventTarget”protocolEventTarget: ProtocolEventTarget<TModules>Defined in: connections/utils.ts:68
rejectRemoteValue
Section titled “rejectRemoteValue”rejectRemoteValue: (error: unknown) => void;Defined in: connections/utils.ts:69
Parameters
Section titled “Parameters”unknown
Returns
Section titled “Returns”void
revivableModules
Section titled “revivableModules”revivableModules: TModulesDefined in: connections/utils.ts:61
sendMessage
Section titled “sendMessage”sendMessage: (message: MessageVariant, targetOrigin?: string) => void;Defined in: connections/utils.ts:67
targetOrigin overrides the configured origin for this one send - only the unsolicited announce beacon broadcasts with ‘*’.
Parameters
Section titled “Parameters”message
Section titled “message”targetOrigin?
Section titled “targetOrigin?”string
Returns
Section titled “Returns”void
transport
Section titled “transport”transport: TransportDefined in: connections/utils.ts:57
unregisterSignal?
Section titled “unregisterSignal?”optional unregisterSignal?: AbortSignal;Defined in: connections/utils.ts:78
valueFor
Section titled “valueFor”valueFor: (peer: Context) => Capable<TModules>Defined in: connections/utils.ts:60
The exposed value for ONE peer. A factory rather than a value so a server can answer each realm differently (scoped resolvers per origin) instead of sharing one object across every connection.
Parameters
Section titled “Parameters”Returns
Section titled “Returns”Capable<TModules>
ProtocolEventMap
Section titled “ProtocolEventMap”type ProtocolEventMap<TModules> = { message: CustomEvent<{ message: Message<TModules> peer: () => Context }>}Defined in: connections/utils.ts:43
Type Parameters
Section titled “Type Parameters”TModules
Section titled “TModules”TModules extends readonly RevivableModule[] = DefaultRevivableModules
Properties
Section titled “Properties”message
Section titled “message”message: CustomEvent<{ message: Message<TModules> peer: () => Context}>Defined in: connections/utils.ts:47
ProtocolEventTarget
Section titled “ProtocolEventTarget”type ProtocolEventTarget<TModules> = TypedEventTarget<ProtocolEventMap<TModules>>Defined in: connections/utils.ts:50
Type Parameters
Section titled “Type Parameters”TModules
Section titled “TModules”TModules extends readonly RevivableModule[] = DefaultRevivableModules
RelayOptions
Section titled “RelayOptions”Guide: Low-level API
type RelayOptions = { key?: string nameA?: string nameB?: string origin?: string originA?: string originB?: string unregisterSignal?: AbortSignal}Defined in: connections/relay.ts:12
Properties
Section titled “Properties”optional key?: string;Defined in: connections/relay.ts:13
nameA?
Section titled “nameA?”optional nameA?: string;Defined in: connections/relay.ts:17
nameB?
Section titled “nameB?”optional nameB?: string;Defined in: connections/relay.ts:18
origin?
Section titled “origin?”optional origin?: string;Defined in: connections/relay.ts:14
originA?
Section titled “originA?”optional originA?: string;Defined in: connections/relay.ts:15
originB?
Section titled “originB?”optional originB?: string;Defined in: connections/relay.ts:16
unregisterSignal?
Section titled “unregisterSignal?”optional unregisterSignal?: AbortSignal;Defined in: connections/relay.ts:19
StartConnectionsOptions
Section titled “StartConnectionsOptions”type StartConnectionsOptions<TModules> = { connection?: (connected: Connected<unknown>) => unknown key?: string name?: string origin?: string remoteName?: string remoteUuid?: Uuid revivableModules?: (defaults: DefaultRevivableModules) => TModules transport: Transport unregisterSignal?: AbortSignal uuid?: Uuid}Defined in: connections/utils.ts:81
Type Parameters
Section titled “Type Parameters”TModules
Section titled “TModules”TModules extends readonly RevivableModule[] = DefaultRevivableModules
Properties
Section titled “Properties”connection?
Section titled “connection?”optional connection?: (connected: Connected<unknown>) => unknown;Defined in: connections/utils.ts:115
Decides what one connection resolves to, for the await and for iteration alike. Omit it and that
is the peer’s value, which is what expose has always given back:
const remote = await expose(api, { transport })
const { value, context } = await expose(api, { transport, connection: ({ value, context }) => ({ value, context }),})
for await (const origin of expose(api, { transport, connection: ({ context }) => context.origin,})) {}It runs per connection, on this side, after the handshake. It cannot change what is sent, and nothing it returns crosses the wire.
Parameters
Section titled “Parameters”connected
Section titled “connected”Connected<unknown>
Returns
Section titled “Returns”unknown
optional key?: string;Defined in: connections/utils.ts:87
optional name?: string;Defined in: connections/utils.ts:85
origin?
Section titled “origin?”optional origin?: string;Defined in: connections/utils.ts:88
remoteName?
Section titled “remoteName?”optional remoteName?: string;Defined in: connections/utils.ts:86
remoteUuid?
Section titled “remoteUuid?”optional remoteUuid?: Uuid;Defined in: connections/utils.ts:95
revivableModules?
Section titled “revivableModules?”optional revivableModules?: (defaults: DefaultRevivableModules) => TModules;Defined in: connections/utils.ts:93
Configure the revivable module list. Receives the defaults and returns the final ordered list - add modules, drop defaults, reorder, or override per-type as needed.
Parameters
Section titled “Parameters”defaults
Section titled “defaults”Returns
Section titled “Returns”TModules
transport
Section titled “transport”transport: TransportDefined in: connections/utils.ts:84
unregisterSignal?
Section titled “unregisterSignal?”optional unregisterSignal?: AbortSignal;Defined in: connections/utils.ts:89
optional uuid?: Uuid;Defined in: connections/utils.ts:94