functionalscript 0.19.0 → 0.20.0

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

@@ -77,8 +77,15 @@ export type Module = {
 };
 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. */
@@ -87,12 +94,19 @@ export declare const log: Console;
 export declare const error: Console;
 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>;
     /**
-     * Measured milliseconds but it's not limited to that.
-     * Instead, they represent times as floating-point numbers
-     * with up to microsecond precision.
+     * Elapsed time in milliseconds (microsecond precision via `performance.now()`).
+     * The virtual runner returns `0` for deterministic tests.
      */
     readonly duration: number;
 };
@@ -116,15 +130,36 @@ export type Sandbox = readonly ['sandbox', <T>(f: () => T) => SandboxResult<T>];
  * @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 `fs/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`, `pwTest`). 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 and Playwright, which do not support nested
+ * `test()` calls inside a callback).
+ */
 export type TestContext = {
     readonly test: TestFn;
 };
-export type Test = readonly ['test', (ctx: TestContext, name: string, expectFailure: boolean, test: (t: TestContext) => Effect<Test | All, void>) => void];
+/** 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 = All | Fetch | Fs | Http | Forever | Import | Now | Sandbox | Write | Test;
+export type NodeOp = All | Await | Fetch | Fs | Http | Forever | Import | Now | Sandbox | Write | Test;
 export type NodeEffect<T> = Effect<NodeOp, T>;
 export type NodeOperationMap = ToAsyncOperationMap<NodeOp>;
 /**
@@ -133,7 +168,21 @@ export type NodeOperationMap = ToAsyncOperationMap<NodeOp>;
 export type Env = {
     readonly [k: string]: string | undefined;
 };
+/** Identifies the JavaScript runtime detected at startup. */
 export type Engine = 'node' | 'bun' | 'playwright';
