functionalscript 0.33.0 → 0.35.0

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

@@ -23,10 +23,11 @@
  */
 import { bitLength, divUp, mask, maxLength, xor } from "../bigint/module.f.js";
 import { flip, identity } from "../function/module.f.js";
-import { fold, iterable, map } from "../list/module.f.js";
+import { iterable, map } from "../list/module.f.js";
 import { asBase, asNominal } from "../nominal/module.f.js";
 import { repeat as mRepeat } from "../monoid/module.f.js";
 import { cmp, max, min } from "../function/compare/module.f.js";
+import { mapUnwrap } from "../nullable/module.f.js";
 /**
  * Maximum length of a bit vector in bits (1_048_576 = 0x10_0000).
  * This limit is enforced by Bun's `bigint` size constraint, the minimal limit
@@ -133,6 +134,64 @@ const op = (norm) => (op) => ap => bp => {
     const { a, b } = norm(au)(bu)(len);
     return vec(len)(op(a)(b));
 };
+const unpackEmpty = { length: 0n, uint: 0n };
+const listToVecOp = (unpackConcat) => ({
+    init: { len: 0n, stack: [] },
+    update: (v, { len, stack }) => {
+        len += v.length;
+        if (len > maxLength) {
+            return null;
+        }
+        let i = 0;
+        while (true) {
+            if (stack.length <= i) {
+                stack = [...stack, v];
+                break;
+            }
+            const old = stack[i];
+            if (old.length === 0n) {
+                stack = stack.toSpliced(i, 1, v);
+                break;
+            }
+            stack = stack.toSpliced(i, 1, unpackEmpty);
+            v = unpackConcat(old)(v);
+            i++;
+        }
+        return { len, stack };
+    },
+    end: ({ stack }) => pack(stack.reduce((p, c) => unpackConcat(c)(p), unpackEmpty))
+});
+/**
+ * Concatenates a list of unpacked vectors using a binary-counter accumulator,
+ * giving O(n log n) total `bigint` shifting work instead of the O(n²) of a
+ * naive left fold.
+ *
+ * Slot `i` of `result` holds an already-combined run of the most recent
+ * `2 ** i` elements. Each arriving element "carries" upward, merging only with
+ * runs of comparable size — exactly like incrementing a binary number — so
+ * every merge joins two runs of similar length. Left-to-right element order is
+ * preserved: `unpackConcat(old)(cur)` keeps the earlier run on the left, and
+ * the final reduce prepends higher (earlier) slots in front of accumulated
+ * later runs. An empty list yields `unpackEmpty`.
+ *
+ * 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 bo = ({ front, removeFront, norm, uintCmp, unpackSplit, unpackConcatUint }) => {
     const unpackPopFront = (len) => {
         const m = mask(len);
@@ -142,8 +201,9 @@ const bo = ({ front, removeFront, norm, uintCmp, unpackSplit, unpackConcatUint }
             return [uint & m, { length: v.length - len, uint: rest }];
         };
     };
-    const unpackConcat = (a) => (b) => ({
-        length: a.length + b.length, uint: unpackConcatUint(a)(b)
+    const unpackConcat = a => b => ({
+        length: a.length + b.length,
+        uint: unpackConcatUint(a)(b)
     });
     const popFront = len => {
         const f = unpackPopFront(len);
@@ -157,11 +217,13 @@ const bo = ({ front, removeFront, norm, uintCmp, unpackSplit, unpackConcatUint }
         const bu = unpack(b);
         return pack(unpackConcat(au)(bu));
     };
+    const tryListToVec = (list) => unpackListToVec(unpackConcat)(map(unpack)(list));
     return {
         front,
         removeFront,
         concat,
-        listToVec: fold(flip(concat))(empty),
+        tryListToVec,
+        listToVec: mapUnwrap(tryListToVec),
         xor: op(norm)(xor),
         unpackPopFront,
         popFront,
@@ -232,7 +294,16 @@ export const msb = bo({
     unpackSplit: len => ({ length, uint }) => [uint >> (length - len), uint],
     unpackConcatUint: flip(lsbUnpackConcatUint),
 });
-const unpackEmpty = { length: 0n, uint: 0n };
+/**
+ * Converts a list of unsigned 8-bit integers to a bit vector using the provided
+ * bit order, like `u8ListToVec`, but returns `null` instead of throwing when the
+ * result would exceed `maxLength`.
+ *
+ * @param bo The bit order for the conversion
+ * @param list The list of unsigned 8-bit integers to be converted.
+ * @returns The resulting vector, or `null` if it would exceed `maxLength`.
+ */
+export const tryU8ListToVec = ({ unpackConcat }) => (list) => unpackListToVec(unpackConcat)(map((b) => ({ length: 8n, uint: BigInt(b) }))(list));
 /**
  * Converts a list of unsigned 8-bit integers to a bit vector using the provided bit order.
  *
@@ -240,28 +311,7 @@ const unpackEmpty = { length: 0n, uint: 0n };
  * @param list The list of unsigned 8-bit integers to be converted.
  * @returns The resulting vector based on the provided bit order.
  */
