Module: Dommy::Js::WireTags

Defined in:

lib/dommy/js/wire_tags.rb

Overview

The wire protocol shared by every Ruby<->JS marshaller in this gem: the tagged-Hash shapes that cross the boundary (a handle, a callback, an opaque JS ref, a byte buffer, a tagged exception, …). Both Ruby marshallers — HostBridge#wrap/#unwrap (the Proxy bridge) and WasmBridge#pack/#unpack (the wasm guest bridge) — build and match these keys, so keeping them as one set of constants prevents the two sides from drifting apart.

The JS half (host_runtime.js: dehydrate/rehydrate/wasmTag/wasmDeref) mirrors the SAME string literals. When changing a tag here, update host_runtime.js in lockstep — these constants are the canonical names; the JS literals are the mirror.

Constant Summary

HANDLE =

A bridged Ruby object, referenced by its HandleTable id (becomes an ES Proxy on the JS side).

"__rb_handle"

INTERFACE =

The host object's WebIDL interface name, carried alongside its handle so makeProxy can reuse a cached per-interface descriptor (prototype chain + method set) instead of a __rb_host_describe round trip per new proxy — the dominant overhead when JS traverses/builds many nodes.

"__rb_if"

CUSTOM_ELEMENT =

The custom-element tag of a handle whose node is a registered custom element (so makeProxy upgrades it), carried per-instance since it is the one part of a describe that is NOT per-interface.

"__rb_ce"

CALLBACK =

A live JS function that crossed into Ruby, referenced by callback id.

"__rb_callback"

JS_REF =

An opaque JS value referenced by its id in the JS-side jsRefs table (shared by the Proxy and wasm bridges). See Dommy::Bridge::JSValue.

"__rb_js_ref"

JS_LABEL =

A human-readable label captured alongside a JS ref (for #to_s/#inspect).

"__rb_js_label"

HANDLE_EVENT =

Marks a JS ref that implements the EventListener interface (handleEvent).

"__rb_handle_event"

ACCEPT_NODE =

Marks a JS ref that implements the NodeFilter interface (acceptNode).

"__rb_accept_node"

UNDEFINED =

The JS undefined value (distinct from null / Ruby nil).

"__rb_undefined"

ABSENT =

A genuinely-absent property: marshals to JS undefined as a value, but the proxy reports it MISSING for the in operator (distinct from UNDEFINED, which is present-but-undefined). See Dommy::Bridge::ABSENT.

"__rb_absent"

BYTES =

A byte buffer crossing as a JS Uint8Array.

"__rb_bytes"

ARRAY_BUFFER =

A byte buffer crossing as a bare JS ArrayBuffer.

"__rb_arraybuffer"

EXCEPTION =

A host-raised DOMException/TypeError/RangeError, re-thrown JS-side.

"__rb_exception__"

ERROR_VALUE =

A host-created native JS error (TypeError/RangeError) crossing as a VALUE — not thrown — so e.g. a promise rejected with it has a reason that is a real instanceof TypeError. Rehydrates to the error object itself.

"__rb_error_value"

THROW =

An arbitrary host-thrown value, re-thrown JS-side verbatim.

"__rb_throw__"

CALLBACK_THREW =

A callback whose JS invocation threw (the thrown value is carried here).

"__rb_cb_threw__"