npm - sandlot - Versions diffs - 0.2.1 → 0.2.2 - Mend

sandlot 0.2.1 → 0.2.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (38) hide show

package/dist/browser/bundler.d.ts +8 -0
package/dist/browser/bundler.d.ts.map +1 -1
package/dist/browser/iframe-executor.d.ts +82 -0
package/dist/browser/iframe-executor.d.ts.map +1 -0
package/dist/browser/index.d.ts +4 -2
package/dist/browser/index.d.ts.map +1 -1
package/dist/browser/index.js +205 -9
package/dist/browser/main-thread-executor.d.ts +46 -0
package/dist/browser/main-thread-executor.d.ts.map +1 -0
package/dist/browser/preset.d.ts +7 -2
package/dist/browser/preset.d.ts.map +1 -1
package/dist/core/executor.d.ts.map +1 -1
package/dist/core/sandlot.d.ts.map +1 -1
package/dist/index.js +5 -0
package/dist/node/bundler.d.ts +5 -0
package/dist/node/bundler.d.ts.map +1 -1
package/dist/node/index.d.ts +2 -0
package/dist/node/index.d.ts.map +1 -1
package/dist/node/index.js +174 -8
package/dist/node/preset.d.ts +16 -1
package/dist/node/preset.d.ts.map +1 -1
package/dist/node/wasm-bundler.d.ts +86 -0
package/dist/node/wasm-bundler.d.ts.map +1 -0
package/dist/types.d.ts +25 -0
package/dist/types.d.ts.map +1 -1
package/package.json +1 -1
package/src/browser/bundler.ts +17 -0
package/src/browser/iframe-executor.ts +320 -0
package/src/browser/index.ts +9 -2
package/src/browser/preset.ts +30 -6
package/src/core/executor.ts +8 -7
package/src/core/sandlot.ts +7 -0
package/src/node/bundler.ts +11 -0
package/src/node/index.ts +10 -0
package/src/node/preset.ts +59 -5
package/src/node/wasm-bundler.ts +299 -0
package/src/types.ts +27 -0
/package/src/browser/{executor.ts → main-thread-executor.ts} +0 -0

package/src/browser/iframe-executor.ts ADDED Viewed

