@ricsam/isolate 0.0.1 → 0.1.0

package/dist/types/internal/runtime/index.d.ts

@@ -0,0 +1,200 @@
+export { normalizeEntryFilename } from "../protocol/index.ts";
+import type { DispatchRequestOptions, UpgradeRequest, WebSocketCommand, ClientWebSocketCommand } from "../fetch/index.ts";
+import type { FsOptions } from "../fs/index.ts";
+import type { RunResults } from "../test-environment/index.ts";
+import type { NetworkRequestInfo, NetworkResponseInfo, BrowserConsoleLogEntry, PageErrorInfo, RequestFailureInfo } from "../playwright/index.ts";
+import type { EvalOptions as ProtocolEvalOptions, PlaywrightOptions as ProtocolPlaywrightOptions, BaseRuntimeOptions } from "../protocol/index.ts";
+import { type MarshalContext } from "../protocol/index.ts";
+export type { ConsoleCallbacks, ConsoleEntry, FetchCallback, FetchRequestInit, ModuleLoaderCallback, CustomFunction, CustomFunctionDefinition, CustomFunctions, DispatchOptions, } from "../protocol/index.ts";
+export type EvalOptions = ProtocolEvalOptions;
+export type PlaywrightOptions = ProtocolPlaywrightOptions;
+/**
+ * Options for customizing how custom function return values are marshalled.
+ * Used by the daemon to support returned callbacks/promises/iterators via IPC.
+ */
+export interface CustomFunctionsMarshalOptions {
+    /** Factory to create a MarshalContext for registering returned callbacks/promises/iterators */
+    createMarshalContext: () => MarshalContext;
+    /** Post-processor to add callback IDs to PromiseRef/AsyncIteratorRef values */
+    addCallbackIdsToRefs: (value: unknown) => unknown;
+    /** Handler for numeric callback IDs from marshalled refs (CallbackRef, PromiseRef, AsyncIteratorRef) */
+    invokeCallback: (callbackId: number, args: unknown[]) => Promise<unknown>;
+}
+/**
+ * Options for creating a runtime.
+ * Extends BaseRuntimeOptions and adds runtime-specific fs type.
+ */
+export interface RuntimeOptions<T extends Record<string, any[]> = Record<string, unknown[]>> extends BaseRuntimeOptions<T> {
+    /**
+     * File system options.
+     * Note: For local runtime, this uses FsOptions with getDirectory returning a FileSystemHandler.
+     * For remote runtime (isolate-client), use FileSystemCallbacks instead.
+     */
+    fs?: FsOptions;
+    /**
+     * Optional marshal options for custom functions.
+     * When provided, enables MarshalContext-based marshalling for returned values.
+     * Used by the daemon for IPC proxying of callbacks/promises/iterators.
+     */
+    customFunctionsMarshalOptions?: CustomFunctionsMarshalOptions;
+}
+/**
+ * Runtime fetch handle - provides access to fetch/serve operations.
+ */
+export interface RuntimeFetchHandle {
+    /** Dispatch HTTP request to serve() handler */
+    dispatchRequest(request: Request, options?: DispatchRequestOptions): Promise<Response>;
+    /** Check if isolate requested WebSocket upgrade */
+    getUpgradeRequest(): UpgradeRequest | null;
+    /** Dispatch WebSocket open event to isolate */
+    dispatchWebSocketOpen(connectionId: string): void;
+    /** Dispatch WebSocket message event to isolate */
+    dispatchWebSocketMessage(connectionId: string, message: string | ArrayBuffer): void;
+    /** Dispatch WebSocket close event to isolate */
+    dispatchWebSocketClose(connectionId: string, code: number, reason: string): void;
+    /** Dispatch WebSocket error event to isolate */
+    dispatchWebSocketError(connectionId: string, error: Error): void;
+    /** Register callback for WebSocket commands from isolate */
+    onWebSocketCommand(callback: (cmd: WebSocketCommand) => void): () => void;
+    /** Check if serve() has been called */
+    hasServeHandler(): boolean;
+    /** Check if there are active WebSocket connections */
+    hasActiveConnections(): boolean;
+    /** Dispatch open event to a client WebSocket in the isolate */
+    dispatchClientWebSocketOpen(socketId: string, protocol: string, extensions: string): void;
+    /** Dispatch message event to a client WebSocket in the isolate */
+    dispatchClientWebSocketMessage(socketId: string, data: string | ArrayBuffer): void;
+    /** Dispatch close event to a client WebSocket in the isolate */
+    dispatchClientWebSocketClose(socketId: string, code: number, reason: string, wasClean: boolean): void;
+    /** Dispatch error event to a client WebSocket in the isolate */
+    dispatchClientWebSocketError(socketId: string): void;
+    /** Register callback for client WebSocket commands from isolate */
+    onClientWebSocketCommand(callback: (cmd: ClientWebSocketCommand) => void): () => void;
+    /** Register callback for events emitted from isolate code */
+    onEvent(callback: (event: string, payload: unknown) => void): () => void;
+    /** Dispatch an event into the isolate (calls __on listeners) */
+    dispatchEvent(event: string, payload: unknown): void;
+}
+/**
+ * Runtime timers handle - provides access to timer operations.
+ * Timers fire automatically based on real time.
+ */
+export interface RuntimeTimersHandle {
+    /** Clear all pending timers */
+    clearAll(): void;
+}
+/**
+ * Runtime console handle - provides access to console state.
+ */
+export interface RuntimeConsoleHandle {
+    /** Reset all console state (timers, counters, group depth) */
+    reset(): void;
+    /** Get console.time() timers */
+    getTimers(): Map<string, number>;
+    /** Get console.count() counters */
+    getCounters(): Map<string, number>;
+    /** Get current console.group() nesting depth */
+    getGroupDepth(): number;
+}
+/**
+ * Runtime test environment handle - provides access to test execution.
+ */
+export interface RuntimeTestEnvironmentHandle {
+    /** Run all registered tests */
+    runTests(timeout?: number): Promise<RunResults>;
+    /** Check if any tests are registered */
+    hasTests(): boolean;
+    /** Get count of registered tests */
+    getTestCount(): number;
+    /** Reset test state */
+    reset(): void;
+}
+/**
+ * Runtime playwright handle - provides access to browser data collection.
+ */
+export interface RuntimePlaywrightHandle {
+    /** Get collected browser data (console logs, network requests/responses) */
+    getCollectedData(): CollectedData;
+    /** Clear collected browser data */
+    clearCollectedData(): void;
+}
+/**
+ * Collected browser data from playwright.
+ */
+export interface CollectedData {
+    /** Browser console logs (from the page, not sandbox) */
+    browserConsoleLogs: BrowserConsoleLogEntry[];
+    pageErrors: PageErrorInfo[];
+    networkRequests: NetworkRequestInfo[];
+    networkResponses: NetworkResponseInfo[];
+    requestFailures: RequestFailureInfo[];
+}
+/**
+ * Runtime handle - the main interface for interacting with the isolate.
+ */
+export interface RuntimeHandle {
+    /** Unique runtime identifier */
+    readonly id: string;
+    /** Execute code as ES module (supports top-level await) */
+    eval(code: string, filenameOrOptions?: string | EvalOptions): Promise<void>;
+    /** Dispose all resources */
+    dispose(): Promise<void>;
+    /** Clear module cache and source maps (used for namespace pooling/reuse) */
+    clearModuleCache(): void;
+    /**
+     * Array of pending callback promises. Push promises here to have them
+     * awaited after each eval() call completes. Used by daemon for IPC flush.
+     * For standalone use this array stays empty (callbacks are synchronous).
+     */
+    readonly pendingCallbacks: Promise<unknown>[];
+    /** Fetch handle - access to fetch/serve operations */
+    readonly fetch: RuntimeFetchHandle;
+    /** Timers handle - access to timer operations */
+    readonly timers: RuntimeTimersHandle;
+    /** Console handle - access to console state */
+    readonly console: RuntimeConsoleHandle;
+    /** Test environment handle - access to test execution (throws if not enabled) */
+    readonly testEnvironment: RuntimeTestEnvironmentHandle;
+    /** Playwright handle - access to playwright operations (throws if not configured) */
+    readonly playwright: RuntimePlaywrightHandle;
+}
+/**
+ * Create a fully configured isolated-vm runtime
+ *
+ * Sets up all WHATWG APIs: fetch, fs, console, crypto, encoding, timers
+ *
+ * @example
+ * const runtime = await createRuntime({
+ *   console: { log: (...args) => console.log("[isolate]", ...args) },
+ *   fetch: async (request) => fetch(request),
+ * });
+ *
+ * await runtime.eval(`
+ *   console.log("Hello from sandbox!");
+ *   const response = await fetch("https://example.com");
+ * `);
+ *
+ * await runtime.dispose();
+ */
+export declare function createRuntime<T extends Record<string, any[]> = Record<string, unknown[]>>(options?: RuntimeOptions<T>): Promise<RuntimeHandle>;
+export { setupCore } from "../core/index.ts";
+export type { CoreHandle, SetupCoreOptions } from "../core/index.ts";
+export { setupConsole } from "../console/index.ts";
+export { simpleConsoleHandler, type SimpleConsoleCallbacks, } from "../console/utils.ts";
+export type { ConsoleHandle, ConsoleOptions, ConsoleEntry as ConsoleEntryFromConsole, } from "../console/index.ts";
+export { setupCrypto } from "../crypto/index.ts";
+export type { CryptoHandle } from "../crypto/index.ts";
+export { setupEncoding } from "../encoding/index.ts";
+export type { EncodingHandle } from "../encoding/index.ts";
+export { setupFetch } from "../fetch/index.ts";
+export type { FetchHandle, FetchOptions, WebSocketCommand, UpgradeRequest, ClientWebSocketCommand, } from "../fetch/index.ts";
+export { setupFs, createNodeFileSystemHandler } from "../fs/index.ts";
+export type { FsHandle, FsOptions, FileSystemHandler, NodeFileSystemHandlerOptions, } from "../fs/index.ts";
+export { setupPath } from "../path/index.ts";
+export type { PathHandle, PathOptions } from "../path/index.ts";
+export { setupTimers } from "../timers/index.ts";
+export type { TimersHandle } from "../timers/index.ts";
+export { setupTestEnvironment, runTests, hasTests, getTestCount, } from "../test-environment/index.ts";
+export type { TestEnvironmentHandle, TestEnvironmentOptions, RunResults, TestResult, TestInfo, TestError, TestEvent, SuiteInfo, SuiteResult, } from "../test-environment/index.ts";
+export { setupPlaywright, createPlaywrightHandler, defaultPlaywrightHandler, getDefaultPlaywrightHandlerMetadata, } from "../playwright/index.ts";
+export type { PlaywrightHandle, PlaywrightSetupOptions, PlaywrightCallback, PlaywrightEvent, NetworkRequestInfo, NetworkResponseInfo, BrowserConsoleLogEntry, PageErrorInfo, RequestFailureInfo, } from "../playwright/index.ts";

