functionalscript 0.43.1 → 0.45.0

package/fjs/effects/types.d.ts

@@ -0,0 +1,115 @@
+/**
+ * Types for the core effect system.
+ *
+ * @module
+ */
+export type Operation = readonly [string, (..._: readonly never[]) => unknown];
+/**
+ * An `Effect<O, T>` is the raw value: a {@link Pure} thunk that yields `T`, or a
+ * {@link Do} node describing a command to perform. It is plain data — compose
+ * effects with the external `step`, which is eager wherever the head is
+ * `Pure`.
+ */
+export type Effect<O extends Operation, T> = Pure<T> | Do<O, T>;
+/**
+ * A pure effect: an *already-computed* `T` behind a thunk.
+ *
+ * The thunk is a **discriminator, not a suspension**. `Effect` is a union with
+ * no tag field, so telling its two cases apart needs a runtime test, and
+ * `typeof e === 'function'` is it — wrapping the value in a function is what
+ * makes that test work. Deferral is not what the thunk is for. A `Pure` never
+ * holds work that has yet to happen; everything that *does* something is a
+ * {@link Do} node, and only a runner performs those.
+ *
+ * Two rules follow, and the rest of the module leans on both:
+ *
+ * - **The thunk must be pure and total.** Work hidden behind it is an effect
+ *   that no runner ever sees and no `OperationMap` can interpret or mock.
+ * - **It may be called more than once.** Nothing memoizes it. The same effect
+ *   can be decoded repeatedly — `Eff` re-forces the effect it wraps on each
+ *   `.step` — and under the first rule that costs nothing and changes nothing.
+ *
+ * A `lazy` constructor (`<T>(t: () => T): Effect<never, T> => t`) once existed
+ * to advertise the thunk as a suspension. It was the identity function, and it
+ * promised a deferral this representation does not keep; it has been removed.
+ * Reintroducing it would reintroduce the contradiction, not fix one.
+ */
+export type Pure<T> = () => T;
+export type Pr<O extends Operation, K extends O[0]> = O extends readonly [K, (...args: infer P) => infer R] ? readonly [P, R] : never;
+/**
+ * A `Do` node's continuation: given the command's output, produce the rest of
+ * the effect.
+ *
+ * The `out O` annotation asserts a covariance TypeScript cannot derive through
+ * the conditional `Pr` type: the command's output sits in the *contravariant*
+ * parameter position, so a bare function type would be measured contravariant
+ * in `O`, but the effect system only ever *widens* `O` (grows the op-set), never
+ * narrows it.
+ *
+ * **It is sound.** The `command` tag pins exactly which command's output the
+ * continuation receives, and every interpreter dispatches on the tag first
+ * (`match` → runner), so a `write` node's continuation is only ever
+ * called with `void`; the op-set can grow without any continuation ever being
+ * handed the wrong output. `out` enables only the widening direction
+ * (`Effect<A>` <: `Effect<A | B>`), never the unsound narrowing. Anyone changing
+ * the continuation representation must re-check this argument before keeping the
+ * annotation.
+ */
+export type Cont<out O extends Operation, T> = (_: Pr<O, O[0]>[1]) => Effect<O, T>;
+/**
+ * A `Do` node: the command to perform, its payload, and the continuation to
+ * resume with the command's output. Its runtime value is exactly this record,
+ * and every reader destructures it by name —
+ * `const { command, payload, continuation } = e`.
+ *
+ * It must be an object rather than a tuple, and that is not a style choice:
+ * only object / function / mapped-type aliases may carry a variance annotation
+ * (`TS2637` forbids `out` on a tuple), and the raw `Effect` union must be
+ * covariant in `O` end to end. `command` and `payload` are indexed/conditional
+ * types over `O` that TypeScript will not widen generically on their own —
+ * annotating only {@link Cont} is not enough — so the whole node carries
+ * `out O`. The same tag-dispatch soundness argument that justifies `Cont`'s
+ * `out O` applies here (see {@link Cont}); widening only ever grows the op-set.
+ *
+ * The fields were once numeric (`0` / `1` / `2`) over a real `[cmd, param,
+ * cont]` array, which is where the positional reads and the `Decoded` record
+ * that wrapped them came from. Nothing needed the positions: the constraint
+ * above is satisfied by any object type, so the numeric keys were paying a
+ * tuple's price without being a tuple. Named fields make the node
+ * self-describing at every read and leave no layout to memorize.
+ */
+export type Do<out O extends Operation, T> = {
+    readonly command: O[0];
+    readonly payload: Pr<O, O[0]>[0];
+    readonly continuation: Cont<O, T>;
+};
+/**
+ * An effect whose result is a **history tuple**: the values a chain has bound so
+ * far, newest first. `History<O, readonly[C, B, A]>` is three links deep, with
+ * `A` bound earliest.
+ *
+ * This is a transparent alias for `Effect`. It adds the tuple bound and
+ * nothing else, so any tuple-valued effect satisfies it whether or not
+ * `history` produced it — it names the convention at the signatures that
+ * rely on it rather than enforcing it.
+ *
+ * Heterogeneous by design: each element has its own type, so this is not a
+ * `List` and nothing that folds or maps a list applies to it.
+ */
+export type History<O extends Operation, H extends readonly unknown[]> = Effect<O, H>;
+export type Param<O extends Operation> = F<O>[0];
+export type Return<O extends Operation> = F<O>[1];
+/**
+ * An operation map whose entries take a command's payload and return some
+ * output `R`. Generalizes `ToAsyncOperationMap` (`R = Promise<…>`) and the
+ * curried `MemOperationMap` (`R = (state) => [state, …]`).
+ */
+export type OperationMap<O extends Operation, R> = {
+    readonly [K in O[0]]: (...payload: Pr<O, K>[0]) => R;
+};
+export type MatchResult<O extends Operation, T, R> = readonly ['done', T] | readonly ['cont', R, Do<O, T>['continuation']];
+export type ToAsyncOperationMap<O extends Operation> = {
+    readonly [K in O[0]]: (...payload: Pr<O, K>[0]) => Promise<Pr<O, K>[1]>;
+};
+export type F<O extends Operation> = Pr<O, O[0]>;
+export type Func<O extends Operation> = (..._: Param<O>) => Effect<O, Return<O>>;

