functionalscript 0.43.1 → 0.44.0

package/fjs/effects/proof.f.d.ts

@@ -1,56 +0,0 @@
-import { type Effect, type Operation } from './module.f.ts';
-/**
- * Asserts that `e` yields `expected` without performing a command. Exported so
- * `eff/proof.f.ts` shares this definition instead of repeating it.
- *
- * Not `assertEq(runPure(e), [expected])`: `assertEq` compares with `===`, so a
- * freshly allocated `[expected]` is never equal to the returned option. Assert
- * the option's shape first, then compare the value inside it.
- */
-export declare const assertPure: <O extends Operation, T>(e: Effect<O, T>, expected: T) => void;
-export declare const proof: {
-    foldStep: {
-        empty: () => void;
-        threadsState: () => void;
-        order: () => void;
-    };
-    forEachStep: {
-        empty: () => void;
-        runs: () => void;
-    };
-    okStep: {
-        ok: () => void;
-        error: () => void;
-    };
-    runPure: {
-        pure: () => void;
-        pureNull: () => void;
-        do_: () => void;
-    };
-    doNode: () => void;
-    match: {
-        done: () => void;
-        cont: () => void;
-        ownCommand: () => void;
-        throw: {
-            constructorCommand: () => void;
-            toStringCommand: () => void;
-        };
-    };
-    step: {
-        pure: () => void;
-        chain: () => void;
-        overDo: () => void;
-    };
-    mapStep: {
-        pure: () => void;
-        constant: () => void;
-        overDo: () => void;
-    };
-    historyStep: {
-        pure: () => void;
-        overDo: () => void;
-        chain: () => void;
-        fReceivesWholeHistory: () => void;
-    };
-};

package/fjs/effects/proof.f.js

