functionalscript 0.43.1 → 0.45.0

package/fjs/basen/base128/proof.f.mjs

@@ -0,0 +1,32 @@
+/**
+ * @import { Vec } from '../../types/bit_vec/types.ts'
+ */
+
+import { empty, vec, vec8 } from '../../types/bit_vec/module.f.mjs'
+import { asBase } from '../../types/nominal/module.f.mjs'
+import { encode, decode } from './module.f.mjs'
+
+//
+
+/**
+ * @param {bigint} a
+ * @param {Vec} b
+ */
+const test = (a, b) => {
+    const encoded = encode(a)
+    if (encoded !== b) { throw `encoded: ${asBase(encoded).toString(16)}, expected: ${asBase(b).toString(16)}` }
+    const [decoded, rest] = decode(b)
+    if (decoded !== a) { throw `decoded: ${decoded.toString(16)}, expected: ${a.toString(16)}` }
+    if (rest !== empty) { throw `rest: ${asBase(rest).toString(16)}, expected: ${asBase(empty).toString(16)}` }
+}
+
+export const proof = () => {
+    test(0n, vec8(0n))
+    test(1n, vec8(1n))
+    test(0x7Fn, vec8(0x7Fn))
+    test(0x80n, vec(16n)(0x8100n))
+    test(0x81n, vec(16n)(0x8101n))
+    test(0x82n, vec(16n)(0x8102n))
+    test(0x3FFFn, vec(16n)(0xFF7Fn))
+    test(0x4000n, vec(24n)(0x818000n))
+}

package/fjs/basen/base64/module.f.d.mts

@@ -0,0 +1,14 @@
+/**
+ * Standard Base64 encoding and decoding (RFC 4648).
+ *
+ * @module
+ *
+ * @import { Vec } from '../../types/bit_vec/types.ts'
+ * @import { Nullable } from '../../types/nullable/types.ts'
+ */
+import type { Vec } from '../../types/bit_vec/types.ts';
+import type { Nullable } from '../../types/nullable/types.ts';
+/** @type {(input: Vec) => Nullable<string>} */
+export declare const encode: (input: Vec) => Nullable<string>;
+/** @type {(input: string) => Nullable<Vec>} */
+export declare const decode: (input: string) => Nullable<Vec>;

package/fjs/basen/base64/module.f.mjs

@@ -0,0 +1,75 @@
+/**
+ * Standard Base64 encoding and decoding (RFC 4648).
+ *
+ * @module
+ *
+ * @import { Vec } from '../../types/bit_vec/types.ts'
+ * @import { Nullable } from '../../types/nullable/types.ts'
+ */
+
+import { msb, length, vec } from '../../types/bit_vec/module.f.mjs'
+import { baseN } from "../module.f.mjs"
+
+const alphabet = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/'
+
+const { popFront } = msb
+
+const { vecToString, stringToVec } = baseN(6n, alphabet)
+
+/** @type {(input: Vec) => Nullable<string>} */
+export const encode = input => {
+    const len = length(input)
+    // Base64 is a byte codec; reject non-octet-aligned inputs.
+    if (len % 8n !== 0n) { return null }
+    // `vecToString` (via `baseN`'s `chunkList`) already left-pads a trailing
+    // partial 6-bit chunk with zeros, so `input` needs no explicit padding —
+    // building one would risk pushing an intermediate `Vec` past `maxLength`
+    // for input already at or near that limit, for no benefit.
+    let result = vecToString(input)
+    // Append `=` padding to make total length a multiple of 4.
+    while (result.length % 4 !== 0) { result += '=' }
+    return result
+}
+
+/** @type {(input: string) => Nullable<Vec>} */
+export const decode = input => {
+    // Count and strip trailing `=` padding (0, 1, or 2).
+    let padChars = 0
+    for (let i = input.length - 1; i >= 0 && input[i] === '='; i--) { padChars++ }
+    if (padChars > 2) { return null }
+
+    const body = input.slice(0, input.length - padChars)
+
+    // Total chars must make a multiple of 4 with the padding.
+    if ((body.length + padChars) % 4 !== 0) { return null }
+
+    if (padChars === 0) { return stringToVec(body) }
+
+    // `encode`'s zero-padding bits (added to reach a 6-bit boundary) live
+    // entirely inside the *last* character's chunk — RFC 4648 padding never
+    // spans more than one base64 character. Decode every character but the
+    // last through `stringToVec` as usual, then decode and trim the last
+    // character on its own, so no intermediate `Vec` built here is ever
+    // wider than the final, post-trim result — even for input whose decoded
+    // payload lands exactly at `maxLength`.
+    const removeBits = BigInt(padChars * 2)
+    const realBits = 6n - removeBits
+
+    const head = stringToVec(body.slice(0, body.length - 1))
+    if (head === null) { return null }
+
+    const lastChunk = stringToVec(body.slice(body.length - 1))
+    if (lastChunk === null) { return null }
+
+    // No `head`/`realBits` overflow check is needed here: `head` is built
+    // from whole 6-bit chunks, so its length is always a multiple of 6, and
+    // the largest such length `stringToVec` can return without itself
+    // failing is `maxLength - (maxLength % 6)` = `maxLength - 4`. Adding
+    // `realBits` (at most 4, when `padChars` is 1) reaches `maxLength`
+    // exactly and never exceeds it.
+    const [kept, pad] = popFront(realBits)(lastChunk)
+    // Padding bits must be zero (RFC 4648 §3.5).
+    if (pad !== vec(removeBits)(0n)) { return null }
+
+    return msb.concat(head)(vec(realBits)(kept))
+}