package/dist/types/internal/server/index.d.ts

@@ -0,0 +1,42 @@
+import type { DaemonConnection, DispatchOptions, RemoteRuntime, RuntimeOptions, UpgradeRequest, WebSocketCommand } from "../client/index.ts";
+export interface IsolateServerOptions {
+    namespaceId: string;
+    getConnection: () => Promise<DaemonConnection>;
+}
+export interface IsolateServerStartOptions {
+    runtimeOptions: RuntimeOptions;
+    entry: string;
+    entryFilename?: string;
+    onWebSocketCommand?: (cmd: WebSocketCommand) => void;
+}
+export interface IsolateServerFetch {
+    dispatchRequest(request: Request, options?: DispatchOptions): Promise<Response>;
+    getUpgradeRequest(): Promise<UpgradeRequest | null>;
+    dispatchWebSocketOpen(connectionId: string): Promise<void>;
+    dispatchWebSocketMessage(connectionId: string, message: string | ArrayBuffer): Promise<void>;
+    dispatchWebSocketClose(connectionId: string, code: number, reason: string): Promise<void>;
+    dispatchWebSocketError(connectionId: string, error: Error): Promise<void>;
+    hasServeHandler(): Promise<boolean>;
+    hasActiveConnections(): Promise<boolean>;
+}
+export declare class IsolateServer {
+    private readonly namespaceId;
+    private readonly getConnection;
+    private runtime;
+    private lastStartOptions;
+    private lifecycleLock;
+    private closed;
+    readonly fetch: IsolateServerFetch;
+    constructor(options: IsolateServerOptions);
+    start(options: IsolateServerStartOptions): Promise<void>;
+    reload(): Promise<void>;
+    close(): Promise<void>;
+    getRuntime(): RemoteRuntime | null;
+    private withLifecycleLock;
+    private buildRuntimeOptions;
+    private createAndInitializeRuntime;
+    private disposeRuntime;
+    private ensureStarted;
+    private getActiveRuntime;
+    private dispatchRequestWithRetry;
+}

