Revivables

Functions

boxBuffer()

function boxBuffer<TCtx>(buffer: ArrayBuffer, context: TCtx): BoxedBuffer<TCtx>

Defined in: revivables/utils.ts:75

Type Parameters

TCtx

TCtx extends RevivableContext<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"; }]>

Parameters

buffer

ArrayBuffer

context

TCtx

Returns

BoxedBuffer<TCtx>

---

boxClaimedValue()

function boxClaimedValue<T, TModules>(
  value: T,
  context: RevivableContext<TModules>,
  claimedBy: string,
): DeepReplaceWithBox<T, TModules[number]>

Defined in: revivables/index.ts:221

Box a value your own module claimed in place: every other module gets its turn and children are walked as usual, but claimedBy is skipped, and the cycle guard the caller’s recursiveBox frame already holds for this value is not re-entered. A module needs this when its isType matches a bare value rather than a wrapper around one, the way identity() marks a reference in place: recursiveBox on that same value would come straight back to the module, and the guard would report it as a cycle.

Type Parameters

T

T extends Capable

TModules

TModules extends readonly RevivableModule<string, any, any, MessageFields>[]

Parameters

value

T

context

RevivableContext<TModules>

claimedBy

string

Returns

DeepReplaceWithBox<T, TModules[number]>

---

identity()

Guide: identity() and transfer()

function identity<T>(value: T): T

Defined in: revivables/identity.ts:67

Mark a value so osra preserves its reference identity across the boundary. The peer’s revived value stands for this one, and handing it back - to you, or onward to a further context and back again - resolves to this very reference. The mark sticks to the value, so only the side that owns it has to opt in. Idempotent, and primitives pass through unchanged.

Type Parameters

T

T

Parameters

value

T

Returns

T

---

isRevivableBox()

Guide: Low-level API

function isRevivableBox(value: unknown): value is BoxBase<string>

Defined in: revivables/utils.ts:63

Parameters

value

unknown

Returns

value is BoxBase<string>

---

onBoxWalkSettled()

function onBoxWalkSettled(commit: () => void, rollback: () => void): void

Defined in: revivables/index.ts:130

Hold a side effect until the whole box walk this value belongs to has finished, and undo it if the walk throws. A module that records state the PEER will be told about (“it knows this id now”) must not keep that record when a later sibling breaks the message it was recorded for: nothing ships, and every later send would then reference something the peer never received. Outside a walk the effect is already settled, so commit runs immediately.

Parameters

commit

() => void

rollback

() => void

Returns

void

---

recursiveBox()

Guide: Low-level API

function recursiveBox<T, TModules>(
  value: T,
  context: RevivableContext<TModules>,
): DeepReplaceWithBox<T, TModules[number]>

Defined in: revivables/index.ts:186

Type Parameters

T

T extends Capable

TModules

TModules extends readonly RevivableModule<string, any, any, MessageFields>[]

Parameters

value

T

context

RevivableContext<TModules>

Returns

DeepReplaceWithBox<T, TModules[number]>

---

recursiveRevive()

Guide: Low-level API

function recursiveRevive<T, TModules>(
  value: T,
  context: RevivableContext<TModules>,
): DeepReplaceWithRevive<T, TModules[number]>

Defined in: revivables/index.ts:231

Type Parameters

T

T extends Capable

TModules

TModules extends readonly RevivableModule<string, any, any, MessageFields>[]

Parameters

value

T

context

RevivableContext<TModules>

Returns

DeepReplaceWithRevive<T, TModules[number]>

---

reviveBuffer()

function reviveBuffer(
  boxed:
    | {
        arrayBuffer: ArrayBuffer
      }
    | {
        base64Buffer: string
      },
): ArrayBuffer

Defined in: revivables/utils.ts:84

Parameters

boxed

| { arrayBuffer: ArrayBuffer; } | { base64Buffer: string; }

Returns

ArrayBuffer

---

transfer()

Guide: identity() and transfer()

function transfer<T>(value: T): T

Defined in: revivables/transfer.ts:56

Opt into transfer (move) semantics for a transferable value. Idempotent; non-transferable inputs pass through unchanged. Silently degrades to a copy when the platform/transport can’t transfer the given type. Lies at the type level - runtime value is a TransferWrapper<T> typed as T.

Type Parameters

T

T

Parameters

value

T

Returns

T

Type Aliases

BoxBase

Guide: Custom revivables

type BoxBase<T> = typeof BoxBase & {
  type: T
}

Defined in: revivables/utils.ts:16

Type Declaration

type

type: T

Type Parameters

T

T extends string = string

---

BoxedBuffer

type BoxedBuffer<TCtx> =
  IsJsonOnlyTransport<TCtx['transport']> extends true
    ? {
        base64Buffer: string
      }
    : IsJsonOnlyTransport<TCtx['transport']> extends false
      ? {
          arrayBuffer: ArrayBuffer
        }
      : | {
            base64Buffer: string
          }
        | {
            arrayBuffer: ArrayBuffer
          }

Defined in: revivables/utils.ts:70

Wire shape for an ArrayBuffer: base64 on JSON, raw on clone.

Type Parameters

TCtx

TCtx extends RevivableContext = RevivableContext

---