package/fjs/basen/base64/proof.f.d.mts

@@ -0,0 +1,19 @@
+/**
+ * @import { Vec } from '../../types/bit_vec/types.ts'
+ */
+export declare const proof: {
+    empty: () => void;
+    oneByte: () => void;
+    twoBytes: () => void;
+    threeBytes: () => void;
+    roundtrip: () => void;
+    nonOctet: () => void;
+    invalidInput: () => void;
+    validPadding: () => void;
+    knownVectors: () => void;
+    decodeOverflow: () => void;
+    decodePaddedTailRejections: () => void;
+    encodeAtMaxLengthSucceeds: () => void;
+    decodeAtMaxLengthSucceeds: () => void;
+    encodeLargeVecIsSlow: () => void;
+};

package/fjs/basen/base64/proof.f.mjs

@@ -0,0 +1,150 @@
+/**
+ * @import { Vec } from '../../types/bit_vec/types.ts'
+ */
+
+import { assertEq } from '../../asserts/module.f.mjs'
+import { empty, vec, repeat, vec8, maxLength } from '../../types/bit_vec/module.f.mjs'
+import { encode, decode } from './module.f.mjs'
+
+/**
+ * @param {string} s
+ * @param {Vec} v
+ */
+const check = (s, v) => {
+    assertEq(encode(v), s)
+    assertEq(decode(s), v)
+}
+
+export const proof = {
+    empty: () => {
+        check('', empty)
+    },
+    oneByte: () => {
+        // 0x00 → 0b00000000, padded to 12 bits → AA==
+        check('AA==', vec(8n)(0b00000000n))
+        // 0x48 'H' → 0b01001000 → SA==
+        check('SA==', vec(8n)(0b01001000n))
+        // 0xFF → 0b11111111, padded 12: 111111110000 → /w==
+        check('/w==', vec(8n)(0b11111111n))
+    },
+    twoBytes: () => {
+        // 0x0000 → AAAA with == stripped → 16 bits: AA==? No: 16 bits → 18 bits with 2 pad → 3 chars + =
+        // 0b0000000000000000 padded 2 bits → 18 bits: 000000 000000 000000 → AAA=
+        check('AAA=', vec(16n)(0n))
+        // 0xFFFF → 0b1111111111111111 padded 2 bits → 111111 111111 111100 → //8=
+        check('//8=', vec(16n)(0b1111111111111111n))
+    },
+    threeBytes: () => {
+        // 24 bits, no padding
+        check('AAAA', vec(24n)(0n))
+        check('////', vec(24n)(0b111111111111111111111111n))
+    },
+    roundtrip: () => {
+        // Various bit lengths
+        check('AA==', vec(8n)(0n))
+        check('AAA=', vec(16n)(0n))
+        check('AAAA', vec(24n)(0n))
+        // 32 bits
+        check('AAAAAA==', vec(32n)(0n))
+        // 40 bits (5 bytes: AAAA + AAA=)
+        check('AAAAAAA=', vec(40n)(0n))
+    },
+    nonOctet: () => {
+        // encode rejects bit vectors whose length is not a multiple of 8
+        assertEq(encode(vec(1n)(0n)), null)
+        assertEq(encode(vec(6n)(0n)), null)
+        assertEq(encode(vec(12n)(0n)), null)
+    },
+    invalidInput: () => {
+        assertEq(decode('!'), null)
+        assertEq(decode('A!AA'), null)
+        assertEq(decode('A==='), null)
+        assertEq(decode('A'), null)
+        assertEq(decode('AA'), null)
+        assertEq(decode('AAA'), null)
+        assertEq(decode('=AAA'), null)
+        // Non-zero padding bits must be rejected (RFC 4648 §3.5)
+        assertEq(decode('AB=='), null)
+        assertEq(decode('AAB='), null)
+    },
+    validPadding: () => {
+        // "==" padding
+        assertEq(decode('AA=='), vec(8n)(0n))
+        // "=" padding
+        assertEq(decode('AAA='), vec(16n)(0n))
+        // No padding
+        assertEq(decode('AAAA'), vec(24n)(0n))
+    },
+    knownVectors: () => {
+        // RFC 4648 §10 test vectors (byte-aligned, treating bytes as 8-bit MSB vectors)
+        // '' → ''
+        check('', empty)
+        // 0x66 ('f') → Zg==
+        check('Zg==', vec(8n)(0x66n))
+        // 0x66 0x6f ('fo') → Zm8=
+        check('Zm8=', vec(16n)(0x666fn))
+        // 0x66 0x6f 0x6f ('foo') → Zm9v
+        check('Zm9v', vec(24n)(0x666f6fn))
+    },
+    decodeOverflow: () => {
+        // 174_764 base64 chars decode to 1_048_584 bits, 8 over `maxLength`;
+        // `decode` should return `null` instead of throwing on (or hanging
+        // while building) an oversized `bigint`.
+        const oversized = 'A'.repeat(174_764)
+        assertEq(decode(oversized), null)
+    },
+    decodePaddedTailRejections: () => {
+        // These all take the padded branch of `decode` (`padChars > 0`,
+        // i.e. the `head`/`lastChunk` split), unlike `decodeOverflow` above
+        // which takes the unpadded fast path. An invalid character before
+        // the final char must be rejected via the `head` decode...
+        assertEq(decode('!A=='), null)
+        // ...and an invalid final character (the one holding the padding
+        // bits) must be rejected via the last-character decode.
+        assertEq(decode('A!=='), null)
+        // Same as `decodeOverflow`, but with a padded tail: `head` (all
+        // characters but the last) is still over `maxLength` on its own, so
+        // this is rejected by `head`'s own `stringToVec` overflow check, not
+        // by a separate `head`-plus-`realBits` measurement.
+        assertEq(decode('A'.repeat(174_764) + '='), null)
+    },
+    encodeAtMaxLengthSucceeds: () => {
+        // A `maxLength`-sized vector's trailing partial 6-bit chunk is
+        // left-padded by `vecToString` itself (see `baseN`), so `encode`
+        // never needs to build an over-`maxLength` intermediate and must not
+        // reject this boundary input.
+        assertEq(encode(vec(maxLength)(0n)), 'A'.repeat(174_763) + '=')
+    },
+    decodeAtMaxLengthSucceeds: () => {
+        // Companion to `encodeAtMaxLengthSucceeds`: the encoded string's raw,
+        // pre-trim bit count (1_048_578) is 2 over `maxLength` even though
+        // the payload it decodes to is exactly `maxLength`. `decode` must
+        // trim the last character's 2 zero-padding bits before — not after —
+        // measuring the result against `maxLength`.
+        check('A'.repeat(174_763) + '=', vec(maxLength)(0n))
+    },
+    // Regression guard: `encode` used to be quadratic in the input size, not
+    // linear. `baseN`'s `vecToString` (`fjs/basen/module.f.mjs`) popped one
+    // 6-bit chunk off the front at a time via `popFront`, and each `popFront`
+    // re-masked the entire remaining bigint through `vec()`'s `m & ui` —
+    // O(remaining length) — so encoding a vector of `n` bits cost O(n²). A
+    // 90,000-byte input took ~5.6s on Node and ~18.4s on Bun (Bun's `bigint`
+    // has a much higher per-operation constant, see PR #1190), reliably
+    // blowing `bun test`'s 5s per-test timeout — the same class of failure
+    // that hit `cas_get content:true` on a comparably-sized binary blob in CI
+    // (PR #1201).
+    //
+    // Fixed by rewriting `vecToString` as a balanced recursive split
+    // (`unpackToString`), mirroring the `chunkList`/`unpackChunkList`
+    // divide-and-conquer already used by `u8List` and by concatenation
+    // (`msb.concat` / `unpackListToVec`, PR #1192) — true O(n log n) now,
+    // since each half is masked to its own length before recursing. The same
+    // call now takes ~50ms on Node and ~225ms on Bun. No timing assertion
+    // (duration varies by engine/machine) — this just exercises the call and
+    // relies on the test runner's own per-test timing to catch a regression.
+    encodeLargeVecIsSlow: () => {
+        const big = repeat(90_000n)(vec8(0xffn))
+        const result = encode(big)
+        assertEq(result?.length, 120_000)
+    },
+}

