functionalscript 0.44.0 → 0.46.0

package/fjs/sul/proof.f.mjs

@@ -1,8 +1,11 @@
+/**
+ * @import { Id } from './id/types.ts'
+ * @import { Add } from './level/hash/types.ts'
+ */
+
 import { assert, assertEq } from '../asserts/module.f.mjs'
 import { compress } from './id/module.f.mjs'
-/** @import { Id } from './id/types.ts' */
 import { encode, emptyEncodeState } from './module.f.mjs'
-/** @import { Add } from './level/hash/types.ts' */
 
 /** @typedef {readonly [Id, Id, Id, boolean]} _Merge */
 

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

@@ -1,8 +1,16 @@
 /**
  * Provides ASCII code point constants and helpers for creating numeric code points and inclusive ranges.
  *
+ * It also owns the hexadecimal digit codec (`hexDigitValue` /
+ * `hexDigitCodePoint`), so no consumer has to rederive the `'0'`, `'a' - 10`
+ * and `'A' - 10` offsets for itself.
+ *
  * @module
+ *
+ * @import { Nullable } from '../../types/nullable/types.ts'
+ * @import { Range } from '../../types/range/types.ts'
  */
+import type { Nullable } from '../../types/nullable/types.ts';
 import type { Range } from '../../types/range/types.ts';
 /** Returns the code point value of the first character in a string. @type {(s: string) => number} */
 export declare const one: (s: string) => number;
@@ -94,6 +102,8 @@ export declare const latinCapitalLetterA: number;
 export declare const latinCapitalLetterE: number;
 /** 0x46 */
 export declare const latinCapitalLetterF: number;
+/** 0x41..0x46, the uppercase hexadecimal digits. */
+export declare const latinCapitalLetterAFRange: Range;
 /** 0x5B */
 export declare const leftSquareBracket: number;
 /** 0x5C */
@@ -116,6 +126,8 @@ export declare const latinSmallLetterB: number;
 export declare const latinSmallLetterE: number;
 /** 0x66 */
 export declare const latinSmallLetterF: number;
+/** 0x61..0x66, the lowercase hexadecimal digits. */
+export declare const latinSmallLetterAFRange: Range;
 /** 0x6E */
 export declare const latinSmallLetterN: number;
 /** 0x72 */
@@ -134,3 +146,17 @@ export declare const verticalLine: number;
 export declare const rightCurlyBracket: number;
 /** 0x7E */
 export declare const tilde: number;
+/**
+ * The value `0..15` denoted by a hexadecimal digit code point, or `null` when
+ * the code point is not one of `0-9`, `a-f`, `A-F`.
+ *
+ * @type {(codePoint: number) => Nullable<number>}
+ */
+export declare const hexDigitValue: (codePoint: number) => Nullable<number>;
+/**
+ * The lowercase hexadecimal digit code point denoting a value in `0..15`.
+ * `hexDigitValue(hexDigitCodePoint(v))` is `v` for every such value.
+ *
+ * @type {(value: number) => number}
+ */
+export declare const hexDigitCodePoint: (value: number) => number;

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

@@ -1,10 +1,17 @@
 /**
  * Provides ASCII code point constants and helpers for creating numeric code points and inclusive ranges.
  *
+ * It also owns the hexadecimal digit codec (`hexDigitValue` /
+ * `hexDigitCodePoint`), so no consumer has to rederive the `'0'`, `'a' - 10`
+ * and `'A' - 10` offsets for itself.
+ *
  * @module
+ *
+ * @import { Nullable } from '../../types/nullable/types.ts'
+ * @import { Range } from '../../types/range/types.ts'
  */
 
