functionalscript 0.16.1 → 0.18.0

package/fs/html/module.f.js

@@ -1,3 +1,9 @@
+/**
+ * HTML serialization helpers: `Element`/`Attributes` builders, void-tag
+ * handling, attribute/text escaping, and a UTF-8 emitter for full documents.
+ *
+ * @module
+ */
 import { map, flatMap, flat, concat as listConcat } from "../types/list/module.f.js";
 import { concat, concat as stringConcat } from "../types/string/module.f.js";
 import { compose } from "../types/function/module.f.js";

package/fs/io/module.d.ts

@@ -1,9 +1,9 @@
-import { type Io, type Run } from './module.f.ts';
+import { type Io } from './module.f.ts';
 import type { Module, NodeProgram } from '../types/effects/node/module.f.ts';
+import { type Result } from '../types/result/module.f.ts';
 export declare const asyncImport: (v: string) => Promise<Module>;
+export declare const tryCatch: <T>(f: () => T) => Result<T, unknown>;
 export declare const io: Io;
-export declare const legacyRun: Run;
 export type NodeRun = (p: NodeProgram) => Promise<number>;
-export declare const ioRun: (io: Io) => NodeRun;
 declare const effectRun: NodeRun;
 export default effectRun;

package/fs/io/module.f.d.ts

@@ -1,5 +1,6 @@
 import { type Effect } from '../types/effects/module.f.ts';
-import type { Headers, Module, NodeOp, Env } from '../types/effects/node/module.f.ts';
+import type { Headers, Module, NodeOp, Env, SandboxResult, NodeProgram, WriteConsoles } from '../types/effects/node/module.f.ts';
+import type { Vec } from '../types/bit_vec/module.f.ts';
 import { type Result } from '../types/result/module.f.ts';
 /**
  * Represents a directory entry (file or directory) in the filesystem
@@ -73,6 +74,7 @@ export type Process = {
     readonly stderr: Writable;
 };
 export type TryCatch = <T>(f: () => T) => Result<T, unknown>;
+export type Sandbox = <T>(f: () => T) => SandboxResult<T>;
 export type Server = {
     readonly listen: (port: number) => void;
 };
@@ -111,6 +113,9 @@ export type Io = {
     readonly asyncTryCatch: <T>(f: () => Promise<T>) => Promise<Result<T, unknown>>;
     readonly http: Http;
     readonly childProcess: ChildProcess;
+    readonly now: () => number;
+    readonly sandbox: Sandbox;
+    readonly write: (stream: WriteConsoles, data: Vec) => Promise<void>;
 };
 export type App = (io: Io) => Promise<number>;
 export type Run = (f: App) => Promise<never>;
@@ -120,4 +125,5 @@ export type Run = (f: App) => Promise<never>;
  */
 export declare const run: (io: Io) => Run;
 export type EffectToPromise = <T>(effect: Effect<NodeOp, T>) => Promise<T>;
-export declare const fromIo: ({ console: { error, log }, fs: { promises: { mkdir, readFile, readdir, writeFile, rm, access } }, fetch, http: { createServer }, childProcess, asyncImport, }: Io) => EffectToPromise;
+export declare const fromIo: ({ fs: { promises: { mkdir, readFile, readdir, writeFile, rm, access } }, fetch, http: { createServer }, childProcess, asyncImport, now: ioNow, sandbox: ioSandbox, write: ioWrite, }: Io) => EffectToPromise;
+export declare const runProgram: (io: Io) => (args: readonly string[]) => (program: NodeProgram) => Promise<number>;

package/fs/io/module.f.js

@@ -1,3 +1,12 @@
+/**
+ * Legacy `Io` interface and adapter (`fromIo`) bridging the old IO API to the
+ * effect runner.
+ *
+ * @deprecated Use `fs/types/effects/node` (see issue
+ * [i139](../../issues/README.md)).
+ *
+ * @module
+ */
 import { normalize } from "../path/module.f.js";
 import {} from "../types/effects/module.f.js";
 import { asyncRun } from "../types/effects/module.js";
@@ -35,11 +44,9 @@ const collect = async (v) => {
     }
     return result;
 };
