Utilities

Functions

createTypedEventTarget()

function createTypedEventTarget<T>(): TypedEventTarget<T>

Defined in: utils/typed-event-target.ts:37

Create a new TypedEventTarget<T> for a given event map. Centralises the EventTarget → TypedEventTarget<T> cast so individual call sites don’t each need their own (EventTarget lacks the generic event map at the type level, but the runtime behaviour is identical).

Type Parameters

T

T extends EventMap

Returns

TypedEventTarget<T>

getTransferableObjects()

Guide: Low-level API

function getTransferableObjects(value: unknown): Transferable[]

Defined in: utils/transferable.ts:33

Walk a boxed message and collect Transferables to move (rather than copy) on postMessage:

Must-transfer types are always included.
Clonable types (SharedArrayBuffer) are skipped.
Other Transferables are included only inside a non-degraded transfer box (user opted in AND the platform supports transferring).

Parameters

value

unknown

Returns

Transferable[]

isTornDown()

function isTornDown(scope: WeakKey): boolean

Defined in: utils/teardown.ts:23

Whether a scope’s teardown has already run. Callers use this to REFUSE work rather than start it: onTeardown against a dead scope runs the callback immediately, which is a footgun inside an initializer, and anything registered afterwards is state no teardown will ever visit again.

Parameters

scope

WeakKey

Returns

boolean

onTeardown()

function onTeardown(scope: WeakKey, fn: () => void): () => void

Defined in: utils/teardown.ts:9

Parameters

scope

WeakKey

fn

() => void

Returns

() => void

trackGc()

function trackGc(target: WeakKey, cleanup: () => void): GcUnregister

Defined in: utils/gc-tracker.ts:25

Parameters

target

WeakKey

cleanup

() => void

Returns

GcUnregister

Classes

EventChannel

Defined in: utils/event-channel.ts:130

Type Parameters

T1

T1 = unknown

T2

T2 = unknown

Constructors

Constructor

new EventChannel<T1, T2>(): EventChannel<T1, T2>;

Defined in: utils/event-channel.ts:134

Returns

EventChannel<T1, T2>

Properties

port1

readonly port1: EventPort<T1>;

Defined in: utils/event-channel.ts:131

port2

readonly port2: EventPort<T2>;

Defined in: utils/event-channel.ts:132

EventPort

Defined in: utils/event-channel.ts:6

Extends

Omit<TypedMessagePort<T>, "addEventListener" | "removeEventListener">

Type Parameters

T

T

Accessors

onmessage

Get Signature

get onmessage():
  | ((this: MessagePort, ev: MessageEvent<T>) => unknown)
  | null;

Defined in: utils/event-channel.ts:60

Returns

| ((this: MessagePort, ev: MessageEvent<T>) => unknown) | null

Set Signature

set onmessage(value:
  | ((this: MessagePort, ev: MessageEvent<T>) => unknown)
  | null): void;

Defined in: utils/event-channel.ts:63

Parameters

value

| ((this: MessagePort, ev: MessageEvent<T>) => unknown) | null

Returns

void

Constructors

Constructor

new EventPort<T>(): EventPort<T>;

Returns

EventPort<T>

Methods

addEventListener()

Call Signature

addEventListener<K>(
   type: K,
   listener:
  | ((event: TypedMessagePortEventMap<T>[K]) => void)
  | null,
   options?: boolean | AddEventListenerOptions): void;

Defined in: utils/event-channel.ts:10

Type Parameters

K

K extends "close" | "message" | "messageerror"

Parameters

type

K

listener

| ((event: TypedMessagePortEventMap<T>[K]) => void) | null

options?

boolean | AddEventListenerOptions

Returns

void

Call Signature

addEventListener(
   type: string,
   listener: EventListenerOrEventListenerObject | null,
   options?: boolean | AddEventListenerOptions): void;

Defined in: utils/event-channel.ts:15

Parameters

type

string

listener

EventListenerOrEventListenerObject | null

options?

boolean | AddEventListenerOptions

Returns

void

close()

close(): void;

Defined in: utils/event-channel.ts:109

Returns

void

dispatchEvent()

dispatchEvent(event: Event): boolean;

