English | 한국어

@rustra/types

The core types package of rustra-bridge. Provides the EngineClient interface shared by all platform adapters (Node, Bun, Tauri, React Native), error types, the Frame codec, and Tauri-like global invoke.

Public API overview

// Configure the platform engine once
import { configure } from '@rustra/types';
import { createFrameEngine } from '@rustra/react-native';
configure(createFrameEngine(native, registry));

// Type-safe invocations from anywhere (used inside generated clients)
import { addNumbers } from './generated/commands.js';
const result = await addNumbers({ a: 42, b: 58 });

Key exports:

• EngineClient — the common interface: invoke<T>() (+ optional invokeBatch)
• configure() / invoke() — global invoke (Tauri-like single entry point)
• InvokeOptions.signal — AbortSignal — on abort, the promise rejects immediately and the cancellation propagates to the native side (when invokeAsync/invokeCancel are exposed), with error code cancelled
• invokeBatch() / invokeBatchSettled() — batch invoke. The settled form always runs entries sequentially per-entry (never the atomic wire batch) and reports each as fulfilled / rejected / unexecuted, so a failed entry and the never-dispatched entries after it are distinguishable (see "Timeout, Cancellation, and Retry Semantics" in docs/rust-api-guide.md)
• withRetry(fn, options?) — exponential-backoff retry limited to retryable failures (retries default 2, baseDelayMs default 100, retryIf replaces the default judgment, signal aborts mid-backoff as CancelledError); the last error is re-thrown as-is
• configureDebug(sink) / RustraDebugEvent — opt-in structured diagnostics sink. RUSTRA_DEBUG=1|true|verbose additionally logs every event as [rustra:debug] and dumps wire bytes as hex to stderr ([rustra:wire]); on React Native globalThis.__RUSTRA_DEBUG__ = true enables the event log. Diagnostic events carry optional kind/reason (response.shape from the JSON engine, ndjson.unparsed from @rustra/node)
• RustraCommandError — serializable error + parseRustraErrorString
• Frame codec — pure-JS encoder/decoder for the Rust invoke_frame round trip
• contractHash verification — checks that the build-time contract matches the runtime contract
• FrameEngineOptions — engine options: onContractMismatch (opt-in degraded mode on hash mismatch), schemaVersion/onSchemaStale (warning when JS is staler than native), maxPayloadBytes (size pre-check of the payload right after encoding)
• invokeLoose() — name-based loose invoke without the generated client (dynamic development tier)
• registerDeviceStatusProvider() / getDeviceStatus() — fail-open device availability/permission lookup backed by a host-registered provider

Related docs

• rustra-bridge
• docs/architecture.md, docs/compatibility-contract.md