functionalscript 0.18.0 → 0.20.0

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

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

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

@@ -3,7 +3,7 @@ import { every, countdown, map, toArray } from "../list/module.f.js";
 import { stringify as jsonStringify } from "../../json/module.f.js";
 import { sort } from "../object/module.f.js";
 const stringify = jsonStringify(sort);
-export default {
+export const proof = {
     has: [
         () => {
             if (has(0)(empty)) {

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

@@ -3,6 +3,7 @@
  *
  * @module
  */
+import { type List } from '../list/module.f.ts';
 export type Operation = readonly [string, (..._: readonly never[]) => unknown];
 export type Effect<O extends Operation, T> = {
     value: Value<O, T>;
@@ -20,6 +21,22 @@ export type Param<O extends Operation> = F<O>[0];
 export type Return<O extends Operation> = F<O>[1];
 export declare const do_: <O extends Operation>(cmd: O[0]) => (...param: Param<O>) => Effect<O, Return<O>>;
 export declare const begin: Effect<never, void>;
+/**
+ * Sequentially threads a state value through an effect for each item in `items`.
+ *
+ * Given `f: item => state => Effect<O, state>`, `init: S`, and `items: [x₀, x₁, …]`,
+ * builds `f(x₀)(init).step(f(x₁)).step(f(x₂)).…` and yields a single
+ * `Effect<O, S>` that produces the final state.
+ *
+ * Sequential — each step depends on the previous state. Compare to `all`,
+ * which fans out independent effects.
+ */
+export declare const foldStep: <O extends Operation, T, S>(f: (item: T) => (state: S) => Effect<O, S>) => (init: S) => (items: List<T>) => Effect<O, S>;
+/**
+ * Sequentially runs `f(item)` for each item in `items`, discarding intermediate
+ * results. The `void` accumulator sibling of `foldStep`.
+ */
+export declare const forEachStep: <O extends Operation, T>(f: (item: T) => Effect<O, void>) => (items: List<T>) => Effect<O, void>;
 export type ToAsyncOperationMap<O extends Operation> = {
     readonly [K in O[0]]: (...payload: Pr<O, K>[0]) => Promise<Pr<O, K>[1]>;
 };

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

@@ -3,6 +3,7 @@
  *
  * @module
  */
+import { fold } from "../list/module.f.js";
 export const pure = (v) => ({
     value: [v],
     step: f => f(v)
@@ -13,3 +14,19 @@ export const doFull = (cmd, param, cont) => ({
 });
 export const do_ = (cmd) => (...param) => doFull(cmd, param, pure);
 export const begin = pure(undefined);
+/**
+ * Sequentially threads a state value through an effect for each item in `items`.
+ *
+ * Given `f: item => state => Effect<O, state>`, `init: S`, and `items: [x₀, x₁, …]`,
+ * builds `f(x₀)(init).step(f(x₁)).step(f(x₂)).…` and yields a single
+ * `Effect<O, S>` that produces the final state.
+ *
+ * Sequential — each step depends on the previous state. Compare to `all`,
+ * which fans out independent effects.
+ */
+export const foldStep = (f) => (init) => (items) => fold(item => acc => acc.step(f(item)))(pure(init))(items);
+/**
+ * Sequentially runs `f(item)` for each item in `items`, discarding intermediate
+ * results. The `void` accumulator sibling of `foldStep`.
+ */
+export const forEachStep = (f) => (items) => foldStep((item) => () => f(item))(undefined)(items);

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,7 +130,36 @@ export type Sandbox = readonly ['sandbox', <T>(f: () => T) => SandboxResult<T>];
  * @see {@link SandboxResult}
  */
 export declare const sandbox: Func<Sandbox>;
-export type NodeOp = All | Fetch | Fs | Http | Forever | Import | Now | Sandbox | Write;
+/**
+ * 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;
+};
+/** 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 | Await | Fetch | Fs | Http | Forever | Import | Now | Sandbox | Write | Test;
 export type NodeEffect<T> = Effect<NodeOp, T>;
 export type NodeOperationMap = ToAsyncOperationMap<NodeOp>;
 /**
@@ -125,6 +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;
@@ -133,6 +191,10 @@ export type NodeProgramOptions = {
             readonly isTTY: boolean;
         };
     };
+    readonly testContext: TestContext;
+    readonly bunTestContext: TestContext;
+    readonly playwrightTestContext: TestContext;
+    readonly engine: Engine;
 };
 export type Program<O extends Operation> = (options: NodeProgramOptions) => Effect<O, number>;
 export type NodeProgram = Program<NodeOp>;

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,3 +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.d.ts

@@ -10,8 +10,9 @@ import type { Module, NodeOp } from '../module.f.ts';
  * each import for closures/state.
  */
 export type JsModule = () => Module;
+export type Entity = Vec | Dir | JsModule;
 export type Dir = {
-    readonly [name in string]?: Dir | Vec | JsModule;
+    readonly [name in string]?: Entity;
 };
 export type State = {
     stdout: string;

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

@@ -167,6 +167,8 @@ 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);
         return [{ ...state, [stream]: `${state[stream]}${s}` }, undefined];

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, toOption } from "./module.f.js";
-export default [
+import { map, match, toOption } from "./module.f.js";
+export const proof = [
     () => {
         const optionSq = map((v) => v * v);
         const sq3 = optionSq(3);
@@ -20,5 +20,14 @@ export default [
         if (opt2.length !== 0) {
             throw opt2;
         }
+    },
+    () => {
+        const double = match((v) => v * 2)(() => -1);
+        if (double(3) !== 6) {
+            throw double(3);
+        }
+        if (double(null) !== -1) {
+            throw double(null);
+        }
     }
 ];

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);