functionalscript 0.43.1 → 0.44.0

package/fjs/text/utf8/module.f.d.mts

@@ -0,0 +1,69 @@
+/**
+ * UTF-8 byte-level encoding and decoding utilities for FunctionalScript streams.
+ *
+ * @module
+ */
+import type { List, Thunk } from '../../types/list/types.ts';
+import type { StateScan } from '../../types/function/operator/types.ts';
+import type { Vec } from '../../types/bit_vec/types.ts';
+import type { I32, U8, Utf8NonEmptyState, Utf8State } from './types.ts';
+/**
+ * Maps a list of Unicode code points to a stream of UTF-8 bytes.
+ *
+ * @param input - A list of Unicode code points to be converted.
+ * @returns A thunk that lazily produces a sequence of UTF-8 bytes.
+ *
+ * @type {(input: List<number>) => Thunk<U8>}
+ */
+export declare const fromCodePointList: (input: List<number>) => Thunk<U8>;
+/**
+ * Converts a non-empty UTF-8 decoding state to an error code.
+ *
+ * @param {Utf8NonEmptyState} state A non-empty UTF-8 decoding state.
+ * @returns {I32} An I32 error code derived from the invalid UTF-8 state.
+ */
+export declare const utf8StateToError: (state: Utf8NonEmptyState) => I32;
+/**
+ * Decodes a byte into a Unicode code point, using a given UTF-8 state.
+ *
+ * Rejects overlong 3-/4-byte encodings (Unicode Table 3-7): a lead `E0` must
+ * be followed by a continuation `>= 0xA0`, and a lead `F0` by a continuation
+ * `>= 0x90`. It does not itself reject surrogates (`ED A0..BF`) or code
+ * points above `U+10FFFF` (`F4 90..BF`); {@link fromVec}'s
+ * `isValidCodePoint` pass filters those out of the raw code-point stream.
+ *
+ * @param state - The current UTF-8 decoding state.
+ * @param byte - A single byte to decode.
+ * @returns A tuple containing:
+ *   - A list of decoded Unicode code points or error codes.
+ *   - The updated UTF-8 state.
+ *
+ * @type {StateScan<number, Utf8State, readonly I32[]>}
+ */
+export declare const utf8ByteToCodePointOp: StateScan<number, Utf8State, readonly I32[]>;
+/**
+ * Handles the end-of-file (EOF) case for UTF-8 decoding.
+ *
+ * @param {Utf8State} state The current UTF-8 decoding state.
+ * @returns {readonly [List<I32>, Utf8State]} A tuple containing:
+ *   - A list of decoded Unicode code points or error codes.
+ *   - The reset UTF-8 state (`null`).
+ */
+export declare const utf8EofToCodePointOp: (state: Utf8State) => readonly [List<I32>, Utf8State];
+/**
+ * Converts a list of UTF-8 bytes into a list of Unicode code points.
+ *
+ * @param input - A list of UTF-8 bytes.
+ * @returns A list of Unicode code points or error codes.
+ *
+ * @type {(input: List<U8>) => List<I32>}
+ */
+export declare const toCodePointList: (input: List<U8>) => List<I32>;
+/**
+ * Returns the decoded string if `v` is valid UTF-8, or `null` otherwise.
+ * Rejects non-octet Vecs, invalid byte sequences, surrogates, and out-of-range
+ * code points.
+ *
+ * @type {(v: Vec) => string | null}
+ */
+export declare const fromVec: (v: Vec) => string | null;

package/fjs/text/utf8/module.f.mjs

