functionalscript 0.43.1 → 0.44.0

package/fjs/asn.1/proof.f.mjs

@@ -0,0 +1,309 @@
+/** @import { Vec } from '../types/bit_vec/types.ts' */
+import { empty, isVec, length, msb, uint, unpack, vec, vec8 } from '../types/bit_vec/module.f.mjs'
+
+import { asBase } from '../types/nominal/module.f.mjs'
+
+import {
+    decodeRaw,
+    decodeInteger,
+    encodeRaw,
+    encodeInteger,
+    integer,
+    encode,
+    decode,
+    constructedSequence,
+    octetString,
+    boolean,
+    constructedSet,
+    encodeObjectIdentifier,
+    decodeObjectIdentifier,
+} from './module.f.mjs'
+/** @import { SupportedRecord, ObjectIdentifier } from './types.ts' */
+
+import { assert, assertEq } from '../asserts/module.f.mjs'
+
+const { concat, popFront: pop, listToVec } = msb
+const pop8 = pop(8n)
+
+/**
+ * @param {bigint} tag
+ * @param {Vec} v
+ * @param {Vec} rest
+ */
+const check = (tag, v, rest) => {
+    const s = encodeRaw([tag, v])
+    const [[t0, v0], r] = decodeRaw(concat(s)(rest))
+    if (t0 !== tag) { throw `t0: ${t0}` }
+    if (v0 !== v) { throw `v0: ${asBase(v0)}` }
+    if (r !== rest) { throw `r: ${asBase(r)}` }
+}
+
+/**
+ * @param {bigint} i
+ * @param {Vec} v
+ */
+const integerValueCheck = (i, v) => {
+    const v0 = encodeInteger(i)
+    if (v !== v0) { throw `encode: ${asBase(v)}, ${asBase(v0)}` }
+    const i0 = decodeInteger(v)
+    assertEq(i, i0, [i, i0])
+}
+
+/**
+ * @param {SupportedRecord} r
+ * @param {Vec} v
+ * @param {Vec} rest
+ */
+const ch0 = (r, v, rest) => {
+    const [r0, rest0] = decode(concat(v)(rest))
+    if (rest0 !== rest) { throw `rest: ${asBase(rest0)}` }
+    const v0 = encode(r)
+    const v1 = encode(r0)
+    if (v !== v0) { throw `encode: ${asBase(v)}, ${asBase(v0)}` }
+    if (v !== v1) { throw `encode: ${asBase(v)}, ${asBase(v1)}` }
+}
+
+/**
+ * @param {SupportedRecord} r
+ * @param {Vec} v
+ */
+const ch = (r, v) => {
+    ch0(r, v, empty)
+    ch0(r, v, vec8(0x23n))
+    ch0(r, v, vec(16n)(0x2345n))
+}
+
+export const proof = {
+    encodeSmall: () => {
+        const v = vec8(0x13n)
+        const x = encodeRaw([integer, v])
+        const lx = length(x)
+        assertEq(lx, 24n)
+        const [tag, x1] = pop8(x)
+        assertEq(tag, BigInt(integer))
+        const [len, x2] = pop8(x1)
+        assertEq(len, 1n)
+        const { length: intLen, uint } = unpack(x2)
+        assertEq(intLen, 8n)
+        assertEq(uint, 0x13n)
+    },
+    encode7F: () => {
+        const valueLen = 0x7Fn << 3n
+        const value = 0x1234n
+        const v = vec(valueLen)(value)
+        const x = encodeRaw([integer, v])
+        const lx = length(x)
+        assertEq(lx, 0x81n << 3n)
+        const [tag, x1] = pop8(x)
+        assertEq(tag, BigInt(integer))
+        const [len, x2] = pop8(x1)
+        assertEq(len, 0x7Fn)
+        const { length: intLen, uint } = unpack(x2)
+        assertEq(intLen, valueLen)
+        assertEq(uint, value)
+    },
+    encode80: () => {
+        const valueLen = 0x80n << 3n
+        const value = 0x123456n
+        const v = vec(valueLen)(value)
+        const x = encodeRaw([integer, v])
+        const lx = length(x)
+        assertEq(lx, 0x83n << 3n)
+        const [tag, x1] = pop8(x)
+        assertEq(tag, BigInt(integer))
+        const [lenLen, x2] = pop8(x1)
+        assertEq(lenLen, 0x81n)
+        const [len, x3] = pop8(x2)
+        assertEq(len, 0x80n)
+        const { length: intLen, uint } = unpack(x3)
+        assertEq(intLen, valueLen)
+        assertEq(uint, value)
+    },
+    encodeFF: () => {
+        const valueLen = 0xFFn << 3n
+        const value = 0x123456n
+        const v = vec(valueLen)(value)
+        const x = encodeRaw([integer, v])
+        const lx = length(x)
+        if (lx !== valueLen + (3n << 3n)) { throw `lx: ${lx}` }
+        const [tag, x1] = pop8(x)
+        assertEq(tag, BigInt(integer))
+        const [lenLen, x2] = pop8(x1)
+        assertEq(lenLen, 0x81n)
+        const [len, x3] = pop8(x2)
+        assertEq(len, 0xFFn)
+        const { length: intLen, uint } = unpack(x3)
+        assertEq(intLen, valueLen)
+        assertEq(uint, value)
+    },
+    encode103: () => {
+        const valueLen = 0x103n << 3n
+        const value = 0x123456n
+        const v = vec(valueLen)(value)
+        const x = encodeRaw([integer, v])
+        const lx = length(x)
+        if (lx !== valueLen + (4n << 3n)) { throw `lx: ${lx}` }
+        const [tag, x1] = pop8(x)
+        assertEq(tag, BigInt(integer))
+        const [lenLen, x2] = pop8(x1)
+        assertEq(lenLen, 0x82n)
+        const [len, x3] = pop(16n)(x2)
+        assertEq(len, 0x103n)
+        const { length: intLen, uint } = unpack(x3)
+        assertEq(intLen, valueLen)
+        assertEq(uint, value)
+    },
+    ed: [
+        () => {
+            const tag = integer
+            const v = vec(0x10n)(0x8234n)
+            assertEq(asBase(v), 0x8234n, asBase(v).toString(16))
+            check(integer, v, empty)
+        },
+        {
+            x80: () => check(integer, vec(0x80n)(0x8234n), empty),
+            x100: () => check(integer, vec(0x100n)(0x8234n), vec8(0x23n)),
+            x1000: () => check(integer, vec(0x1000n)(0x8234n), vec8(0x23n)),
+            x10000: () => check(integer, vec(0x1_0000n)(0x8234n), vec8(0x23n)),
+            x20000: () => check(integer, vec(0x2_0000n)(0x8234n), vec8(0x23n)),
+            x40000: () => check(integer, vec(0x4_0000n)(0x8234n), empty),
+            x80000: () => check(integer, vec(0x8_0000n)(0x8234n), empty),
+            xC0000: () => check(integer, vec(0xC_0000n)(0x8234n), empty),
+            xE0000: () => check(integer, vec(0xE_0000n)(0x8234n), empty),
+            xF0000: () => check(integer, vec(0xF_0000n)(0x8234n), empty),
+            xFFF00: () => check(integer, vec(0xF_FF00n)(0x8234n), empty),
+            xFFF80: () => check(integer, vec(0xF_FF80n)(0x8234n), empty),
+            xFFFC0: () => check(integer, vec(0xF_FFC0n)(0x8234n), empty),
+            xFFFD0: () => check(integer, vec(0xF_FFD0n)(0x8234n), empty),
+            //// fail on Bun because it has a smaller limit for BigInt
+            //xFFFD8: () => check(integer, vec(0xF_FFD8n)(0x8234n), empty),
+            //xFFFE0: () => check(integer, vec(0xF_FFE0n)(0x8234n), empty),
+            //e100000: () => check(integer, vec(0x10_0000n)(0x8234n), empty),
+            //x100000: () => check(integer, vec(0x10_0000n)(0x8234n), vec8(0x23n)),
+            //x1000000: () => check(integer, vec(0x100_0000n)(0x8234n), vec8(0x23n)),
+            //x10000000: () => check(integer, vec(0x1000_0000n)(0x8234n), vec8(0x23n)),
+            //x20000000: () => check(integer, vec(0x2000_0000n)(0x8234n), vec8(0x23n)),
+            //x30000000: () => check(integer, vec(0x3000_0000n)(0x8234n), vec8(0x23n)),
+            //x38000000: () => check(integer, vec(0x3800_0000n)(0x8234n), vec8(0x23n)),
+            //x3C000000: () => check(integer, vec(0x3800_0000n)(0x8234n), vec8(0x23n)),
+            //x3E000000: () => check(integer, vec(0x3E00_0000n)(0x8234n), vec8(0x23n)),
+            //x3F000000: () => check(integer, vec(0x3F00_0000n)(0x8234n), vec8(0x23n)),
+            //x3F800000: () => check(integer, vec(0x3F80_0000n)(0x8234n), vec8(0x23n)),
+            //x3FFFFFC0: () => check(integer, vec(0x3FFF_FFC0n)(0x8234n), vec8(0x23n)),
+            //e3FFFFFC8: () => check(integer, vec(0x3FFF_FFC8n)(0x8234n), empty),
+            //// fail on Node
+            //x3FFFFFC8: () => check(integer, vec(0x3FFF_FFC1n)(0x8234n), vec8(0x23n)),
+            //x40000000: () => check(integer, vec(0x4000_0000n)(0x8234n), vec8(0x23n)),
+            // check(integer, vec(0x1_0000_0000n)(0x8234n), vec8(0x23n))
+        },
+    ],
+    integerValue: {
+        zero: () => integerValueCheck(0n, vec8(0n)),
+        one: () => integerValueCheck(1n, vec8(1n)),
+        minusOne: () => integerValueCheck(-1n, vec8(0xFFn)),
+        x7F: () => integerValueCheck(0x7Fn, vec8(0x7Fn)),
+        x80: () => integerValueCheck(0x80n, vec(16n)(0x80n)),
+        xFF: () => integerValueCheck(0xFFn, vec(16n)(0xFFn)),
+        nx7F: () => integerValueCheck(-0x7Fn, vec8(0x81n)),
+        nx80: () => integerValueCheck(-0x80n, vec8(0x80n)),
+        nx81: () => integerValueCheck(-0x81n, vec(16n)(0xFF7Fn)),
+        nx7FFF: () => integerValueCheck(-0x7FFFn, vec(16n)(0x8001n)),
+        nx8000: () => integerValueCheck(-0x8000n, vec(16n)(0x8000n)),
+        nx8001: () => integerValueCheck(-0x8001n, vec(24n)(0xFF7FFFn)),
+    },
+    encodeDecode: {
+        integer: () => {
+            ch([integer, 0n], listToVec([vec8(BigInt(integer)), vec8(1n), vec8(0n)]))
+            ch([integer, 1n], listToVec([vec8(BigInt(integer)), vec8(1n), vec8(1n)]))
+        },
+        sequence: () => {
+            ch([constructedSequence, []], listToVec([vec8(BigInt(constructedSequence)), vec8(0n)]))
+            ch(
+                [constructedSequence, [[integer, 0n]]],
+                listToVec([vec8(BigInt(constructedSequence)), vec8(3n), encode([integer, 0n])])
+            )
+            ch(
+                [constructedSequence, [[integer, 1n], [integer, 2n]]],
+                listToVec([
+                    vec8(BigInt(constructedSequence)),
+                    vec8(6n),
+                    encode([integer, 1n]),
+                    encode([integer, 2n])
+                ])
+            )
+            ch(
+                [constructedSequence, [[octetString, vec8(0x23n)], [boolean, true], [boolean, false]]],
+                listToVec([
+                    vec8(BigInt(constructedSequence)),
+                    vec8(9n),
+                    encode([octetString, vec8(0x23n)]),
+                    encode([boolean, true]),
+                    encode([boolean, false]),
+                ])
+            )
+        },
+        set: () => {
+            ch([constructedSet, [[integer, 2n], [integer, 1n]]],
+                listToVec([
+                    vec8(BigInt(constructedSet)),
+                    vec8(6n),
+                    encode([integer, 1n]),
+                    encode([integer, 2n])
+                ])
+            )
+        },
+    },
+    objectIdentifier: {
+        simple: () => {
+            /** @type {ObjectIdentifier} */
+            const oid = [1n, 2n]
+            const encoded = encodeObjectIdentifier(oid)
+            const decoded = decodeObjectIdentifier(encoded)
+            assertEq(decoded.length, 2)
+            assertEq(decoded[0], 1n)
+            assertEq(decoded[1], 2n)
+        },
+        withArc: () => {
+            // OID 1.2.840.113549 (RSA)
+            /** @type {ObjectIdentifier} */
+            const oid = [1n, 2n, 840n, 113549n]
+            const decoded = decodeObjectIdentifier(encodeObjectIdentifier(oid))
+            assertEq(decoded.length, 4)
+            assertEq(decoded[0], 1n)
+            assertEq(decoded[1], 2n)
+            assertEq(decoded[2], 840n)
+            assertEq(decoded[3], 113549n)
+        },
+    },
+    unknownTag: () => {
+        // bitString (0x03) is not in SupportedRecord, exercises the default case in rawToRecord
+        const raw = encodeRaw([0x03n, vec8(0x42n)])
+        const [decoded, rest] = decode(raw)
+        assert(isVec(decoded), 'expected UnsupportedRecord (Vec)')
+        assertEq(rest, empty, 'expected empty rest')
+        // Re-encoding an UnsupportedRecord returns it unchanged (it is already the TLV bytes)
+        assertEq(encode(decoded), raw, 'encode should round-trip UnsupportedRecord')
+    },
+    raw: [
+        () => {
+            const e = encodeRaw([0x00n, vec8(0x23n)])
+            if (e !== listToVec([vec8(0x00n), vec8(1n), vec8(0x23n)])) { throw `encode: ${length(e)}: ${uint(e).toString(2)}` }
+            const [[tag, value], rest] = decodeRaw(e)
+            if (rest !== empty) { throw `rest: ${asBase(rest)}` }
+            if (tag !== 0x00n) { throw `tag: ${tag}` }
+            if (value !== vec8(0x23n)) { throw `value: ${asBase(value)}` }
+        },
+        () => {
+            const e = encodeRaw([0x1F20n, vec(16n)(0x1234n)])
+            if (e !== listToVec([vec8(0x1Fn), vec8(0x20n), vec8(2n), vec(16n)(0x1234n)])) {
+                const l = length(e)
+                const u = uint(e)
+                throw `encode: ${l}: ${u.toString(16)}`
+            }
+            const [[tag, value], rest] = decodeRaw(e)
+            if (rest !== empty) { throw `rest: ${asBase(rest)}` }
+            if (tag !== 0x1F20n) { throw `tag: ${tag}` }
+            if (value !== vec(16n)(0x1234n)) { throw `value: ${asBase(value)}` }
+        }
+    ]
+}