@@ -1,200 +0,0 @@
-import { step, do_, foldStep, forEachStep, mapStep, match, okStep, history, pure, runPure, historyStep } from './module.f.js';
-import { error, ok } from '../types/result/module.f.js';
-import { assert, assertEq } from '../asserts/module.f.js';
-/**
- * Asserts that `e` yields `expected` without performing a command. Exported so
- * `eff/proof.f.ts` shares this definition instead of repeating it.
- *
- * Not `assertEq(runPure(e), [expected])`: `assertEq` compares with `===`, so a
- * freshly allocated `[expected]` is never equal to the returned option. Assert
- * the option's shape first, then compare the value inside it.
- */
-export const assertPure = (e, expected) => {
-    const o = runPure(e);
-    assert(o.length === 1, e);
-    assertEq(o[0], expected);
-};
-const next = match({ add: (a, b) => a + b });
-const anyNext = match({ add: a => a + 1 });
-export const proof = {
-    foldStep: {
-        empty: () => {
-            const e = foldStep(pure([]), 10, x => s => pure(s + x));
-            assertPure(e, 10);
-        },
-        threadsState: () => {
-            const e = foldStep(pure([1, 2, 3, 4]), 0, x => s => pure(s + x));
-            assertPure(e, 10);
-        },
-        order: () => {
-            const e = foldStep(pure(['a', 'b', 'c']), '', x => s => pure(s + x));
-            assertPure(e, 'abc');
-        },
-    },
-    forEachStep: {
-        empty: () => {
-            const e = forEachStep(pure([]), () => pure(undefined));
-            assertPure(e, undefined);
-        },
-        runs: () => {
-            const e = forEachStep(pure([1, 2, 3]), () => pure(undefined));
-            assertPure(e, undefined);
-        },
-    },
-    okStep: {
-        ok: () => {
-            const e = step(pure(ok(5)), okStep((v) => pure(ok(v * 2))));
-            const o = runPure(e);
-            assert(o.length === 1, e);
-            const [r] = o;
-            assert(r[0] === 'ok', r);
-            assertEq(r[1], 10);
-        },
-        error: () => {
-            const e = step(pure(error('oops')), okStep(v => pure(ok(v * 2))));
-            const o = runPure(e);
-            assert(o.length === 1, e);
-            const [r] = o;
-            assert(r[0] === 'error', r);
-            assertEq(r[1], 'oops');
-        },
-    },
-    runPure: {
-        pure: () => {
-            const o = runPure(pure(5));
-            assert(o.length === 1, o);
-            assertEq(o[0], 5);
-        },
-        // A pure `null` is `[null]`, never `[]`. Collapsing the two is what a
-        // `T | null` result would do, and why the option is tagged.
-        pureNull: () => {
-            const o = runPure(pure(null));
-            assertEq(o.length, 1, o);
-            assertEq(o[0], null);
-        },
-        do_: () => {
-            assertEq(runPure(do_('add')(2, 3)).length, 0);
-        },
-    },
-    // The one place a `Do` node is opened on purpose: `do_` builds the command,
-    // the payload it was called with, and a continuation that resumes with the
-    // command's output. Everything else goes through `step`, `match`, or
-    // `runPure`.
-    doNode: () => {
-        const e = do_('add')(2, 3);
-        assert(typeof e !== 'function', e);
-        const { command, payload, continuation } = e;
-        assertEq(command, 'add');
-        const [a, b] = payload;
-        assertEq(a, 2, payload);
-        assertEq(b, 3, payload);
-        assertPure(continuation(5), 5);
-    },
-    match: {
-        done: () => {
-            const r = next(pure(7));
-            assert(r[0] === 'done', r);
-            assertEq(r[1], 7);
-        },
-        cont: () => {
-            const r = next(do_('add')(2, 3));
-            assert(r[0] === 'cont', r);
-            assertEq(r[1], 5);
-            const r2 = next(r[2](r[1]));
-            assert(r2[0] === 'done', r2);
-            assertEq(r2[1], 5);
-        },
-        ownCommand: () => {
-            // The same map the two cases below dispatch against: an own
-            // property still resolves, so what they prove is refusal of
-            // inherited names, not a map that dispatches nothing.
-            const r = anyNext(do_('add')(41));
-            assert(r[0] === 'cont', r);
-            assertEq(r[1], 42);
-        },
-        // A `command` naming an `Object.prototype` member must not dispatch to
-        // the inherited value. `map['constructor']` is `Object` and
-        // `map['toString']` is `Function.prototype.toString` — both callable,
-        // neither a handler — so a plain index read would call one of them with
-        // the node's payload instead of throwing.
-        throw: {
-            constructorCommand: () => {
-                anyNext(do_('constructor')(1));
-            },
-            toStringCommand: () => {
-                anyNext(do_('toString')(1));
-            },
-        },
-    },
-    step: {
-        pure: () => {
-            assertPure(step(pure(3), v => pure(v + 1)), 4);
-        },
-        chain: () => {
-            // Chains as step(step(e, f), g), raw effect in and out.
-            assertPure(step(step(pure(3), v => pure(v + 1)), v => pure(v * 2)), 8);
-        },
-        overDo: () => {
-            // Stepping a Do node preserves the command and threads the result
-            // through the rebuilt continuation.
-            const e = step(do_('add')(2, 3), r => pure(r * 10));
-            const r = next(e);
-            assert(r[0] === 'cont', r);
-            assertEq(r[1], 5);
-            assertPure(r[2](r[1]), 50);
-        },
-    },
-    mapStep: {
-        pure: () => {
-            assertPure(mapStep(pure(3), v => v + 1), 4);
-        },
-        constant: () => {
-            // The `() => v` shape a `constStep` would have covered.
-            assertPure(mapStep(pure('ignored'), () => 1), 1);
-        },
-        overDo: () => {
-            // A projection over a `Do` node keeps the command intact and is
-            // applied to the command's output when the continuation resumes.
-            const r = next(mapStep(do_('add')(2, 3), v => v * 10));
-            assert(r[0] === 'cont', r);
-            assertEq(r[1], 5);
-            assertPure(r[2](r[1]), 50);
-        },
-    },
-    historyStep: {
-        pure: () => {
-            const o = runPure(historyStep(history(pure(3)), v => pure(v * 2)));
-            assert(o.length === 1, o);
-            const [[result, param]] = o;
-            assertEq(param, 3);
-            assertEq(result, 6);
-        },
-        overDo: () => {
-            // The captured value survives a command boundary: the history is
-            // rebuilt inside the continuation rather than lost when `e` is a Do.
-            const c = next(historyStep(history(do_('add')(2, 3)), r => pure(r * 10)));
-            assert(c[0] === 'cont', c);
-            assertEq(c[1], 5);
-            const o = runPure(c[2](c[1]));
-            assert(o.length === 1, o);
-            const [[result, param]] = o;
-            assertEq(param, 5);
-            assertEq(result, 50);
-        },
-        chain: () => {
-            // `historyStep` takes a history and returns one, so link two is
-            // spelled exactly like link one. The tuple is newest first, so a
-            // destructuring reads reverse-chronologically.
-            const a = historyStep(history(pure(1)), x => pure(x + 1));
-            const b = historyStep(a, (result, param) => pure(result + param));
-            assertPure(step(b, ([z, y, x]) => pure(`${x}${y}${z}`)), '123');
-        },
-        fReceivesWholeHistory: () => {
-            // `f` is handed the whole history spread as arguments, not just the
-            // most recent value - which is what lets a later link reach back.
-            const a = historyStep(history(pure(1)), x => pure(x + 1));
-            const b = historyStep(a, (...p) => pure(p[1] * 100 + p[0]));
-            assertPure(step(b, ([result]) => pure(result)), 102);
-        },
-    },
-};