package/fjs/emergent_testing/all.test.d.mts

@@ -0,0 +1,8 @@
+/**
+ * External-runner entry point: importing this module discovers every proof
+ * module and registers each test case with the active test runner. In this
+ * repository `node --test`, `bun test`, and `deno test` discover it by its
+ * `.test.` name; projects consuming the package re-export it from their own
+ * entry file with a bare side-effect import — see `README.md`.
+ */
+export {};

package/fjs/emergent_testing/all.test.mjs

@@ -0,0 +1,14 @@
+/**
+ * External-runner entry point: importing this module discovers every proof
+ * module and registers each test case with the active test runner. In this
+ * repository `node --test`, `bun test`, and `deno test` discover it by its
+ * `.test.` name; projects consuming the package re-export it from their own
+ * entry file with a bare side-effect import — see `README.md`.
+ */
+
+import { runEffect } from '../effects/node/module.mjs'
+import { register } from './module.f.mjs'
+
+// Top-level `await`: every proof must be registered before the runner starts
+// collecting tests.
+await runEffect(register)

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

@@ -0,0 +1,16 @@
+/** @type {(a: number, b: number) => number} */
+export declare const add: (a: number, b: number) => number;
+/** @type {(a: number, b: number) => number} */
+export declare const mul: (a: number, b: number) => number;
+/** @type {(a: 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.mjs

@@ -0,0 +1,34 @@
+/** @type {(a: number, b: number) => number} */
+export const add = (a, b) => a + b
+
+/** @type {(a: number, b: number) => number} */
+export const mul = (a, b) => a * b
+
+/** @type {(a: number) => number} */
+export const sqr = a => mul(a, a)
+
+export const todo = () => { throw "not implemented" }
+
+/** @type {(a: number, b: number, r: number) => void} */
+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.mts