package/fjs/asn.1/types.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Types for ASN.1 BER/DER encoding and decoding over bit vectors.
+ *
+ * @module
+ */
+import type { Vec } from '../types/bit_vec/types.ts';
+import type { boolean as booleanTag, constructedSequence, constructedSet, integer, objectIdentifier, octetString } from './module.f.mjs';
+/**
+ * ASN.1 tag number.
+ */
+export type _Tag = bigint;
+/**
+ * Raw ASN.1 TLV tuple.
+ */
+export type Raw = readonly [_Tag, Vec];
+/**
+ * ASN.1 OBJECT IDENTIFIER components.
+ */
+export type ObjectIdentifier = readonly bigint[];
+/**
+ * ASN.1 ordered collection of records.
+ */
+export type Sequence = readonly Record[];
+/**
+ * ASN.1 SET represented as a sequence of records.
+ */
+export type Set = Sequence;
+/**
+ * Supported ASN.1 record variants.
+ */
+export type SupportedRecord = readonly [typeof booleanTag, boolean] | readonly [typeof integer, bigint] | readonly [typeof octetString, Vec] | readonly [typeof objectIdentifier, ObjectIdentifier] | readonly [typeof constructedSequence, Sequence] | readonly [typeof constructedSet, Set];
+/**
+ * For unsupported tags, we just store the raw value including the tag and
+ * length, so that it can be re-encoded without loss of information.
+ */
+export type UnsupportedRecord = Vec;
+export type Record = SupportedRecord | UnsupportedRecord;