@@ -0,0 +1,320 @@
+/**
+ * Iframe executor for browser environments.
+ *
+ * This executor runs code in a sandboxed iframe, providing DOM isolation
+ * and configurable security policies via the sandbox attribute.
+ *
+ * Key characteristics:
+ * - Per-execution lifecycle: fresh iframe for each execute() call
+ * - Configurable sandbox attributes (default: allow-scripts only)
+ * - No shared module support (use MainThreadExecutor for that)
+ * - Communication via postMessage
+ */
+import type { IExecutor, ExecuteOptions, ExecuteResult } from "../types";
+/**
+ * Options for creating an IframeExecutor.
+ */
+export interface IframeExecutorOptions {
+  /**
+   * Sandbox attributes for the iframe.
+   * @default ["allow-scripts"]
+   *
+   * Common options:
+   * - "allow-scripts": Required for code execution
+   * - "allow-same-origin": Enables localStorage, cookies (reduces isolation)
+   * - "allow-modals": Enables alert/confirm/prompt
+   *
+   * Security note: "allow-scripts" + "allow-same-origin" together allows
+   * the iframe code to potentially remove the sandbox via script.
+   */
+  sandbox?: string[];
+  /**
+   * Default timeout in milliseconds.
+   * @default 30000
+   */
+  defaultTimeout?: number;
+  /**
+   * Container element for iframes.
+   * Iframes are created hidden (display: none).
+   * @default document.body
+   */
+  container?: HTMLElement;
+}
+/**
+ * Message types for parent -> iframe communication.
+ */
+interface ExecuteMessage {
+  type: "execute";
+  code: string;
+  entryExport: "main" | "default";
+  context: Record<string, unknown>;
+}
+/**
+ * Message types for iframe -> parent communication.
+ */
+interface LogMessage {
+  type: "log";
+  level: "log" | "warn" | "error" | "info" | "debug";
+  args: string;
+}
+interface ResultMessage {
+  type: "result";
+  success: boolean;
+  returnValue?: unknown;
+  error?: string;
+}
+interface ReadyMessage {
+  type: "ready";
+}
+type IframeMessage = LogMessage | ResultMessage | ReadyMessage;
+/**
+ * Bootstrap HTML that runs inside the iframe.
+ * This is injected via srcdoc and handles:
+ * 1. Console capture and forwarding
+ * 2. Code execution via Blob URL import
+ * 3. Result reporting back to parent
+ */
+const BOOTSTRAP_HTML = `<!DOCTYPE html>
+<html>
+<head>
+  <meta charset="utf-8">
+</head>
+<body>
+<script type="module">
+// Capture console methods and forward to parent
+function formatArgs(...args) {
+  return args
+    .map(v => typeof v === "object" ? JSON.stringify(v) : String(v))
+    .join(" ");
+}
+function createLogger(level) {
+  return (...args) => {
+    parent.postMessage({ type: "log", level, args: formatArgs(...args) }, "*");
+  };
+}
+console.log = createLogger("log");
+console.warn = createLogger("warn");
+console.error = createLogger("error");
+console.info = createLogger("info");
+console.debug = createLogger("debug");
+// Handle unhandled promise rejections
+window.addEventListener("unhandledrejection", (event) => {
+  const message = event.reason instanceof Error
+    ? event.reason.message
+    : String(event.reason);
+  parent.postMessage({
+    type: "result",
+    success: false,
+    error: "Unhandled promise rejection: " + message
+  }, "*");
+});
+// Handle uncaught errors
+window.addEventListener("error", (event) => {
+  parent.postMessage({
+    type: "result",
+    success: false,
+    error: event.message || "Unknown error"
+  }, "*");
+});
+// Listen for execute messages from parent
+window.addEventListener("message", async (event) => {
+  if (event.data?.type !== "execute") return;
+  const { code, entryExport, context } = event.data;
+  try {
+    // Create Blob URL and import as ESM module
+    const blob = new Blob([code], { type: "application/javascript" });
+    const url = URL.createObjectURL(blob);
+    let module;
+    try {
+      module = await import(url);
+    } finally {
+      URL.revokeObjectURL(url);
+    }
+    // Execute the appropriate export
+    let returnValue;
+    if (entryExport === "main" && typeof module.main === "function") {
+      returnValue = await module.main(context);
+    } else if (entryExport === "default" && typeof module.default === "function") {
+      returnValue = await module.default();
+    } else if (entryExport === "default" && module.default !== undefined) {
+      returnValue = module.default;
+    }
+    // If neither export exists, top-level code already ran on import
+    parent.postMessage({ type: "result", success: true, returnValue }, "*");
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    parent.postMessage({ type: "result", success: false, error: message }, "*");
+  }
+});
+// Signal that we're ready to receive code
+parent.postMessage({ type: "ready" }, "*");
+<\/script>
+</body>
+</html>`;
+/**
+ * Executor that runs code in a sandboxed iframe.
+ *
+ * Each execute() call creates a fresh iframe, runs the code, and destroys
+ * the iframe. This provides clean isolation between executions.
+ *
+ * Note: This executor does NOT support shared modules. The iframe runs
+ * in complete isolation. Use MainThreadExecutor if you need shared modules.
+ *
+ * @example
+ * ```ts
+ * // Default: strict sandboxing (allow-scripts only)
+ * const executor = createIframeExecutor();
+ *
+ * // With additional permissions
+ * const executor = createIframeExecutor({
+ *   sandbox: ["allow-scripts", "allow-same-origin"],
+ * });
+ *
+ * const result = await executor.execute(bundledCode, {
+ *   entryExport: 'main',
+ *   context: { args: ['--verbose'] },
+ *   timeout: 5000,
+ * });
+ * console.log(result.logs);
+ * ```
+ */
+export class IframeExecutor implements IExecutor {
+  private options: Required<Omit<IframeExecutorOptions, "container">> & {
+    container?: HTMLElement;
+  };
+  constructor(options: IframeExecutorOptions = {}) {
+    this.options = {
+      sandbox: options.sandbox ?? ["allow-scripts"],
+      defaultTimeout: options.defaultTimeout ?? 30000,
+      container: options.container,
+    };
+  }
+  async execute(code: string, options: ExecuteOptions = {}): Promise<ExecuteResult> {
+    const {
+      entryExport = "main",
+      context = {},
+      timeout = this.options.defaultTimeout,
+    } = options;
+    const startTime = performance.now();
+    const logs: string[] = [];
+    // Get container (default to document.body)
+    const container = this.options.container ?? document.body;
+    // Create iframe
+    const iframe = document.createElement("iframe");
+    iframe.style.display = "none";
+    iframe.sandbox.add(...this.options.sandbox);
+    iframe.srcdoc = BOOTSTRAP_HTML;
+    // Track whether we've received a result
+    let resolved = false;
+    return new Promise<ExecuteResult>((resolve) => {
+      const cleanup = () => {
+        if (iframe.parentNode) {
+          iframe.parentNode.removeChild(iframe);
+        }
+        window.removeEventListener("message", handleMessage);
+        if (timeoutId) clearTimeout(timeoutId);
+      };
+      const finish = (result: ExecuteResult) => {
+        if (resolved) return;
+        resolved = true;
+        cleanup();
+        resolve(result);
+      };
+      // Handle messages from iframe
+      const handleMessage = (event: MessageEvent) => {
+        // Verify message is from our iframe
+        if (event.source !== iframe.contentWindow) return;
+        const data = event.data as IframeMessage;
+        if (data.type === "log") {
+          const prefix =
+            data.level === "log" ? "" : `[${data.level}] `;
+          logs.push(prefix + data.args);
+        } else if (data.type === "result") {
+          const executionTimeMs = performance.now() - startTime;
+          finish({
+            success: data.success,
+            logs,
+            returnValue: data.returnValue,
+            error: data.error,
+            executionTimeMs,
+          });
+        } else if (data.type === "ready") {
+          // Iframe is ready, send the code to execute
+          const message: ExecuteMessage = {
+            type: "execute",
+            code,
+            entryExport,
+            context,
+          };
+          iframe.contentWindow?.postMessage(message, "*");
+        }
+      };
+      // Set up timeout
+      let timeoutId: ReturnType<typeof setTimeout> | undefined;
+      if (timeout > 0) {
+        timeoutId = setTimeout(() => {
+          const executionTimeMs = performance.now() - startTime;
+          finish({
+            success: false,
+            logs,
+            error: `Execution timed out after ${timeout}ms`,
+            executionTimeMs,
+          });
+        }, timeout);
+      }
+      // Listen for messages
+      window.addEventListener("message", handleMessage);
+      // Append iframe to DOM (this starts loading the srcdoc)
+      container.appendChild(iframe);
+    });
+  }
+}
+/**
+ * Create an iframe executor.
+ *
+ * @param options - Executor options
+ * @returns A new IframeExecutor instance
+ */
+export function createIframeExecutor(
+  options?: IframeExecutorOptions
+): IframeExecutor {
+  return new IframeExecutor(options);
+}

