functionalscript 0.29.1 → 0.31.0

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

@@ -1,15 +1,28 @@
 /**
  * Node.js effect operations: filesystem (`mkdir`, `readFile`, `readdir`,
- * `writeFile`, `rm`, `access`), networking (`fetch`, `createServer`, `listen`),
+ * `writeFile`, `rm`, `access`, plus the `readUtf8File`/`writeUtf8File` text
+ * helpers), 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 { utf8, utf8ToString } from "../../text/module.f.js";
+import { toCodePointList } from "../../text/utf8/module.f.js";
+import { codePointListToString } from "../../text/utf16/module.f.js";
+import { reverse } from "../../types/list/module.f.js";
+import { ok } from "../../types/result/module.f.js";
 import { do_, pure } from "../module.f.js";
-const doAll = do_('all');
+/**
+ * True if `e` is a "file or directory does not exist" (`ENOENT`) error.
+ *
+ * Node's filesystem rejections are `Error`s carrying `code: 'ENOENT'`; the
+ * virtual interpreter mirrors that shape for absent paths. Lets callers swallow
+ * only the missing-path case (e.g. a fresh store) while propagating genuine
+ * failures (permissions, corruption) rather than masking them.
+ */
+export const isNotFound = (e) => typeof e === 'object' && e !== null && e.code === 'ENOENT';
 /**
  * To run the operation `O` should be known by the runner/engine.
  * This is the reason why we merge `O` with `All` in the resulted `Effect`.
@@ -17,13 +30,23 @@ const doAll = do_('all');
  * @param a
  * @returns
  */
-export const all = (...a) => doAll(...a);
+export const all = do_('all');
 export const both = (a) => (b) => all(a, b);
 export const fetch = do_('fetch');
 export const mkdir = do_('mkdir');
 export const readFile = do_('readFile');
+/**
+ * Reads a file as UTF-8 text.
+ *
+ * Preserves the `IoResult` instead of unwrapping so callers can pattern-match
+ * on errors (e.g. convert them into domain-specific errors) or `unwrap` at the
+ * call site.
+ */
+export const readUtf8File = (path) => readFile(path).step(r => pure(r[0] === 'ok' ? ok(utf8ToString(r[1])) : r));
 export const readdir = do_('readdir');
 export const writeFile = do_('writeFile');
+/** Writes a string to `path` as UTF-8 bytes. */
+export const writeUtf8File = (path, content) => writeFile(path, utf8(content));
 export const rm = do_('rm');
 export const exec = do_('exec');
 export const access = do_('access');
@@ -42,6 +65,34 @@ const writeString = (stream) => (s) => write(stream, utf8(s + '\n'));
 export const log = writeString('stdout');
 /** Writes a line to `stderr`. Replaces the retired `Error` effect. */
 export const error = writeString('stderr');
+/** Emits a `Read` effect, yielding the next input byte or `null` at EOF. */
+export const read = do_('read');
+/** Decodes accumulated UTF-8 bytes (MSB-first, already in order) into a string. */
+const utf8ListToString = (bytes) => codePointListToString(toCodePointList(bytes));
+/** The line-feed byte (`\n`) that terminates a line. */
+const lf = 0x0a;
+/**
+ * Reads one line from `stream` as a pure combinator over the byte-level
+ * {@link read}: accumulates bytes until a `\n` terminator or EOF, then
+ * UTF-8-decodes them. The terminator is consumed but excluded from the result.
+ *
+ * Reading a single byte per step means a line never over-reads past its
+ * terminator, so no leftover-byte buffer has to survive between calls — each
+ * `readLine` is self-contained. Yields `null` only at EOF with nothing
+ * buffered; a final line lacking a trailing newline is returned in full.
+ *
+ * Bytes accumulate into a cons-list by prepending (O(1) per byte) and are
+ * reversed and decoded once at the terminator, so a large line costs O(n)
+ * rather than the O(n²) of copying a growing array on every byte.
+ */
+export const readLine = (stream) => {
+    const loop = (acc) => read(stream).step(b => b === null
+        ? pure(acc === null ? null : utf8ListToString(reverse(acc)))
+        : b === lf
+            ? pure(utf8ListToString(reverse(acc)))
+            : loop({ first: b, tail: acc }));
+    return loop(null);
+};
 export const now = do_('now');
 /**
  * Runs a plain synchronous function in an isolated, measured environment.

package/fs/effects/node/module.js

@@ -6,9 +6,24 @@ var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExte
     }
     return path;
 };
+/**
+ * Node.js effect runner: interprets `Effect<NodeOp, T>` directly against the
+ * Node globals and built-in modules (`fs`, `http`, `child_process`, `process`,
+ * `fetch`, …).
+ *
+ * There is deliberately no injectable IO seam here. Effectful programs are
+ * tested against the in-memory interpreters in `fs/effects/mock` and
+ * `fs/effects/node/virtual`, which interpret the same operations without
+ * touching the OS, so a handler-table indirection in this module would have
+ * exactly one instance and no consumer — the handlers reference the Node
+ * globals directly instead.
+ *
+ * @module
+ */
 import http from 'node:http';
 import childProcess from 'node:child_process';
 import fs from 'node:fs';