package/fjs/basen/cbase32/module.f.d.mts

@@ -0,0 +1,18 @@
+/**
+ * Content-addressable Base32 encoding and decoding helpers.
+ *
+ * @module
+ *
+ * @import { Vec } from '../../types/bit_vec/types.ts'
+ * @import { Nullable } from '../../types/nullable/types.ts'
+ */
+import type { Vec } from '../../types/bit_vec/types.ts';
+import type { Nullable } from '../../types/nullable/types.ts';
+/** @type {(v: Vec) => string} */
+export declare const vec5xToCBase32: (v: Vec) => string;
+/** @type {(s: string) => Nullable<Vec>} */
+export declare const cBase32ToVec5x: (s: string) => Nullable<Vec>;
+/** @type {(v: Vec) => string} */
+export declare const vecToCBase32: (v: Vec) => string;
+/** @type {(s: string) => Nullable<Vec>} */
+export declare const cBase32ToVec: (s: string) => Nullable<Vec>;

package/fjs/basen/cbase32/module.f.mjs

@@ -0,0 +1,61 @@
+/**
+ * Content-addressable Base32 encoding and decoding helpers.
+ *
+ * @module
+ *
+ * @import { Vec } from '../../types/bit_vec/types.ts'
+ * @import { Nullable } from '../../types/nullable/types.ts'
+ */
+
+import { msb, lsb, length, vec, empty } from '../../types/bit_vec/module.f.mjs'
+import { baseN } from '../module.f.mjs'
+
+//                         0123456789abcdef
+const m = '0123456789abcdefghjkmnpqrstvwxyz'
+
+const { concat } = msb
+
+const popBack1 = lsb.popFront(1n)
+
+/** @type {(c: string) => string} */
+const normalizeChar = c => {
+    const lower = c.toLowerCase()
+    switch (lower) {
+        case 'i': { return '1' }
+        case 'l': { return '1' }
+        case 'o': { return '0' }
+        default: { return lower }
+    }
+}
+
+const codec = baseN(5n, m, normalizeChar)
+
+/** @type {(v: Vec) => string} */
+export const vec5xToCBase32 = codec.vecToString
+
+/** @type {(s: string) => Nullable<Vec>} */
+export const cBase32ToVec5x = codec.stringToVec
+
+/** @type {(v: Vec) => string} */
+export const vecToCBase32 = v => {
+    const len = length(v)
+    const extraLen = 5n - len % 5n
+    const last = 1n << (extraLen - 1n)
+    const padded = concat(v)(vec(extraLen)(last))
+    return vec5xToCBase32(padded)
+}
+
+/** @type {(s: string) => Nullable<Vec>} */
+export const cBase32ToVec = s => {
+    let v = cBase32ToVec5x(s)
+    if (v === null) { return null }
+    // Strip the padding: trailing zeros up to and including the sentinel `1` bit.
+    // A string with no sentinel — only zero symbols (`0`/`o`), or empty — exhausts
+    // to `empty` and is rejected as `null` rather than looping forever.
+    while (v !== empty) {
+        const [last, rest] = popBack1(v)
+        v = rest
+        if (last === 1n) { return v }
+    }
+    return null
+}

