sandboxedjs 0.1.30 → 0.1.32

package/dist/index.d.cts

@@ -6,7 +6,7 @@ interface ChildHandle {
     pid: number;
     state: "starting" | "running" | "exited";
     exitCode: number | undefined;
-    on(event: "stdout" | "stderr" | "exit", listener: (...args: any[]) => void): unknown;
+    on(event: "stdout" | "stderr" | "exit" | "rawmode", listener: (...args: any[]) => void): unknown;
     exec(): void;
     sendStdin(data: string): void;
     /**
@@ -442,7 +442,10 @@ declare class Pipe implements InputStream, OutputStream {
      * whole line on every keystroke — so the terminal must stop echoing, or
      * every character appears twice.
      */
-    rawMode: boolean;
+    private raw;
+    onRawMode?: (enabled: boolean) => void;
+    get rawMode(): boolean;
+    set rawMode(enabled: boolean);
     columns: number | undefined;
     rows: number | undefined;
     get closed(): boolean;
@@ -1391,6 +1394,8 @@ declare class Shell {
     constructor(init: ShellInit);
     /** Parse and run a script fragment. Returns the last exit status. */
     execute(source: string, io: ShellIO): Promise<number>;
+    /** Signal the current terminal pipeline without terminating the interactive shell. */
+    interruptForeground(signal: string, stdin: InputStream): void;
     get isExiting(): boolean;
     /** True when `source` is not yet a complete command (for REPL continuation). */
     static isIncomplete(source: string): boolean;
@@ -1674,12 +1679,15 @@ interface ContainerOptions {
     /**
      * Where guest programs run.
      *
-     * `"worker"` (the default) gives each program its own thread, which is what
-     * makes synchronous child processes work and keeps guest code out of the
-     * host's realm; it falls back automatically where the host cannot support it.
-     * `"realm"` forces the in-realm runtime.
+     * `"auto"` (the default) tries the worker runtime and reports any fallback.
+     * `"worker"` requires a working guest worker and shared-memory channel: boot
+     * rejects with the cause if either is unavailable, rather than letting
+     * synchronous child-process calls fail later. `"realm"` opts out explicitly.
+     * Processes requiring host-native modules can still run in the host realm.
      */
-    isolation?: "worker" | "realm";
+    isolation?: "auto" | "worker" | "realm";
+    /** Receives the reason for an automatic fallback; defaults to console.warn. */
+    onRuntimeFallback?: (error: Error) => void;
     /**
      * Where to load the guest worker bundle from.
      *
@@ -2466,6 +2474,7 @@ declare class VirtualHttpServer extends EventEmitter {
     readonly owner: string;
     listening: boolean;
     private portValue;
+    private referenced;
     constructor(router: VirtualHttpRouter, owner: string, listener?: (req: VirtualIncomingMessage, res: VirtualServerResponse) => void);
     listen(...args: any[]): this;
     close(callback?: (error?: Error) => void): this;
@@ -2476,17 +2485,20 @@ declare class VirtualHttpServer extends EventEmitter {
     } | null;
     ref(): this;
     unref(): this;
+    hasRef(): boolean;
     setTimeout(_milliseconds: number, callback?: () => void): this;
 }
 declare class VirtualHttpRouter {
     private readonly servers;
     /** Notified when a server begins listening, for `onServerReady`. */
     onListen: ((port: number) => void) | undefined;
+    onClose: ((port: number) => void) | undefined;
     register(port: number, server: VirtualHttpServer, owner: string): void;
     unregister(port: number, server: VirtualHttpServer): void;
     /** Whether anything in this container is listening on `port`. */
     activePortsIncludes(port: number): boolean;
     activePorts(owner?: string): number[];
+    referencedPorts(owner: string): number[];
     closeOwner(owner: string): void;
     closeAll(): void;
     request(port: number, init?: VirtualRequestInit): Promise<RuntimeHttpResponse>;
@@ -2743,6 +2755,7 @@ declare class LocalRuntimePod implements RuntimePod {
         spawn(config: ChildSpawnConfig): ChildHandle;
     };
     private disposed;
+    private readonly running;
     protected readonly workdir: string;
     protected readonly env: Record<string, string>;
     protected readonly aliases: Record<string, string>;
@@ -2814,16 +2827,10 @@ declare class WorkerRuntimePod extends LocalRuntimePod {
     /** Live workers, so teardown can stop them all. */
     private readonly live;
     protected constructor(options: WorkerRuntimeOptions);
-    /**
-     * Boot a Worker-backed pod, or return null when this host cannot support one.
-     *
-     * Declining is a first-class outcome. `SharedArrayBuffer` needs cross-origin
-     * isolation, a bundler may have made the guest script unreachable, and a host
-     * that supplied its own module objects has handed over things no thread
-     * boundary can carry. In every case the caller falls back to the in-realm pod
-     * and keeps working.
-     */
-    static tryBoot(options?: WorkerRuntimeOptions): Promise<WorkerRuntimePod | null>;
+    /** Boot without silently dropping synchronous child-process support. */
+    static boot(options?: WorkerRuntimeOptions): Promise<WorkerRuntimePod>;
+    /** Compatibility mode, with an observable explanation for every fallback. */
+    static tryBoot(options?: WorkerRuntimeOptions, onFallback?: (error: Error) => void): Promise<WorkerRuntimePod | null>;
     spawn(command: string, args?: string[], options?: Record<string, unknown>): Promise<RuntimeProcess>;
     private spawnInWorker;
     /** Start an asynchronous child on the host's behalf and relay its events. */
@@ -2908,8 +2915,8 @@ declare function extractNpmTarball(volume: RuntimeVolume, compressed: Uint8Array
  * own dependency cache, where no such file exists. That is the same trap
  * Rolldown's WASI binding falls into, and it surfaces just as obliquely.
  *
- * So this never assumes it worked. The caller treats a failure to start as
- * "this host cannot run the Worker pod" and uses the in-realm pod instead.
+ * So this never assumes it worked. Strict boot surfaces the failure; automatic mode reports
+ * the cause before choosing the in-realm pod.
  */
 interface RuntimeWorker {
     postMessage(message: unknown): void;
@@ -2930,13 +2937,6 @@ declare function startRuntimeWorker(options?: {
     timeoutMs?: number;
 }): Promise<RuntimeWorker>;
 
-/**
- * Can this environment support a blocking client at all?
- *
- * `SharedArrayBuffer` needs cross-origin isolation in a browser, and
- * `Atomics.wait` is forbidden on a browser's main thread — which is why the
- * client is always the Worker.
- */
 declare function syncChannelSupported(): boolean;
 
 /**

package/dist/index.d.ts

@@ -6,7 +6,7 @@ interface ChildHandle {
     pid: number;
     state: "starting" | "running" | "exited";
     exitCode: number | undefined;
-    on(event: "stdout" | "stderr" | "exit", listener: (...args: any[]) => void): unknown;
+    on(event: "stdout" | "stderr" | "exit" | "rawmode", listener: (...args: any[]) => void): unknown;
     exec(): void;
     sendStdin(data: string): void;
     /**
@@ -442,7 +442,10 @@ declare class Pipe implements InputStream, OutputStream {
      * whole line on every keystroke — so the terminal must stop echoing, or
      * every character appears twice.
      */
-    rawMode: boolean;
+    private raw;
+    onRawMode?: (enabled: boolean) => void;
+    get rawMode(): boolean;
+    set rawMode(enabled: boolean);
     columns: number | undefined;
     rows: number | undefined;
     get closed(): boolean;
@@ -1391,6 +1394,8 @@ declare class Shell {
     constructor(init: ShellInit);
     /** Parse and run a script fragment. Returns the last exit status. */
     execute(source: string, io: ShellIO): Promise<number>;
+    /** Signal the current terminal pipeline without terminating the interactive shell. */
+    interruptForeground(signal: string, stdin: InputStream): void;
     get isExiting(): boolean;
     /** True when `source` is not yet a complete command (for REPL continuation). */
     static isIncomplete(source: string): boolean;
@@ -1674,12 +1679,15 @@ interface ContainerOptions {
     /**
      * Where guest programs run.
      *
-     * `"worker"` (the default) gives each program its own thread, which is what
-     * makes synchronous child processes work and keeps guest code out of the
-     * host's realm; it falls back automatically where the host cannot support it.
-     * `"realm"` forces the in-realm runtime.
+     * `"auto"` (the default) tries the worker runtime and reports any fallback.
+     * `"worker"` requires a working guest worker and shared-memory channel: boot
+     * rejects with the cause if either is unavailable, rather than letting
+     * synchronous child-process calls fail later. `"realm"` opts out explicitly.
+     * Processes requiring host-native modules can still run in the host realm.
      */
-    isolation?: "worker" | "realm";
+    isolation?: "auto" | "worker" | "realm";
+    /** Receives the reason for an automatic fallback; defaults to console.warn. */
+    onRuntimeFallback?: (error: Error) => void;
     /**
      * Where to load the guest worker bundle from.
      *
@@ -2466,6 +2474,7 @@ declare class VirtualHttpServer extends EventEmitter {
     readonly owner: string;
     listening: boolean;
     private portValue;
+    private referenced;
     constructor(router: VirtualHttpRouter, owner: string, listener?: (req: VirtualIncomingMessage, res: VirtualServerResponse) => void);
     listen(...args: any[]): this;
     close(callback?: (error?: Error) => void): this;
@@ -2476,17 +2485,20 @@ declare class VirtualHttpServer extends EventEmitter {
     } | null;
     ref(): this;
     unref(): this;
+    hasRef(): boolean;
     setTimeout(_milliseconds: number, callback?: () => void): this;
 }
 declare class VirtualHttpRouter {
     private readonly servers;
     /** Notified when a server begins listening, for `onServerReady`. */
     onListen: ((port: number) => void) | undefined;
+    onClose: ((port: number) => void) | undefined;
     register(port: number, server: VirtualHttpServer, owner: string): void;
     unregister(port: number, server: VirtualHttpServer): void;
     /** Whether anything in this container is listening on `port`. */
     activePortsIncludes(port: number): boolean;
     activePorts(owner?: string): number[];
+    referencedPorts(owner: string): number[];
     closeOwner(owner: string): void;
     closeAll(): void;
     request(port: number, init?: VirtualRequestInit): Promise<RuntimeHttpResponse>;
@@ -2743,6 +2755,7 @@ declare class LocalRuntimePod implements RuntimePod {
         spawn(config: ChildSpawnConfig): ChildHandle;
     };
     private disposed;
+    private readonly running;
     protected readonly workdir: string;
     protected readonly env: Record<string, string>;
     protected readonly aliases: Record<string, string>;
@@ -2814,16 +2827,10 @@ declare class WorkerRuntimePod extends LocalRuntimePod {
     /** Live workers, so teardown can stop them all. */
     private readonly live;
     protected constructor(options: WorkerRuntimeOptions);
-    /**
-     * Boot a Worker-backed pod, or return null when this host cannot support one.
-     *
-     * Declining is a first-class outcome. `SharedArrayBuffer` needs cross-origin
-     * isolation, a bundler may have made the guest script unreachable, and a host
-     * that supplied its own module objects has handed over things no thread
-     * boundary can carry. In every case the caller falls back to the in-realm pod
-     * and keeps working.
-     */
-    static tryBoot(options?: WorkerRuntimeOptions): Promise<WorkerRuntimePod | null>;
+    /** Boot without silently dropping synchronous child-process support. */
+    static boot(options?: WorkerRuntimeOptions): Promise<WorkerRuntimePod>;
+    /** Compatibility mode, with an observable explanation for every fallback. */
+    static tryBoot(options?: WorkerRuntimeOptions, onFallback?: (error: Error) => void): Promise<WorkerRuntimePod | null>;
     spawn(command: string, args?: string[], options?: Record<string, unknown>): Promise<RuntimeProcess>;
     private spawnInWorker;
     /** Start an asynchronous child on the host's behalf and relay its events. */
@@ -2908,8 +2915,8 @@ declare function extractNpmTarball(volume: RuntimeVolume, compressed: Uint8Array
  * own dependency cache, where no such file exists. That is the same trap
  * Rolldown's WASI binding falls into, and it surfaces just as obliquely.
  *
- * So this never assumes it worked. The caller treats a failure to start as
- * "this host cannot run the Worker pod" and uses the in-realm pod instead.
+ * So this never assumes it worked. Strict boot surfaces the failure; automatic mode reports
+ * the cause before choosing the in-realm pod.
  */
 interface RuntimeWorker {
     postMessage(message: unknown): void;
@@ -2930,13 +2937,6 @@ declare function startRuntimeWorker(options?: {
     timeoutMs?: number;
 }): Promise<RuntimeWorker>;
 
-/**
- * Can this environment support a blocking client at all?
- *
- * `SharedArrayBuffer` needs cross-origin isolation in a browser, and
- * `Atomics.wait` is forbidden on a browser's main thread — which is why the
- * client is always the Worker.
- */
 declare function syncChannelSupported(): boolean;
 
 /**