package/fjs/asn.1/types.js

@@ -0,0 +1,6 @@
+/**
+ * Types for ASN.1 BER/DER encoding and decoding over bit vectors.
+ *
+ * @module
+ */
+export {};

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

@@ -0,0 +1,37 @@
+/**
+ * Assertion helpers for runtime checks and compile-time type-level tests.
+ *
+ * @module
+ */
+/**
+ * Marks a code path as unimplemented. Always throws.
+ * @type {() => never}
+ */
+export declare const todo: () => never;
+/**
+ * Throws `msg` (default `'assertion failed'`) if `v` is `false`.
+ *
+ * Narrows `v` to `true` via `asserts v`, so callers can rely on the
+ * condition holding for the rest of the enclosing scope.
+ *
+ * @type {(v: boolean, msg?: unknown) => asserts v}
+ */
+export declare const assert: (v: boolean, msg?: unknown) => asserts v;
+/**
+ * Asserts that `a` and `b` are `===`, throwing `x` (the `[a, b]` pair, plus
+ * an optional third element used as an extra message) if they differ.
+ *
+ * @type {<T>(...x: readonly[T, T, unknown?]) => void}
+ */
+export declare const assertEq: <T>(...x: readonly [T, T, unknown?]) => void;
+/**
+ * Asserts that `a` is neither `null` nor `undefined` and returns it,
+ * narrowed to `T`.
+ *
+ * Use this to chain directly off a call that may return a nullish value,
+ * e.g. `const r = assertNotNullish(f(x))`. For a variable that already
+ * exists, prefer `assert(a !== null && a !== undefined)` instead.
+ *
+ * @type {<T>(a: T|null|undefined, msg?: unknown) => T}
+ */
+export declare const assertNotNullish: <T>(a: T | null | undefined, msg?: unknown) => T;