package/fjs/basen/cbase32/proof.f.d.mts

@@ -0,0 +1,10 @@
+/**
+ * @import { Vec } from '../../types/bit_vec/types.ts'
+ */
+export declare const proof: {
+    roundtrip5x: () => void;
+    roundtrip: () => void;
+    unalignedBits: () => void;
+    caseInsensitive: () => void;
+    unterminated: () => void;
+};

package/fjs/basen/cbase32/proof.f.mjs

@@ -0,0 +1,79 @@
+/**
+ * @import { Vec } from '../../types/bit_vec/types.ts'
+ */
+
+import { empty, vec } from '../../types/bit_vec/module.f.mjs'
+import { cBase32ToVec, cBase32ToVec5x, vec5xToCBase32, vecToCBase32 } from './module.f.mjs'
+import { assertEq } from '../../asserts/module.f.mjs'
+
+//
+
+/**
+ * @param {string} s
+ * @param {Vec} v
+ */
+const check5x = (s, v) => {
+    const sr = vec5xToCBase32(v)
+    assertEq(sr, s, [sr, s])
+    const vr = cBase32ToVec5x(s)
+    assertEq(vr, v, [vr, v])
+    //
+    check(`${s}g`, v)
+}
+
+/**
+ * @param {string} s
+ * @param {Vec} v
+ */
+const check = (s, v) => {
+    const sr = vecToCBase32(v)
+    assertEq(sr, s, [sr, s])
+    const vr = cBase32ToVec(s)
+    assertEq(vr, v, [vr, v])
+}
+
+export const proof = {
+    roundtrip5x: () => {
+        check5x("", empty)
+        check5x("0", vec(5n)(0b00000n))
+        check5x("1", vec(5n)(0b00001n))
+        check5x("7", vec(5n)(0b00111n))
+        check5x("a", vec(5n)(0b01010n))
+        check5x("b", vec(5n)(0b01011n))
+        check5x("f", vec(5n)(0b01111n))
+        check5x("gh", vec(10n)(0b10000_10001n))
+        check5x("jk", vec(10n)(0b10010_10011n))
+        check5x("mnpq", vec(20n)(0b010100_10101_10110_10111n))
+        check5x("rstvwxyz", vec(40n)(0b11000_11001_11010_11011_11100_11101_11110_11111n))
+    },
+    roundtrip: () => {
+        check("g", empty)
+        check("8", vec(1n)(0n))
+        check("r", vec(1n)(1n))
+        check("4", vec(2n)(0n))
+        check("c", vec(2n)(1n))
+        check("2", vec(3n)(0n))
+        check("1", vec(4n)(0n))
+        check("2g", vec(5n)(2n))
+        check("01", vec(9n)(0n))
+    },
+    unalignedBits: () => {
+        const v = vec(1n)(1n)
+        const cr = vec5xToCBase32(v)
+        assertEq(cr, "g", ['g', cr])
+    },
+    caseInsensitive: () => {
+        assertEq(cBase32ToVec5x("A"), cBase32ToVec5x("a"), 'case-insensitive expected')
+        assertEq(cBase32ToVec5x("I"), cBase32ToVec5x("1"), 'i maps to 1')
+        assertEq(cBase32ToVec5x("l"), cBase32ToVec5x("1"), 'l maps to 1')
+        assertEq(cBase32ToVec5x("o"), cBase32ToVec5x("0"), 'o maps to 0')
+        assertEq(cBase32ToVec5x("u"), null, 'should error on invalid character')
+    },
+    unterminated: () => {
+        // No sentinel `1` bit → invalid; must return null, not loop forever.
+        assertEq(cBase32ToVec(""), null, 'empty must be null')
+        assertEq(cBase32ToVec("0"), null, 'single zero symbol must be null')
+        assertEq(cBase32ToVec("00"), null, 'all-zero symbols must be null')
+        assertEq(cBase32ToVec("o"), null, 'o (maps to 0) must be null')
+    }
+}