+/**
+ * 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.
+ * - `playwrightTestContext`: Playwright context using the same inline strategy.
+ * - `engine`: runtime detected at startup; controls which context `register` selects.
+ */
 export type NodeProgramOptions = {
     readonly args: readonly string[];
     readonly env: Env;

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

@@ -8,7 +8,7 @@
  * @module
  */
 import { utf8 } from "../../../text/module.f.js";
-import { do_ } from "../module.f.js";
+import { do_, pure } from "../module.f.js";
 const doAll = do_('all');
 /**
  * To run the operation `O` should be known by the runner/engine.
@@ -31,6 +31,7 @@ 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`.
@@ -61,4 +62,6 @@ export const now = do_('now');
  * @see {@link SandboxResult}
  */
 export const sandbox = do_('sandbox');
+const awaitPromise = do_('await');
+export const awaitIfPromise = (p) => awaitPromise(p).step(([x]) => pure(x));
 export const test = do_('test');

package/fs/types/effects/node/{test.f.d.ts → proof.f.d.ts}

@@ -1,4 +1,4 @@
-declare const _default: {
+export declare const proof: {
     map: () => void;
     fetch: () => void;
     mkdir: {
@@ -36,4 +36,3 @@ declare const _default: {
         error: () => void;
     };
 };
-export default _default;

package/fs/types/effects/node/{test.f.js → proof.f.js}

@@ -2,7 +2,7 @@ import { empty, isVec, uint, vec8 } from "../../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 { emptyState, virtual } from "./virtual/module.f.js";
-export default {
+export const proof = {
     map: () => {
         let e = readFile('hello').step(([k, v]) => {
             if (k === 'error') {

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

@@ -167,6 +167,7 @@ const map = {
     // exception in a fixture propagates loudly as a bug in the fixture.
     // See: issues/156-tf-virtual-tests.md
     sandbox: (state, f) => [state, f()],
+    await: (state, p) => [state, [p]],
     test: todo,
     write: (state, stream, data) => {
         const s = utf8ToString(data);

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

@@ -0,0 +1,11 @@
+export declare const proof: {
+    foldStep: {
+        empty: () => void;
+        threadsState: () => void;
+        order: () => void;
+    };
+    forEachStep: {
+        empty: () => void;
+        runs: () => void;
+    };
+};

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

@@ -0,0 +1,57 @@
+import { foldStep, forEachStep, pure } from "./module.f.js";
+export const proof = {
+    foldStep: {
+        empty: () => {
+            const e = foldStep((x) => (s) => pure(s + x))(10)([]);
+            const { value } = e;
+            if (value.length !== 1) {
+                throw value;
+            }
+            if (value[0] !== 10) {
+                throw value[0];
+            }
+        },
+        threadsState: () => {
+            const e = foldStep((x) => (s) => pure(s + x))(0)([1, 2, 3, 4]);
+            const { value } = e;
+            if (value.length !== 1) {
+                throw value;
+            }
+            if (value[0] !== 10) {
+                throw value[0];
+            }
+        },
+        order: () => {
+            const e = foldStep((x) => (s) => pure(s + x))('')(['a', 'b', 'c']);
+            const { value } = e;
+            if (value.length !== 1) {
+                throw value;
+            }
+            if (value[0] !== 'abc') {
+                throw value[0];
+            }
+        },
+    },
+    forEachStep: {
+        empty: () => {
+            const e = forEachStep(() => pure(undefined))([]);
+            const { value } = e;
+            if (value.length !== 1) {
+                throw value;
+            }
+            if (value[0] !== undefined) {
+                throw value[0];
+            }
+        },
+        runs: () => {
+            const e = forEachStep(() => pure(undefined))([1, 2, 3]);
+            const { value } = e;
+            if (value.length !== 1) {
+                throw value;
+            }
+            if (value[0] !== undefined) {
+                throw value[0];
+            }
+        },
+    },
+};

package/fs/types/function/compare/proof.f.d.ts

@@ -0,0 +1 @@
+export declare const proof: () => void;

package/fs/types/function/compare/{test.f.js → proof.f.js}

@@ -1,5 +1,5 @@
 import { cmp } from "./module.f.js";
-export default () => {
+export const proof = () => {
     {
         const result = cmp(true)(false);
         if (result !== 1) {

package/fs/types/function/operator/proof.f.d.ts

@@ -0,0 +1,12 @@
+export declare const proof: {
+    joinTest: () => void;
+    concatTest: () => void;
+    logicalNotTest: () => void;
+    strictEqualTest: () => void;
+    additionTest: () => void;
+    minTest: () => void;
+    maxTest: () => void;
+    incrementTest: () => void;
+    foldToScanTest: () => void;
+    reduceToScanTest: () => void;
+};

package/fs/types/function/operator/{test.f.js → proof.f.js}

@@ -1,17 +1,17 @@
 import { join, concat, logicalNot, strictEqual, addition, min, max, increment, foldToScan, reduceToScan, } from "./module.f.js";
-export const joinTest = () => {
+const joinTest = () => {
     const result = join(', ')('world')('hello');
     if (result !== 'hello, world') {
         throw result;
     }
 };
-export const concatTest = () => {
+const concatTest = () => {
     const result = concat('world')('hello');
     if (result !== 'helloworld') {
         throw result;
     }
 };
-export const logicalNotTest = () => {
+const logicalNotTest = () => {
     if (logicalNot(true) !== false) {
         throw 'expected false';
     }
@@ -19,7 +19,7 @@ export const logicalNotTest = () => {
         throw 'expected true';
     }
 };
-export const strictEqualTest = () => {
+const strictEqualTest = () => {
     if (!strictEqual(1)(1)) {
         throw 'expected true';
     }
@@ -27,13 +27,13 @@ export const strictEqualTest = () => {
         throw 'expected false';
     }
 };
-export const additionTest = () => {
+const additionTest = () => {
     const result = addition(3)(4);
     if (result !== 7) {
         throw result;
     }
 };
-export const minTest = () => {
+const minTest = () => {
     if (min(3)(5) !== 3) {
         throw 'min(3)(5)';
     }
@@ -41,7 +41,7 @@ export const minTest = () => {
         throw 'min(7)(2)';
     }
 };
-export const maxTest = () => {
+const maxTest = () => {
     if (max(3)(5) !== 5) {
         throw 'max(3)(5)';
     }
@@ -49,7 +49,7 @@ export const maxTest = () => {
         throw 'max(7)(2)';
     }
 };
-export const incrementTest = () => {
+const incrementTest = () => {
     if (increment(4) !== 5) {
         throw 'increment(4)';
     }
@@ -57,7 +57,7 @@ export const incrementTest = () => {
         throw 'increment(0)';
     }
 };
-export const foldToScanTest = () => {
+const foldToScanTest = () => {
     const scan = foldToScan(addition)(0);
     const [v1, scan2] = scan(3);
     if (v1 !== 3) {
@@ -68,7 +68,7 @@ export const foldToScanTest = () => {
         throw v2;
     }
 };
-export const reduceToScanTest = () => {
+const reduceToScanTest = () => {
     const scan = reduceToScan(addition);
     const [v0, scan2] = scan(10);
     if (v0 !== 10) {
@@ -79,3 +79,4 @@ export const reduceToScanTest = () => {
         throw v1;
     }
 };
+export const proof = { joinTest, concatTest, logicalNotTest, strictEqualTest, additionTest, minTest, maxTest, incrementTest, foldToScanTest, reduceToScanTest };

package/fs/types/function/proof.f.d.ts

@@ -0,0 +1 @@
+export declare const proof: () => void;

package/fs/types/function/{test.f.js → proof.f.js}

@@ -1,5 +1,5 @@
 import { fn } from "./module.f.js";
-export default () => {
+export const proof = () => {
     const f = x => [x];
     const g = ([x]) => [x.length];
     const w = ([x]) => x;

package/fs/types/list/{test.f.d.ts → proof.f.d.ts}

@@ -1,4 +1,4 @@
-declare const _default: {
+export declare const proof: {
     stringifyTest: () => void;
     cycle: () => void;
     countdown: () => void;
@@ -19,4 +19,3 @@ declare const _default: {
     isEmpty: (() => void)[];
     length: () => void;
 };
-export default _default;

package/fs/types/list/{test.f.js → proof.f.js}

@@ -321,7 +321,7 @@ const stress = () => ({
         }
     }
 });
-export default {
+export const proof = {
     stringifyTest,
     cycle: cycleTest,
     countdown: countdownTest,

package/fs/types/map/proof.f.d.ts

@@ -0,0 +1,4 @@
+export declare const proof: {
+    set: () => void;
+    delete: () => void;
+};

package/fs/types/map/{test.f.js → proof.f.js}

@@ -1,5 +1,5 @@
 import { mapSet, mapDelete } from "./module.f.js";
-export default {
+export const proof = {
     set: () => {
         const map = mapSet(new Map(), 'a', 'b');
         if (map.get('a') !== 'b') {

package/fs/types/monoid/{test.f.d.ts → proof.f.d.ts}

@@ -1,5 +1,4 @@
-declare const _default: {
+export declare const proof: {
     numberAdd: () => void;
     stringConcat: () => void;
 };
-export default _default;

package/fs/types/monoid/{test.f.js → proof.f.js}

@@ -1,5 +1,5 @@
 import { repeat } from "./module.f.js";
-export default {
+export const proof = {
     numberAdd: () => {
         const add = {
             identity: 0,

package/fs/types/nibble_set/{test.f.d.ts → proof.f.d.ts}

@@ -1,4 +1,4 @@
-declare const _default: {
+export declare const proof: {
     has: () => void;
     set: (() => void)[];
     unset: () => (() => void)[];
@@ -9,4 +9,3 @@ declare const _default: {
         universe: () => void;
     };
 };
-export default _default;

package/fs/types/nibble_set/{test.f.js → proof.f.js}

@@ -1,6 +1,6 @@
 import { every, map, countdown } from "../list/module.f.js";
 import { empty, has, set, setRange, unset, universe, complement } from "./module.f.js";
-export default {
+export const proof = {
     has: () => {
         if (has(0)(empty)) {
             throw empty;

package/fs/types/nominal/proof.f.d.ts

@@ -0,0 +1,4 @@
+export declare const proof: {
+    pre: () => void;
+    nominal: () => void;
+};

package/fs/types/nominal/{test.f.js → proof.f.js}

@@ -1,5 +1,5 @@
 import { asBase, asNominal } from "./module.f.js";
-export default {
+export const proof = {
     pre: () => {
         const strA = asNominal(7560413859n); // "¢£"
         const strB = asNominal(7560413860n); // "¢¤"

package/fs/types/nullable/proof.f.d.ts

@@ -0,0 +1 @@
+export declare const proof: (() => void)[];

package/fs/types/nullable/{test.f.js → proof.f.js}

@@ -1,5 +1,5 @@
 import { map, match, toOption } from "./module.f.js";
-export default [
+export const proof = [
     () => {
         const optionSq = map((v) => v * v);
         const sq3 = optionSq(3);

package/fs/types/number/{test.f.d.ts → proof.f.d.ts}

@@ -1,4 +1,4 @@
-declare const _default: {
+export declare const proof: {
     sum: () => void;
     min: {
         empty: () => void;
@@ -9,4 +9,3 @@ declare const _default: {
     standard: () => void;
     countOnes: (() => void)[];
 };
-export default _default;

package/fs/types/number/{test.f.js → proof.f.js}

@@ -1,5 +1,5 @@
 import { sum, min, max, cmp, countOnes } from "./module.f.js";
-export default {
+export const proof = {
     sum: () => {
         const result = sum([2, 3, 4, 5]);
         if (result !== 14) {

package/fs/types/object/{test.f.d.ts → proof.f.d.ts}

@@ -1,5 +1,4 @@
-declare const _default: {
+export declare const proof: {
     ctor: () => void;
     property: () => void;
 };
-export default _default;

package/fs/types/object/{test.f.js → proof.f.js}

@@ -1,5 +1,5 @@
 import { at } from "./module.f.js";
-export default {
+export const proof = {
     ctor: () => {
         const a = {};
         const value = at('constructor')(a);

package/fs/types/ordered_map/{test.f.d.ts → proof.f.d.ts}

@@ -1,5 +1,4 @@
-declare const _default: {
+export declare const proof: {
     main: (() => void)[];
     stress: () => void;
 };
-export default _default;

package/fs/types/ordered_map/{test.f.js → proof.f.js}

@@ -1,6 +1,6 @@
 import { at, setReplace, setReduce, empty, entries, remove } from "./module.f.js";
 import { toArray } from "../list/module.f.js";
-export default {
+export const proof = {
     main: [
         () => {
             let m = setReplace('a')(1)(null);

package/fs/types/patricia_trie/{test.f.d.ts → proof.f.d.ts}

@@ -1,8 +1,7 @@
-declare const _default: {
+export declare const proof: {
     empty: () => void;
     singleLeaf: () => void;
     twoLeaves: () => void;
     descending: () => void;
     ascending: () => void;
 };
-export default _default;

package/fs/types/patricia_trie/{test.f.js → proof.f.js}

@@ -112,7 +112,7 @@ const ascending = () => runExample([
     [119n, 179n, 200n, 227n, 242n],
     [119n, 179n, 200n, 227n, 242n, 249n],
 ], [0, 0, 0, 2, 1, 0, 1, 0, 3, 0, 0, 1, 2, 0, 0, 0]);
-export default {
+export const proof = {
     empty,
     singleLeaf,
     twoLeaves,

package/fs/types/prime_field/{test.f.d.ts → proof.f.d.ts}

@@ -1,4 +1,4 @@
-declare const _default: {
+export declare const proof: {
     prime_field_test: () => {
         neg: () => void;
         sub: () => void;
@@ -10,4 +10,3 @@ declare const _default: {
         sqrt: () => void;
     };
 };
-export default _default;

package/fs/types/prime_field/{test.f.js → proof.f.js}

@@ -1,5 +1,5 @@
 import { prime_field, sqrt } from "./module.f.js";
-export default {
+export const proof = {
     prime_field_test: () => {
         const p = 0xfffffffffffffffffffffffffffffffffffffffffffffffffffffffefffffc2fn;
         const f = prime_field(p);

package/fs/types/range/proof.f.d.ts

@@ -0,0 +1 @@
+export declare const proof: () => void;

package/fs/types/range/{test.f.js → proof.f.js}

@@ -1,5 +1,5 @@
 import { contains } from "./module.f.js";
-export default () => {
+export const proof = () => {
     if (!contains([0, 5])(1)) {
         throw 1;
     }

package/fs/types/range_map/{test.f.d.ts → proof.f.d.ts}

@@ -1,7 +1,6 @@
-declare const _default: {
+export declare const proof: {
     example: () => void;
     merge: (() => void)[];
     get: () => (() => void)[];
     fromRange: () => (() => void)[];
 };
-export default _default;

package/fs/types/range_map/{test.f.js → proof.f.js}

@@ -11,7 +11,7 @@ const op = {
     equal: equal(strictEqual),
     def: []
 };
-export default {
+export const proof = {
     example: () => {
         const rmOps = rangeMap({
             union: a => b => a | b,

package/fs/types/result/proof.f.d.ts

@@ -0,0 +1,5 @@
+export declare const proof: {
+    example: () => void;
+    invertTest: () => void;
+    unwrapError: () => void;
+};

package/fs/types/result/{test.f.js → proof.f.js}

@@ -1,5 +1,5 @@
 import { error, ok, unwrap, invert } from "./module.f.js";
-export const example = () => {
+const example = () => {
     const success = ok(42);
     const failure = error('Something went wrong');
     if (unwrap(success) !== 42) {
@@ -14,7 +14,7 @@ export const example = () => {
         throw 'error';
     }
 };
-export const invertTest = () => {
+const invertTest = () => {
     const [k0, v0] = invert(ok(42));
     if (k0 !== 'error' || v0 !== 42) {
         throw [k0, v0];
@@ -24,3 +24,19 @@ export const invertTest = () => {
         throw [k1, v1];
     }
 };
+const unwrapError = () => {
+    let caught = false;
+    try {
+        unwrap(error('oops'));
+    }
+    catch (e) {
+        if (e !== 'oops') {
+            throw e;
+        }
+        caught = true;
+    }
+    if (!caught) {
+        throw 'expected throw';
+    }
+};
+export const proof = { example, invertTest, unwrapError };

package/fs/types/rtti/parse/{test.f.d.ts → proof.f.d.ts}

@@ -1,4 +1,4 @@
-declare const _default: {
+export declare const proof: {
     boolean: {
         ok: () => void;
         error: () => void;
@@ -113,4 +113,3 @@ declare const _default: {
         recordOfRecords: () => void;
     };
 };
-export default _default;

package/fs/types/rtti/parse/{test.f.js → proof.f.js}

@@ -55,7 +55,7 @@ const assertDeepEqual = (a, b) => {
     }
     throw `not deep-equal: ${String(a)} vs ${String(b)}`;
 };
-export default {
+export const proof = {
     boolean: {
         ok: () => {
             assertOk(parse(boolean)(true));

package/fs/types/rtti/{test.f.d.ts → proof.f.d.ts}

@@ -1,6 +1,5 @@
-declare const _default: {
+export declare const proof: {
     typeof: {
         [k: string]: (() => void)[];
     };
 };
-export default _default;

package/fs/types/rtti/{test.f.js → proof.f.js}

@@ -7,7 +7,7 @@ const tests = {
     object: [null, {}, []],
     function: [() => undefined]
 };
-export default {
+export const proof = {
     typeof: Object.fromEntries(Object.entries(tests).map(([k, a]) => [k, a.map(v => () => {
             if (typeof v !== k) {
                 throw `typeof ${v} !== ${k}`;