functionalscript 0.38.0 → 0.39.0

package/fjs/mcp/stdio/module.f.js

@@ -29,7 +29,7 @@
  *
  * @module
  */
-import { pure } from '../../effects/module.f.js';
+import { pure, step } from '../../effects/module.f.js';
 import { readLine, write } from '../../effects/node/module.f.js';
 import { tryUtf8 } from '../../text/module.f.js';
 import { stringToList } from '../../text/utf16/module.f.js';
@@ -49,24 +49,24 @@ const writeResponse = (resp) => {
     const v = tryUtf8(stringifyJson(resp) + '\n');
     return v === null
         ? pure(error(undefined))
-        : write('stdout', v).step(() => pure(ok(undefined)));
+        : step(write('stdout', v), () => pure(ok(undefined)));
 };
 /**
- * Drives the read-parse-dispatch-write loop for `step` over stdin/stdout.
+ * Drives the read-parse-dispatch-write loop for `handler` over stdin/stdout.
  *
  * Recurses after each handled line; terminates (resolving to `void`) when
  * `readLine` reports EOF.
  */
-export const stdioTransport = (step) => readLine('stdin').step(line => line === null
+export const stdioTransport = (handler) => step(readLine('stdin'), line => line === null
     ? pure(undefined)
-    : handleLine(step)(line));
-const handleLine = (step) => (line) => {
+    : handleLine(handler)(line));
+const handleLine = (handler) => (line) => {
     const [t, value] = parse(tokenize(stringToList(line)));
-    return (t === 'error'
+    return step(t === 'error'
         ? writeResponse(parseErrorResponse)
-        : step(value).step(resp => resp === null
+        : step(handler(value), resp => resp === null
             ? pure(undefined)
-            : writeResponse(resp).step(([t2]) => t2 === 'error'
+            : step(writeResponse(resp), ([t2]) => t2 === 'error'
                 // The real response didn't fit. Retry with a fixed, small
                 // internal-error body carrying `resp.id` — but a
                 // caller-controlled `id` (e.g. a very large string) can
@@ -74,8 +74,8 @@ const handleLine = (step) => (line) => {
                 // that retry is bounded by one more: an `id: null`
                 // internal-error, whose fully-constant shape is the only
                 // line in this transport guaranteed to always encode.
-                ? writeResponse(internalErrorResponse(resp.id)).step(([t3]) => t3 === 'error'
-                    ? writeResponse(internalErrorResponse(null)).step(() => pure(undefined))
+                ? step(writeResponse(internalErrorResponse(resp.id)), ([t3]) => t3 === 'error'
+                    ? step(writeResponse(internalErrorResponse(null)), () => pure(undefined))
                     : pure(undefined))
-                : pure(undefined)))).step(() => stdioTransport(step));
+                : pure(undefined))), () => stdioTransport(handler));
 };

package/fjs/media/type/module.f.js

@@ -34,7 +34,7 @@
  */
 import { msb, fromSentinel, length, u8List } from '../../types/bit_vec/module.f.js';
 import { iterable } from '../../types/list/module.f.js';
-import { pure } from '../../effects/module.f.js';
+import { pure, step } from '../../effects/module.f.js';
 import { ok, error } from '../../types/result/module.f.js';
 import { isValidCodePoint, isTextCodePoint } from '../../text/code_point/module.f.js';
 import { utf8ByteToCodePointOp } from '../../text/utf8/module.f.js';
@@ -216,7 +216,7 @@ export const detectVec = (bytes) => finish(push(detectInit)(bytes));
  * item short-circuits into the `IoResult` error.
  */
 export const detectStream = (stream) => {
-    const loop = (s) => (l) => l.step((node) => {
+    const loop = (s) => (l) => step(l, (node) => {
         if (node === undefined) {
             return pure(ok(finish(s)));
         }

package/fjs/media/type/proof.f.js

@@ -1,6 +1,6 @@
 import { assert, assertEq } from '../../asserts/module.f.js';
 import { msb, u8ListToVec, vec8, repeat, empty } from '../../types/bit_vec/module.f.js';
-import { decode } from '../../effects/module.f.js';
+import { runPure } from '../../effects/module.f.js';
 import { nonEmpty, empty as emptyList } from '../../effects/list/module.f.js';
 import { ok } from '../../types/result/module.f.js';
 import { detect, detectStream, detectVec } from './module.f.js';
@@ -8,17 +8,13 @@ import { detect, detectStream, detectVec } from './module.f.js';
 // store would hold the leading bytes of a stored blob.
 const bytes = (...b) => u8ListToVec(msb)(b);
 // ── Streaming detector helpers ──────────────────────────────────────────────────
-// Evaluates a fully pure effect (no operations) to its result.
-const runPure = (e) => {
-    const d = decode(e);
-    assert(d.done, 'effect is not pure');
-    return d.result;
-};
 // Builds a CAS-style read stream from a sequence of ok(chunk) items.
 const stream = (...chunks) => chunks.reduceRight((tail, c) => nonEmpty(ok(c), tail), emptyList());
 // Runs the streaming detector over the given chunks and unwraps the metadata.
 const detectChunks = (...chunks) => {
-    const r = runPure(detectStream(stream(...chunks)));
+    const o = runPure(detectStream(stream(...chunks)));
+    assert(o.length === 1, 'effect is not pure');
+    const [r] = o;
     assert(r[0] !== 'error', r[1]);
     return r[1];
 };
@@ -173,8 +169,9 @@ export const proof = {
         // A read `error` item short-circuits into the IoResult error.
         readErrorSurfaces: () => {
             const errStream = nonEmpty(['error', 'boom'], emptyList());
-            const r = runPure(detectStream(errStream));
-            assert(r[0] === 'error');
+            const o = runPure(detectStream(errStream));
+            assert(o.length === 1, 'effect is not pure');
+            assert(o[0][0] === 'error');
         },
         // Empty stream: zero-length text/plain.
         empty: () => {

package/fjs/module.f.js

@@ -10,7 +10,8 @@ import { main as ciMain } from './ci/module.f.js';
 import { import_ } from './effects/node/module.f.js';
 import { dispatch } from './cli/module.f.js';
 import { casMcpServer } from './cas/mcp/module.f.js';
-import { pure } from './effects/module.f.js';
+import { pure, step } from './effects/module.f.js';
+import { unwrap } from './types/result/module.f.js';
 const commands = [
     {
         names: ['test', 't'],
@@ -30,7 +31,7 @@ const commands = [
     {
         names: ['mcp', 'm'],
         description: 'Run an MCP server over stdio exposing the CAS and Evo (subjects/heads) as tools',
-        handler: ({ home }) => casMcpServer(home).step(() => pure(0)),
+        handler: ({ home }) => step(casMcpServer(home), () => pure(0)),
     },
     {
         names: ['ci', 'i'],
@@ -42,12 +43,7 @@ const commands = [
         description: 'Run a FunctionalScript module as a NodeProgram',
         handler: options => {
             const [file, ...args] = options.args;
-            return import_(file).step(([s, v]) => {
-                if (s === 'error') {
-                    throw v;
-                }
-                return v.main({ ...options, args });
-            });
+            return step(import_(file), x => unwrap(x).main({ ...options, args }));
         },
     },
 ];

package/fjs/types/bigint/module.f.js

@@ -17,7 +17,8 @@
  * ```
  */
 import { cmp } from '../function/compare/module.f.js';
-import { reduce } from '../list/module.f.js';
+import {} from '../list/module.f.js';
+import { fold } from '../../common/monoid/module.f.js';
 /**
  * Adds two `bigint` values.
  *
@@ -31,7 +32,7 @@ export const addition = a => b => a + b;
  * @param input - A list of bigint values.
  * @returns The sum of all values in the list.
  */
-export const sum = reduce(addition)(0n);
+export const sum = fold({ identity: 0n, operation: addition });
 /**
  * Multiplies two `bigint` values.
  *
@@ -45,7 +46,7 @@ export const multiple = a => b => a * b;
  * @param input - A list of bigint values.
  * @returns The product of all values in the list.
  */
-export const product = reduce(multiple)(1n);
+export const product = fold({ identity: 1n, operation: multiple });
 /**
  * Calculates the absolute value of a `bigint`.
  *

package/fjs/types/bit_vec/module.f.js

@@ -23,7 +23,7 @@
  */
 import { bitLength, divUp, mask, maxLength, xor } from '../bigint/module.f.js';
 import { flip, identity } from '../function/module.f.js';
-import { iterable, map } from '../list/module.f.js';
+import { map, tryFold } from '../list/module.f.js';
 import { asBase, asNominal } from '../nominal/module.f.js';
 import { repeat as mRepeat } from '../../common/monoid/module.f.js';
 import { cmp, max, min } from '../function/compare/module.f.js';
@@ -174,24 +174,14 @@ const listToVecOp = (unpackConcat) => ({
  * the final reduce prepends higher (earlier) slots in front of accumulated
  * later runs. An empty list yields `unpackEmpty`.
  *
+ * Returns `null` as soon as the accumulated length exceeds `maxLength`, which
+ * `tryFold` propagates by abandoning the rest of the list.
+ *
  * This is the bit-vector analogue of a builder that accumulates appended pieces
  * and materializes the combined result on demand, such as `StringBuilder`
  * (Java, C#) or `strings.Builder` (Go).
  */
-const unpackListToVec = (unpackConcat) => {
-    const { init, update, end } = listToVecOp(unpackConcat);
-    return (list) => {
-        let result = init;
-        for (const e of iterable(list)) {
-            const candidate = update(e, result);
-            if (candidate === null) {
-                return null;
-            }
-            result = candidate;
-        }
-        return end(result);
-    };
-};
+const unpackListToVec = (unpackConcat) => tryFold(listToVecOp(unpackConcat));
 const bo = ({ front, removeFront, norm, uintCmp, unpackSplit, unpackConcatUint }) => {
     const unpackPopFront = (len) => {
         const m = mask(len);

package/fjs/types/btree/remove/module.f.d.ts

@@ -7,3 +7,8 @@ import { type TNode, type Tree } from '../types/module.f.ts';
 import type { Compare } from '../../function/compare/module.f.ts';
 export declare const nodeRemove: <T>(c: Compare<T>) => (node: TNode<T>) => Tree<T>;
 export declare const remove: <T>(c: Compare<T>) => (tree: Tree<T>) => Tree<T>;
+export declare const proof: {
+    throw: {
+        reduceValue0DefaultBranch: () => void;
+    };
+};

package/fjs/types/btree/remove/module.f.js

@@ -172,3 +172,15 @@ export const nodeRemove = (c) => (node) => {
     return collapseRoot(reduce(initReduce(tf)(first))(tt));
 };
 export const remove = c => map(nodeRemove(c));
+// `reduceValue0`/`reduceValue2`/`initValue0`/`initValue1` merge a Branch1's lone
+// child into its Branch3 sibling. The sibling is always a Branch (length 3 or 5)
+// in every reachable tree shape, so the `default` arm guarding a mismatched
+// (leaf) sibling length can't be hit through the public `remove` API. Exercise
+// it directly here so the invariant guard itself stays covered.
+export const proof = {
+    throw: {
+        reduceValue0DefaultBranch: () => {
+            reduceValue0([['leaf']])([['x'], 's', ['y']]);
+        },
+    },
+};

package/fjs/types/list/module.f.d.ts

@@ -1,3 +1,4 @@
+import type { Nullable } from '../nullable/module.f.ts';
 import { type Scan, type StateScan, type Fold, type Reduce, type Equal } from '../function/operator/module.f.ts';
 export type List<T> = NotLazy<T> | Thunk<T>;
 type NotLazy<T> = Result<T> | Concat<T> | readonly T[];
@@ -44,6 +45,26 @@ export declare const stateScan: <I, S, O>(op: StateScan<I, S, O>) => (init: S) =
 export declare const foldScan: <I, O>(op: Fold<I, O>) => (init: O) => (input: List<I>) => Thunk<O>;
 export declare const fold: <I, O>(op: Fold<I, O>) => (init: O) => (input: List<I>) => O;
 export declare const reduce: <T>(op: Reduce<T>) => <D>(def: D) => (input: List<T>) => D | T;
+/**
+ * A fold that can bail out early, packaged as plain data.
+ *
+ * `init` is the starting state, `update` advances the state by one item and
+ * returns `null` to abort the whole fold, and `end` finalizes the surviving
+ * state into a result. Keeping the three parts together lets `tryFold` drive
+ * any short-circuiting accumulation without knowing its domain.
+ */
+export type Accumulator<I, T, R> = {
+    readonly init: T;
+    readonly update: (i: I, state: T) => Nullable<T>;
+    readonly end: (state: T) => R;
+};
+/**
+ * Folds `input` with an {@link Accumulator}, short-circuiting to `null` the
+ * moment `update` rejects an item; otherwise finalizes with `end`. This is the
+ * list-level `try*` sibling of {@link fold} for accumulations that can fail
+ * partway through (see the `try*`/`Nullable` convention in `AGENTS.md`).
+ */
+export declare const tryFold: <I, T, R>({ init, update, end }: Accumulator<I, T, R>) => (input: List<I>) => Nullable<R>;
 export declare const length: <T>(input: List<T>) => number;
 export type Entry<T> = readonly [number, T];
 export declare const entries: <T>(input: List<T>) => Thunk<Entry<T>>;

package/fjs/types/list/module.f.js

@@ -127,6 +127,23 @@ export const stateScan = op => compose(stateScanToScan(op))(scan);
 export const foldScan = op => compose(foldToScan(op))(scan);
 export const fold = op => init => compose(foldScan(op)(init))(last(init));
 export const reduce = op => def => compose(scan(reduceToScan(op)))(last(def));
+/**
+ * Folds `input` with an {@link Accumulator}, short-circuiting to `null` the
+ * moment `update` rejects an item; otherwise finalizes with `end`. This is the
+ * list-level `try*` sibling of {@link fold} for accumulations that can fail
+ * partway through (see the `try*`/`Nullable` convention in `AGENTS.md`).
+ */
+export const tryFold = ({ init, update, end }) => (input) => {
+    let state = init;
+    for (const i of iterable(input)) {
+        const candidate = update(i, state);
+        if (candidate === null) {
+            return null;
+        }
+        state = candidate;
+    }
+    return end(state);
+};
 const lengthList = list => () => {
     const notLazy = trampoline(list);
     if (notLazy === null) {

package/fjs/types/list/proof.f.d.ts

@@ -19,6 +19,7 @@ export declare const proof: {
     drop: (() => void)[];
     additionTests: (() => void)[];
     entries: (() => void)[];
+    tryFold: readonly [() => void, () => void, () => void];
     reverse: (() => void)[];
     zip: (() => void)[];
     logic: typeof logic;

package/fjs/types/list/proof.f.js

@@ -1,4 +1,4 @@
-import { length, concat, countdown, cycle, drop, dropWhile, entries, every, filter, find, flat, flatMap, map, next, reduce, reverse, scan, some, take, takeWhile, toArray, zip, first, filterMap, isEmpty, equal } from './module.f.js';
+import { length, concat, countdown, cycle, drop, dropWhile, entries, every, filter, find, flat, flatMap, map, next, reduce, reverse, scan, some, take, takeWhile, toArray, zip, first, filterMap, isEmpty, equal, tryFold } from './module.f.js';
 import { stringify } from '../../media/json/module.f.js';
 import { sort } from '../object/module.f.js';
 import { addition, strictEqual, reduceToScan } from '../function/operator/module.f.js';
@@ -112,6 +112,28 @@ const entriesTest = [
         assertEq(result, '[[0,"hello"],[1,"world"]]');
     }
 ];
+const sumUpTo = (limit) => ({
+    init: 0,
+    update: (i, state) => {
+        const next = state + i;
+        return next > limit ? null : next;
+    },
+    end: (state) => state * 10,
+});
+const tryFoldTest = [
+    () => {
+        const result = tryFold(sumUpTo(100))([1, 2, 3]);
+        assertEq(result, 60);
+    },
+    () => {
+        const result = tryFold(sumUpTo(4))([1, 2, 3]);
+        assertEq(result, null);
+    },
+    () => {
+        const result = tryFold(sumUpTo(100))([]);
+        assertEq(result, 0);
+    },
+];
 const reverseTest = [
     () => {
         const result = str(reverse([]));
@@ -257,6 +279,7 @@ export const proof = {
     drop: dropTest,
     additionTests,
     entries: entriesTest,
+    tryFold: tryFoldTest,
     reverse: reverseTest,
     zip: zipTest,
     logic,

package/fjs/types/number/module.f.js

@@ -7,7 +7,8 @@
 import { reduce } from '../list/module.f.js';
 import { addition } from '../function/operator/module.f.js';
 import { cmp as uCmp, min as uMin, max as uMax } from '../function/compare/module.f.js';
-export const sum = reduce(addition)(0);
+import { fold } from '../../common/monoid/module.f.js';
+export const sum = fold({ identity: 0, operation: addition });
 export const min = reduce(uMin)(null);
 export const max = reduce(uMax)(null);
 export const cmp = uCmp;

package/fjs/types/string/module.f.js

@@ -18,10 +18,18 @@
 import { reduce as listReduce, repeat as listRepeat } from '../list/module.f.js';
 import { compose } from '../function/module.f.js';
 import { cmp as uCmp } from '../function/compare/module.f.js';
-import { join as joinOp, concat as concatOp } from '../function/operator/module.f.js';
+import { join as joinOp } from '../function/operator/module.f.js';
+import { fold } from '../../common/monoid/module.f.js';
+// `join`'s per-separator reduction is seeded at `''` but is *not* a monoid fold:
+// `joinOp(sep)` has no identity (`joinOp(sep)('')(x)` prepends a separator), so
+// it stays a hand-seeded `reduce` rather than going through `monoid.fold`.
 const reduce = o => listReduce(o)('');
 export const join = compose(joinOp)(reduce);
-export const concat = reduce(concatOp);
+// String concatenation with identity `''` is a lawful monoid, so `concat` is a
+// monoid fold. The operation is accumulator-first (`a` on the left), matching
+// `monoid.fold`'s convention — unlike the element-first `concat` in
+// `function/operator`, which is written for `list.reduce`.
+export const concat = fold({ identity: '', operation: a => b => a + b });
 export const repeat = v => compose(listRepeat(v))(concat);
 export const cmp = uCmp;
 export const splitAt = (p) => (v) => [v.substring(0, p), v.substring(p)];

package/fjs/website/module.f.js

@@ -5,11 +5,10 @@
  */
 import { htmlUtf8 } from '../media/html/module.f.js';
 import { writeFile } from '../effects/node/module.f.js';
-import { pure } from '../effects/module.f.js';
+import { pure, step } from '../effects/module.f.js';
 const html = htmlUtf8()(['a',
     { href: 'https://github.com/functionalscript/functionalscript' },
     'GitHub Repository'
 ]);
-const program = writeFile('index.html', html)
-    .step(() => pure(0));
+const program = step(writeFile('index.html', html), () => pure(0));
 export const main = () => program;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "functionalscript",
-  "version": "0.38.0",
+  "version": "0.39.0",
   "type": "module",
   "files": [
     "**/*.js",
@@ -43,8 +43,8 @@
   },
   "homepage": "https://github.com/functionalscript/functionalscript#readme",
   "devDependencies": {
-    "@playwright/test": "1.61.1",
-    "@types/node": "26.1.1",
+    "@playwright/test": "1.62.0",
+    "@types/node": "26.1.2",
     "typescript": "7.0.2"
   }
 }