package/fjs/asserts/module.f.mjs

@@ -0,0 +1,49 @@
+/**
+ * Assertion helpers for runtime checks and compile-time type-level tests.
+ *
+ * @module
+ */
+
+/**
+ * Marks a code path as unimplemented. Always throws.
+ * @type {() => never}
+ */
+export const todo = () => { throw 'not implemented' }
+
+/**
+ * Throws `msg` (default `'assertion failed'`) if `v` is `false`.
+ *
+ * Narrows `v` to `true` via `asserts v`, so callers can rely on the
+ * condition holding for the rest of the enclosing scope.
+ *
+ * @type {(v: boolean, msg?: unknown) => asserts v}
+ */
+export const assert = (v, msg = 'assertion failed') => {
+    if (!v) throw msg
+}
+
+/**
+ * Asserts that `a` and `b` are `===`, throwing `x` (the `[a, b]` pair, plus
+ * an optional third element used as an extra message) if they differ.
+ *
+ * @type {<T>(...x: readonly[T, T, unknown?]) => void}
+ */
+export const assertEq = (...x) => {
+    const [a, b] = x
+    assert(a === b, x)
+}
+
+/**
+ * Asserts that `a` is neither `null` nor `undefined` and returns it,
+ * narrowed to `T`.
+ *
+ * Use this to chain directly off a call that may return a nullish value,
+ * e.g. `const r = assertNotNullish(f(x))`. For a variable that already
+ * exists, prefer `assert(a !== null && a !== undefined)` instead.
+ *
+ * @type {<T>(a: T|null|undefined, msg?: unknown) => T}
+ */
+export const assertNotNullish = (a, msg) => {
+    assert(a !== null && a !== undefined, msg)
+    return a
+}