@@ -0,0 +1,280 @@
+/**
+ * UTF-8 byte-level encoding and decoding utilities for FunctionalScript streams.
+ *
+ * @module
+ */
+
+import { flatMap, toArray } from '../../types/list/module.f.mjs'
+/** @import { List, Thunk } from '../../types/list/types.ts' */
+/** @import { StateScan } from '../../types/function/operator/types.ts' */
+import { decoder, errorMask, isValidCodePoint } from '../code_point/module.f.mjs'
+import { msb, u8List, length } from '../../types/bit_vec/module.f.mjs'
+/** @import { Vec } from '../../types/bit_vec/types.ts' */
+import { codePointListToString } from '../utf16/module.f.mjs'
+/**
+ * @import {
+ *  ByteOrEof, I32, U8, Utf8NonEmptyState, Utf8State,
+ * } from './types.ts'
+ */
+
+/**
+ * UTF-8 byte-format constants. Each byte kind is defined by a tag — the fixed
+ * high bits identifying the kind — and a payload mask selecting the code-point
+ * bits the byte carries. The encoder and the decoder are exact inverses, so
+ * both read their bit patterns from this single set of definitions:
+ *
+ * | byte kind   | pattern      | tag       | payload mask |
+ * |-------------|--------------|-----------|--------------|
+ * | continuation| `10xx_xxxx`  | `contTag` | `contMask`   |
+ * | 2-byte lead | `110x_xxxx`  | `lead2Tag`| `lead2Mask`  |
+ * | 3-byte lead | `1110_xxxx`  | `lead3Tag`| `lead3Mask`  |
+ * | 4-byte lead | `1111_0xxx`  | `lead4Tag`| `lead4Mask`  |
+ */
+const contTag = 0b1000_0000
+const contMask = 0b0011_1111
+const lead2Tag = 0b1100_0000
+const lead2Mask = 0b0001_1111
+const lead3Tag = 0b1110_0000
+const lead3Mask = 0b0000_1111
+const lead4Tag = 0b1111_0000
+const lead4Mask = 0b0000_0111
+
+/**
+ * Encodes the low six bits of `x` as a UTF-8 continuation byte.
+ *
+ * @type {(x: number) => number}
+ */
+const contByte = x => x & contMask | contTag
+
+/**
+ * Reads the six payload bits of a continuation byte.
+ *
+ * @type {(b: number) => number}
+ */
+const contPayload = b => b & contMask
+
+/**
+ * The valid lead-byte range for 2-, 3-, and 4-byte sequences (RFC 3629);
+ * excludes overlong 2-byte leads (`C0`, `C1`) and leads above `U+10FFFF` (`F5`-`F7`).
+ */
+const leadMin = 0b1100_0010
+const leadMax = 0b1111_0100
+/** @type {(b: number) => boolean} */
+const isLeadByte = b => b >= leadMin && b <= leadMax
+
+/**
+ * Dispatches a fresh-state byte, emitting `prefix` ahead of whatever the byte
+ * itself produces. Shared by the `state === null` arm and by error recovery
+ * after {@link utf8StateToError}, which differ only in `prefix`.
+ *
+ * @type {(prefix: readonly I32[]) => (byte: number) => readonly [readonly I32[], Utf8State]}
+ */
+const restart = prefix =>
+    byte =>
+        byte < contTag ? [[...prefix, byte], null]
+        : isLeadByte(byte) ? [[...prefix], [byte]]
+        : [[...prefix, byte | errorMask], null]
+
+/**
+ * Converts a Unicode code point to a sequence of UTF-8 bytes.
+ * @param {number} input The Unicode code point to be converted. Valid range:
+ *   - 0x0000 to 0x007F for 1-byte sequences.
+ *   - 0x0080 to 0x07FF for 2-byte sequences.
+ *   - 0x0800 to 0xFFFF for 3-byte sequences.
+ *   - 0x10000 to 0x10FFFF for 4-byte sequences.
+ * @returns {readonly U8[]} A readonly array of UTF-8 bytes representing the input code point.
+ *   - Returns `[errorMask]` if the input does not match valid UTF-8 encoding rules.
+ */
+const codePointToUtf8 = input => {
+    if (input >= 0x0000 && input <= 0x007f) {
+        return [input & 0b01111_1111]
+    }
+    if (input >= 0x0080 && input <= 0x07ff) {
+        return [input >> 6 | lead2Tag, contByte(input)]
+    }
+    if (input >= 0x0800 && input <= 0xffff) {
+        return [
+            input >> 12 | lead3Tag,
+            contByte(input >> 6),
+            contByte(input),
+        ]
+    }
+    if (input >= 0x10000 && input <= 0x10ffff) {
+        return [
+            input >> 18 | lead4Tag,
+            contByte(input >> 12),
+            contByte(input >> 6),
+            contByte(input),
+        ]
+    }
+    if ((input & errorMask) !== 0) {
+        if ((input & 0b1000_0000_0000_0000) !== 0) {
+            return [
+                input >> 12 & lead4Mask | lead4Tag,
+                contByte(input >> 6),
+                contByte(input),
+            ]
+        }
+        if ((input & 0b0000_0100_0000_0000) !== 0) {
+            return [
+                input >> 6 & lead3Mask | lead3Tag,
+                contByte(input),
+            ]
+        }
+        if ((input & 0b0000_0010_0000_0000) !== 0) {
+            return [
+                input >> 6 & lead4Mask | lead4Tag,
+                contByte(input),
+            ]
+        }
+        if ((input & 0b0000_0000_1000_0000) !== 0) return [input & 0b1111_1111]
+    }
+    return [errorMask]
+}
+
+/**
+ * Maps a list of Unicode code points to a stream of UTF-8 bytes.
+ *
+ * @param input - A list of Unicode code points to be converted.
+ * @returns A thunk that lazily produces a sequence of UTF-8 bytes.
+ *
+ * @type {(input: List<number>) => Thunk<U8>}
+ */
+export const fromCodePointList = flatMap(
+    codePointToUtf8,
+)
+
+/**
+ * Converts a non-empty UTF-8 decoding state to an error code.
+ *
+ * @param {Utf8NonEmptyState} state A non-empty UTF-8 decoding state.
+ * @returns {I32} An I32 error code derived from the invalid UTF-8 state.
+ */
+export const utf8StateToError = state => {
+    let x
+    switch (state.length) {
+        case 1: {
+            [x] = state
+            break
+        }
+        case 2: {
+            const [s0, s1] = state
+            x = s0 < lead4Tag
+                ? ((s0 & lead3Mask) << 6) + contPayload(s1) + 0b0000_0100_0000_0000
+                : ((s0 & lead4Mask) << 6) + contPayload(s1) +
+                    0b0000_0010_0000_0000
+            break
+        }
+        case 3: {
+            const [s0, s1, s2] = state
+            x = ((s0 & lead4Mask) << 12) + (contPayload(s1) << 6) +
+                contPayload(s2) + 0b1000_0000_0000_0000
+            break
+        }
+        //default:
+        //    throw 'invalid state'
+    }
+    return x | errorMask
+}
+
+/**
+ * Decodes a byte into a Unicode code point, using a given UTF-8 state.
+ *
+ * Rejects overlong 3-/4-byte encodings (Unicode Table 3-7): a lead `E0` must
+ * be followed by a continuation `>= 0xA0`, and a lead `F0` by a continuation
+ * `>= 0x90`. It does not itself reject surrogates (`ED A0..BF`) or code
+ * points above `U+10FFFF` (`F4 90..BF`); {@link fromVec}'s
+ * `isValidCodePoint` pass filters those out of the raw code-point stream.
+ *
+ * @param state - The current UTF-8 decoding state.
+ * @param byte - A single byte to decode.
+ * @returns A tuple containing:
+ *   - A list of decoded Unicode code points or error codes.
+ *   - The updated UTF-8 state.
+ *
+ * @type {StateScan<number, Utf8State, readonly I32[]>}
+ */
+export const utf8ByteToCodePointOp = (byte, state) => {
+    if (byte < 0x00 || byte > 0xff) {
+        return [[errorMask], state]
+    }
+    if (state === null) return restart([])(byte)
+    if (byte >= contTag && byte < lead2Tag) {
+        switch (state.length) {
+            case 1: {
+                const [s0] = state
+                if (s0 < lead3Tag) {
+                    return [[((s0 & lead2Mask) << 6) + contPayload(byte)], null]
+                }
+                if (s0 < 0b1111_1000) {
+                    // Reject overlong 3-/4-byte encodings: after lead `E0` the
+                    // first continuation must be >= 0xA0, after lead `F0` it
+                    // must be >= 0x90 (Unicode Table 3-7).
+                    const overlong = s0 === lead3Tag && byte < 0b1010_0000 ||
+                        s0 === lead4Tag && byte < 0b1001_0000
+                    if (!overlong) return [[], [s0, byte]]
+                }
+                break
+            }
+            case 2: {
+                const [s0, s1] = state
+                if (s0 < lead4Tag) {
+                    return [[
+                        ((s0 & lead3Mask) << 12) + (contPayload(s1) << 6) +
+                        contPayload(byte),
+                    ], null]
+                }
+                if (s0 < 0b1111_1000) return [[], [s0, s1, byte]]
+                break
+            }
+            case 3: {
+                const [s0, s1, s2] = state
+                return [[
+                    ((s0 & lead4Mask) << 18) + (contPayload(s1) << 12) +
+                    (contPayload(s2) << 6) + contPayload(byte),
+                ], null]
+            }
+        }
+    }
+    return restart([utf8StateToError(state)])(byte)
+}
+
+/**
+ * Handles the end-of-file (EOF) case for UTF-8 decoding.
+ *
+ * @param {Utf8State} state The current UTF-8 decoding state.
+ * @returns {readonly [List<I32>, Utf8State]} A tuple containing:
+ *   - A list of decoded Unicode code points or error codes.
+ *   - The reset UTF-8 state (`null`).
+ */
+export const utf8EofToCodePointOp = state => [
+    state === null ? null : [utf8StateToError(state)],
+    null,
+]
+
+/**
+ * Converts a list of UTF-8 bytes into a list of Unicode code points.
+ *
+ * @param input - A list of UTF-8 bytes.
+ * @returns A list of Unicode code points or error codes.
+ *
+ * @type {(input: List<U8>) => List<I32>}
+ */
+export const toCodePointList =
+    decoder(utf8ByteToCodePointOp, utf8EofToCodePointOp)
+
+/**
+ * Returns the decoded string if `v` is valid UTF-8, or `null` otherwise.
+ * Rejects non-octet Vecs, invalid byte sequences, surrogates, and out-of-range
+ * code points.
+ *
+ * @type {(v: Vec) => string | null}
+ */
+export const fromVec = v => {
+    if ((length(v) & 0b111n) !== 0n) { return null }
+    const arr = toArray(toCodePointList(u8List(msb)(v)))
+    for (const cp of arr) {
+        if (!isValidCodePoint(cp)) { return null }
+    }
+    return codePointListToString(arr)
+}