package/dist/types/internal/test-environment/index.d.ts

@@ -0,0 +1,112 @@
+import type ivm from "isolated-vm";
+export interface TestEnvironmentOptions {
+    /** Receive test lifecycle events */
+    onEvent?: (event: TestEvent) => void;
+    /** Timeout for individual tests (ms) */
+    testTimeout?: number;
+}
+export type TestEvent = {
+    type: "runStart";
+    testCount: number;
+    suiteCount: number;
+} | {
+    type: "suiteStart";
+    suite: SuiteInfo;
+} | {
+    type: "suiteEnd";
+    suite: SuiteResult;
+} | {
+    type: "testStart";
+    test: TestInfo;
+} | {
+    type: "testEnd";
+    test: TestResult;
+} | {
+    type: "runEnd";
+    results: RunResults;
+};
+export interface SuiteInfo {
+    name: string;
+    /** Ancestry path: ["outer", "inner"] */
+    path: string[];
+    /** Full display name: "outer > inner" */
+    fullName: string;
+    /** Nesting depth (0 for root-level suites) */
+    depth: number;
+}
+export interface SuiteResult extends SuiteInfo {
+    passed: number;
+    failed: number;
+    skipped: number;
+    todo: number;
+    duration: number;
+}
+export interface TestInfo {
+    name: string;
+    /** Suite ancestry */
+    suitePath: string[];
+    /** Full display name: "suite > test name" */
+    fullName: string;
+}
+export interface TestResult extends TestInfo {
+    status: "pass" | "fail" | "skip" | "todo";
+    duration: number;
+    error?: TestError;
+}
+export interface TestError {
+    message: string;
+    stack?: string;
+    /** For assertion failures */
+    expected?: unknown;
+    actual?: unknown;
+    /** e.g., "toBe", "toEqual", "toContain" */
+    matcherName?: string;
+}
+export interface RunResults {
+    passed: number;
+    failed: number;
+    skipped: number;
+    todo: number;
+    total: number;
+    duration: number;
+    success: boolean;
+    suites: SuiteResult[];
+    tests: TestResult[];
+}
+export interface TestEnvironmentHandle {
+    dispose(): void;
+}
+/**
+ * Setup test environment primitives in an isolated-vm context
+ *
+ * Provides Jest/Vitest-compatible test primitives:
+ * - describe, test, it
+ * - beforeEach, afterEach, beforeAll, afterAll
+ * - expect matchers
+ *
+ * @example
+ * const handle = await setupTestEnvironment(context, {
+ *   onEvent: (event) => console.log(event),
+ * });
+ *
+ * await context.eval(`
+ *   describe("my tests", () => {
+ *     test("example", () => {
+ *       expect(1 + 1).toBe(2);
+ *     });
+ *   });
+ * `);
+ */
+export declare function setupTestEnvironment(context: ivm.Context, options?: TestEnvironmentOptions): Promise<TestEnvironmentHandle>;
+/**
+ * Run tests in the context and return results
+ */
+export declare function runTests(context: ivm.Context): Promise<RunResults>;
+/**
+ * Check if any tests are registered
+ */
+export declare function hasTests(context: ivm.Context): boolean;
+/**
+ * Get the count of registered tests
+ */
+export declare function getTestCount(context: ivm.Context): number;