package/fjs/asserts/proof.f.mjs

@@ -0,0 +1,19 @@
+import { assert, assertEq, todo } from './module.f.mjs'
+
+export const proof = {
+    assertPassesOnTrue: () => {
+        assert(true)
+        assert(true, 'with message')
+    },
+    assertEqPassesOnEqual: () => {
+        assertEq(1, 1)
+        assertEq('x', 'x')
+    },
+    throw: {
+        assertEqThrowsOnUnequal: () => assertEq(1, 2),
+        assertEqThrowsOnUnequal3: () => assertEq(1, 2, "message"),
+        assertThrowsDefaultMsg: () => assert(false),
+        assertThrowsCustomMsg: () => assert(false, 'oops'),
+        todoThrows: () => todo(),
+    },
+}

package/fjs/asserts/types.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Type-level assertion helpers.
+ *
+ * @module
+ */
+/**
+ * Compile-time-only check: a type resolves only if it is exactly `true`.
+ * Used to assert type-level properties without any runtime cost, e.g.
+ * `type _ = Assert<Equal<A, B>>`.
+ */
+export type Assert<T extends true> = T;

package/fjs/asserts/types.js

@@ -0,0 +1,6 @@
+/**
+ * Type-level assertion helpers.
+ *
+ * @module
+ */
+export {};

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