package/src/browser/index.ts CHANGED Viewed

@@ -46,8 +46,15 @@ export type { EsbuildWasmBundlerOptions } from "./bundler";
 // Executor (browser-specific: runs in main thread)
 // -----------------------------------------------------------------------------
-export { MainThreadExecutor, createMainThreadExecutor } from "./executor";
-export type { MainThreadExecutorOptions } from "./executor";
+export { MainThreadExecutor, createMainThreadExecutor } from "./main-thread-executor";
+export type { MainThreadExecutorOptions } from "./main-thread-executor";
+// -----------------------------------------------------------------------------
+// Iframe Executor (browser-specific: runs in sandboxed iframe)
+// -----------------------------------------------------------------------------
+export { IframeExecutor, createIframeExecutor } from "./iframe-executor";
+export type { IframeExecutorOptions } from "./iframe-executor";
 // -----------------------------------------------------------------------------
 // Convenience Preset

package/src/browser/preset.ts CHANGED Viewed

@@ -12,7 +12,11 @@ import {
 import {
   MainThreadExecutor,
   type MainThreadExecutorOptions,
-} from "./executor";
+} from "./main-thread-executor";
+import {
+  IframeExecutor,
+  type IframeExecutorOptions,
+} from "./iframe-executor";
 export interface CreateBrowserSandlotOptions
   extends Omit<SandlotOptions, "bundler" | "typechecker" | "typesResolver" | "executor"> {
@@ -42,11 +46,17 @@ export interface CreateBrowserSandlotOptions
   /**
    * Custom executor options, or a pre-configured executor instance.
    * Set to `false` to disable execution (sandbox.run() will throw).
+   * Set to `"iframe"` to use IframeExecutor with default options.
    * Defaults to MainThreadExecutor.
+   *
+   * Note: IframeExecutor does NOT support shared modules. Use MainThreadExecutor
+   * (the default) if you need shared modules like React.
    */
   executor?:
   | MainThreadExecutorOptions
+  | IframeExecutorOptions
   | SandlotOptions["executor"]
+  | "iframe"
   | false;
 }