Defined in: utils/event-channel.ts:70

Parameters

event

Event

Returns

boolean

postMessage()

postMessage(message: T, _options?: Transferable[] | StructuredSerializeOptions): void;

Defined in: utils/event-channel.ts:87

Parameters

message

T

_options?

Transferable[] | StructuredSerializeOptions

Returns

void

removeEventListener()

Call Signature

removeEventListener<K>(
   type: K,
   listener:
  | ((event: TypedMessagePortEventMap<T>[K]) => void)
  | null,
   options?: boolean | EventListenerOptions): void;

Defined in: utils/event-channel.ts:33

Type Parameters

K

K extends "close" | "message" | "messageerror"

Parameters

type

K

listener

| ((event: TypedMessagePortEventMap<T>[K]) => void) | null

options?

boolean | EventListenerOptions

Returns

void

Call Signature

removeEventListener(
   type: string,
   listener: EventListenerOrEventListenerObject | null,
   options?: boolean | EventListenerOptions): void;

Defined in: utils/event-channel.ts:38

Parameters

type

string

listener

EventListenerOrEventListenerObject | null

options?

boolean | EventListenerOptions

Returns

void

start()

start(): void;

Defined in: utils/event-channel.ts:101

Returns

void

Properties

_closed

_closed: boolean = false

Defined in: utils/event-channel.ts:55

_onClose

_onClose: (() => void) | undefined;

Defined in: utils/event-channel.ts:56

_peer

_peer: EventPort<any> | undefined

Defined in: utils/event-channel.ts:52

_queue

_queue: MessageEvent<T>[] = [];

Defined in: utils/event-channel.ts:53

_started

_started: boolean = false

Defined in: utils/event-channel.ts:54

[UnderlyingType]?

optional [UnderlyingType]?: T;

Defined in: utils/typed-message-channel.ts:15

onmessageerror

onmessageerror: ((this: MessagePort, ev: MessageEvent) => unknown) | null = null;

Defined in: utils/event-channel.ts:68

Interfaces

TypedEventTarget

Defined in: utils/typed-event-target.ts:5

Extends

EventTarget

Type Parameters

T

T extends EventMap

Methods

addEventListener()

Call Signature

addEventListener<K>(
   type: K,
   listener: ((event: T[K]) => void) | null,
   options?: boolean | AddEventListenerOptions): void;

Defined in: utils/typed-event-target.ts:8

The addEventListener() method of the EventTarget interface sets up a function that will be called whenever the specified event is delivered to the target.

MDN Reference

Type Parameters

K

K extends string

Parameters

type

K

listener

((event: T[K]) => void) | null

options?

boolean | AddEventListenerOptions

Returns

void

Overrides

EventTarget.addEventListener

Call Signature

addEventListener(
   type: string,
   listener: EventListenerOrEventListenerObject | null,
   options?: boolean | AddEventListenerOptions): void;

Defined in: utils/typed-event-target.ts:13

The addEventListener() method of the EventTarget interface sets up a function that will be called whenever the specified event is delivered to the target.

MDN Reference

Parameters

type

string

listener

EventListenerOrEventListenerObject | null

options?

boolean | AddEventListenerOptions

Returns

void

Overrides

EventTarget.addEventListener

removeEventListener()

Call Signature

removeEventListener<K>(
   type: K,
   listener: ((event: T[K]) => void) | null,
   options?: boolean | EventListenerOptions): void;

Defined in: utils/typed-event-target.ts:19

The removeEventListener() method of the EventTarget interface removes an event listener previously registered with EventTarget.addEventListener() from the target. The event listener to be removed is identified using a combination of the event type, the event listener function itself, and various optional options that may affect the matching process; see Matching event listeners for removal.

MDN Reference

Type Parameters

K

K extends string

Parameters

type

K

listener

((event: T[K]) => void) | null

options?

boolean | EventListenerOptions

Returns

void

Overrides

EventTarget.removeEventListener

Call Signature

removeEventListener(
   type: string,
   listener: EventListenerOrEventListenerObject | null,
   options?: boolean | EventListenerOptions): void;

Defined in: utils/typed-event-target.ts:24