DefaultRevivableModule

type DefaultRevivableModule = DefaultRevivableModules[number]

Defined in: revivables/index.ts:93

---

DefaultRevivableModules

type DefaultRevivableModules = typeof defaultRevivableModules

Defined in: revivables/index.ts:92

---

ExtractMessages

type ExtractMessages<T> = T extends {
  Messages?: infer B
}
  ? B extends {
      type: string
    }
    ? string extends B['type']
      ? never
      : B
    : never
  : never

Defined in: revivables/utils.ts:47

Type Parameters

T

T

---

ExtractType

type ExtractType<T, Ctx> = T extends {
  capableOnly: true
}
  ? IsJsonOnlyTransport<Ctx['transport']> extends true
    ? never
    : T extends {
          isType: (value: unknown) => value is infer S
        }
      ? S
      : never
  : T extends {
        isType: (value: unknown) => value is infer S
      }
    ? S
    : never

Defined in: revivables/utils.ts:40

Extract the type a module’s isType narrows to. Modules marked capableOnly: true (clonable, transferable) contribute never on JSON transports so users can’t type values JSON would silently drop.

Type Parameters

T

T

Ctx

Ctx extends RevivableContext = RevivableContext

---

InferMessages

type InferMessages<TModules> = ExtractMessages<TModules[number]>

Defined in: revivables/utils.ts:54

Type Parameters

TModules

TModules extends readonly unknown[]

---

InferRevivables

type InferRevivables<TModules, Ctx> = ExtractType<TModules[number], Ctx>

Defined in: revivables/utils.ts:57

Type Parameters

TModules

TModules extends readonly unknown[]

Ctx

Ctx extends RevivableContext = RevivableContext

---

RevivableContext

Guide: Custom revivables

type RevivableContext<TModules> = {
  eventTarget: MessageEventTarget<TModules>
  remoteUuid: Uuid
  revivableModules: TModules
  sendMessage: (message: MessageFields & Record<string, unknown>) => void
  transport: Transport
}

Defined in: revivables/utils.ts:24

Type Parameters

TModules

TModules extends readonly RevivableModule[] = DefaultRevivableModules

Properties

eventTarget

eventTarget: MessageEventTarget<TModules>

Defined in: revivables/utils.ts:34

remoteUuid

remoteUuid: Uuid

Defined in: revivables/utils.ts:28

revivableModules

revivableModules: TModules

Defined in: revivables/utils.ts:33

sendMessage

sendMessage: (message: MessageFields & Record<string, unknown>) => void;

Defined in: revivables/utils.ts:32

Typed as a broad dispatcher so revivables can post their own message variants without triggering contravariant function-parameter mismatches across modules. The shape is enforced structurally via MessageFields.

Parameters

message

MessageFields & Record<string, unknown>

Returns

void

transport

transport: Transport

Defined in: revivables/utils.ts:27

---

RevivableModule

Guide: Custom revivables

type RevivableModule<T, T2, T3, T4> = {
  box: ((value: T2, context: RevivableContext<any>) => T3) | ((...args: any[]) => any)
  init?: (context: RevivableContext<any>) => void
  isType: (value: unknown) => value is T2
  Messages?: T4
  objectsOnly?: boolean
  revive: (value: T3, context: RevivableContext<any>) => T2
  type: T
}

Defined in: revivables/index.ts:37

Type Parameters

T

T extends string = string

T2

T2 = any

T3

T3 extends BoxBase<T> = any

T4

T4 extends MessageFields = MessageFields

Properties

box

readonly box:
  | ((value: T2, context: RevivableContext<any>) => T3)
  | ((...args: any[]) => any);

Defined in: revivables/index.ts:51

init?

readonly optional init?: (context: RevivableContext<any>) => void;

Defined in: revivables/index.ts:53

Parameters

context

RevivableContext<any>

Returns

void

isType

readonly isType: (value: unknown) => value is T2;

Defined in: revivables/index.ts:44

Parameters

value

unknown

Returns

value is T2

Messages?

readonly optional Messages?: T4;

Defined in: revivables/index.ts:54

objectsOnly?

readonly optional objectsOnly?: boolean;

Defined in: revivables/index.ts:50

Declare true when isType never claims a primitive (string, number, boolean, bigint, symbol, undefined, null). The walker then skips the module for primitive leaves, which is most of what a large payload is made of. Leaving it off is always safe: the default is to call isType for every value, exactly as before. objectsOnlyFlagsAreHonest in the suite calls every flagged module with a set of primitives and fails if one of them says yes.

revive

readonly revive: (value: T3, context: RevivableContext<any>) => T2;

Defined in: revivables/index.ts:52

Parameters

value

T3

context

RevivableContext<any>

Returns

T2

type

readonly type: T;

Defined in: revivables/index.ts:43

Variables

BoxBase

Guide: Custom revivables

const BoxBase: {
  __OSRA_BOX__: 'revivable'
}

Defined in: revivables/utils.ts:16

Type Declaration

__OSRA_BOX__

readonly __OSRA_BOX__: "revivable" = 'revivable';

---

defaultRevivableModules

Guide: Custom revivables

const defaultRevivableModules: 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'
  },
]

Defined in: revivables/index.ts:57