`WASM_COMPILER` error codes

Purpose

This module defines the six stable error codes raised by the TS->WASM compiler and the concrete WasmCompilerError class every production path throws. The codes name the failure modes exhaustively: the bundle step (BUNDLE_FAILED), bundler input rejections (BROWSER_INCOMPAT_DEPENDENCY), the platform-locate step (JAVY_PLATFORM_MISMATCH), the Javy spawn step (JAVY_INVOCATION_FAILED), the post-Javy ABI reflection (ABI_VALIDATION_FAILED), and the route-extraction probe (MANIFEST_MISSING_ROUTES).

Stability matters because callers (@suaveplan/api-host operators, CI gates, plugin operators) branch on error.code rather than parsing free-form messages. The code registry is built via @suaveplan/error's defineCodes so each code is a frozen "WASM_COMPILER.<NAME>" string literal, and TypeScript can narrow error.code to the WasmCompilerCode union for exhaustive switches.

Features

WASM_COMPILER_CODES — frozen defineCodes registry of all six codes.
WasmCompilerCode — exhaustive union type.
WasmCompilerError — SuaveplanError subclass with a public constructor (rule §19), carrying the namespaced code and i18n message key.
WASM_COMPILER_ERROR_NAME — stable error.name ("WasmCompilerError") for cross-realm instanceof fallbacks.

Usage: Basic

import { WASM_COMPILER_CODES, WasmCompilerError } from "@suaveplan/wasm-compiler-javy";

throw new WasmCompilerError(
    WASM_COMPILER_CODES.JAVY_PLATFORM_MISMATCH,
    "error.wasm_compiler.javy_platform_mismatch",
    { context: { requested: "freebsd-x64" } }
);

Usage: Advanced

import { WasmCompilerError } from "@suaveplan/wasm-compiler-javy";

try {
    await compilePluginToWasm({ pluginEntry, outDir });
} catch (err) {
    if (err instanceof WasmCompilerError) {
        switch (err.code) {
            case "WASM_COMPILER.BUNDLE_FAILED":
            case "WASM_COMPILER.BROWSER_INCOMPAT_DEPENDENCY":
                console.error("bundle:", err.message);
                break;
            case "WASM_COMPILER.JAVY_PLATFORM_MISMATCH":
            case "WASM_COMPILER.JAVY_INVOCATION_FAILED":
                console.error("javy:", err.message);
                break;
            case "WASM_COMPILER.ABI_VALIDATION_FAILED":
            case "WASM_COMPILER.MANIFEST_MISSING_ROUTES":
                console.error("post-compile:", err.message);
                break;
        }
    }
    throw err;
}

API Reference

WASM_COMPILER_CODES: Readonly<Record<"BUNDLE_FAILED" | "BROWSER_INCOMPAT_DEPENDENCY" | "JAVY_PLATFORM_MISMATCH" | "JAVY_INVOCATION_FAILED" | "ABI_VALIDATION_FAILED" | "MANIFEST_MISSING_ROUTES", string>>.
type WasmCompilerCode = (typeof WASM_COMPILER_CODES)[keyof typeof WASM_COMPILER_CODES].
class WasmCompilerError extends SuaveplanError<WasmCompilerCode> — public constructor taking (code, messageKey, options?).
const WASM_COMPILER_ERROR_NAME = "WasmCompilerError".

Implementation Notes

The class extends the framework's SuaveplanError<TCode>, providing the namespace-qualified code, an i18n messageKey, and the cause/context plumbing every @suaveplan package shares. The public constructor satisfies rule §19 (catches stale // biome-ignore suppressions where subclasses redeclared protected constructors as private). Every throw site in this package allocates one of these — no naked Errors — so instanceof WasmCompilerError is sufficient to distinguish compiler failures from unrelated runtime errors at the boundary.

3.5 KiB Raw Blame History

WASM_COMPILER error codes