-/** @import { Range } from '../../types/range/types.ts' */
+import { contains } from '../../types/range/module.f.mjs'
 
 /** @type {(s: string) => (i: number) => number} */
 const at = s => i => {
@@ -161,6 +168,9 @@ export const latinCapitalLetterE = one('E')
 /** 0x46 */
 export const latinCapitalLetterF = one('F')
 
+/** 0x41..0x46, the uppercase hexadecimal digits. */
+export const latinCapitalLetterAFRange = range('AF')
+
 /** 0x5B */
 export const leftSquareBracket = one('[')
 
@@ -196,6 +206,9 @@ export const latinSmallLetterE = one('e')
 /** 0x66 */
 export const latinSmallLetterF = one('f')
 
+/** 0x61..0x66, the lowercase hexadecimal digits. */
+export const latinSmallLetterAFRange = range('af')
+
 /** 0x6E */
 export const latinSmallLetterN = one('n')
 
@@ -222,3 +235,38 @@ export const rightCurlyBracket = one('}')
 
 /** 0x7E */
 export const tilde = one('~')
+
+// hexadecimal digits
+
+const isDigit = contains(...digitRange)
+
+const isLatinSmallLetterAF = contains(...latinSmallLetterAFRange)
+
+const isLatinCapitalLetterAF = contains(...latinCapitalLetterAFRange)
+
+/** The distance from a lowercase hexadecimal letter to the value it denotes. */
+const latinSmallLetterAFOffset = latinSmallLetterA - 10
+
+/** The distance from an uppercase hexadecimal letter to the value it denotes. */
+const latinCapitalLetterAFOffset = latinCapitalLetterA - 10
+
+/**
+ * The value `0..15` denoted by a hexadecimal digit code point, or `null` when
+ * the code point is not one of `0-9`, `a-f`, `A-F`.
+ *
+ * @type {(codePoint: number) => Nullable<number>}
+ */
+export const hexDigitValue = codePoint =>
+    isDigit(codePoint) ? codePoint - digit0
+        : isLatinSmallLetterAF(codePoint) ? codePoint - latinSmallLetterAFOffset
+            : isLatinCapitalLetterAF(codePoint) ? codePoint - latinCapitalLetterAFOffset
+                : null
+
+/**
+ * The lowercase hexadecimal digit code point denoting a value in `0..15`.
+ * `hexDigitValue(hexDigitCodePoint(v))` is `v` for every such value.
+ *
+ * @type {(value: number) => number}
+ */
+export const hexDigitCodePoint = value =>
+    value < 10 ? digit0 + value : latinSmallLetterAFOffset + value

package/fjs/text/ascii/proof.f.d.mts

@@ -1,5 +1,15 @@
 export declare const proof: {
     range: () => void;
+    hexDigitValue: {
+        digit: () => void;
+        latinSmallLetterAF: () => void;
+        latinCapitalLetterAF: () => void;
+        notAHexDigit: () => void;
+    };
+    hexDigitCodePoint: {
+        lowercaseDigits: () => void;
+        roundTrip: () => void;
+    };
     throw: {
         oneThrowsOnEmpty: () => number;
     };

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

@@ -1,15 +1,47 @@
-import { one, range } from './module.f.mjs'
+import { hexDigitCodePoint, hexDigitValue, one, range } from './module.f.mjs'
 import { stringify as jsonStringify } from '../../media/json/module.f.mjs'
 import { sort } from '../../types/object/module.f.mjs'
 import { assertEq } from '../../asserts/module.f.mjs'
 
 const stringify = jsonStringify(sort)
 
+const values = [0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15]
+
 export const proof = {
     range: () => {
         const r = stringify(range("A"))
         assertEq(r, '[65,65]')
     },
+    hexDigitValue: {
+        digit: () => {
+            assertEq(hexDigitValue(one('0')), 0)
+            assertEq(hexDigitValue(one('9')), 9)
+        },
+        latinSmallLetterAF: () => {
+            assertEq(hexDigitValue(one('a')), 10)
+            assertEq(hexDigitValue(one('f')), 15)
+        },
+        latinCapitalLetterAF: () => {
+            assertEq(hexDigitValue(one('A')), 10)
+            assertEq(hexDigitValue(one('F')), 15)
+        },
+        notAHexDigit: () => {
+            assertEq(hexDigitValue(one('/')), null)
+            assertEq(hexDigitValue(one(':')), null)
+            assertEq(hexDigitValue(one('@')), null)
+            assertEq(hexDigitValue(one('G')), null)
+            assertEq(hexDigitValue(one('`')), null)
+            assertEq(hexDigitValue(one('g')), null)
+        },
+    },
+    hexDigitCodePoint: {
+        lowercaseDigits: () => {
+            assertEq(String.fromCodePoint(...values.map(v => hexDigitCodePoint(v))), '0123456789abcdef')
+        },
+        roundTrip: () => {
+            assertEq(stringify(values.map(v => hexDigitValue(hexDigitCodePoint(v)))), stringify(values))
+        },
+    },
     throw: {
         oneThrowsOnEmpty: () => one(''),
     },

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

@@ -2,11 +2,14 @@
  * Shared Unicode code-point contract for the UTF-8 and UTF-16 decoders: the
  * error-tag mask used to flag invalid sequences, the streaming `decoder`
  * factory that wraps a per-unit step and an end-of-input step into a single
- * `List`-to-`List` conversion, and the code-point classification predicates
- * (BMP / surrogate / supplementary-plane / overall validity) that both codecs
- * share.
+ * `List`-to-`List` conversion, the `eofFlush` factory that builds that
+ * end-of-input step, and the code-point classification predicates (BMP /
+ * surrogate / supplementary-plane / overall validity) that both codecs share.
  *
  * @module
+ *
+ * @import { List } from '../../types/list/types.ts'
+ * @import { StateScan } from '../../types/function/operator/types.ts'
  */
 import type { List } from '../../types/list/types.ts';
 import type { StateScan } from '../../types/function/operator/types.ts';
@@ -31,6 +34,29 @@ export declare const errorMask = 2147483648;
  * @returns {(input: List<Unit>) => List<Cp>} A function converting a list of code units into a list of code points.
  */
 export declare const decoder: <Unit, S, Cp>(byteOp: StateScan<Unit, S | null, List<Cp>>, eofOp: (state: S | null) => readonly [List<Cp>, S | null]) => (input: List<Unit>) => List<Cp>;
+/**
+ * Builds the end-of-input step {@link decoder} needs, from the one function
+ * that differs between codecs.
+ *
+ * The flush contract is the same for every decoder: leftover state at the end
+ * of the input becomes **exactly one** error unit and the state resets to
+ * empty (`null`); with no leftover state nothing is emitted. Only the mapping
+ * from a non-empty state to its error unit is codec-specific.
+ *
+ * @template S
+ * @template Cp
+ * @param {(state: S) => Cp} toError - Turns a non-empty leftover state into a single error unit.
+ * @returns {(state: S | null) => readonly [List<Cp>, S | null]} The end-of-input step.
+ */
+export declare const eofFlush: <S, Cp>(toError: (state: S) => Cp) => (state: S | null) => readonly [List<Cp>, S | null];
+/**
+ * The last code point of the Basic Multilingual Plane. Exported because the
+ * UTF-8 encoder needs the boundary itself — its 3-byte form covers the BMP up
+ * to here — where the predicates below only answer membership. `maxCodePoint`
+ * stays private: `isSupplementaryPlane` already expresses the one range a
+ * caller has wanted it for.
+ */
+export declare const bmpMax = /** @type {const} */ 65535;
 /**
  * Checks whether the 16-bit word (U16) is a high surrogate.
  * Range: 0xD800 - 0xDBFF.

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

@@ -2,18 +2,17 @@
  * Shared Unicode code-point contract for the UTF-8 and UTF-16 decoders: the
  * error-tag mask used to flag invalid sequences, the streaming `decoder`
  * factory that wraps a per-unit step and an end-of-input step into a single
- * `List`-to-`List` conversion, and the code-point classification predicates
- * (BMP / surrogate / supplementary-plane / overall validity) that both codecs
- * share.
+ * `List`-to-`List` conversion, the `eofFlush` factory that builds that
+ * end-of-input step, and the code-point classification predicates (BMP /
+ * surrogate / supplementary-plane / overall validity) that both codecs share.
  *
  * @module
+ *
+ * @import { List } from '../../types/list/types.ts'
+ * @import { StateScan } from '../../types/function/operator/types.ts'
  */
 
-import { flat, stateScan } from '../../types/list/module.f.mjs'
-/** @import { List } from '../../types/list/types.ts' */
-
-/** @import { StateScan } from '../../types/function/operator/types.ts' */
-
+import { empty, flat, stateScan } from '../../types/list/module.f.mjs'
 import { contains } from '../../types/range/module.f.mjs'
 
 //
@@ -50,6 +49,23 @@ export const decoder = (
     return input => flat(run(flat(/** @type {List<List<Unit|null>>} */([input, [null]]))))
 }
 
+/**
+ * Builds the end-of-input step {@link decoder} needs, from the one function
+ * that differs between codecs.
+ *
+ * The flush contract is the same for every decoder: leftover state at the end
+ * of the input becomes **exactly one** error unit and the state resets to
+ * empty (`null`); with no leftover state nothing is emitted. Only the mapping
+ * from a non-empty state to its error unit is codec-specific.
+ *
+ * @template S
+ * @template Cp
+ * @param {(state: S) => Cp} toError - Turns a non-empty leftover state into a single error unit.
+ * @returns {(state: S | null) => readonly [List<Cp>, S | null]} The end-of-input step.
+ */
+export const eofFlush = toError => state =>
+    [state === null ? empty : [toError(state)], null]
+
 /**
  * Unicode code-point classification boundaries. The surrogate block
  * (`0xD800`–`0xDFFF`) splits into a high half (`0xD800`–`0xDBFF`) and a low half
@@ -60,7 +76,14 @@ export const decoder = (
 const surrogateMin = /** @type {const} */ 0xd800
 const lowSurrogateMin = /** @type {const} */ 0xdc00
 const surrogateMax = /** @type {const} */ 0xdfff
-const bmpMax = /** @type {const} */ 0xffff
+/**
+ * The last code point of the Basic Multilingual Plane. Exported because the
+ * UTF-8 encoder needs the boundary itself — its 3-byte form covers the BMP up
+ * to here — where the predicates below only answer membership. `maxCodePoint`
+ * stays private: `isSupplementaryPlane` already expresses the one range a
+ * caller has wanted it for.
+ */
+export const bmpMax = /** @type {const} */ 0xffff
 const maxCodePoint = /** @type {const} */ 0x10_ffff
 
 /**

package/fjs/text/code_point/proof.f.d.mts

@@ -1,7 +1,9 @@
 export declare const proof: {
+    eofFlush: (() => void)[];
     isHighSurrogate: (() => void)[];
     isLowSurrogate: (() => void)[];
     isBmpCodePoint: (() => void)[];
+    bmpMax: (() => void)[];
     isSupplementaryPlane: (() => void)[];
     isValidCodePoint: (() => void)[];
     isTextCodePoint: (() => void)[];

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

@@ -1,4 +1,8 @@
+import { assertEq } from '../../asserts/module.f.mjs'
+import { toArray } from '../../types/list/module.f.mjs'
 import {
+    bmpMax,
+    eofFlush,
     isBmpCodePoint,
     isHighSurrogate,
     isLowSurrogate,
@@ -12,7 +16,32 @@ const check = (actual, expected) => {
     if (actual !== expected) { throw `${actual} !== ${expected}` }
 }
 
+/**
+ * A stand-in for a codec's state-to-error function.
+ *
+ * @type {(state: number) => number}
+ */
+const negate = state => -state
+
+const flush = eofFlush(negate)
+
 export const proof = {
+    eofFlush: [
+        // no leftover state: nothing is flushed, the state stays empty
+        () => {
+            const [out, next] = flush(null)
+            assertEq(toArray(out).length, 0)
+            assertEq(next, null)
+        },
+        // leftover state: exactly one error unit, then the state resets
+        () => {
+            const [out, next] = flush(42)
+            const [first, ...rest] = toArray(out)
+            assertEq(first, -42)
+            assertEq(rest.length, 0)
+            assertEq(next, null)
+        },
+    ],
     isHighSurrogate: [
         () => check(isHighSurrogate(0xd800), true),
         () => check(isHighSurrogate(0xdbff), true),
@@ -36,6 +65,16 @@ export const proof = {
         () => check(isBmpCodePoint(0xd800), false),
         () => check(isBmpCodePoint(0x10000), false),
     ],
+    bmpMax: [
+        // The exported boundary and the predicates derived from it must agree:
+        // `bmpMax` is the last BMP code point, and the next one starts the
+        // supplementary planes. This is the pairing the UTF-8 encoder relies
+        // on to split its 3-byte and 4-byte forms.
+        () => check(isBmpCodePoint(bmpMax), true),
+        () => check(isSupplementaryPlane(bmpMax), false),
+        () => check(isSupplementaryPlane(bmpMax + 1), true),
+        () => check(isBmpCodePoint(bmpMax + 1), false),
+    ],
     isSupplementaryPlane: [
         () => check(isSupplementaryPlane(0x10000), true),
         () => check(isSupplementaryPlane(0x10ffff), true),

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

@@ -4,12 +4,14 @@
  * strings and MSB-first UTF-8 bit vectors.
  *
  * @module
+ *
+ * @import { List } from '../types/list/types.ts'
+ * @import { Nullable } from '../types/nullable/types.ts'
+ * @import { Block, Item, Utf8 } from './types.ts'
  */
 import type { List } from '../types/list/types.ts';
 import type { Nullable } from '../types/nullable/types.ts';
 import type { Block, Utf8 } from './types.ts';
-/** @import { Nullable } from '../types/nullable/types.ts' */
-/** @import { Block, Item, Utf8 } from './types.ts' */
 /** @type {(indent: string) => (text: Block) => List<string>} */
 export declare const flat: (indent: string) => (text: Block) => List<string>;
 /**

package/fjs/text/module.f.mjs

@@ -4,16 +4,17 @@
  * strings and MSB-first UTF-8 bit vectors.
  *
  * @module
+ *
+ * @import { List } from '../types/list/types.ts'
+ * @import { Nullable } from '../types/nullable/types.ts'
+ * @import { Block, Item, Utf8 } from './types.ts'
  */
 
 import { msb, tryU8ListToVec, u8List } from '../types/bit_vec/module.f.mjs'
 import { flatMap } from '../types/list/module.f.mjs'
-/** @import { List } from '../types/list/types.ts' */
 import { fromCodePointList, toCodePointList } from './utf8/module.f.mjs'
 import { stringToCodePointList, codePointListToString } from './utf16/module.f.mjs'
 import { mapUnwrap } from '../types/nullable/module.f.mjs'
-/** @import { Nullable } from '../types/nullable/types.ts' */
-/** @import { Block, Item, Utf8 } from './types.ts' */
 
 /** @type {(indent: string) => (text: Block) => List<string>} */
 export const flat = indent => {

package/fjs/text/proof.f.d.mts

@@ -1,3 +1,6 @@
+/**
+ * @import { Block } from './types.ts'
+ */
 export declare const proof: {
     block: () => void;
     encoding: () => void;

package/fjs/text/proof.f.mjs

@@ -1,5 +1,8 @@
+/**
+ * @import { Block } from './types.ts'
+ */
+
 import { assertEq, assertNotNullish } from '../asserts/module.f.mjs'
-/** @import { Block } from './types.ts' */
 import { flat, utf8, utf8ToString, tryUtf8 } from './module.f.mjs'
 import { join } from '../types/string/module.f.mjs'
 import { empty, maxLengthBytes } from '../types/bit_vec/module.f.mjs'

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

@@ -5,11 +5,12 @@
  * See `./types.ts` for the type-level API.
  *
  * @module
+ *
+ * @import { Console, Write, WriteConsoles, NodeProgramOptions } from '../../effects/node/types.ts'
+ * @import { Stdout, WriteText, CsiConsole } from './types.ts'
  */
-import type { Write, WriteConsoles, NodeProgramOptions } from '../../effects/node/types.ts';
-import type { Effect } from '../../effects/types.ts';
+import type { Console, WriteConsoles, NodeProgramOptions } from '../../effects/node/types.ts';
 import type { Stdout, WriteText } from './types.ts';
-/** @import { Stdout, WriteText, CsiConsole } from './types.ts' */
 /** @type {string} */
 export declare const backspace: string;
 export type _End = 'm';
@@ -53,6 +54,6 @@ export declare const createConsoleText: (stdout: Stdout) => WriteText;
  * stream is not a TTY, then encodes to UTF-8 and emits a `Write` effect.
  * Does NOT append `\n` — callers are responsible for line termination.
  *
- * @type {(options: NodeProgramOptions) => (stream: WriteConsoles) => (s: string) => Effect<Write, void>}
+ * @type {(options: NodeProgramOptions) => (stream: WriteConsoles) => Console}
  */
-export declare const csiWrite: (options: NodeProgramOptions) => (stream: WriteConsoles) => (s: string) => Effect<Write, void>;
+export declare const csiWrite: (options: NodeProgramOptions) => (stream: WriteConsoles) => Console;

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

@@ -5,16 +5,16 @@
  * See `./types.ts` for the type-level API.
  *
  * @module
+ *
+ * @import { Console, Write, WriteConsoles, NodeProgramOptions } from '../../effects/node/types.ts'
+ * @import { Stdout, WriteText, CsiConsole } from './types.ts'
  */
 
 // C0 control codes
 // https://en.wikipedia.org/wiki/ANSI_escape_code#C0_control_codes
 
 import { write } from '../../effects/node/module.f.mjs'
-/** @import { Write, WriteConsoles, NodeProgramOptions } from '../../effects/node/types.ts' */
-/** @import { Effect } from '../../effects/types.ts' */
 import { utf8 } from "../module.f.mjs"
-/** @import { Stdout, WriteText, CsiConsole } from './types.ts' */
 
 /** @type {string} */
 export const backspace = '\x08'
@@ -48,13 +48,13 @@ export const csi = end => code =>
 export const sgr = csi('m')
 
 /** Resets all SGR styles to terminal defaults. */
-export const reset = /** @type {string} */ (sgr(0))
+export const reset = sgr(0)
 /** Enables bold/intense text rendering when supported by the terminal. */
-export const bold = /** @type {string} */ (sgr(1))
+export const bold = sgr(1)
 /** Applies red foreground color to subsequent text. */
-export const fgRed = /** @type {string} */ (sgr(31))
+export const fgRed = sgr(31)
 /** Applies green foreground color to subsequent text. */
-export const fgGreen = /** @type {string} */ (sgr(32))
+export const fgGreen = sgr(32)
 
 const { max } = Math
 
@@ -91,7 +91,7 @@ const str = isTTY => s =>
  * stream is not a TTY, then encodes to UTF-8 and emits a `Write` effect.
  * Does NOT append `\n` — callers are responsible for line termination.
  *
- * @type {(options: NodeProgramOptions) => (stream: WriteConsoles) => (s: string) => Effect<Write, void>}
+ * @type {(options: NodeProgramOptions) => (stream: WriteConsoles) => Console}
  */
 export const csiWrite = ({ std }) => stream => {
     const toStr = str(std[stream].isTTY)

package/fjs/text/sgr/proof.f.d.mts

@@ -1 +1,4 @@
+/**
+ * @import { NodeProgramOptions } from '../../effects/node/types.ts'
+ */
 export declare const proof: (() => void)[];

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

@@ -1,6 +1,9 @@
+/**
+ * @import { NodeProgramOptions } from '../../effects/node/types.ts'
+ */
+
 import { fgRed, reset, createConsoleText, backspace, csiWrite } from './module.f.mjs'
 import { virtual, emptyState, defaultNodeProgramOptions } from '../../effects/node/virtual/module.f.mjs'
-/** @import { NodeProgramOptions } from '../../effects/node/types.ts' */
 import { assert, assertEq } from '../../asserts/module.f.mjs'
 
 /** @type {(isTTY: boolean) => NodeProgramOptions} */

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

@@ -4,10 +4,14 @@
  * `stateScan` operations.
  *
  * @module
+ *
+ * @import { List, Result, Thunk } from '../../types/list/types.ts'
+ * @import { StateScan } from '../../types/function/operator/types.ts'
+ * @import { CodePoint, U16 } from './types.ts'
  */
 import type { List, Thunk } from '../../types/list/types.ts';
-export type _Utf16State = number | null;
 import type { CodePoint, U16 } from './types.ts';
+export type _Utf16State = number | null;
 /**
  * Converts a UTF-16 sequence to its corresponding Unicode code points.
  *