-export const fromIo = ({ console: { error, log }, fs: { promises: { mkdir, readFile, readdir, writeFile, rm, access } }, fetch, http: { createServer }, childProcess, asyncImport, }) => {
+export const fromIo = ({ fs: { promises: { mkdir, readFile, readdir, writeFile, rm, access } }, fetch, http: { createServer }, childProcess, asyncImport, now: ioNow, sandbox: ioSandbox, write: ioWrite, }) => {
     const result = asyncRun({
         all: async (...effects) => await Promise.all(effects.map(result)),
-        error: async (message) => error(message),
-        log: async (message) => log(message),
         fetch: async (url) => tc(async () => {
             const response = await fetch(url);
             if (!response.ok) {
@@ -86,7 +93,21 @@ export const fromIo = ({ console: { error, log }, fs: { promises: { mkdir, readF
             s.listen(port);
         },
         forever: () => new Promise(() => { }),
-        now: async () => BigInt(Date.now()) * 1000000n,
+        now: async () => ioNow(),
+        sandbox: async (f) => ioSandbox(f),
+        write: ioWrite,
     });
     return result;
 };
+export const runProgram = (io) => {
+    const { process: { env, stdout, stderr } } = io;
+    const f = fromIo(io);
+    return (args) => (program) => f(program({
+        args,
+        env,
+        std: {
+            stdout: { isTTY: stdout.isTTY },
+            stderr: { isTTY: stderr.isTTY },
+        },
+    }));
+};

package/fs/io/module.js

@@ -10,11 +10,46 @@ import http from 'node:http';
 import childProcess from 'node:child_process';
 import fs from 'node:fs';
 import process from 'node:process';
-import { fromIo, run } from "./module.f.js";
 import { concat } from "../path/module.f.js";
+import { once } from 'node:events';
+import { fromIo, runProgram } from "./module.f.js";
 import { error, ok } from "../types/result/module.f.js";
+import { fromVec } from "../types/uint8array/module.f.js";
 const prefix = 'file:///';
+const { now } = Date;
+/** Maps `WriteConsoles` names to the corresponding Node.js writable streams. */
+const streams = {
+    stdout: process.stdout,
+    stderr: process.stderr,
+};
+/**
+ * Writes `data` to `stream` respecting Node.js backpressure.
+ *
+ * `stream.write()` returns `false` when the internal buffer is full; the data
+ * is already buffered at that point (no retry needed) but the caller must not
+ * issue more writes until the `'drain'` event fires. Waiting here throttles the
+ * producer to the speed of the OS consumer, preventing unbounded memory growth
+ * when many large messages arrive faster than they can be flushed.
+ *
+ * When the buffer is not full `write()` returns `true` and we return
+ * immediately, so large computations with occasional prints never stall.
+ *
+ * @see {@link https://nodejs.org/api/stream.html#writablewritechunk}
+ */
+const writeAll = async (stream, data) => {
+    if (!stream.write(data)) {
+        await once(stream, 'drain');
+    }
+};
 export const asyncImport = (v) => import(__rewriteRelativeImportExtension(v));
+export const tryCatch = f => {
+    try {
+        return ok(f());
+    }
+    catch (e) {
+        return error(e);
+    }
+};
 export const io = {
     console,
     fs,
@@ -26,30 +61,34 @@ export const io = {
     },
     performance,
     fetch,
-    tryCatch: f => {
+    tryCatch,
+    asyncTryCatch: async (f) => {
         try {
-            return ok(f());
+            return ok(await f());
         }
         catch (e) {
             return error(e);
         }
     },
-    asyncTryCatch: async (f) => {
+    http,
+    childProcess,
+    now,
+    sandbox: (f) => {
+        let result;
+        let after;
+        const before = performance.now();
         try {
-            return ok(await f());
+            const value = f();
+            after = performance.now();
+            result = ok(value);
         }
         catch (e) {
-            return error(e);
+            after = performance.now();
+            result = error(e);
         }
+        return { result, duration: after - before };
     },
-    http,
-    childProcess,
-};
-export const legacyRun = run(io);
-export const ioRun = (io) => {
-    const r = fromIo(io);
-    const { argv, env } = io.process;
-    return p => r(p(argv, env));
+    write: (stream, data) => writeAll(streams[stream], fromVec(data)),
 };
-const effectRun = ioRun(io);
+const effectRun = runProgram(io)(io.process.argv.slice(2));
 export default effectRun;

package/fs/js/tokenizer/module.f.js

@@ -1,3 +1,10 @@
+/**
+ * JavaScript tokenizer built as a range-map state machine over code points,
+ * producing tokens for keywords, identifiers, punctuators, comments, strings,
+ * and numeric literals (including `BigFloat`).
+ *
+ * @module
+ */
 import { strictEqual } from "../../types/function/operator/module.f.js";
 import { merge, fromRange, get } from "../../types/range_map/module.f.js";
 import { empty, stateScan, flat, toArray, reduce as listReduce, scan, map as listMap } from "../../types/list/module.f.js";

package/fs/json/module.f.d.ts

@@ -1,3 +1,10 @@
+/**
+ * JSON tree types and utilities: `Primitive`/`Unknown` value shapes,
+ * `setProperty` for immutable nested updates, and a `stringify` built from the
+ * serializer wraps.
+ *
+ * @module
+ */
 import { type List } from '../types/list/module.f.ts';
 import { type Entry as ObjectEntry } from '../types/object/module.f.ts';
 type Object = {

package/fs/json/module.f.js

@@ -1,3 +1,10 @@
+/**
+ * JSON tree types and utilities: `Primitive`/`Unknown` value shapes,
+ * `setProperty` for immutable nested updates, and a `stringify` built from the
+ * serializer wraps.
+ *
+ * @module
+ */
 import { next, flat, map } from "../types/list/module.f.js";
 import { concat } from "../types/string/module.f.js";
 import { at } from "../types/object/module.f.js";

package/fs/path/module.f.d.ts

@@ -20,3 +20,9 @@ export declare const normalize: Unary<string, string>;
  * Concatenates two path fragments and returns a normalized path.
  */
 export declare const concat: Reduce<string>;
+/**
+ * Returns `path` relative to `base` with a `./` prefix, or `path` unchanged
+ * if it does not start with `base` or `base` is empty.
+ * E.g. `relativize('/repo', '/repo/fs/a.ts')` → `'./fs/a.ts'`.
+ */
+export declare const relativize: (base: string, path: string) => string;

package/fs/path/module.f.js

@@ -46,3 +46,9 @@ export const concat = a => b => {
     const s = stringConcat([a, '/', b]);
     return normalize(s);
 };
+/**
+ * Returns `path` relative to `base` with a `./` prefix, or `path` unchanged
+ * if it does not start with `base` or `base` is empty.
+ * E.g. `relativize('/repo', '/repo/fs/a.ts')` → `'./fs/a.ts'`.
+ */
+export const relativize = (base, path) => base !== '' && path.startsWith(base) ? `.${path.slice(base.length)}` : path;

package/fs/path/test.f.d.ts

@@ -1,5 +1,3 @@
-declare const _default: {
-    normalize: (() => void)[];
-    concat: (() => void)[];
-};
-export default _default;
+export declare const normalizeTest: (() => void)[];
+export declare const concatTest: (() => void)[];
+export declare const relativizeTest: (() => void)[];

package/fs/path/test.f.js

@@ -1,49 +1,67 @@
-import { concat, normalize } from "./module.f.js";
-export default {
-    normalize: [
-        () => {
-            const norm = normalize("dir/file.json");
-            if (norm !== "dir/file.json") {
-                throw norm;
-            }
-        },
-        () => {
-            const norm = normalize("dir//file.json");
-            if (norm !== "dir/file.json") {
-                throw norm;
-            }
-        },
-        () => {
-            const norm = normalize("../../dir/file.json");
-            if (norm !== "../../dir/file.json") {
-                throw norm;
-            }
-        },
-        () => {
-            const norm = normalize("../../dir/../file.json");
-            if (norm !== "../../file.json") {
-                throw norm;
-            }
-        },
-    ],
-    concat: [
-        () => {
-            const c = concat("a")("b");
-            if (c !== "a/b") {
-                throw c;
-            }
-        },
-        () => {
-            const c = concat("a///b/")("c");
-            if (c !== "a/b/c") {
-                throw c;
-            }
-        },
-        () => {
-            const c = concat("a/../b/..")("c");
-            if (c !== "c") {
-                throw c;
-            }
-        },
-    ]
-};
+import { concat, normalize, relativize } from "./module.f.js";
+export const normalizeTest = [
+    () => {
+        const norm = normalize("dir/file.json");
+        if (norm !== "dir/file.json") {
+            throw norm;
+        }
+    },
+    () => {
+        const norm = normalize("dir//file.json");
+        if (norm !== "dir/file.json") {
+            throw norm;
+        }
+    },
+    () => {
+        const norm = normalize("../../dir/file.json");
+        if (norm !== "../../dir/file.json") {
+            throw norm;
+        }
+    },
+    () => {
+        const norm = normalize("../../dir/../file.json");
+        if (norm !== "../../file.json") {
+            throw norm;
+        }
+    },
+];
+export const concatTest = [
+    () => {
+        const c = concat("a")("b");
+        if (c !== "a/b") {
+            throw c;
+        }
+    },
+    () => {
+        const c = concat("a///b/")("c");
+        if (c !== "a/b/c") {
+            throw c;
+        }
+    },
+    () => {
+        const c = concat("a/../b/..")("c");
+        if (c !== "c") {
+            throw c;
+        }
+    },
+];
+export const relativizeTest = [
+    () => {
+        const r = relativize('/repo', '/repo/fs/a.ts');
+        if (r !== './fs/a.ts') {
+            throw r;
+        }
+    },
+    () => {
+        const r = relativize('/repo', '/other/a.ts');
+        if (r !== '/other/a.ts') {
+            throw r;
+        }
+    },
+    () => {
+        const r = relativize('', './fs/a.ts');
+        if (r !== './fs/a.ts') {
+            throw r;
+        }
+    },
+];

package/fs/text/module.f.d.ts

@@ -1,3 +1,10 @@
+/**
+ * Indented text `Block` rendering and UTF-8 helpers: `flat` flattens a nested
+ * block into prefixed lines, while `utf8`/`utf8ToString` convert between
+ * strings and MSB-first UTF-8 bit vectors.
+ *
+ * @module
+ */
 import { type Vec } from '../types/bit_vec/module.f.ts';
 import { type List } from '../types/list/module.f.ts';
 export type Block = ItemThunk | ItemArray;

package/fs/text/module.f.js

@@ -1,3 +1,10 @@
+/**
+ * Indented text `Block` rendering and UTF-8 helpers: `flat` flattens a nested
+ * block into prefixed lines, while `utf8`/`utf8ToString` convert between
+ * strings and MSB-first UTF-8 bit vectors.
+ *
+ * @module
+ */
 import { msb, u8List, u8ListToVec } from "../types/bit_vec/module.f.js";
 import { flatMap } from "../types/list/module.f.js";
 import { fromCodePointList, toCodePointList } from "./utf8/module.f.js";

package/fs/text/sgr/module.f.d.ts

@@ -5,6 +5,8 @@
  * @module
  */
 import type { Io, Writable } from "../../io/module.f.ts";
+import { type Write, type WriteConsoles, type NodeProgramOptions } from '../../types/effects/node/module.f.ts';
+import { type Effect } from '../../types/effects/module.f.ts';
 export declare const backspace: string;
 type End = 'm';
 type Csi = (code: number | string) => string;
@@ -44,7 +46,7 @@ export type WriteText = (text: string) => WriteText;
 export declare const createConsoleText: (stdout: Stdout) => WriteText;
 export type CsiConsole = (s: string) => void;
 /**
- * Creates a TTY-aware console function.
+ * Creates a TTY-aware console function. Appends `\n` to each string before writing.
  *
  * For TTY destinations, ANSI SGR sequences are preserved.
  * For non-TTY destinations, ANSI SGR sequences are stripped.
@@ -57,4 +59,10 @@ export declare const console: ({ fs: { writeSync } }: Io) => (w: Writable) => Cs
 export declare const stdio: (io: Io) => CsiConsole;
 /** Writes to process stderr using a TTY-aware CSI console. */
 export declare const stderr: (io: Io) => CsiConsole;
+/**
+ * Effect-based TTY-aware write. Strips ANSI SGR sequences when the target
+ * stream is not a TTY, then encodes to UTF-8 and emits a `Write` effect.
+ * Does NOT append `\n` — callers are responsible for line termination.
+ */
+export declare const csiWrite: ({ std }: NodeProgramOptions) => (stream: WriteConsoles) => (s: string) => Effect<Write, void>;
 export {};

package/fs/text/sgr/module.f.js

@@ -4,6 +4,9 @@
  *
  * @module
  */
+import { write } from "../../types/effects/node/module.f.js";
+import {} from "../../types/effects/module.f.js";
+import { utf8 } from "../module.f.js";
 export const backspace = '\x08';
 const begin = '\x1b[';
 /**
@@ -46,8 +49,9 @@ export const createConsoleText = (stdout) => {
     };
     return f('');
 };
+const str = (isTTY) => (s) => isTTY ? s : s.replace(/\x1b\[[0-9;]*m/g, '');
 /**
- * Creates a TTY-aware console function.
+ * Creates a TTY-aware console function. Appends `\n` to each string before writing.
  *
  * For TTY destinations, ANSI SGR sequences are preserved.
  * For non-TTY destinations, ANSI SGR sequences are stripped.
@@ -56,12 +60,19 @@ export const createConsoleText = (stdout) => {
  * @returns A function that targets a writable stream.
  */
 export const console = ({ fs: { writeSync } }) => (w) => {
-    const { isTTY } = w;
-    return isTTY
-        ? (s) => writeSync(w.fd, s + '\n')
-        : (s) => writeSync(w.fd, s.replace(/\x1b\[[0-9;]*m/g, '') + '\n');
+    const toStr = str(w.isTTY);
+    return (s) => writeSync(w.fd, toStr(s) + '\n');
 };
 /** Writes to process stdout using a TTY-aware CSI console. */
 export const stdio = (io) => console(io)(io.process.stdout);
 /** Writes to process stderr using a TTY-aware CSI console. */
 export const stderr = (io) => console(io)(io.process.stderr);
+/**
+ * Effect-based TTY-aware write. Strips ANSI SGR sequences when the target
+ * stream is not a TTY, then encodes to UTF-8 and emits a `Write` effect.
+ * Does NOT append `\n` — callers are responsible for line termination.
+ */
+export const csiWrite = ({ std }) => (stream) => {
+    const toStr = str(std[stream].isTTY);
+    return (s) => write(stream, utf8(toStr(s)));
+};

package/fs/text/utf16/module.f.d.ts

@@ -1,3 +1,10 @@
+/**
+ * UTF-16 utilities: convert between strings, UTF-16 code units, and Unicode
+ * code points, including surrogate-pair encoding/decoding via streaming
+ * `stateScan` operations.
+ *
+ * @module
+ */
 import { type List, type Thunk } from '../../types/list/module.f.ts';
 /**
  * Represent an unsigned UTF16, used to store one word UTF-16 (code unit).

package/fs/text/utf16/module.f.js

@@ -1,3 +1,10 @@
+/**
+ * UTF-16 utilities: convert between strings, UTF-16 code units, and Unicode
+ * code points, including surrogate-pair encoding/decoding via streaming
+ * `stateScan` operations.
+ *
+ * @module
+ */
 import { map, flat, stateScan, reduce, flatMap, empty, } from "../../types/list/module.f.js";
 import { concat } from "../../types/function/operator/module.f.js";
 import { contains } from "../../types/range/module.f.js";

package/fs/types/effects/node/module.f.d.ts

@@ -49,11 +49,6 @@ export declare const exec: Func<Exec>;
 export type Access = readonly ['access', (path: string) => IoResult<void>];
 export declare const access: Func<Access>;
 export type Fs = Mkdir | ReadFile | Readdir | WriteFile | Rm | Exec | Access;
-export type Error = ['error', (message: string) => void];
-export declare const error: Func<Error>;
-export type Log = ['log', (message: string) => void];
-export declare const log: Func<Log>;
-export type Console = Log | Error;
 export type Server = Nominal<'server', `160855c4f69310fece3273c1853ac32de43dee1eb41bf59d821917f8eebe9272`, unknown>;
 export type Headers = {
     readonly [k in string]: string;
@@ -78,13 +73,50 @@ export type Http = CreateServer | Listen;
 export type Forever = ['forever', () => never];
 export declare const forever: Func<Forever>;
 export type Module = {
-    readonly default: unknown;
+    readonly [k in string]: unknown;
 };
 export type Import = ['import', (path: string) => IoResult<Module>];
 export declare const import_: Func<Import>;
-export type Now = readonly ['now', () => bigint];
+export type WriteConsoles = 'stdout' | 'stderr';
+export type Write = readonly ['write', (stream: WriteConsoles, data: Vec) => void];
+export declare const write: Func<Write>;
+export type Console = (s: string) => Effect<Write, void>;
+/** Writes a line to `stdout`. Replaces the retired `Log` effect. */
+export declare const log: Console;
+/** Writes a line to `stderr`. Replaces the retired `Error` effect. */
+export declare const error: Console;
+export type Now = readonly ['now', () => number];
 export declare const now: Func<Now>;
-export type NodeOp = All | Fetch | Console | Fs | Http | Forever | Import | Now;
+export type SandboxResult<T> = {
+    readonly result: Result<T, unknown>;
+    /**
+     * Measured milliseconds but it's not limited to that.
+     * Instead, they represent times as floating-point numbers
+     * with up to microsecond precision.
+     */
+    readonly duration: number;
+};
+export type Sandbox = readonly ['sandbox', <T>(f: () => T) => SandboxResult<T>];
+/**
+ * Runs a plain synchronous function in an isolated, measured environment.
+ *
+ * Combines try/catch and high-resolution timing into a single atomic operation.
+ * Only plain synchronous functions are accepted — no effects, no promises.
+ *
+ * Using a single operation rather than separate `TryCatch` + `Perf` effects is
+ * necessary for correctness: effects execute as async tasks, so the scheduler
+ * can insert arbitrary work between two separate timing calls, making the
+ * measured delta inaccurate. Here the clock reads happen synchronously around
+ * the function call with nothing in between.
+ *
+ * Future parameters (time limit, memory limit) can be added to the payload
+ * without breaking the API. Worker-based implementations can enforce hard
+ * limits via worker termination.
+ *
+ * @see {@link SandboxResult}
+ */
+export declare const sandbox: Func<Sandbox>;
+export type NodeOp = All | Fetch | Fs | Http | Forever | Import | Now | Sandbox | Write;
 export type NodeEffect<T> = Effect<NodeOp, T>;
 export type NodeOperationMap = ToAsyncOperationMap<NodeOp>;
 /**
@@ -93,4 +125,14 @@ export type NodeOperationMap = ToAsyncOperationMap<NodeOp>;
 export type Env = {
     readonly [k: string]: string | undefined;
 };
-export type NodeProgram = (argv: readonly string[], env: Env) => Effect<NodeOp, number>;
+export type NodeProgramOptions = {
+    readonly args: readonly string[];
+    readonly env: Env;
+    readonly std: {
+        readonly [k in WriteConsoles]: {
+            readonly isTTY: boolean;
+        };
+    };
+};
+export type Program<O extends Operation> = (options: NodeProgramOptions) => Effect<O, number>;
+export type NodeProgram = Program<NodeOp>;

package/fs/types/effects/node/module.f.js

@@ -1,3 +1,13 @@
+/**
+ * Node.js effect operations: filesystem (`mkdir`, `readFile`, `readdir`,
+ * `writeFile`, `rm`, `access`), networking (`fetch`, `createServer`, `listen`),
+ * subprocess `exec`, `log`/`error` (wrappers over `write`), `import_`, `now`,
+ * `sandbox`, `forever`, and `all`/`both` parallelism; defines the
+ * `NodeOp`/`NodeProgram` types used by the Node runner.
+ *
+ * @module
+ */
+import { utf8 } from "../../../text/module.f.js";
 import { do_ } from "../module.f.js";
 const doAll = do_('all');
 /**
@@ -17,10 +27,37 @@ export const writeFile = do_('writeFile');
 export const rm = do_('rm');
 export const exec = do_('exec');
 export const access = do_('access');
-export const error = do_('error');
-export const log = do_('log');
 export const createServer = do_('createServer');
 export const listen = do_('listen');
 export const forever = do_('forever');
 export const import_ = do_('import');
+export const write = do_('write');
+/**
+ * Encodes `s + '\n'` as UTF-8 and emits a `Write` effect to `stream`.
+ * Shared implementation for `log` and `error`.
+ */
+const writeString = (stream) => (s) => write(stream, utf8(s + '\n'));
+/** Writes a line to `stdout`. Replaces the retired `Log` effect. */
+export const log = writeString('stdout');
+/** Writes a line to `stderr`. Replaces the retired `Error` effect. */
+export const error = writeString('stderr');
 export const now = do_('now');
+/**
+ * Runs a plain synchronous function in an isolated, measured environment.
+ *
+ * Combines try/catch and high-resolution timing into a single atomic operation.
+ * Only plain synchronous functions are accepted — no effects, no promises.
+ *
+ * Using a single operation rather than separate `TryCatch` + `Perf` effects is
+ * necessary for correctness: effects execute as async tasks, so the scheduler
+ * can insert arbitrary work between two separate timing calls, making the
+ * measured delta inaccurate. Here the clock reads happen synchronously around
+ * the function call with nothing in between.
+ *
+ * Future parameters (time limit, memory limit) can be added to the payload
+ * without breaking the API. Worker-based implementations can enforce hard
+ * limits via worker termination.
+ *
+ * @see {@link SandboxResult}
+ */
+export const sandbox = do_('sandbox');

package/fs/types/effects/node/test.f.d.ts

@@ -31,5 +31,9 @@ declare const _default: {
         isDirectory: () => void;
     };
     now: () => void;
+    sandbox: {
+        ok: () => void;
+        error: () => void;
+    };
 };
 export default _default;