package/fjs/basen/module.f.d.mts

@@ -0,0 +1,30 @@
+/**
+ * Shared bit-codec factory for alphabet-based encodings such as `base64` and
+ * `cbase32`.
+ *
+ * Each call returns the raw `Vec ↔ string` codec parameterised by the chunk
+ * width (`bits`) and the alphabet (and an optional input-character
+ * normalisation step on the decode side). Padding strategies — RFC 4648 `=`
+ * octet-alignment, Crockford-style stop-bit sentinels, etc. — are deliberately
+ * out of scope: they vary per format and are handled by the caller around
+ * `vecToString` / `stringToVec`.
+ *
+ * @module
+ *
+ * @import { Vec } from '../types/bit_vec/types.ts'
+ * @import { List } from '../types/list/types.ts'
+ * @import { BaseN } from './types.ts'
+ */
+import type { BaseN } from './types.ts';
+/**
+ * Builds a {@link BaseN} codec for a fixed chunk width and alphabet.
+ *
+ * @param {bigint} bits The chunk width in bits. `alphabet.length` must equal `2 ** bits`.
+ * @param {string} alphabet The character used for each unsigned `bits`-bit value, in
+ *   ascending order (index `0` → first character).
+ * @param {undefined | ((c: string) => string)} normalize Optional pre-lookup transform applied to each input
+ *   character on decode — e.g. Crockford base32 lowercases and folds
+ *   `i`/`l`→`1`, `o`→`0`.
+ * @return {BaseN}
+ */
+export declare const baseN: (bits: bigint, alphabet: string, normalize?: undefined | ((c: string) => string)) => BaseN;