MDN Reference

Parameters

type

string

listener

EventListenerOrEventListenerObject | null

options?

boolean | EventListenerOptions

Returns

void

Overrides

EventTarget.removeEventListener

Properties

[UnderlyingType]?

optional [UnderlyingType]?: T;

Defined in: utils/typed-event-target.ts:6

TypedMessageChannel

Defined in: utils/typed-message-channel.ts:27

Type Parameters

T1

T1 = unknown

T2

T2 = unknown

Properties

port1

readonly port1: TypedMessagePort<T1>;

Defined in: utils/typed-message-channel.ts:28

port2

readonly port2: TypedMessagePort<T2>;

Defined in: utils/typed-message-channel.ts:29

TypedMessagePort

Defined in: utils/typed-message-channel.ts:10

Extends

Omit<TypedEventTarget<TypedMessagePortEventMap<T>>, typeof UnderlyingType>

Type Parameters

T

T = unknown

Methods

addEventListener()

Call Signature

addEventListener<K>(
   type: K,
   listener:
  | ((event: TypedMessagePortEventMap<T>[K]) => void)
  | null,
   options?: boolean | AddEventListenerOptions): void;

Defined in: utils/typed-event-target.ts:8

The addEventListener() method of the EventTarget interface sets up a function that will be called whenever the specified event is delivered to the target.

MDN Reference

Type Parameters

K

K extends "close" | "message" | "messageerror"

Parameters

type

K

listener

| ((event: TypedMessagePortEventMap<T>[K]) => void) | null

options?

boolean | AddEventListenerOptions

Returns

void

Inherited from

Omit.addEventListener

Call Signature

addEventListener(
   type: string,
   listener: EventListenerOrEventListenerObject | null,
   options?: boolean | AddEventListenerOptions): void;

Defined in: utils/typed-event-target.ts:13

The addEventListener() method of the EventTarget interface sets up a function that will be called whenever the specified event is delivered to the target.

MDN Reference

Parameters

type

string

listener

EventListenerOrEventListenerObject | null

options?

boolean | AddEventListenerOptions

Returns

void

Inherited from

Omit.addEventListener

close()

close(): void;

Defined in: utils/typed-message-channel.ts:24

Returns

void

postMessage()

Call Signature

postMessage(message: T, transfer: Transferable[]): void;

Defined in: utils/typed-message-channel.ts:20

Parameters

message

T

transfer

Transferable[]

Returns

void

Call Signature

postMessage(message: T, options?: StructuredSerializeOptions): void;

Defined in: utils/typed-message-channel.ts:21

Parameters

message

T

options?

StructuredSerializeOptions

Returns

void

removeEventListener()

Call Signature

removeEventListener<K>(
   type: K,
   listener:
  | ((event: TypedMessagePortEventMap<T>[K]) => void)
  | null,
   options?: boolean | EventListenerOptions): void;

Defined in: utils/typed-event-target.ts:19

MDN Reference

Type Parameters

K

K extends "close" | "message" | "messageerror"

Parameters

type

K

listener

| ((event: TypedMessagePortEventMap<T>[K]) => void) | null

options?

boolean | EventListenerOptions

Returns

void

Inherited from

Omit.removeEventListener

Call Signature

removeEventListener(
   type: string,
   listener: EventListenerOrEventListenerObject | null,
   options?: boolean | EventListenerOptions): void;

Defined in: utils/typed-event-target.ts:24

MDN Reference

Parameters

type

string

listener

EventListenerOrEventListenerObject | null

options?

boolean | EventListenerOptions

Returns

void

Inherited from

Omit.removeEventListener

start()

start(): void;

Defined in: utils/typed-message-channel.ts:23

Returns

void

Properties

[UnderlyingType]?

optional [UnderlyingType]?: T;

Defined in: utils/typed-message-channel.ts:15

onmessage

onmessage:
  | ((this: MessagePort, ev: MessageEvent<T>) => unknown)
  | null;

Defined in: utils/typed-message-channel.ts:17

onmessageerror

onmessageerror: ((this: MessagePort, ev: MessageEvent) => unknown) | null

Defined in: utils/typed-message-channel.ts:18