+import os from 'node:os';
 import process from 'node:process';
 import { once } from 'node:events';
 import * as testContext from 'node:test';
@@ -16,10 +31,18 @@ import { concat } from "../../path/module.f.js";
 import { normalize } from "../../path/module.f.js";
 import {} from "../module.f.js";
 import { asyncRun } from "../module.js";
+import { memoryOperationMap } from "./memory/module.js";
 import {} from "./module.f.js";
 import { asBase, asNominal } from "../../types/nominal/module.f.js";
 import { error, ok } from "../../types/result/module.f.js";
 import { fromVec, listToVec, toVec } from "../../types/uint8array/module.f.js";
+/**
+ * Narrowed structural view of `node:http`'s `createServer`. The official types
+ * declare `method`/`url` optional and header values as
+ * `string | string[] | undefined`, while the effect-level `RequestListener`
+ * requires them present; this local view keeps the narrowing in one place.
+ */
+const createServer = http.createServer;
 const tc = async (f) => {
     try {
         return ok(await f());
@@ -35,97 +58,34 @@ const collect = async (v) => {
     }
     return result;
 };
-const fromIo = ({ fs: { promises: { mkdir, readFile, readdir, writeFile, rm, access } }, fetch, http: { createServer }, childProcess, asyncImport, now: ioNow, sandbox, write, await: awaitPromise, }) => {
-    const result = asyncRun({
-        all: async (...effects) => await Promise.all(effects.map(result)),
-        fetch: async (url) => tc(async () => {
-            const response = await fetch(url);
-            if (!response.ok) {
-                throw new Error(`Fetch error: ${response.status} ${response.statusText}`);
-            }
-            return toVec(new Uint8Array(await response.arrayBuffer()));
-        }),
-        mkdir: (...p) => tc(async () => { await mkdir(...p); }),
-        readFile: path => tc(async () => toVec(await readFile(path))),
-        readdir: (path, r) => tc(async () => (await readdir(path, { ...r, withFileTypes: true }))
-            .map(v => ({
-            name: v.name,
-            parentPath: normalize(v.parentPath),
-            isFile: v.isFile()
-        }))),
-        writeFile: (path, data) => tc(() => writeFile(path, fromVec(data))),
-        rm: path => tc(() => rm(path)),
-        access: path => tc(() => access(path)),
-        import: path => tc(() => asyncImport(path)),
-        exec: (command, stdin) => new Promise(resolve => {
-            const child = childProcess.exec(command, (e, stdout, stderr) => resolve(e !== null ? ['error', e] : ok({ stdout, stderr })));
-            child.stdin?.end(stdin);
-        }),
-        createServer: async (requestListener) => {
-            const erl = requestListener;
-            const nodeRl = async (req, res) => {
-                const reqBody = await collect(req);
-                const { method, url, headers } = req;
-                const { status, headers: outHeaders, body: outBody } = await result(erl({
-                    method,
-                    url,
-                    headers,
-                    body: listToVec(reqBody)
-                }));
-                res
-                    .writeHead(status, outHeaders)
-                    .end(fromVec(outBody));
-            };
-            const server = asNominal(createServer(nodeRl));
-            return server;
-        },
-        listen: async (server, port) => {
-            const s = asBase(server);
-            s.listen(port);
-        },
-        forever: () => new Promise(() => { }),
-        now: async () => ioNow(),
-        sandbox,
-        await: awaitPromise,
-        write,
-        test: async (ctx, name, expectFailure, test) => ctx.test(name, { expectFailure }, async (t) => result(test(t))),
-    });
-    return result;
-};
-const runProgram = (io) => {
-    const { process: { env, stdout, stderr }, testContext, bunTestContext, playwrightTestContext, engine } = io;
-    const std = { stdout, stderr };
-    const f = fromIo(io);
-    return args => {
-        const options = { args, env, std, testContext, bunTestContext, playwrightTestContext, engine };
-        return program => f(program(options));
-    };
+const { mkdir, readFile, readdir, writeFile, rm, access } = fs.promises;
+const { exec } = childProcess;
+const prefix = 'file:///';
+const asyncImport = (v) => {
+    const s0 = v.includes(':') || v.startsWith('/') ? v : concat(process.cwd())(v);
+    const s1 = s0.startsWith(prefix) ? s0 : `${prefix}${s0}`;
+    return import(__rewriteRelativeImportExtension(s1));
 };
-const isPlaywright = 'PLAYWRIGHT_TEST' in (process?.env ?? {});
-const pwTest = isPlaywright
-    ? (await import('@playwright/test')).test
-    : undefined;
-const inlineTest = async (name, { expectFailure }, fn) => {
-    if (expectFailure) {
-        try {
-            await fn(inlineContext);
-        }
-        catch {
-            return;
+const sandbox = async (f) => {
+    let result;
+    let after;
+    const before = performance.now();
+    try {
+        let p = f();
+        after = performance.now();
+        if (p instanceof Promise) {
+            p = await p;
+            after = performance.now();
         }
-        throw new Error(`expected to throw: ${name}`);
+        result = ok(p);
     }
-    else {
-        await fn(inlineContext);
+    catch (e) {
+        after = performance.now();
+        result = error(e);
     }
+    return { result, duration: after - before };
 };
-const inlineContext = { test: inlineTest };
-const wrapInlineTest = (register) => ({
-    test: (name, opts, fn) => register(name, () => inlineTest(name, opts, fn))
-});
-const bunTestContext = wrapInlineTest(testContext.test);
-const playwrightTestContext = wrapInlineTest(pwTest);
-const prefix = 'file:///';
+const awaitPromise = async (p) => [p instanceof Promise ? await p : p];
 const { now } = Date;
 /** Maps `WriteConsoles` names to the corresponding Node.js writable streams. */
 const streams = {
@@ -151,67 +111,138 @@ const writeAll = async (stream, data) => {
         await once(stream, 'drain');
     }
 };
-const asyncImport = (v) => import(__rewriteRelativeImportExtension(v));
-const tryCatch = f => {
-    try {
-        return ok(f());
-    }
-    catch (e) {
-        return error(e);
+/**
+ * Resolves `true` once stdin reaches EOF, or `false` as soon as more data is
+ * readable. Both listeners are removed the moment either fires, so a
+ * long-running server that idles between messages never accumulates leftover
+ * `'readable'`/`'end'` listeners (which would eventually trip
+ * `MaxListenersExceededWarning`).
+ */
+const waitReadableOrEnd = (stdin) => new Promise(resolve => {
+    const cleanup = () => {
+        stdin.removeListener('readable', onReadable);
+        stdin.removeListener('end', onEnd);
+    };
+    const onReadable = () => { cleanup(); resolve(false); };
+    const onEnd = () => { cleanup(); resolve(true); };
+    stdin.once('readable', onReadable);
+    stdin.once('end', onEnd);
+});
+/**
+ * Reads one byte from `process.stdin`, or `null` at EOF.
+ *
+ * `read(1)` returns `null` both at end-of-stream and when no byte is buffered
+ * yet, so the two are told apart by waiting on `'readable'` (more data) vs
+ * `'end'` (EOF). The line framing lives in the pure `readLine` combinator; this
+ * interpreter is deliberately just "next byte".
+ */
+const readStdinByte = async () => {
+    const stdin = process.stdin;
+    while (true) {
+        const chunk = stdin.read(1);
+        if (chunk !== null) {
+            return chunk[0];
+        }
+        if (stdin.readableEnded) {
+            return null;
+        }
+        if (await waitReadableOrEnd(stdin)) {
+            return null;
+        }
     }
 };
-const awaitPromise = async (p) => [p instanceof Promise ? await p : p];
-const io = {
-    console,
-    fs,
-    process,
-    asyncImport: (v) => {
-        const s0 = v.includes(':') || v.startsWith('/') ? v : concat(process.cwd())(v);
-        const s1 = s0.startsWith(prefix) ? s0 : `${prefix}${s0}`;
-        return asyncImport(s1);
-    },
-    performance,
-    fetch,
-    tryCatch,
-    asyncTryCatch: async (f) => {
-        try {
-            return ok(await f());
-        }
-        catch (e) {
-            return error(e);
+const runNodeEffect = asyncRun({
+    ...memoryOperationMap(),
+    all: async (...effects) => await Promise.all(effects.map(runNodeEffect)),
+    fetch: async (url) => tc(async () => {
+        const response = await fetch(url);
+        if (!response.ok) {
+            throw new Error(`Fetch error: ${response.status} ${response.statusText}`);
         }
+        return toVec(new Uint8Array(await response.arrayBuffer()));
+    }),
+    mkdir: (...p) => tc(async () => { await mkdir(...p); }),
+    readFile: path => tc(async () => toVec(await readFile(path))),
+    readdir: (path, r) => tc(async () => (await readdir(path, { ...r, withFileTypes: true }))
+        .map(v => ({
+        name: v.name,
+        parentPath: normalize(v.parentPath),
+        isFile: v.isFile()
+    }))),
+    writeFile: (path, data) => tc(() => writeFile(path, fromVec(data))),
+    rm: path => tc(() => rm(path)),
+    access: path => tc(() => access(path)),
+    import: path => tc(() => asyncImport(path)),
+    exec: (command, stdin) => new Promise(resolve => {
+        const child = exec(command, (e, stdout, stderr) => resolve(e !== null ? ['error', e] : ok({ stdout, stderr })));
+        child.stdin?.end(stdin);
+    }),
+    createServer: async (requestListener) => {
+        const erl = requestListener;
+        const nodeRl = async (req, res) => {
+            const reqBody = await collect(req);
+            const { method, url, headers } = req;
+            const { status, headers: outHeaders, body: outBody } = await runNodeEffect(erl({
+                method,
+                url,
+                headers,
+                body: listToVec(reqBody)
+            }));
+            res
+                .writeHead(status, outHeaders)
+                .end(fromVec(outBody));
+        };
+        const server = asNominal(createServer(nodeRl));
+        return server;
     },
-    http,
-    childProcess,
-    now,
-    sandbox: async (f) => {
-        let result;
-        let after;
-        const before = performance.now();
+    listen: async (server, port) => {
+        const s = asBase(server);
+        s.listen(port);
+    },
+    forever: () => new Promise(() => { }),
+    now: async () => now(),
+    sandbox,
+    await: awaitPromise,
+    write: (stream, data) => writeAll(streams[stream], fromVec(data)),
+    read: readStdinByte,
+    test: async (ctx, name, expectFailure, test) => ctx.test(name, { expectFailure }, async (t) => runNodeEffect(test(t))),
+});
+const isPlaywright = 'PLAYWRIGHT_TEST' in (process?.env ?? {});
+const pwTest = isPlaywright
+    ? (await import('@playwright/test')).test
+    : undefined;
+const inlineTest = async (name, { expectFailure }, fn) => {
+    if (expectFailure) {
         try {
-            let p = f();
-            after = performance.now();
-            if (p instanceof Promise) {
-                p = await p;
-                after = performance.now();
-            }
-            result = ok(p);
+            await fn(inlineContext);
         }
-        catch (e) {
-            after = performance.now();
-            result = error(e);
+        catch {
+            return;
         }
-        return { result, duration: after - before };
-    },
-    write: (stream, data) => writeAll(streams[stream], fromVec(data)),
-    await: awaitPromise,
+        throw new Error(`expected to throw: ${name}`);
+    }
+    else {
+        await fn(inlineContext);
+    }
+};
+const inlineContext = { test: inlineTest };
+const wrapInlineTest = (register) => ({
+    test: (name, opts, fn) => register(name, () => inlineTest(name, opts, fn))
+});
+const bunTestContext = wrapInlineTest(testContext.test);
+const playwrightTestContext = wrapInlineTest(pwTest);
+const options = {
+    args: process.argv.slice(2),
+    env: process.env,
+    home: os.homedir(),
+    std: { stdout: process.stdout, stderr: process.stderr },
     testContext,
     bunTestContext,
     playwrightTestContext,
     engine: isPlaywright ? 'playwright' : 'Bun' in globalThis ? 'bun' : 'node',
 };
 /**
- * Runs a `NodeProgram` against the real Node `io` and process arguments,
+ * Runs a `NodeProgram` against the real Node globals and process arguments,
  * resolving to its exit code **without** terminating the process.
  *
  * Use this when the caller must stay alive afterwards — e.g. when proofs are
@@ -219,7 +250,7 @@ const io = {
  * that owns the process lifecycle. For a standalone CLI entry point that should
  * exit with the program's code, use {@link run} instead.
  */
-export const runEffect = runProgram(io)(io.process.argv.slice(2));
+export const runEffect = program => runNodeEffect(program(options));
 /**
  * CLI entry point: runs a `NodeProgram` via {@link runEffect}, then calls
  * `process.exit` with its exit code. The `Promise<never>` return type reflects

package/fs/effects/node/proof.f.d.ts

@@ -12,6 +12,10 @@ export declare const proof: {
         noSuchFile: () => void;
         nestedPath: () => void;
     };
+    readUtf8File: {
+        ok: () => void;
+        noSuchFile: () => void;
+    };
     readdir: {
         one: () => void;
         nonRecursive: () => void;
@@ -24,15 +28,21 @@ export declare const proof: {
         nestedPath: () => void;
         directory: () => void;
     };
+    writeUtf8File: () => void;
     rm: {
         one: () => void;
         nested: () => void;
         noSuchFile: () => void;
         isDirectory: () => void;
     };
+    both: () => void;
     now: () => void;
     sandbox: {
         ok: () => void;
         error: () => void;
     };
+    memory: {
+        createAndRead: () => void;
+        createAndWrite: () => void;
+    };
 };

package/fs/effects/node/proof.f.js

@@ -1,33 +1,30 @@
 import { empty, isVec, uint, vec8 } from "../../types/bit_vec/module.f.js";
-import { pure } from "../module.f.js";
-import { fetch, mkdir, now, readdir, readFile, rm, sandbox, writeFile } from "./module.f.js";
+import { utf8, utf8ToString } from "../../text/module.f.js";
+import { decode, pure } from "../module.f.js";
+import { both, fetch, mkdir, now, readdir, readFile, readUtf8File, rm, sandbox, writeFile, writeUtf8File } from "./module.f.js";
+import { create as memCreate, read as memRead, write as memWrite } from "../memory/module.f.js";
 import { emptyState, virtual } from "./virtual/module.f.js";
 export const proof = {
     map: () => {
-        let e = readFile('hello').step(([k, v]) => {
+        const e = readFile('hello').step(([k, v]) => {
             if (k === 'error') {
                 throw v;
             }
             return pure(uint(v) * 2n);
         });
         //
-        while (true) {
-            const { value } = e;
-            if (value.length === 1) {
-                const [result] = value;
-                if (result !== 0x2an) {
-                    throw result;
-                }
-                return;
-            }
-            const [cmd, p, cont] = value;
-            if (cmd !== 'readFile') {
-                throw cmd;
-            }
-            if (p[0] !== 'hello') {
-                throw p;
-            }
-            e = cont(['ok', vec8(0x15n)]);
+        let d = decode(e);
+        while (!d.done) {
+            if (d.command !== 'readFile') {
+                throw d.command;
+            }
+            if (d.payload[0] !== 'hello') {
+                throw d.payload;
+            }
+            d = decode(d.continuation(['ok', vec8(0x15n)]));
+        }
+        if (d.result !== 0x2an) {
+            throw d.result;
         }
     },
     fetch: () => {
@@ -127,11 +124,31 @@ export const proof = {
             if (t !== 'error') {
                 throw result;
             }
-            if (result !== 'no such file') {
+            if (result.code !== 'ENOENT') {
                 throw result;
             }
         }
     },
+    readUtf8File: {
+        ok: () => {
+            const [_, [t, result]] = virtual({
+                ...emptyState,
+                root: { hello: utf8('Hello, world!') },
+            })(readUtf8File('hello'));
+            if (t !== 'ok') {
+                throw result;
+            }
+            if (result !== 'Hello, world!') {
+                throw result;
+            }
+        },
+        noSuchFile: () => {
+            const [_, [t, result]] = virtual(emptyState)(readUtf8File('hello'));
+            if (t !== 'error') {
+                throw result;
+            }
+        },
+    },
     readdir: {
         one: () => {
             const [_, [t, result]] = virtual({
@@ -272,6 +289,19 @@ export const proof = {
             }
         },
     },
+    writeUtf8File: () => {
+        const [state, [t, result]] = virtual(emptyState)(writeUtf8File('hello', 'Hello, world!'));
+        if (t !== 'ok') {
+            throw result;
+        }
+        const file = state.root.hello;
+        if (!isVec(file)) {
+            throw file;
+        }
+        if (utf8ToString(file) !== 'Hello, world!') {
+            throw file;
+        }
+    },
     rm: {
         one: () => {
             const [state, [t, result]] = virtual({
@@ -326,6 +356,27 @@ export const proof = {
             }
         },
     },
+    both: () => {
+        const [_, results] = virtual({
+            ...emptyState,
+            root: {
+                a: vec8(0x2an),
+                b: vec8(0x15n),
+            },
+        })(both(readFile('a'))(readFile('b')));
+        if (results[0][0] !== 'ok') {
+            throw results[0];
+        }
+        if (results[1][0] !== 'ok') {
+            throw results[1];
+        }
+        if (uint(results[0][1]) !== 0x2an) {
+            throw results[0][1];
+        }
+        if (uint(results[1][1]) !== 0x15n) {
+            throw results[1][1];
+        }
+    },
     now: () => {
         const [_, result] = virtual({ ...emptyState, epochNs: 1_000_000 })(now());
         if (result !== 1_000_000) {
@@ -359,4 +410,20 @@ export const proof = {
             }
         },
     },
+    memory: {
+        createAndRead: () => {
+            const effect = memCreate(42).step(key => memRead(key));
+            const [_, value] = virtual(emptyState)(effect);
+            if (value !== 42) {
+                throw value;
+            }
+        },
+        createAndWrite: () => {
+            const effect = memCreate(1).step(key => memWrite(key, 99).step(() => memRead(key)));
+            const [_, value] = virtual(emptyState)(effect);
+            if (value !== 99) {
+                throw value;
+            }
+        },
+    },
 };

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

@@ -17,11 +17,17 @@ export type Dir = {
 export type State = {
     stdout: string;
     stderr: string;
+    /** Remaining stdin bytes; each `read` pops the first, `null` at EOF. */
+    stdin: readonly number[];
     root: Dir;
     internet: {
         readonly [url: string]: Vec;
     };
     epochNs: number;
+    memoryNext: number;
+    memoryValues: {
+        readonly [key: string]: unknown;
+    };
 };
 export declare const emptyState: State;
 export declare const virtual: RunInstance<NodeOp, State>;