package/fjs/text/utf8/proof.f.mjs

@@ -0,0 +1,217 @@
+import { toCodePointList, fromCodePointList, fromVec, utf8ByteToCodePointOp } from './module.f.mjs'
+import { stringify as jsonStringify } from '../../media/json/module.f.mjs'
+import { sort } from '../../types/object/module.f.mjs'
+import { toArray } from '../../types/list/module.f.mjs'
+import { msb, u8ListToVec, vec } from '../../types/bit_vec/module.f.mjs'
+import { assertEq } from '../../asserts/module.f.mjs'
+
+const stringify = jsonStringify(sort)
+
+export const proof = {
+    toCodePoint: [
+        () => {
+            const result = stringify(toArray(toCodePointList([-1, 256])))
+            assertEq(result, '[2147483648,2147483648]')
+        },
+        () => {
+            const result = stringify(toArray(toCodePointList([128, 193, 245, 255])))
+            assertEq(result, '[-2147483520,-2147483455,-2147483403,-2147483393]')
+        },
+        () => {
+            const result = stringify(toArray(toCodePointList([0, 1, 127])))
+            assertEq(result, '[0,1,127]')
+        },
+        () => {
+            const result = stringify(toArray(toCodePointList([194, 128, 194, 169, 223, 191])))
+            assertEq(result, '[128,169,2047]')
+        },
+        () => {
+            const result = stringify(toArray(toCodePointList([194, 194, 127, 194, 192, 194])))
+            assertEq(result, '[-2147483454,-2147483454,127,-2147483454,-2147483456,-2147483454]')
+        },
+        () => {
+            const result = stringify(toArray(toCodePointList([224, 160, 128, 224, 160, 129, 239, 191, 191])))
+            assertEq(result, '[2048,2049,65535]')
+        },
+        () => {
+            const result = stringify(toArray(toCodePointList([224, 224, 160, 127, 239, 191])))
+            assertEq(result, '[-2147483424,-2147482592,127,-2147481601]')
+        },
+        () => {
+            const result = stringify(toArray(toCodePointList([240, 144, 128, 128, 240, 144, 128, 129, 244, 143, 191, 191])))
+            assertEq(result, '[65536,65537,1114111]')
+        },
+        () => {
+            const result = stringify(toArray(toCodePointList([240, 240, 160, 127, 244, 191])))
+            assertEq(result, '[-2147483408,-2147483104,127,-2147482817]')
+        },
+        () => {
+            const result = stringify(toArray(toCodePointList([240, 160, 160, 244, 160, 160])))
+            assertEq(result, '[-2147448800,-2147432416]')
+        },
+        // Overlong 3-byte encodings (E0 80..9F ..) are rejected, not decoded.
+        () => {
+            const result = stringify(toArray(toCodePointList([224, 128, 128])))
+            assertEq(result, '[-2147483424,-2147483520,-2147483520]')
+        },
+        () => {
+            const result = stringify(toArray(toCodePointList([224, 159, 191])))
+            assertEq(result, '[-2147483424,-2147483489,-2147483457]')
+        },
+        // Overlong 4-byte encodings (F0 80..8F .. ..) are rejected, not decoded.
+        () => {
+            const result = stringify(toArray(toCodePointList([240, 128, 128, 128])))
+            assertEq(result, '[-2147483408,-2147483520,-2147483520,-2147483520]')
+        },
+        () => {
+            const result = stringify(toArray(toCodePointList([240, 143, 191, 191])))
+            assertEq(result, '[-2147483408,-2147483505,-2147483457,-2147483457]')
+        },
+        // Valid boundary cases still decode: E0 A0 80 -> U+0800, F0 90 80 80 -> U+10000.
+        () => {
+            const result = stringify(toArray(toCodePointList([224, 160, 128])))
+            assertEq(result, '[2048]')
+        },
+        () => {
+            const result = stringify(toArray(toCodePointList([240, 144, 128, 128])))
+            assertEq(result, '[65536]')
+        },
+        // A byte stream never accumulates a 2-byte state whose lead is >= F8
+        // (isLeadByte caps leads at F4), so this defensive fallthrough is
+        // only reachable by calling the scan op directly with such a state.
+        () => {
+            const result = stringify(utf8ByteToCodePointOp(0x80, [0xf8, 0x80]))
+            assertEq(result, '[[-2147483136,-2147483520],null]')
+        }
+    ],
+    fromCodePointList: [
+        () => {
+            const result = stringify(toArray(fromCodePointList([0, 1, 0x7F])))
+            assertEq(result, '[0,1,127]')
+        },
+        () => {
+            const result = stringify(toArray(fromCodePointList([0x80])))
+            assertEq(result, '[194,128]')
+        },
+        () => {
+            const result = stringify(toArray(fromCodePointList([0xa9])))
+            assertEq(result, '[194,169]')
+        },
+        () => {
+            const result = stringify(toArray(fromCodePointList([0x7ff])))
+            assertEq(result, '[223,191]')
+        },
+        () => {
+            const result = stringify(toArray(fromCodePointList([0x800])))
+            assertEq(result, '[224,160,128]')
+        },
+        () => {
+            const result = stringify(toArray(fromCodePointList([0x801])))
+            assertEq(result, '[224,160,129]')
+        },
+        () => {
+            const result = stringify(toArray(fromCodePointList([0xffff])))
+            assertEq(result, '[239,191,191]')
+        },
+        () => {
+            const result = stringify(toArray(fromCodePointList([0x10000])))
+            assertEq(result, '[240,144,128,128]')
+        },
+        () => {
+            const result = stringify(toArray(fromCodePointList([0x10001])))
+            assertEq(result, '[240,144,128,129]')
+        },
+        () => {
+            const result = stringify(toArray(fromCodePointList([0x10FFFF])))
+            assertEq(result, '[244,143,191,191]')
+        },
+        () => {
+            const result = stringify(toArray(fromCodePointList([0x110000, 2147483648])))
+            assertEq(result, '[2147483648,2147483648]')
+        }
+    ],
+    toFrom: [
+        () => {
+            const codePointList = toCodePointList([128, 193, 245, 255])
+            const result = stringify(toArray(fromCodePointList(codePointList)))
+            assertEq(result, '[128,193,245,255]')
+        },
+        () => {
+            const codePointList = toCodePointList([194, 194, 127, 194, 192, 194])
+            const result = stringify(toArray(fromCodePointList(codePointList)))
+            assertEq(result, '[194,194,127,194,192,194]')
+        },
+        () => {
+            const codePointList = toCodePointList([224, 224, 160, 127, 239, 191])
+            const result = stringify(toArray(fromCodePointList(codePointList)))
+            assertEq(result, '[224,224,160,127,239,191]')
+        },
+        () => {
+            const codePointList = toCodePointList([240, 240, 160, 127, 244, 191])
+            const result = stringify(toArray(fromCodePointList(codePointList)))
+            assertEq(result, '[240,240,160,127,244,191]')
+        },
+        () => {
+            const codePointList = toCodePointList([240, 160, 160, 244, 160, 160])
+            const result = stringify(toArray(fromCodePointList(codePointList)))
+            assertEq(result, '[240,160,160,244,160,160]')
+        }
+    ],
+    fromVec: [
+        // Valid ASCII → decoded string
+        () => {
+            const v = u8ListToVec(msb)([0x68, 0x65, 0x6c, 0x6c, 0x6f]) // "hello"
+            assertEq(fromVec(v), 'hello', 'expected "hello"')
+        },
+        // Valid multi-byte UTF-8 → decoded string (U+00A9 COPYRIGHT SIGN, 2-byte)
+        () => {
+            const v = u8ListToVec(msb)([0xc2, 0xa9]) // "©"
+            assertEq(fromVec(v), '©', 'expected copyright sign')
+        },
+        // Valid 3-byte UTF-8 (U+4E2D CJK)
+        () => {
+            const v = u8ListToVec(msb)([0xe4, 0xb8, 0xad]) // "中"
+            assertEq(fromVec(v), '中', 'expected CJK character')
+        },
+        // Valid 4-byte UTF-8 (U+1F600 GRINNING FACE)
+        () => {
+            const v = u8ListToVec(msb)([0xf0, 0x9f, 0x98, 0x80])
+            if (fromVec(v) !== '\u{1f600}') { throw 'expected emoji' }
+        },
+        // Invalid byte sequence → null
+        () => {
+            const v = u8ListToVec(msb)([0xff, 0xfe]) // not valid UTF-8
+            assertEq(fromVec(v), null, 'expected null for invalid UTF-8')
+        },
+        // Lone continuation byte → null
+        () => {
+            const v = u8ListToVec(msb)([0x80])
+            assertEq(fromVec(v), null, 'expected null for lone continuation byte')
+        },
+        // Surrogate half (U+D800, encoded as CESU-8 0xED 0xA0 0x80) → null
+        () => {
+            const v = u8ListToVec(msb)([0xed, 0xa0, 0x80])
+            assertEq(fromVec(v), null, 'expected null for surrogate')
+        },
+        // Empty Vec → empty string
+        () => {
+            const v = u8ListToVec(msb)([])
+            assertEq(fromVec(v), '', 'expected empty string')
+        },
+        // Overlong 3-byte encoding (E0 80 80, would decode to U+0000) → null
+        () => {
+            const v = u8ListToVec(msb)([0xe0, 0x80, 0x80])
+            assertEq(fromVec(v), null, 'expected null for overlong 3-byte encoding')
+        },
+        // Overlong 4-byte encoding (F0 80 80 80, would decode to U+0000) → null
+        () => {
+            const v = u8ListToVec(msb)([0xf0, 0x80, 0x80, 0x80])
+            assertEq(fromVec(v), null, 'expected null for overlong 4-byte encoding')
+        },
+        // Vec length not a multiple of 8 bits → null
+        () => {
+            const v = vec(4n)(0n)
+            assertEq(fromVec(v), null)
+        },
+    ]
+}

