@swmansion/popcorn (Popcorn v1.0.0)

View Source

Summary

Types

AnyValue

A value exchanged with BEAM. Containers convert their contents recursively.

GenServer
OtpErrorPayload

VM shutdown notification.

Pid

An opaque BEAM process identifier received from the VM.

PopcornErrors

Error tags and their structured details. Match tags instead of message text.

PopcornEvent

A decoded BEAM message payload.

PopcornOpts

Browser VM configuration.

Result

An operation result. Check ok before accessing data or error. Expected failures from try* methods use the error branch. Invalid usage can still throw.

SchedulerOptions

Thread counts for schedulers.

SerializedError

Error tag and details without the Error instance or stack.

TtySize

Terminal dimensions in character cells, from 1 to 65,535 per dimension.

Functions

atom(name)

Creates a BEAM atom value.

schedulers(opts)

Builds beam.emulatorArgs for scheduler counts.

tuple(first, second, ...rest)

Creates a BEAM tuple.

Types

AnyValue

@type type AnyValue = unknown

A value exchanged with BEAM. Containers convert their contents recursively.

See Sharing values across languages for supported types and conversions.

GenServer

@type type GenServer = Pick<Popcorn, "call" | "cast" | "tryCall" | "tryCast">

OtpErrorPayload

@type type OtpErrorPayload = {
  data: string;
  kind: "abort";
} | {
  data: string;
  kind: "error";
} | {
  data: number;
  kind: "exit";
}

VM shutdown notification.

An exit carries a status code, including zero for a normal exit.

Pid

@type type Pid = {
  readonly [pidBrand]: true;
}

An opaque BEAM process identifier received from the VM.

Valid only with the Popcorn instance and boot that produced it.

PopcornErrors

@type type PopcornErrors = {
  "asset:load": {
    kind: "manifest" | "tarball";
    url: string;
  } | {
    available: string[];
    kind: "manifest-entry";
    name: string;
    url: string;
  };
  "bridge:invalid-target": EmptyData;
  "bridge:listener-not-found": {
    targetName: string;
  };
  "bridge:not-started": EmptyData;
  "bridge:unserializable": UnserializableData;
  "genserver:exit": {
    reason: string;
  };
  "genserver:noproc": {
    target: string;
  };
  "genserver:unserializable": EmptyData;
  "runtime:eval-unavailable": EmptyData;
  "stdio:overflow": {
    attemptedBytes: number;
    capacityBytes: number;
  };
  timeout: {
    operation: "init" | "send" | "call";
    timeoutMs: number;
  };
  "vm:exited": VmExitedData;
  "worker:load": {
    message: string;
  };
}

Error tags and their structured details. Match tags instead of message text.

PopcornEvent

@type type PopcornEvent = AnyValue

A decoded BEAM message payload.

Includes restored PID handles and tracked JavaScript values.

PopcornOpts

@type type PopcornOpts<Output extends TtyOutput = "text"> = {
  beam?: Pick<BeamBootOptions, "emulatorArgs" | "extraArgs" | "env"> & {
    maxMemory?: MemoryLimits;
    otpAssetsRoot?: string;
  };
  onError?: (event: OtpErrorPayload) => void;
  onEvent?: (event: PopcornEvent) => void;
  onStderr?: (chunk: OutputChunk<Output>) => void;
  onStdout?: (chunk: OutputChunk<Output>) => void;
  timeoutsMs?: {
    appStartup?: number;
    boot?: number;
    send?: number;
  };
  tty?: {
    output?: Output;
    size?: TtySize;
  };
  workerUrl?: string | URL;
}

Browser VM configuration.

Properties

  • onError?: (event: OtpErrorPayload) => void - Receives VM errors and exits before shutdown.

Defaults to console output.

  • onEvent?: (event: PopcornEvent) => void - Receives BEAM message payloads, including messages sent during startup.
  • onStderr?: (chunk: OutputChunk<Output>) => void - Receives stderr.

Defaults to console.error. Receives Uint8Array when tty.output is "bytes", and string otherwise.

  • onStdout?: (chunk: OutputChunk<Output>) => void - Receives stdout.

Defaults to console.log. Receives Uint8Array when tty.output is "bytes", and string otherwise.

  • workerUrl?: string | URL - Module worker URL.

Defaults to the worker included with the package.

Result

@type type Result<T, E extends Tag = Tag> = {
  data: T;
  ok: true;
} | {
  error: PopcornError<E>;
  ok: false;
}

An operation result. Check ok before accessing data or error. Expected failures from try* methods use the error branch. Invalid usage can still throw.

SchedulerOptions

@type type SchedulerOptions = {
  base: number;
  dirtyCpu: number;
  dirtyIo: number;
}

Thread counts for schedulers.

Each count must be positive.

Properties

  • base: number - Regular schedulers.
  • dirtyCpu: number - Dirty CPU schedulers.
  • dirtyIo: number - Dirty I/O schedulers.

SerializedError

@type type SerializedError<T extends Tag = Tag> = {
  [K in T]: {
    data: PopcornErrors[K];
    t: K;
  };
}[T]

Error tag and details without the Error instance or stack.

TtySize

@type type TtySize = {
  columns: number;
  rows: number;
}

Terminal dimensions in character cells, from 1 to 65,535 per dimension.

Functions

atom(name)

@spec atom(name: string): AtomTerm

Creates a BEAM atom value.

The atom must already exist in the receiving VM. Plain strings encode as binaries.

schedulers(opts)

@spec schedulers(opts: SchedulerOptions): string[]

Builds beam.emulatorArgs for scheduler counts.

Defaults to one scheduler of each type.

tuple(first, second, ...rest)

(variadic) 
@spec tuple(first: unknown, second: unknown, ...rest: unknown[]): TupleTerm

Creates a BEAM tuple.

Plain arrays encode as lists.