functionalscript 0.19.0 → 0.21.0

package/fs/types/btree/remove/proof.f.d.ts

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

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

@@ -625,7 +625,7 @@ const test2 = () => {
         }
     }
 };
-export default {
+export const proof = {
     test,
     test2,
 };

package/fs/types/btree/set/proof.f.d.ts

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

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

@@ -354,4 +354,4 @@ const test = [
         }
     }
 ];
-export default test;
+export const proof = test;

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

@@ -12,4 +12,12 @@ export type TNode<T> = Leaf1<T> | Leaf2<T> | Branch3<T> | Branch5<T>;
 export type Tree<T> = TNode<T> | null;
 export type Branch1<T> = readonly [TNode<T>];
 export type Branch7<T> = readonly [...Branch5<T>, T, TNode<T>];
+/**
+ * Demotes a single-child branch root to its only child.
+ *
+ * After an insert or remove the root may temporarily hold exactly one child
+ * (a `Branch1`). In that case the tree is one level taller than necessary;
+ * returning the child directly restores the correct height. If the root has
+ * more than one child it is returned unchanged.
+ */
 export declare const collapseRoot: <T>(b: Branch1<T> | Branch3<T> | Branch5<T>) => TNode<T>;

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

@@ -1 +1,9 @@
+/**
+ * Demotes a single-child branch root to its only child.
+ *
+ * After an insert or remove the root may temporarily hold exactly one child
+ * (a `Branch1`). In that case the tree is one level taller than necessary;
+ * returning the child directly restores the correct height. If the root has
+ * more than one child it is returned unchanged.
+ */
 export const collapseRoot = b => b.length === 1 ? b[0] : b;

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,16 +130,43 @@ 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>;
+/**
+ * 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 `error(s).step(() => pure(n))` directly.
+ */
+export declare const errorExit: (s: string) => Effect<NodeOp, number>;
 export type NodeOperationMap = ToAsyncOperationMap<NodeOp>;
 /**
  * The environment variables.
@@ -133,7 +174,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 { begin, 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,14 @@ 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');
+/**
+ * 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 `error(s).step(() => pure(n))` directly.
+ */
+export const errorExit = (s) => begin
+    .step(() => error(s))
+    .step(() => pure(1));

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

@@ -3,7 +3,7 @@
  *
  * @module
  */
-import { assert, todo } from "../../../../dev/module.f.js";
+import { assert, todo } from "../../../../asserts/module.f.js";
 import { parse } from "../../../../path/module.f.js";
 import { utf8ToString } from "../../../../text/module.f.js";
 import { isVec } from "../../../bit_vec/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;
@@ -18,5 +18,5 @@ declare const _default: {
     strictEqual: (() => void)[];
     isEmpty: (() => void)[];
     length: () => void;
+    filterMap: (() => 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,
@@ -389,5 +389,19 @@ export default {
             throw 6;
         }
     },
+    filterMap: [
+        () => {
+            const result = str(filterMap((x) => x % 2 === 0 ? x * 10 : null)([1, 2, 3, 4, 5]));
+            if (result !== '[20,40]') {
+                throw result;
+            }
+        },
+        () => {
+            const result = str(filterMap((x) => x > 3 ? x : null)([1, 2, 3]));
+            if (result !== '[]') {
+                throw result;
+            }
+        },
+    ],
     // stress
 };

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/module.f.d.ts

@@ -8,3 +8,10 @@ export type Nullable<T> = T | null;
 export declare const map: <T, R>(f: (value: T) => R) => (value: Nullable<T>) => Nullable<R>;
 export declare const match: <T, R>(f: (_: T) => R) => (none: () => R) => (_: Nullable<T>) => Nullable<R>;
 export declare const toOption: <T>(value: Nullable<T>) => Option<T>;
+/**
+ * Normalizes a possibly-`undefined` value into the codebase's `null` convention.
+ *
+ * The boundary rule between JavaScript hosts (which return `undefined` from
+ * property/index lookups) and FunctionalScript (which uses `null` for absence).
+ */
+export declare const fromUndefined: <T>(value: T | undefined) => Nullable<T>;

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

@@ -1,3 +1,10 @@
 export const map = f => value => value === null ? null : f(value);
 export const match = f => none => value => value === null ? none() : f(value);
 export const toOption = (value) => value === null ? [] : [value];
+/**
+ * Normalizes a possibly-`undefined` value into the codebase's `null` convention.
+ *
+ * The boundary rule between JavaScript hosts (which return `undefined` from
+ * property/index lookups) and FunctionalScript (which uses `null` for absence).
+ */
+export const fromUndefined = (value) => value === undefined ? null : value;

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

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