package/fjs/emergent_testing/example.f.d.ts

@@ -1,13 +0,0 @@
-export declare const add: (a: number, b: number) => number;
-export declare const mul: (a: number, b: number) => number;
-export declare const sqr: (a: number) => number;
-export declare const todo: () => never;
-export declare const proof: {
-    addTest: () => void;
-    mulTest: (() => void)[];
-    throw: {
-        todo: typeof todo;
-        divByZero: () => bigint;
-    };
-    generateSqrTests: () => (() => void)[];
-};

package/fjs/emergent_testing/example.f.js

@@ -1,31 +0,0 @@
-export const add = (a, b) => a + b;
-export const mul = (a, b) => a * b;
-export const sqr = (a) => mul(a, a);
-export const todo = () => { throw "not implemented"; };
-const checkMul = (a, b, r) => {
-    if (mul(a, b) !== r) {
-        throw `mul(${a}, ${b}) !== ${r}`;
-    }
-};
-export const proof = {
-    addTest: () => {
-        if (add(2, 2) !== 4) {
-            throw "something wrong with the math";
-        }
-    },
-    mulTest: [
-        () => checkMul(2, 3, 6),
-        () => checkMul(22, 34, 748),
-        () => checkMul(-2, 3, -6),
-        () => checkMul(-2, -3, 6),
-    ],
-    throw: {
-        todo,
-        divByZero: () => 5n / 0n,
-    },
-    generateSqrTests: () => [1, 2, 3, 5].map(a => () => {
-        if (sqr(a) !== a * a) {
-            throw `sqr(${a})`;
-        }
-    })
-};

package/fjs/emergent_testing/module.f.d.ts