package/fjs/basen/module.f.mjs

@@ -0,0 +1,88 @@
+/**
+ * Shared bit-codec factory for alphabet-based encodings such as `base64` and
+ * `cbase32`.
+ *
+ * Each call returns the raw `Vec ↔ string` codec parameterised by the chunk
+ * width (`bits`) and the alphabet (and an optional input-character
+ * normalisation step on the decode side). Padding strategies — RFC 4648 `=`
+ * octet-alignment, Crockford-style stop-bit sentinels, etc. — are deliberately
+ * out of scope: they vary per format and are handled by the caller around
+ * `vecToString` / `stringToVec`.
+ *
+ * @module
+ *
+ * @import { Vec } from '../types/bit_vec/types.ts'
+ * @import { List } from '../types/list/types.ts'
+ * @import { BaseN } from './types.ts'
+ */
+
+import { msb, lsb, vec, chunkList, unpack } from '../types/bit_vec/module.f.mjs'
+import { fold } from '../types/list/module.f.mjs'
+import { compose } from '../types/function/module.f.mjs'
+
+const { unpackSplit } = msb
+
+const { tryListToVec: reversedListToVec } = lsb
+
+// `chunkList(msb)` doesn't depend on `bits` or `v` — shared across every
+// `baseN(...)` codec (base64, cbase32, ...).
+const chunkListMsb = chunkList(msb)
+
+/**
+ * Builds a {@link BaseN} codec for a fixed chunk width and alphabet.
+ *
+ * @param {bigint} bits The chunk width in bits. `alphabet.length` must equal `2 ** bits`.
+ * @param {string} alphabet The character used for each unsigned `bits`-bit value, in
+ *   ascending order (index `0` → first character).
+ * @param {undefined | ((c: string) => string)} normalize Optional pre-lookup transform applied to each input
+ *   character on decode — e.g. Crockford base32 lowercases and folds
+ *   `i`/`l`→`1`, `o`→`0`.
+ * @return {BaseN}
+ */
+export const baseN = (
+    bits,
+    alphabet,
+    normalize = undefined,
+) => {
+    const vecN = vec(bits)
+    const toIndex = normalize === undefined
+        ? (/** @type {string} */c) => alphabet.indexOf(c)
+        : (/** @type {string} */c) => alphabet.indexOf(normalize(c))
+    const unpackSplitBits = unpackSplit(bits)
+    // Converts one `<= bits`-wide chunk (as yielded by `chunkList`, already
+    // masked to its own length) to its alphabet index. A trailing partial
+    // chunk shorter than `bits` is left-padded with zeros: `unpackSplit`'s
+    // shift amount goes negative, which per spec becomes a left shift.
+    /** @type {(chunk: Vec) => number} */
+    const chunkToIndex = chunk => {
+        const u = unpack(chunk)
+        return Number(u.length < bits ? unpackSplitBits(u)[0] : u.uint)
+    }
+    // Folds directly over `chunkList`'s lazy list in one pass — faster than
+    // `map` into a second lazy list before joining, since there's no second
+    // list to allocate/traverse.
+    /** @type {(chunk: Vec) => (acc: string) => string} */
+    const chunkToString = chunk => acc =>
+        acc + alphabet[chunkToIndex(chunk)]
+    return {
+        // `chunkListMsb(bits)` then `fold(chunkToString)('')` — neither half
+        // depends on `v`, so `compose` builds (and this closure captures)
+        // the composed function once per `baseN(...)` codec; no need to name
+        // the halves separately just to get that one-time build.
+        vecToString: compose(chunkListMsb(bits))(fold(chunkToString)('')),
+        stringToVec: s => {
+            // Build a reversed chunk list, bailing out at the first invalid
+            // character so malformed input is rejected in O(prefix) time and
+            // `normalize` is never run past it. `listToVec` then concatenates in
+            // O(n log n).
+            /** @type {List<Vec>} */
+            let chunks = null
+            for (const c of s) {
+                const index = toIndex(c)
+                if (index < 0) { return null }
+                chunks = { first: vecN(BigInt(index)), tail: chunks }
+            }
+            return reversedListToVec(chunks)
+        },
+    }
+}