@@ -121,11 +131,15 @@ export async function createBrowserSandlot(
   const executorInstance =
     executor === false
       ? undefined
-      : isExecutor(executor)
-        ? executor
-        : new MainThreadExecutor(
-          executor as MainThreadExecutorOptions | undefined
-        );
+      : executor === "iframe"
+        ? new IframeExecutor()
+        : isExecutor(executor)
+          ? executor
+          : isIframeExecutorOptions(executor)
+            ? new IframeExecutor(executor)
+            : new MainThreadExecutor(
+              executor as MainThreadExecutorOptions | undefined
+            );
   return createSandlot({
     ...rest,
@@ -177,3 +191,13 @@ function isExecutor(value: unknown): value is SandlotOptions["executor"] {
     typeof (value as { execute: unknown }).execute === "function"
   );
 }
+function isIframeExecutorOptions(value: unknown): value is IframeExecutorOptions {
+  // IframeExecutorOptions has "sandbox" or "container" properties
+  // MainThreadExecutorOptions only has "defaultTimeout"
+  return (
+    typeof value === "object" &&
+    value !== null &&
+    ("sandbox" in value || "container" in value)
+  );
+}

package/src/core/executor.ts CHANGED Viewed

@@ -68,23 +68,18 @@ export function createBasicExecutor(
       const captureLog = (...args: unknown[]) => {
         logs.push(formatArgs(...args));
-        originalConsole.log.apply(console, args);
       };
       const captureWarn = (...args: unknown[]) => {
         logs.push(`[warn] ${formatArgs(...args)}`);
-        originalConsole.warn.apply(console, args);
       };
       const captureError = (...args: unknown[]) => {
         logs.push(`[error] ${formatArgs(...args)}`);
-        originalConsole.error.apply(console, args);
       };
       const captureInfo = (...args: unknown[]) => {
         logs.push(`[info] ${formatArgs(...args)}`);
-        originalConsole.info.apply(console, args);
       };
       const captureDebug = (...args: unknown[]) => {
         logs.push(`[debug] ${formatArgs(...args)}`);
-        originalConsole.debug.apply(console, args);
       };
       const restoreConsole = () => {
@@ -125,13 +120,19 @@ export function createBasicExecutor(
         // Execute with optional timeout
         if (timeout > 0) {
+          let timeoutId: ReturnType<typeof setTimeout> | undefined;
           const timeoutPromise = new Promise<never>((_, reject) => {
-            setTimeout(
+            timeoutId = setTimeout(
               () => reject(new Error(`Execution timed out after ${timeout}ms`)),
               timeout
             );
           });
-          await Promise.race([executeExport(), timeoutPromise]);
+          try {
+            await Promise.race([executeExport(), timeoutPromise]);
+          } finally {
+            // Clear the timeout to allow the process to exit
+            if (timeoutId) clearTimeout(timeoutId);
+          }
         } else {
           await executeExport();
         }

package/src/core/sandlot.ts CHANGED Viewed

@@ -73,5 +73,12 @@ export function createSandlot(options: SandlotOptions): Sandlot {
     get sharedModules(): ISharedModuleRegistry | null {
       return sharedModuleRegistry;
     },
+    async dispose(): Promise<void> {
+      // Dispose of the bundler if it has a dispose method
+      if (bundler.dispose) {
+        await bundler.dispose();
+      }
+    },
   };
 }

package/src/node/bundler.ts CHANGED Viewed

@@ -76,6 +76,17 @@ export class EsbuildNativeBundler implements IBundler {
     return this.esbuild;
   }
+  /**
+   * Dispose of the esbuild service.
+   * This stops the esbuild child process and allows the Node.js process to exit.
+   */
+  async dispose(): Promise<void> {
+    if (this.esbuild) {
+      await this.esbuild.stop();
+      this.esbuild = null;
+    }
+  }
   async bundle(options: BundleOptions): Promise<BundleResult> {
     await this.initialize();

package/src/node/index.ts CHANGED Viewed

@@ -17,6 +17,16 @@
 export { EsbuildNativeBundler, createEsbuildNativeBundler } from "./bundler";
 export type { EsbuildNativeBundlerOptions } from "./bundler";
+// -----------------------------------------------------------------------------
+// WASM Bundler (for testing consistency with browser bundler)
+// -----------------------------------------------------------------------------
+export {
+  EsbuildWasmNodeBundler,
+  createEsbuildWasmNodeBundler,
+} from "./wasm-bundler";
+export type { EsbuildWasmNodeBundlerOptions } from "./wasm-bundler";
 // -----------------------------------------------------------------------------
 // Typechecker (platform-agnostic: re-exported for convenience)
 // -----------------------------------------------------------------------------

package/src/node/preset.ts CHANGED Viewed

@@ -5,6 +5,10 @@ import {
 } from "../core/esm-types-resolver";
 import type { Sandlot, SandlotOptions } from "../types";
 import { EsbuildNativeBundler, type EsbuildNativeBundlerOptions } from "./bundler";
+import {
+  EsbuildWasmNodeBundler,
+  type EsbuildWasmNodeBundlerOptions,
+} from "./wasm-bundler";
 import {
   Typechecker,
   type TypecheckerOptions,
@@ -18,8 +22,17 @@ export interface CreateNodeSandlotOptions
   extends Omit<SandlotOptions, "bundler" | "typechecker" | "typesResolver" | "executor"> {
   /**
    * Custom bundler options, or a pre-configured bundler instance.
+   *
+   * Set to `"wasm"` to use the WASM bundler (for testing consistency with browser).
+   * You can also pass `{ wasm: true, ...options }` for WASM bundler with custom options.
+   *
+   * @default EsbuildNativeBundler (fastest, uses native esbuild binary)
    */
-  bundler?: EsbuildNativeBundlerOptions | SandlotOptions["bundler"];
+  bundler?:
+    | EsbuildNativeBundlerOptions
+    | (EsbuildWasmNodeBundlerOptions & { wasm: true })
+    | SandlotOptions["bundler"]
+    | "wasm";
   /**
    * Custom typechecker options, or a pre-configured typechecker instance.
@@ -82,6 +95,13 @@ export interface CreateNodeSandlotOptions
  *   typechecker: false,
  * });
  * ```
+ *
+ * @example Use WASM bundler for testing consistency with browser
+ * ```ts
+ * const sandlot = await createNodeSandlot({
+ *   bundler: "wasm",
+ * });
+ * ```
  */
 export async function createNodeSandlot(
   options: CreateNodeSandlotOptions = {}
@@ -89,11 +109,9 @@ export async function createNodeSandlot(
   const { bundler, typechecker, typesResolver, executor, ...rest } = options;
   // Create or use provided bundler
-  const bundlerInstance = isBundler(bundler)
-    ? bundler
-    : new EsbuildNativeBundler(bundler as EsbuildNativeBundlerOptions | undefined);
+  const bundlerInstance = createBundlerInstance(bundler);
-  // Initialize bundler (loads native esbuild)
+  // Initialize bundler (loads native esbuild or WASM)
   await bundlerInstance.initialize();
   // Create or use provided typechecker
@@ -135,6 +153,42 @@ export async function createNodeSandlot(
   });
 }
+// Helper to create bundler instance based on options
+function createBundlerInstance(
+  bundler: CreateNodeSandlotOptions["bundler"]
+): (EsbuildNativeBundler | EsbuildWasmNodeBundler) & { initialize(): Promise<void> } {
+  // Already a bundler instance
+  if (isBundler(bundler)) {
+    return bundler as (EsbuildNativeBundler | EsbuildWasmNodeBundler) & { initialize(): Promise<void> };
+  }
+  // String shorthand for WASM bundler
+  if (bundler === "wasm") {
+    return new EsbuildWasmNodeBundler();
+  }
+  // Object with wasm: true flag
+  if (isWasmBundlerOptions(bundler)) {
+    const { wasm: _, ...wasmOptions } = bundler;
+    return new EsbuildWasmNodeBundler(wasmOptions);
+  }
+  // Default: native bundler (fastest)
+  return new EsbuildNativeBundler(bundler as EsbuildNativeBundlerOptions | undefined);
+}
+function isWasmBundlerOptions(
+  value: unknown
+): value is EsbuildWasmNodeBundlerOptions & { wasm: true } {
+  return (
+    typeof value === "object" &&
+    value !== null &&
+    "wasm" in value &&
+    (value as { wasm: unknown }).wasm === true
+  );
+}
 // Type guards for detecting pre-configured instances
 function isBundler(