Type Aliases

BadFieldParent

type BadFieldParent<T, TConstraint> =
  FindBadField<T, TConstraint> extends {
    parent: infer P
  }
    ? P
    : T

Defined in: utils/capable-check.ts:62

The immediate parent object/array containing the first non-conforming value. Equals T when the root itself fails.

Type Parameters

T

T

TConstraint

TConstraint

BadFieldPath

type BadFieldPath<T, TConstraint> =
  FindBadField<T, TConstraint> extends {
    path: infer P
  }
    ? P
    : ''

Defined in: utils/capable-check.ts:55

Dotted/bracketed path to the first non-conforming value (e.g. "a.b[2]"). Empty string if the root itself fails the check.

Type Parameters

T

T

TConstraint

TConstraint

BadFieldValue

type BadFieldValue<T, TConstraint> =
  FindBadField<T, TConstraint> extends {
    value: infer V
  }
    ? V
    : T

Defined in: utils/capable-check.ts:48

The first non-conforming value found by deep traversal of T against TConstraint. Falls back to T if no traversal is applicable.

Type Parameters

T

T

TConstraint

TConstraint

DeepReplaceWithBox

type DeepReplaceWithBox<T, M> = [FindMatchingBox<T, M>] extends [never] ? T extends infer U[] ? DeepReplaceWithBox<U, M>[] : T extends object ? { [K in keyof T]: DeepReplaceWithBox<T[K], M> } : T : FindMatchingBox<T, M>;

Defined in: utils/replace.ts:11

Type Parameters

T

T

M

M

DeepReplaceWithRevive

type DeepReplaceWithRevive<T, M> = [FindMatchingRevive<T, M>] extends [never] ? T extends infer U[] ? DeepReplaceWithRevive<U, M>[] : T extends object ? { [K in keyof T]: DeepReplaceWithRevive<T[K], M> } : T : FindMatchingRevive<T, M>;

Defined in: utils/replace.ts:23

Type Parameters

T

T

M

M

EventMap

type EventMap = Record<string, Event>

Defined in: utils/typed-event-target.ts:3

GcUnregister

type GcUnregister = () => void

Defined in: utils/gc-tracker.ts:18

Run cleanup after target is garbage-collected. Returns a handle to cancel the tracking before that happens.

Backed by a single shared FinalizationRegistry - every revivable that needs FR semantics goes through this so the boilerplate (token, unregister, cycle-safety contract) lives in one place.

Contract: cleanup MUST NOT (transitively) reference target. The registry strong-holds the cleanup callback, the cleanup would then strong-hold target, and the engine would never see target as collectable. Use a WeakRef if cleanup needs something that points back at target.

Errors thrown from cleanup are swallowed: the callback fires from the FR thread, where there’s no caller to surface them to.

Returns

void

ReplaceWithBox

type ReplaceWithBox<T, M> = [FindMatchingBox<T, M>] extends [never] ? T : FindMatchingBox<T, M>

Defined in: utils/replace.ts:6

Type Parameters

T

T

M

M

TypedMessagePortEventMap

type TypedMessagePortEventMap<T> = {
  close: Event
  message: MessageEvent<T>
  messageerror: MessageEvent
}

Defined in: utils/typed-message-channel.ts:4

Type Parameters

T

T = unknown

Properties

close

close: Event

Defined in: utils/typed-message-channel.ts:7

message

message: MessageEvent<T>

Defined in: utils/typed-message-channel.ts:5

messageerror

messageerror: MessageEvent

Defined in: utils/typed-message-channel.ts:6

UnderlyingType

type UnderlyingType = typeof UnderlyingType

Defined in: utils/type.ts:1

Variables

BadValue

const BadValue: unique symbol

Defined in: utils/capable-check.ts:2

ErrorMessage

const ErrorMessage: unique symbol

Defined in: utils/capable-check.ts:1

ParentObject

const ParentObject: unique symbol

Defined in: utils/capable-check.ts:4

Path

const Path: unique symbol

Defined in: utils/capable-check.ts:3

UnderlyingType

const UnderlyingType: unique symbol

Defined in: utils/type.ts:1