package/fjs/basen/proof.f.mjs

@@ -0,0 +1,69 @@
+import { assertEq, assertNotNullish } from '../asserts/module.f.mjs'
+import { empty, maxLength, vec, length } from '../types/bit_vec/module.f.mjs'
+import { baseN } from './module.f.mjs'
+
+const hex = baseN(4n, '0123456789abcdef')
+
+const cb32 = baseN(5n, '0123456789abcdefghjkmnpqrstvwxyz', c => {
+    const lower = c.toLowerCase()
+    switch (lower) {
+        case 'i': { return '1' }
+        case 'l': { return '1' }
+        case 'o': { return '0' }
+        default: { return lower }
+    }
+})
+
+// Sample input for the `big` proof below: 262 144 `f` characters decode into a
+// 1 Mibit (`maxLength`) vector.
+const bigSampleHex = `f`.repeat(Number(maxLength >> 2n))
+
+export const proof = {
+    encodeEmpty: () => {
+        const s = hex.vecToString(empty)
+        assertEq(s, '', [s])
+    },
+    encodeAligned: () => {
+        // Two 4-bit chunks → two hex digits
+        const s = hex.vecToString(vec(8n)(0xa5n))
+        assertEq(s, 'a5', [s])
+    },
+    encodeUnaligned: () => {
+        // 6 bits → first 4-bit chunk + a 2-bit tail that popFront pads with
+        // trailing zeros (the standard `popFront` behaviour the codec inherits).
+        const s = hex.vecToString(vec(6n)(0b101001n))
+        assertEq(s, 'a4', [s])
+    },
+    decodeEmpty: () => {
+        const v = hex.stringToVec('')
+        assertEq(v, empty, [v])
+    },
+    decodeRoundTrip: () => {
+        const v = hex.stringToVec('ab')
+        assertEq(v, vec(8n)(0xabn), [v])
+    },
+    decodeInvalid: () => {
+        assertEq(hex.stringToVec('z'), null, 'invalid char should return null')
+        assertEq(hex.stringToVec('aZ'), null, 'mixed invalid char should return null')
+    },
+    normalizeHit: () => {
+        // 'A' lowercases to 'a' — same vector as the lowercase input.
+        const a = cb32.stringToVec('A')
+        const b = cb32.stringToVec('a')
+        assertEq(a, b, [a, b])
+        // Crockford folds: i,l → 1 and o → 0.
+        assertEq(cb32.stringToVec('I'), cb32.stringToVec('1'), 'I→1')
+        assertEq(cb32.stringToVec('l'), cb32.stringToVec('1'), 'l→1')
+        assertEq(cb32.stringToVec('o'), cb32.stringToVec('0'), 'o→0')
+    },
+    normalizeMiss: () => {
+        assertEq(cb32.stringToVec('u'), null, 'unknown char should return null')
+    },
+    // Decodes a 1 Mibit hex string. With the O(n log n) `listToVec` builder this
+    // runs in well under a second (was ~13 s node / ~43 s bun under the old
+    // per-chunk `concat`).
+    big: () => {
+        const x = hex.stringToVec(bigSampleHex)
+        assertEq(length(assertNotNullish(x)), maxLength)
+    }
+}

package/fjs/basen/types.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Types for the shared bit-codec factory.
+ *
+ * @module
+ */
+import type { Vec } from '../types/bit_vec/types.ts';
+import type { Nullable } from '../types/nullable/types.ts';
+/**
+ * The encode/decode pair returned by `baseN` in `./module.f.mjs`.
+ */
+export type BaseN = {
+    readonly vecToString: (v: Vec) => string;
+    readonly stringToVec: (s: string) => Nullable<Vec>;
+};