@@ -1,140 +0,0 @@
-import { type All, type Await, type NodeProgram, type NodeProgramOptions, type Program, type Sandbox, type SandboxResult, type Test, type TestContext, type Write } from '../effects/node/module.f.ts';
-import { type Effect, type Operation } from '../effects/module.f.ts';
-import { type LoadModuleOperations, type ModuleMap } from '../dev/module.f.ts';
-/** A zero-argument test function whose return value may contain sub-tests. */
-export type TestFn = () => unknown;
-/**
- * A leaf test bundled with its throw expectation.
- *
- * `throws: true` means the test is expected to throw; the runner inverts the
- * `sandbox` result so a caught error becomes a pass and a clean return becomes
- * a failure. Using a record instead of a wrapper function avoids a double
- * `sandbox` call and gives accurate per-test timing.
- */
-export type TestEntry = {
-    readonly fn: TestFn;
-    readonly throws: boolean;
-};
-/**
- * Either a leaf `TestEntry` (function + throw flag) or a named sub-tree of
- * `[key, value]` pairs to recurse into. Discriminate with `Array.isArray`.
- */
-export type TestSet = TestEntry | readonly (readonly [string, unknown])[];
-/**
- * Converts an arbitrary JS value into a `TestSet`.
- *
- * - Zero-argument functions become a `TestEntry`; the `throws` flag is set if
- *   `throws` is already `true` (i.e. a `throw` key appears in the ancestor path).
- *   The canonical way to declare a throw-test is structural: nest it under a
- *   `throw` property key. The secondary `fn.name === 'throw'` check is a legacy
- *   path that only fires when a function is extracted from a `throw` key and
- *   placed under a different key; that pattern is engine-dependent (unreliable on
- *   Bun) and is not a supported authoring style.
- * - Non-null objects become an array of `[key, value]` pairs to recurse into.
- * - All other values (including functions with parameters) produce an empty array.
- */
-export declare const parseTestSet: (throws: boolean, x: unknown) => TestSet;
-type TestAndPath = readonly [Path, TestEntry];
-/**
- * Recursively collects all leaf tests reachable from `v` as `[path, entry]`
- * pairs, without running anything. Return-value sub-trees are not walked
- * (that requires execution); only the static object/array/function structure
- * is traversed.
- */
-export declare const collectTests: (path: Path, throws: boolean, v: unknown) => readonly TestAndPath[];
-/**
- * Receives semantic test-run events. Each method is the runner's notification
- * of an event; the reporter decides how to render it (terminal, GitHub
- * annotations, JSON, node `--test`, etc.). `path` is the chain of object keys
- * leading to the current location; `null` marks a function-call boundary, e.g.
- * `['outer', null, 'inner']` means `outer` was invoked and its return value
- * contained `inner`.
- */
-export type Reporter<O extends Operation> = {
-    readonly result: (file: string, path: Path, r: SandboxResult<unknown>, throws: boolean) => Effect<O, void>;
-    readonly summary: (pass: number, fail: number, time: number) => Effect<O, void>;
-    readonly test: (file: string, path: Path, set: TestEntry) => Effect<O, SandboxResult<unknown>>;
-};
-/**
- * Registers all tests reachable from module export `v` (keyed by `k`) with
- * the given `TestContext`.
- *
- * Unlike `runModule`, which sandboxes only the leaf function, `registerModule`
- * lets the external framework own scheduling: each registered test callback
- * calls `fn`, then recursively registers any sub-trees returned by the function.
- * This is the correct model for Node `--test`, Bun, and Deno, where tests must
- * be declared upfront and the framework drives execution.
- */
-export declare const registerModule: (ctx: TestContext, k: string, v: unknown, star: string) => Effect<Test | All | Await, void>;
-/**
- * Runs all test modules in `moduleMap` whose names pass `isTest`, accumulates
- * pass/fail/time via `reporter`, and returns an exit code (0 = all passed,
- * 1 = at least one failure).
- */
-export declare const runModuleMap: <O extends Operation>(reporter: Reporter<O>) => (moduleMap: ModuleMap) => Effect<O | All, number>;
-/**
- * Discovers all test modules via `loadModuleMap`, then runs them through
- * `runModuleMap`. The composed effect is a `NodeProgram` entry point for the
- * `fjs t` test runner.
- */
-export declare const testAll: <O extends Operation>(reporter: Reporter<O>) => Program<O | All | LoadModuleOperations>;
-/**
- * A chain of property-access keys leading to a test location. String entries
- * are object/array keys; `null` marks a function-call boundary (the return
- * value was walked as a sub-tree).
- */
-export type Path = readonly (string | null)[];
-/** Returns `true` if `s` is a non-negative decimal integer without a leading zero. */
-export declare const isInteger: (s: string) => boolean;
-/** Returns `true` if `s` is a valid JS identifier (ASCII subset: `[A-Za-z_$][A-Za-z0-9_$]*`). */
-export declare const isIdentifier: (s: string) => boolean;
-/**
- * Renders a key chain as a JS property-access expression: identifier keys use
- * dot notation, integer keys use `[N]`, other strings use `["key"]`, and `null`
- * emits `()` to mark a function-call boundary.
- * E.g. `['math', 'add']` → `.math.add`, `['outer', null, 'inner']` → `.outer().inner`.
- */
-export declare const fmtPath: (path: Path) => string;
-/**
- * Formats a fully-qualified test identifier as a JS-like expression, e.g.
- * `import("./math.proof.f.ts").add()` or `import("./a.proof.f.ts").users[3].name()`.
- * Self-contained per line — suitable for parallel output and as a CLI filter argument.
- */
-export declare const fmtImport: (file: string, path: Path) => string;
-/**
- * Renders a key chain for terminal output: `| ` per level of depth, followed
- * by the last segment formatted as a bare integer, a bare identifier, or a
- * JSON-quoted string. E.g. `['math', 'add']` → `| | add`,
- * `['a', '0']` → `| | 0`, `['x', 'hello world']` → `| | "hello world"`.
- */
-export declare const fmtTerm: (path: Path) => string;
-/**
- * Percent-encodes characters that GitHub workflow-command property values
- * treat as separators (`%`, `:`, `,`) plus newlines.
- * https://docs.github.com/en/actions/learn-github-actions/workflow-commands-for-github-actions
- */
-export declare const ghEscape: (s: string) => string;
-/**
- * Default `Reporter.test` implementation: sandboxes `fn` once and inverts the
- * result when `throws` is `true` (caught error → pass, clean return → fail).
- */
-export declare const defaultTest: (file: string, path: Path, { fn, throws }: TestEntry) => Effect<Sandbox, SandboxResult<unknown>>;
-/**
- * The terminal/GitHub reporter used by `fjs t`. Output goes through
- * `csiWrite`, so ANSI styles are stripped on non-TTY streams. When
- * `GITHUB_ACTIONS` is set, failures are emitted as `::error` workflow
- * annotations instead of colored lines. Exported as a factory so the
- * GitHub format path can be exercised directly from tests.
- */
-export declare const defaultReporter: (options: NodeProgramOptions) => Reporter<Write | Sandbox>;
-/** The `fjs t` entry point: runs all tests using `defaultReporter`. */
-export declare const main: NodeProgram;
-/**
- * Entry point for external test frameworks (Node `--test`, Bun, Deno).
- *
- * Discovers test modules via `loadModuleMap`, then registers each with the
- * framework-appropriate `TestContext` selected from `NodeProgramOptions`
- * based on the detected `engine`.
- */
-export declare const register: NodeProgram;
-export {};