@@ -0,0 +1,155 @@
+/**
+ * Test-framework helpers for running and reporting FunctionalScript tests.
+ *
+ * Two parallel execution paths:
+ * - `runModule` / `Reporter<O>` — self-hosted Effects runner used by `fjs t`;
+ *   sandboxes each leaf call individually and accumulates `TestState`.
+ * - `registerModule` / `TestContext` — registers tests with an external
+ *   framework (Node `--test`, Bun, Deno) at import time; the framework owns
+ *   scheduling and pass/fail counting.
+ *
+ * @module
+ *
+ * @import { Effect, Operation } from '../effects/types.ts'
+ * @import { LoadModuleOperations, ModuleMap } from '../dev/types.ts'
+ * @import { TestFn, TestEntry, TestSet, Path, Reporter, _TestState, _TestAndPath } from './types.ts'
+ * @import { All, Await, Env, NodeProgram, NodeProgramOptions, Program, Sandbox, SandboxResult, Test, TestContext, Write, WriteConsoles } from '../effects/node/types.ts'
+ */
+import type { Effect, Operation } from '../effects/types.ts';
+import type { LoadModuleOperations, ModuleMap } from '../dev/types.ts';
+import type { TestEntry, TestSet, Path, Reporter, _TestAndPath } from './types.ts';
+import type { All, Await, NodeProgram, NodeProgramOptions, Program, Sandbox, SandboxResult, Test, TestContext, Write } from '../effects/node/types.ts';
+/**
+ * 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.
+ *
+ * @type {(throws: boolean, x: unknown) => TestSet}
+ */
+export declare const parseTestSet: (throws: boolean, x: unknown) => TestSet;
+/**
+ * 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.
+ *
+ * @type {(path: Path, throws: boolean, v: unknown) => readonly _TestAndPath[]}
+ */
+export declare const collectTests: (path: Path, throws: boolean, v: unknown) => readonly _TestAndPath[];
+/**
+ * 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.
+ *
+ * @type {(ctx: TestContext, k: string, v: unknown, star: string) => Effect<Test | All | Await, void>}
+ */
+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).
+ *
+ * @template {Operation} O
+ * @param {Reporter<O>} reporter
+ * @returns {(moduleMap: ModuleMap) => Effect<O | All, number>}
+ */
+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.
+ *
+ * @template {Operation} O
+ * @param {Reporter<O>} reporter
+ * @returns {Program<O | All | LoadModuleOperations>}
+ */
+export declare const testAll: <O extends Operation>(reporter: Reporter<O>) => Program<O | All | LoadModuleOperations>;
+/** Returns `true` if `s` is a non-negative decimal integer without a leading zero.
+ *
+ * @type {(s: string) => boolean}
+ */
+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_$]*`).
+ *
+ * @type {(s: string) => boolean}
+ */
+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`.
+ *
+ * @type {(path: Path) => string}
+ */
+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.
+ *
+ * @type {(file: string, path: Path) => string}
+ */
+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"`.
+ *
+ * @type {(path: Path) => string}
+ */
+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
+ *
+ * @type {(s: string) => string}
+ */
+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).
+ *
+ * @type {(file: string, path: Path, entry: TestEntry) => Effect<Sandbox, SandboxResult<unknown>>}
+ */
+export declare const defaultTest: (file: string, path: Path, entry: 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.
+ *
+ * @type {(options: NodeProgramOptions) => Reporter<Write | Sandbox>}
+ */
+export declare const defaultReporter: (options: NodeProgramOptions) => Reporter<Write | Sandbox>;
+/** The `fjs t` entry point: runs all tests using `defaultReporter`.
+ *
+ * @type {NodeProgram}
+ */
+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`.
+ *
+ * @type {NodeProgram}
+ */
+export declare const register: NodeProgram;