-export const u8ListToVec = ({ unpackConcat }) => (list) => {
-    let result = [];
-    for (const b of iterable(list)) {
-        let v = { length: 8n, uint: BigInt(b) };
-        let i = 0;
-        while (true) {
-            if (result.length <= i) {
-                result = [...result, v];
-                break;
-            }
-            const old = result[i];
-            if (old.length === 0n) {
-                result = result.toSpliced(i, 1, v);
-                break;
-            }
-            result = result.toSpliced(i, 1, unpackEmpty);
-            v = unpackConcat(old)(v);
-            i++;
-        }
-    }
-    return pack(result.reduce((p, c) => unpackConcat(c)(p), unpackEmpty));
-};
+export const u8ListToVec = (bo) => mapUnwrap(tryU8ListToVec(bo));
 const unpackChunkList = ({ unpackSplit }) => (n) => {
     const divUpN2 = divUp(n << 1n);
     return u => {

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

@@ -46,6 +46,14 @@ export declare const proof: {
         emptyVec: () => void;
     };
     u8ListToVec: () => () => void;
+    tryListToVecOverflow: () => void;
+    listToVecOverflow: {
+        throw: () => void;
+    };
+    u8ListToVecOverflow: {
+        try: () => void;
+        throw: () => void;
+    };
     u8ListUnaligned: () => void;
     chunkList: {
         empty: () => void;

package/fs/types/bit_vec/proof.f.js

@@ -1,6 +1,7 @@
+import { assertEq } from "../../asserts/module.f.js";
 import { mask } from "../bigint/module.f.js";
 import { asBase, asNominal } from "../nominal/module.f.js";
-import { length, empty, uint, vec, lsb, msb, repeat, vec8, u8ListToVec, u8List, chunkList, fromSentinel } from "./module.f.js";
+import { length, empty, uint, vec, lsb, msb, repeat, vec8, maxLength, u8ListToVec, tryU8ListToVec, u8List, chunkList, fromSentinel } from "./module.f.js";
 import { repeat as listRepeat, toArray } from "../list/module.f.js";
 const unsafeVec = (a) => asNominal(a);
 // 0x8 = 0b1000 = 0 + 8
@@ -11,11 +12,6 @@ const unsafeVec = (a) => asNominal(a);
 // 0xD = 0b1101 = 5 + 8
 // 0xE = 0b1110 = 6 + 8
 // 0xF = 0b1111 = 7 + 8
-const assertEq = (a, b) => {
-    if (a !== b) {
-        throw [a, b];
-    }
-};
 const assertEq2 = ([a0, a1], [b0, b1]) => {
     assertEq(a0, b0);
     assertEq(a1, b1);
@@ -504,6 +500,28 @@ export const proof = {
             }
         };
     },
+    tryListToVecOverflow: () => {
+        const list = [vec(maxLength)(1n), vec(1n)(1n)];
+        assertEq(lsb.tryListToVec(list), null);
+        assertEq(msb.tryListToVec(list), null);
+    },
+    listToVecOverflow: {
+        // Same oversized input, but through the throwing `listToVec` wrapper.
+        throw: () => {
+            const list = { first: vec(maxLength + 1n)(1n), tail: null };
+            lsb.listToVec(list);
+        },
+    },
+    u8ListToVecOverflow: {
+        // 131_073 bytes is 8 bits past `maxLength`; same null/throw split as
+        // `tryListToVec`/`listToVec` above, exercised through the byte-list API.
+        try: () => {
+            assertEq(tryU8ListToVec(msb)(listRepeat(0x12)(131_073)), null);
+        },
+        throw: () => {
+            u8ListToVec(msb)(listRepeat(0x12)(131_073));
+        },
+    },
     u8ListUnaligned: () => {
         const x = vec(9n)(0x83n);
         const a = toArray(u8List(msb)(x));

package/fs/types/function/operator/module.f.d.ts

@@ -12,6 +12,32 @@ export declare const logicalNot: Unary<boolean, boolean>;
 export type Equal<T> = Binary<T, T, boolean>;
 export declare const strictEqual: <T>(a: T) => (b: T) => boolean;
 export type Scan<I, O> = (input: I) => readonly [O, Scan<I, O>];
+/**
+ * One step of a stream transducer: given an `input` symbol and the `prior`
+ * state, produce an `output` and the next state. It both maps an input stream
+ * to an output stream and threads state, so it models tokenizers, decoders, and
+ * other stream-to-stream stages.
+ *
+ * This is the *shape* of a [Mealy machine](https://en.wikipedia.org/wiki/Mealy_machine)
+ * — a [finite-state transducer](https://en.wikipedia.org/wiki/Finite-state_transducer)
+ * — but only its signature. The state `S` (and `I`, `O`) is an arbitrary type,
+ * not a finite set, so a `StateScan` is strictly more expressive than a Mealy
+ * machine — its power is the power of `S`:
+ * - a finite `S`/`I`/`O` recovers the classical finite-state machine (e.g. the
+ *   DFA states in `../../../fsm/module.f.ts`);
+ * - an `S` that is a stack makes it a
+ *   [pushdown / stack machine](https://en.wikipedia.org/wiki/Pushdown_automaton)
+ *   (context-free power — balanced brackets, nested structure, the AST tier);
+ * - an unbounded `S` like `bigint` can count, which no finite automaton can.
+ *
+ * And `O` may be a list (0+ symbols per input), not the single symbol strict
+ * Mealy emits. (Functional/coalgebraic usage still calls this `(input, state)
+ * => [output, state]` shape a "Mealy machine", finiteness aside.)
+ *
+ * A {@link Fold} is the output-less special case (state only); driving a
+ * `StateScan` over a `List` is `stateScan` in `../../list/module.f.ts`, and
+ * {@link stateScanToScan} hides the state to recover a {@link Scan}.
+ */
 export type StateScan<I, S, O> = (input: I, prior: S) => readonly [O, S];
 export declare const stateScanToScan: <I, S, O>(op: StateScan<I, S, O>) => (prior: S) => Scan<I, O>;
 export declare const foldToScan: <I, O>(fold: Fold<I, O>) => (prior: O) => Scan<I, O>;

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

@@ -4,6 +4,9 @@ type NotLazy<T> = Result<T> | Concat<T> | readonly T[];
 type Empty = null;
 export type Result<T> = Empty | NonEmpty<T>;
 export type Thunk<T> = () => List<T>;
+/**
+ * See also https://en.wikipedia.org/wiki/Cons#Lists
+ */
 export type NonEmpty<T> = {
     readonly first: T;
     readonly tail: List<T>;

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

@@ -1,8 +1,3 @@
-/**
- * Utilities for nullable (`null`/`undefined`) value handling.
- *
- * @module
- */
 import type { Option } from '../option/module.f.ts';
 export type Nullable<T> = T | null;
 export declare const map: <T, R>(f: (value: T) => R) => (value: Nullable<T>) => Nullable<R>;
@@ -15,3 +10,12 @@ export declare const toOption: <T>(value: Nullable<T>) => Option<T>;
  * property/index lookups) and FunctionalScript (which uses `null` for absence).
  */
 export declare const fromUndefined: <T>(value: T | undefined) => Nullable<T>;
+/**
+ * Extracts the value from a `Nullable`, asserting that it is not `null`.
+ */
+export declare const unwrap: <T>(value: Nullable<T>) => T;
+/**
+ * Lifts a function that signals failure with `null` into one that asserts
+ * success instead, unwrapping the result.
+ */
+export declare const mapUnwrap: <I, T>(f: (i: I) => Nullable<T>) => import("../function/module.f.ts").Func<I, T>;

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

@@ -1,3 +1,10 @@
+/**
+ * Utilities for nullable (`null`/`undefined`) value handling.
+ *
+ * @module
+ */
+import { assert } from "../../asserts/module.f.js";
+import { fn } from "../function/module.f.js";
 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];
@@ -8,3 +15,15 @@ export const toOption = (value) => value === null ? [] : [value];
  * property/index lookups) and FunctionalScript (which uses `null` for absence).
  */
 export const fromUndefined = (value) => value === undefined ? null : value;
+/**
+ * Extracts the value from a `Nullable`, asserting that it is not `null`.
+ */
+export const unwrap = (value) => {
+    assert(value !== null);
+    return value;
+};
+/**
+ * Lifts a function that signals failure with `null` into one that asserts
+ * success instead, unwrapping the result.
+ */
+export const mapUnwrap = (f) => fn(f).map(unwrap).result;

package/fs/types/result/module.d.ts

@@ -1,5 +1,3 @@
 import { type Result } from './module.f.ts';
-declare const _default: {
-    readonly tryCatch: <T>(f: () => T) => Result<T, unknown>;
-};
-export default _default;
+export declare const tryCatch: <T>(f: () => T) => Result<T, unknown>;
+export declare const asyncTryCatch: <T>(f: () => Promise<T>) => Promise<Result<T, unknown>>;

package/fs/types/result/module.js

@@ -1,5 +1,5 @@
 import { ok, error } from "./module.f.js";
-const tryCatch = f => {
+export const tryCatch = f => {
     // Side effect: `try catch` is not allowed in FunctionalScript.
     try {
         return ok(f());
@@ -8,6 +8,12 @@ const tryCatch = f => {
         return error(e);
     }
 };
-export default {
-    tryCatch,
+export const asyncTryCatch = async (f) => {
+    // Side effect: `try catch` is not allowed in FunctionalScript.
+    try {
+        return ok(await f());
+    }
+    catch (e) {
+        return error(e);
+    }
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "functionalscript",
-  "version": "0.33.0",
+  "version": "0.35.0",
   "type": "module",
   "files": [
     "**/*.js",
@@ -43,8 +43,8 @@
   },
   "homepage": "https://github.com/functionalscript/functionalscript#readme",
   "devDependencies": {
-    "@playwright/test": "1.61.0",
-    "@types/node": "26.0.0",
+    "@playwright/test": "1.61.1",
+    "@types/node": "26.1.0",
     "typescript": "6.0.3"
   }
 }

package/issues/demo/data/data.f.js

@@ -1,12 +0,0 @@
-import shared from "./shared.f.js"
-
-// comment
-const s = "Hello, world!"
-
-export default {
-  "a": shared,
-  "b": shared,
-  "s": s,
-  d: -24n,
-  x: undefined,
-}

package/issues/demo/data/shared.f.js

@@ -1,3 +0,0 @@
-export default {
-    "name": "shared object"
-}

package/issues/demo/fs/app.js

@@ -1,4 +0,0 @@
-import math from "./math.f.js"
-
-const add2 = math.add(2)
-console.log("5 ===", add2(3))

package/issues/demo/fs/math.f.js

@@ -1,4 +0,0 @@
-export default {
-  add: a => b => a + b,
-  mul: a => b => a * b,
-}

package/issues/demo/sample/proof.f.js

@@ -1,13 +0,0 @@
-const arrayOfTests = [
-  () => {
-    if (2 + 2 !== 4) throw "It's the end of the world as we know it!"
-  },
-  () => {
-    if (2n + 2n !== 4n) throw "It's the end of the world as we know it!"
-  }
-]
-
-export const proof = {
-  arrayOfTests,
-  generatingTests: () => arrayOfTests,
-}