functionalscript 0.43.1 → 0.44.0

package/fjs/effects/node/module.f.d.ts

@@ -1,300 +0,0 @@
-import { type Vec } from '../../types/bit_vec/module.f.ts';
-import type { MemOp } from '../memory/module.f.ts';
-import type { Nominal } from '../../types/nominal/module.f.ts';
-import { type Result } from '../../types/result/module.f.ts';
-import type { StringMap } from '../../types/object/module.f.ts';
-import { type Effect, type Func, type Operation, type ToAsyncOperationMap } from '../module.f.ts';
-import type { List } from '../list/module.f.ts';
-export type IoResult<T> = Result<T, unknown>;
-/**
- * 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 declare const isNotFound: (e: unknown) => boolean;
-export type All = ['all', <T>(...effects: Effect<never, T>[]) => readonly T[]];
-/**
- * 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`.
- *
- * @param a
- * @returns
- */
-export declare const all: <O extends Operation, T>(...a: readonly Effect<O, T>[]) => Effect<O | All, readonly T[]>;
-export declare const both: <O0 extends Operation, T0>(a: Effect<O0, T0>) => <O1 extends Operation, T1>(b: Effect<O1, T1>) => Effect<O0 | O1 | All, readonly [T0, T1]>;
-export type Fetch = ['fetch', (url: string) => IoResult<Vec>];
-export declare const fetch: Func<Fetch>;
-export type MakeDirectoryOptions = {
-    readonly recursive: true;
-};
-export type Mkdir = readonly ['mkdir', (path: string, options?: MakeDirectoryOptions) => IoResult<void>];
-export declare const mkdir: Func<Mkdir>;
-/**
- * Reads a file as a bit vector. File size is limited to 131,072 bytes (128 KiB)
- * to respect Bun's `bigint` size constraint (1,048,575 bits), which is the
- * minimal limit across all runtime environments supported by FunctionalScript.
- * Files exceeding this limit will fail with a validation error.
- */
-export type ReadFile = readonly ['readFile', (path: string) => IoResult<Vec>];
-export declare const readFile: Func<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 declare const readUtf8File: (path: string) => Effect<ReadFile, IoResult<string>>;
-/**
- * Represents a directory entry (file or directory) in the filesystem
- * @see https://nodejs.org/api/fs.html#class-fsdirent
- */
-export type Dirent = {
-    readonly name: string;
-    readonly parentPath: string;
-    readonly isFile: boolean;
-};
-export type ReaddirOptions = {
-    readonly recursive?: true;
-};
-export type Readdir = readonly ['readdir', (path: string, options: ReaddirOptions) => IoResult<readonly Dirent[]>];
-export declare const readdir: Func<Readdir>;
-export type WriteFile = readonly ['writeFile', (path: string, data: Vec) => IoResult<void>];
-export declare const writeFile: Func<WriteFile>;
-/** Writes a string to `path` as UTF-8 bytes. */
-export declare const writeUtf8File: (path: string, content: string) => Effect<WriteFile, IoResult<void>>;
-export type Rm = readonly ['rm', (path: string) => IoResult<void>];
-export declare const rm: Func<Rm>;
-export type Rename = readonly ['rename', (src: string, dst: string) => IoResult<void>];
-export declare const rename: Func<Rename>;
-export type ReadBytes = readonly ['readBytes', (path: string, offset: number, size: number) => IoResult<Vec>];
-export declare const readBytes: Func<ReadBytes>;
-export type RandomInt = readonly ['randomInt', () => number];
-export declare const randomInt: Func<RandomInt>;
-export type ExecResult = {
-    readonly stdout: string;
-    readonly stderr: string;
-};
-export type Exec = readonly ['exec', (command: string, stdin?: string) => IoResult<ExecResult>];
-export declare const exec: Func<Exec>;
-export type Access = readonly ['access', (path: string) => IoResult<void>];
-export declare const access: Func<Access>;
-/**
- * Creates `path` as an empty file with `O_CREAT|O_EXCL` — fails if it already
- * exists. This is the exclusive create that claims a staging name in the
- * lock-free upload ([staging-lease.md](../../../issues/cas/staging-lease.md));
- * with 256 random bits in the name `EEXIST` never happens in practice, so it
- * is just a sanity guard.
- */
-export type CreateExclusive = readonly ['createExclusive', (path: string) => IoResult<void>];
-export declare const createExclusive: Func<CreateExclusive>;
-/**
- * Writes the **entire** `data` vector to an **existing** `path` at byte `offset`
- * (positional write). The mirror of {@link readBytes}: it never creates the file
- * (a missing path is `ENOENT`), and it writes every byte or returns an error —
- * the runner loops over short writes — so a later size check can never pass over
- * a hole. Bounded to ≤128 KiB per call, like `readBytes`.
- */
-export type WriteBytes = readonly ['writeBytes', (path: string, offset: number, data: Vec) => IoResult<void>];
-export declare const writeBytes: Func<WriteBytes>;
-export declare const writeFromStream: <O extends Operation>(path: string, e: List<O, IoResult<Vec>>) => Effect<O | WriteBytes | CreateExclusive, IoResult<void>>;
-/** File metadata returned by {@link stat}. Only `size` (in bytes) for now. */
-export type FileStat = {
-    readonly size: number;
-};
-export type Stat = readonly ['stat', (path: string) => IoResult<FileStat>];
-export declare const stat: Func<Stat>;
-export type Fs = Mkdir | ReadFile | ReadBytes | Readdir | WriteFile | Rm | Rename | Exec | Access | CreateExclusive | WriteBytes | Stat;
-export type Server = Nominal<'server', `160855c4f69310fece3273c1853ac32de43dee1eb41bf59d821917f8eebe9272`, unknown>;
-export type Headers = StringMap<string>;
-export type IncomingMessage = {
-    readonly method: string;
-    readonly url: string;
-    readonly headers: Headers;
-    readonly body: Vec;
-};
-export type ServerResponse = {
-    readonly status: number;
-    readonly headers: Headers;
-    readonly body: Vec;
-};
-export type RequestListener<O extends Operation> = (_: IncomingMessage) => Effect<O, ServerResponse>;
-export type CreateServer = ['createServer', (listener: RequestListener<Operation>) => Server];
-export declare const createServer: <O extends Operation>(listener: RequestListener<O>) => Effect<O | CreateServer, Server>;
-export type Listen = ['listen', (server: Server, port: number) => void];
-export declare const listen: Func<Listen>;
-export type Http = CreateServer | Listen;
-export type Forever = ['forever', () => never];
-export declare const forever: Func<Forever>;
-export type Module = StringMap<unknown>;
-export type Import = ['import', (path: string) => IoResult<Module>];
-export declare const import_: Func<Import>;
-/** Named output streams accepted by the `Write` effect. */
-export type WriteConsoles = 'stdout' | 'stderr';
-/**
- * Raw byte write to a named output stream. Encoding-agnostic — callers supply
- * a `Vec`. The Node runner maps each stream name to the appropriate fd and
- * delegates to the OS via `stream.write()` with backpressure handling.
- */
-export type Write = readonly ['write', (stream: WriteConsoles, data: Vec) => void];
-/** Emits a `Write` effect to the given named stream. */
-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;
-/** Named input streams accepted by the `Read` effect. */
-export type ReadConsoles = 'stdin';
-/**
- * Reads a single byte from a named input stream — the byte-granular dual of
- * {@link write}. Resolves to the byte value (`0`–`255`) or `null` at end of
- * input (EOF). One byte at a time: the effect carries no buffering or line
- * policy, so higher-level framing (see {@link readLine}) lives in pure code
- * rather than the interpreter. Back-pressure is naturally sequential — the next
- * `read` is only issued once the previous byte is consumed.
- */
-export type Read = readonly ['read', (stream: ReadConsoles) => number | null];
-/** Emits a `Read` effect, yielding the next input byte or `null` at EOF. */
-export declare const read: Func<Read>;
-/**
- * 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 declare const readLine: (stream: ReadConsoles) => Effect<Read, string | null>;
-export type Now = readonly ['now', () => number];
-export declare const now: Func<Now>;
-/**
- * The outcome of a `Sandbox` operation.
- *
- * `result` carries either `['ok', value]` or `['error', thrown]`. `duration`
- * is a floating-point millisecond count with up to microsecond precision,
- * matching `performance.now()` directly. Additional fields (allocated memory,
- * max stack depth, coverage) may be added in future without breaking consumers.
- */
-export type SandboxResult<T> = {
-    readonly result: Result<T, unknown>;
-    /**
-     * Elapsed time in milliseconds (microsecond precision via `performance.now()`).
-     * The virtual runner returns `0` for deterministic tests.
-     */
-    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>;
-/**
- * Resolves the return value of a test function inside the effect runner.
- * If `p` is a real `Promise`, it is awaited and rejections propagate as
- * throws. If `p` is any other value it is returned as-is. Plain thenables
- * (objects with a `.then` method that are not `instanceof Promise`) are
- * treated as ordinary values — not awaited. See `fjs/dev/tf/README.md`.
- */
-export type Await = readonly ['await', (p: unknown) => readonly [unknown]];
-export declare const awaitIfPromise: (p: unknown) => Effect<Await, unknown>;
-/**
- * Signature of a framework test-registration function (e.g. `nodeTest.test`,
- * `bunTest.test`). Returns `Promise<void>` so async sub-tests can be awaited.
- */
-export type TestFn = (name: string, options: {
-    readonly expectFailure: boolean;
-}, fn: (t: TestContext) => Promise<void>) => Promise<void>;
-/**
- * A thin wrapper around a framework's `test` function. Passed through
- * `registerModule` so nested test registration uses the appropriate context
- * (e.g. `inlineContext` on Bun, which does not support nested `test()` calls
- * inside a callback).
- */
-export type TestContext = {
-    readonly test: TestFn;
-};
-/** Effect operation that registers a named test with the active `TestContext`. */
-export type Test = readonly ['test', (ctx: TestContext, name: string, expectFailure: boolean, test: (t: TestContext) => Effect<Test | All | Await, void>) => void];
-export declare const test: Func<Test>;
-export type NodeOp = Access | All | Await | Fetch | Fs | Http | Forever | Import | MemOp | Now | RandomInt | Read | Sandbox | Write | Test;
-export type NodeEffect<T> = Effect<NodeOp, T>;
-/**
- * Writes an error line to `stderr` and yields exit code `1`. The canonical
- * "fail with a message" program for a `NodeProgram`. For non-`1` exit codes,
- * compose `mapStep(error(s), () => n)` directly.
- */
-export declare const errorExit: (s: string) => Effect<Write, number>;
-export type NodeOperationMap = ToAsyncOperationMap<NodeOp>;
-/**
- * The environment variables.
- */
-export type Env = {
-    readonly [k: string]: string | undefined;
-};
-/** Identifies the JavaScript runtime detected at startup. */
-export type Engine = 'node' | 'bun' | 'deno';
-/** Compares semantic versions numerically by major, minor, then patch. */
-export declare const versionLessThan: (version: string, minimum: string) => boolean;
-/**
- * Reports whether an external runner needs FunctionalScript's flattened test
- * registration strategy. Node uses the native `expectFailure` option only
- * from the Node 26 baseline; Deno is deliberately exempt from this Node-only
- * version check.
- */
-export declare const usesInlineTestContext: (engine: Engine, nodeVersion?: string) => boolean;
-/**
- * Runtime options passed to every `NodeProgram`.
- *
- * - `args`: command-line arguments (equivalent to `process.argv.slice(2)`).
- * - `env`: process environment variables.
- * - `std`: TTY flags for `stdout` and `stderr`, known at startup and used by
- *   `csiWrite` to decide whether to strip ANSI SGR sequences.
- * - `testContext`: Node `--test` context; used by `register` on Node.
- * - `bunTestContext`: Bun-compatible context that flattens nested tests inline,
- *   working around Bun's lack of nested `test()` support.
- * - `engine`: runtime detected at startup; controls which context `register` selects.
- * - `nodeVersion`: detected Node version; absent for other and virtual runtimes.
- * - `inlineTestContext`: whether the selected context flattens nested tests.
- */
-export type NodeProgramOptions = {
-    readonly args: readonly string[];
-    readonly env: Env;
-    readonly home: string;
-    readonly std: {
-        readonly [k in WriteConsoles]: {
-            readonly isTTY: boolean;
-        };
-    };
-    readonly testContext: TestContext;
-    readonly bunTestContext: TestContext;
-    readonly engine: Engine;
-    readonly nodeVersion?: string;
-    readonly inlineTestContext: boolean;
-};
-export type Program<O extends Operation> = (options: NodeProgramOptions) => Effect<O, number>;
-export type NodeProgram = Program<NodeOp>;

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

@@ -1,171 +0,0 @@
-/**
- * Node.js effect operations: filesystem (`mkdir`, `readFile`, `readdir`,
- * `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, 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 { length } from '../../types/bit_vec/module.f.js';
-import { ok, error as resultError, mapOk } from '../../types/result/module.f.js';
-import { do_, mapStep, okStep, pure, step } from '../module.f.js';
-/**
- * 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`.
- *
- * @param a
- * @returns
- */
-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) => mapStep(readFile(path), mapOk(utf8ToString));
-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 rename = do_('rename');
-export const readBytes = do_('readBytes');
-export const randomInt = do_('randomInt');
-export const exec = do_('exec');
-export const access = do_('access');
-export const createExclusive = do_('createExclusive');
-export const writeBytes = do_('writeBytes');
-const writeLoop = (path) => {
-    const f = (offset, e) => step(e, r => {
-        if (r === undefined) {
-            return pure(ok(undefined));
-        }
-        const { first: [t, v], tail } = r;
-        if (t === 'error') {
-            return pure(resultError(v));
-        }
-        const lenV = length(v);
-        if ((lenV & 7n) !== 0n) {
-            return pure(resultError('invalid buffer size'));
-        }
-        return step(writeBytes(path, offset, v), okStep(() => f(offset + Number(lenV >> 3n), tail)));
-    });
-    return f;
-};
-export const writeFromStream = (path, e) => step(createExclusive(path), okStep(() => writeLoop(path)(0, e)));
-export const stat = do_('stat');
-export const createServer = do_('createServer');
-export const listen = do_('listen');
-export const forever = do_('forever');
-export const import_ = do_('import');
-/** Emits a `Write` effect to the given named stream. */
-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');
-/** 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) => step(read(stream), 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.
- *
- * 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');
-const awaitPromise = do_('await');
-export const awaitIfPromise = (p) => mapStep(awaitPromise(p), ([x]) => x);
-export const test = do_('test');
-/**
- * Writes an error line to `stderr` and yields exit code `1`. The canonical
- * "fail with a message" program for a `NodeProgram`. For non-`1` exit codes,
- * compose `mapStep(error(s), () => n)` directly.
- */
-export const errorExit = (s) => mapStep(error(s), () => 1);
-const versionParts = (version) => version.replace(/^v/, '').split('.').map(Number);
-/** Compares semantic versions numerically by major, minor, then patch. */
-export const versionLessThan = (version, minimum) => {
-    const [major = 0, minor = 0, patch = 0] = versionParts(version);
-    const [minMajor = 0, minMinor = 0, minPatch = 0] = versionParts(minimum);
-    return major < minMajor || major === minMajor && (minor < minMinor || minor === minMinor && patch < minPatch);
-};
-/**
- * Reports whether an external runner needs FunctionalScript's flattened test
- * registration strategy. Node uses the native `expectFailure` option only
- * from the Node 26 baseline; Deno is deliberately exempt from this Node-only
- * version check.
- */
-export const usesInlineTestContext = (engine, nodeVersion) => {
-    if (engine === 'bun') {
-        return true;
-    }
-    if (engine !== 'node' || nodeVersion === undefined) {
-        return false;
-    }
-    return versionLessThan(nodeVersion, '26.0.0');
-};