package/dist/types/internal/timers/index.d.ts

@@ -0,0 +1,22 @@
+import ivm from "isolated-vm";
+export interface TimersHandle {
+    /** Clear all pending timers */
+    clearAll(): void;
+    /** Dispose the timers handle */
+    dispose(): void;
+}
+/**
+ * Setup timer APIs in an isolated-vm context
+ *
+ * Injects setTimeout, setInterval, clearTimeout, clearInterval
+ *
+ * Uses real time - timers fire automatically based on actual elapsed time.
+ *
+ * @example
+ * const handle = await setupTimers(context);
+ * await context.eval(`
+ *   setTimeout(() => console.log("hello"), 1000);
+ * `);
+ * // Timer will fire automatically after 1 second
+ */
+export declare function setupTimers(context: ivm.Context): Promise<TimersHandle>;

package/dist/types/internal/transform/index.d.ts

@@ -0,0 +1,36 @@
+export interface SourceMap {
+    version: number;
+    sources: string[];
+    sourcesContent?: string[];
+    mappings: string;
+    names: string[];
+    file?: string;
+}
+export interface TransformResult {
+    code: string;
+    sourceMap?: SourceMap;
+}
+/**
+ * Transform user entry code:
+ * 1. Find import/body boundary
+ * 2. Validate body (on original code)
+ * 3. Strip TypeScript types from full code
+ * 4. Split at boundary, elide unused imports, clean blank lines
+ * 5. Wrap body in `export default async function() { ... }`
+ */
+export declare function transformEntryCode(code: string, filename: string): Promise<TransformResult>;
+/**
+ * Transform module code:
+ * 1. Strip TypeScript types from full code
+ * 2. Elide unused imports (line-preserving)
+ * 3. Return with identity source map
+ */
+export declare function transformModuleCode(code: string, filename: string): Promise<TransformResult>;
+/**
+ * Compute SHA-256 content hash for caching.
+ */
+export declare function contentHash(code: string): string;
+/**
+ * Map error stack traces through stored source maps back to original code.
+ */
+export declare function mapErrorStack(stack: string, sourceMaps: Map<string, SourceMap>): string;

package/dist/types/internal/typecheck/index.d.ts

@@ -0,0 +1,7 @@
+/**
+ * ./index.ts
+ *
+ * Type definitions and type-checking utilities for isolated-vm V8 sandbox code.
+ */
+export { CORE_TYPES, CONSOLE_TYPES, CRYPTO_TYPES, ENCODING_TYPES, FETCH_TYPES, FS_TYPES, PATH_TYPES, TEST_ENV_TYPES, TIMERS_TYPES, PLAYWRIGHT_TYPES, TYPE_DEFINITIONS, type TypeDefinitionKey, } from "./isolate-types.ts";
+export { typecheckIsolateCode, formatTypecheckErrors, type TypecheckResult, type TypecheckError, type TypecheckOptions, type LibraryTypes, type LibraryTypeFile, } from "./typecheck.ts";