Schemas

(no submodules)

Purpose

Zod schemas guard every public boundary of @suaveplan/sandbox. The package never trusts its caller; instead, every argument that crosses the API boundary is parsed against a strict schema and rejected with a typed SandboxError (INVALID_CONFIG / INVALID_OPTIONS / INVALID_MODULE) when the shape does not match. This means downstream consumers get the same validation guarantees whether they pass typed TypeScript objects or arbitrary JSON deserialised from a network boundary.

The parseConfig helper additionally merges parsed partials with DEFAULT_CONFIG so the rest of the package consumes a fully resolved SandboxConfig rather than a partial. This keeps the merge logic in one place rather than re-implementing it across the facade and the engines.

Features

Strict-mode schemas (.strict()) so unknown keys are rejected.
parseConfig, parseOptions, parseModule helpers that translate Zod errors into SandboxError with the right code.
SandboxEngineKindSchema enum used as the discriminant for engine selection.
safeParse under the hood so the error path stays on the catch-side and the success path stays on the happy path.

Usage: Basic

import { parseConfig } from "@suaveplan/sandbox/schemas";

const cfg = parseConfig({ timeout: 1000, engine: "worker" });

Usage: Advanced

When validating untrusted input (HTTP, IPC), surface the raw Zod issues to the caller via SandboxError.details.issues:

import { SandboxError } from "@suaveplan/sandbox/error-codes";
import { parseConfig } from "@suaveplan/sandbox/schemas";

try {
    parseConfig(JSON.parse(httpBody));
} catch (err) {
    if (err instanceof SandboxError) {
        return Response.json({ issues: err.details.issues }, { status: 400 });
    }
    throw err;
}

API Reference

SandboxConfigPartialSchema — z.ZodObject for Partial<SandboxConfig>.
SandboxOptionsSchema — z.ZodObject for SandboxOptions.
SandboxModuleSchema — z.ZodObject for SandboxModule.
SandboxEngineKindSchema — z.ZodEnum<['vm','worker','spawn','isolate']>.
parseConfig(raw): SandboxConfig — merges with DEFAULT_CONFIG.
parseOptions(raw): SandboxOptions.
parseModule(raw): SandboxModule.

Implementation Notes

onAuditLog is validated via z.custom rather than z.function because Zod's function schema would otherwise wrap the callback in a runtime validator and break referential equality, breaking the "consumer-passes-its-own-callback" contract. The custom validator only checks typeof === "function" (or undefined), which is the actual invariant the consumer cares about.

2.7 KiB Raw Permalink Blame History