@@ -0,0 +1,22 @@
+/**
+ * Base-128 encoding and decoding utilities over bit vectors.
+ *
+ * @module
+ *
+ * @import { Vec } from '../../types/bit_vec/types.ts'
+ */
+import type { Vec } from '../../types/bit_vec/types.ts';
+/**
+ * Encodes a bigint into an MSB Base128 vector.
+ *
+ * @param {bigint} uint The bigint to encode.
+ * @returns {Vec} The encoded MSB Base128 vector.
+ */
+export declare const encode: (uint: bigint) => Vec;
+/**
+ * Decodes an MSB Base128 vector into a bigint.
+ *
+ * @param {Vec} v The MSB Base128 vector to decode.
+ * @returns {readonly[bigint, Vec]} A tuple containing the decoded bigint and the remaining vector.
+ */
+export declare const decode: (v: Vec) => readonly [bigint, Vec];

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

@@ -0,0 +1,51 @@
+/**
+ * Base-128 encoding and decoding utilities over bit vectors.
+ *
+ * @module
+ *
+ * @import { Vec } from '../../types/bit_vec/types.ts'
+ */
+
+import { vec8, msb, empty } from '../../types/bit_vec/module.f.mjs'
+
+const { concat, popFront } = msb
+
+const pop8 = popFront(8n)
+
+/**
+ * Encodes a bigint into an MSB Base128 vector.
+ *
+ * @param {bigint} uint The bigint to encode.
+ * @returns {Vec} The encoded MSB Base128 vector.
+ */
+export const encode = uint => {
+    /** @type {Vec} */
+    let result = empty
+    while (true) {
+        const item = uint & 0x7Fn
+        const flag = result === empty ? 0n : 0x80n
+        result = concat(vec8(flag | item))(result)
+        uint >>= 7n
+        if (uint === 0n) {
+            return result
+        }
+    }
+}
+
+/**
+ * Decodes an MSB Base128 vector into a bigint.
+ *
+ * @param {Vec} v The MSB Base128 vector to decode.
+ * @returns {readonly[bigint, Vec]} A tuple containing the decoded bigint and the remaining vector.
+ */
+export const decode = v => {
+    let result = 0n
+    while (true) {
+        const [byte, rest] = pop8(v)
+        result = (result << 7n) | (byte & 0x7Fn)
+        if (byte < 0x80n) {
+            return [result, rest]
+        }
+        v = rest
+    }
+}

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

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

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

@@ -0,0 +1,30 @@
+/** @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,71 @@
+/**
+ * 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, maxLength } 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 }
+
+    if (length(head) + realBits > maxLength) { return null }
+
+    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))
+}