package/fjs/text/utf8/types.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Types for UTF-8 byte-level encoding and decoding.
+ *
+ * @module
+ */
+import type { Tuple } from '../../types/array/types.ts';
+/** An unsigned 8-bit integer, represents a single byte. */
+export type U8 = number;
+/** A singed 32-bit integer. */
+export type I32 = number;
+/**
+ * Represents an unsigned 8-bit type - U8 or the end-of-file indicator.
+ * The U8 represents the byte itself, and null indicates that reading does not
+ * return anything else.
+ */
+export type ByteOrEof = U8 | null;
+/**
+ * Represents the state of a UTF-8 decoding operation that contains at least one
+ * byte.
+ */
+export type Utf8NonEmptyState = Tuple<1, number> | Tuple<2, number> | Tuple<3, number>;
+/**
+ * Represents the state of a UTF-8 decoding operation, which can be either
+ * `null` (no state) or a non-empty state containing one or more bytes.
+ */
+export type Utf8State = null | Utf8NonEmptyState;

package/fjs/text/utf8/types.js

@@ -0,0 +1,6 @@
+/**
+ * Types for UTF-8 byte-level encoding and decoding.
+ *
+ * @module
+ */
+export {};

package/fjs/types/array/module.f.d.mts

@@ -0,0 +1,68 @@
+/**
+ * JavaScript immutable arrays.
+ *
+ * @module
+ */
+import type { Tuple } from './types.ts';
+/** @import { Tuple } from './types.ts' */
+/**
+ * @type {(value: unknown) => value is readonly unknown[]}
+ */
+export declare const isArray: (value: unknown) => value is readonly unknown[];
+/**
+ * Currently, TypeScript can't narrow the type of `readonly T[]` to `Array2<T>`
+ * only by checking `a.length === 2`, so we need a user-defined type guard.
+ */
+export declare const isTuple: <N extends number>(
+/**
+ * @template {number} N
+ * @param {N} n
+ */
+n: N) => <T>(
+/**
+ * @template T
+ * @param {readonly T[]} a An array of unknown length.
+ * @return {a is Tuple<N, T>} True if `a` has length 2, and `a` is narrowed to `Array2<T>` in that case.
+ */
+a: readonly T[]) => a is Tuple<N, T>;
+/**
+ * @type {(i: number) => <T>(a: readonly T[]) => T | null}
+ */
+export declare const at: (i: number) => <T>(a: readonly T[]) => T | null;
+export declare const first: <T>(a: readonly T[]) => T | null;
+/**
+ * @type {<T>(a: readonly T[]) => T | null}
+ */
+export declare const last: <T>(a: readonly T[]) => T | null;
+/**
+ * @type {<T>(a: readonly T[]) => readonly T[] | null}
+ */
+export declare const tail: <T>(a: readonly T[]) => readonly T[] | null;
+/**
+ * @type {<T>(a: readonly T[]) => readonly [T, readonly T[]] | null}
+ */
+export declare const splitFirst: <T>(a: readonly T[]) => readonly [T, readonly T[]] | null;
+/** @type {<T>(a: readonly T[]) => readonly T[] | null} */
+export declare const head: <T>(a: readonly T[]) => readonly T[] | null;
+/** @type {<T>(a: readonly T[]) => readonly [readonly T[], T] | null} */
+export declare const splitLast: <T>(a: readonly T[]) => readonly [readonly T[], T] | null;
+/**
+ * An empty immutable array.
+ *
+ * Two JavaScript empty arrays are different and has to have two different values.
+ * Usually, it requires memory allocation. If we use the same an empty array everywhere,
+ * we may minimize memory a number of memory allocations.
+ */
+export declare const empty: readonly [];
+export declare const includes: <I, T extends readonly I[]>(
+/**
+ * @template I
+ * @template {readonly I[]} T
+ * @param {T} a
+ */
+a: T) => (
+/**
+ * @param {I} v
+ * @return {v is T[number]}
+ */
+v: I) => v is T[number];