functionalscript 0.43.1 → 0.45.0

package/fjs/sul/level/literal/types.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Type-level API for the literal SUL level encoding.
+ *
+ * @module
+ */
+import type { Vec } from '../../../types/bit_vec/types.ts';
+import type { Func } from '../../../types/function/types.ts';
+import type { StateScan } from '../../../types/function/operator/types.ts';
+import type { List } from '../../../types/list/types.ts';
+export type Word = readonly bigint[];
+/**
+ * Streaming encoder state: `[last, part]`.
+ * - `last` — the most recently consumed input symbol, or `undefined` before any symbol is seen.
+ * - `part` — accumulated index offset from the decreasing prefix consumed so far.
+ */
+export type EncodeState = readonly [bigint | undefined, bigint];
+/**
+ * A literal SUL level with finite alphabet `[0, n)`.
+ */
+export type Level = {
+    /** Number of valid words whose first symbol is ≤ `i`. */
+    readonly sum: (i: bigint) => bigint;
+    /** Inverse of {@link Level.encode}: restores the complete word from a symbol. */
+    readonly decode: (i: bigint) => List<bigint>;
+    /** Streaming encoder: processes one input symbol at a time, emitting an output symbol only
+     *  when the terminating symbol `t >= last` arrives. */
+    readonly encode: StateScan<bigint, EncodeState, bigint | undefined>;
+};
+/** Combined encoder state for the three-level literal pipeline (L1 → L2 → L3). */
+export type PipelineState = readonly [EncodeState, EncodeState, EncodeState];
+export type LiteralToVec = Func<bigint, Vec>;

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

@@ -0,0 +1,27 @@
+/**
+ * Streaming encoder for the full SUL pipeline.
+ * Processes bits one at a time through literal levels L1→L2→L3, then through a dynamic array of hash levels.
+ * See `./types.ts` for the `EncodeState`/`Encode` type-level API.
+ *
+ * @module
+ *
+ * @import { Add } from './level/hash/types.ts'
+ * @import { Id } from './id/types.ts'
+ * @import { InternalState } from '../types/patricia_trie/types.ts'
+ * @import { EncodeState, Encode } from './types.ts'
+ */
+import type { Add } from './level/hash/types.ts';
+import type { Id } from './id/types.ts';
+import type { InternalState } from '../types/patricia_trie/types.ts';
+import type { EncodeState, Encode } from './types.ts';
+export type _HashState = InternalState<Id>;
+/** @typedef {InternalState<Id>} _HashState */
+/** @type {<S>(storage: S) => EncodeState<S>} */
+export declare const emptyEncodeState: <S>(storage: S) => EncodeState<S>;
+export declare const encode: <S>(
+/**
+ * @template S
+ * @param {Add<S>} add
+ * @returns {Encode<S>}
+ */
+add: Add<S>) => Encode<S>;

package/fjs/sul/module.f.mjs

@@ -0,0 +1,70 @@
+/**
+ * Streaming encoder for the full SUL pipeline.
+ * Processes bits one at a time through literal levels L1→L2→L3, then through a dynamic array of hash levels.
+ * See `./types.ts` for the `EncodeState`/`Encode` type-level API.
+ *
+ * @module
+ *
+ * @import { Add } from './level/hash/types.ts'
+ * @import { Id } from './id/types.ts'
+ * @import { InternalState } from '../types/patricia_trie/types.ts'
+ * @import { EncodeState, Encode } from './types.ts'
+ */
+
+import { emptyPipelineState, pipelineStep } from './level/literal/module.f.mjs'
+import { encode as hashEncode } from './level/hash/module.f.mjs'
+import { level3Id } from './id/module.f.mjs'
+
+/** @typedef {InternalState<Id>} _HashState */
+
+/** @type {<S>(storage: S) => EncodeState<S>} */
+export const emptyEncodeState = storage =>
+    [emptyPipelineState, storage, []]
+
+export const encode =
+    /**
+     * @template S
+     * @param {Add<S>} add
+     * @returns {Encode<S>}
+     */
+    add => {
+        const step = hashEncode(add)
+
+        /** @typedef {readonly [Id | undefined, S, readonly _HashState[]]} _CascadeResult */
+
+        /** @type {(id0: Id, storage0: S, stacks0: readonly _HashState[]) => _CascadeResult} */
+        const cascade = (id0, storage0, stacks0) => {
+            let id = id0, storage = storage0, stacks = stacks0
+            for (let index = 0; ; index++) {
+                if (index >= stacks.length) {
+                    const [, [newStorage, newStack]] = step(id, [storage, []])
+                    return [id, newStorage, [...stacks, newStack]]
+                }
+                const [out, [newStorage, newStack]] = step(id, [storage, stacks[index]])
+                stacks = [...stacks.slice(0, index), newStack, ...stacks.slice(index + 1)]
+                storage = newStorage
+                if (out === undefined) return [undefined, storage, stacks]
+                id = out
+            }
+        }
+
+        /** @type {(bit: bigint, state: EncodeState<S>) => readonly [Id | undefined, EncodeState<S>]} */
+        const literalStep = (bit, state) => {
+            const [ps, storage, stacks] = state
+            const [l3Out, newPs] = pipelineStep(bit, ps)
+            if (l3Out === undefined) return [undefined, [newPs, storage, stacks]]
+            const [finalId, newStorage, newStacks] = cascade(level3Id(l3Out), storage, stacks)
+            return [finalId, [newPs, newStorage, newStacks]]
+        }
+
+        return {
+            push: (bit, state) => literalStep(bit, state)[1],
+            end: state => {
+                let [id, s] = literalStep(1n, state)
+                while (id === undefined) {
+                    [id, s] = literalStep(0n, s)
+                }
+                return id
+            }
+        }
+    }

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

@@ -0,0 +1,15 @@
+/**
+ * @import { Id } from './id/types.ts'
+ * @import { Add } from './level/hash/types.ts'
+ */
+import type { Id } from './id/types.ts';
+export type _Merge = readonly [Id, Id, Id, boolean];
+export declare const proof: {
+    deterministic: () => void;
+    distinct: () => void;
+    order_matters: () => void;
+    length_matters: () => void;
+    has_merges: () => void;
+    compress_correct: () => void;
+    isSymbol_terminal_only: () => void;
+};

package/fjs/sul/proof.f.mjs

@@ -0,0 +1,65 @@
+/**
+ * @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 { encode, emptyEncodeState } from './module.f.mjs'
+
+/** @typedef {readonly [Id, Id, Id, boolean]} _Merge */
+
+/** @type {(bits: readonly bigint[]) => readonly [Id, readonly _Merge[]]} */
+const run = bits => {
+    /** @type {_Merge[]} */
+    const log = []
+    /** @type {Add<null>} */
+    const add = (l, r, m, isSymbol) => { log.push([l, r, m, isSymbol]); return null }
+    const enc = encode(add)
+    let s = emptyEncodeState(null)
+    for (const b of bits) { s = enc.push(b, s) }
+    return [enc.end(s), log]
+}
+
+/** @type {(bits: readonly bigint[]) => Id} */
+const id = bits => run(bits)[0]
+
+/** @type {(n: number) => readonly bigint[]} */
+const zeros = n => new Array(n).fill(0n)
+
+export const proof = {
+    deterministic: () => {
+        assertEq(id(zeros(16)), id(zeros(16)))
+    },
+
+    distinct: () => {
+        assert(id([0n]) !== id([1n]))
+    },
+
+    order_matters: () => {
+        assert(id([0n, 1n]) !== id([1n, 0n]))
+    },
+
+    length_matters: () => {
+        assert(id(zeros(8)) !== id(zeros(16)))
+    },
+
+    // Enough bits to trigger at least one hash merge
+    has_merges: () => {
+        const [, log] = run(zeros(16))
+        assert(log.length > 0)
+    },
+
+    // Every recorded merge satisfies merged === compress(left, right)
+    compress_correct: () => {
+        const [, log] = run(zeros(16))
+        for (const [l, r, m] of log) { assertEq(m, compress(l, r)) }
+    },
+
+    // Patricia-trie internal merges are isSymbol=false; terminal merges are isSymbol=true
+    isSymbol_terminal_only: () => {
+        const [, log] = run(zeros(16))
+        assert(log.some(([, , , isSymbol]) => isSymbol))
+        assert(log.every(([l, r, m, isSymbol]) => !isSymbol || m === compress(l, r)))
+    },
+}

package/fjs/sul/types.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Type-level API for the full SUL streaming encoder.
+ *
+ * @module
+ */
+import type { InternalState } from '../types/patricia_trie/types.ts';
+import type { PipelineState } from './level/literal/types.ts';
+import type { Id } from './id/types.ts';
+type HashState = InternalState<Id>;
+export type EncodeState<S> = readonly [
+    PipelineState,
+    S,
+    readonly HashState[]
+];
+export type Encode<S> = {
+    readonly push: (bit: bigint, state: EncodeState<S>) => EncodeState<S>;
+    readonly end: (state: EncodeState<S>) => Id;
+};
+export {};

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

@@ -0,0 +1,162 @@
+/**
+ * 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;
+/** Returns an inclusive code point range from the first two characters in a string. @type {(s: string) => Range} */
+export declare const range: (s: string) => Range;
+/** 0x08 */
+export declare const backspace: number;
+/** 0x09 */
+export declare const ht: number;
+/** 0x0A */
+export declare const lf: number;
+/** 0x0C */
+export declare const ff: number;
+/** 0x0D */
+export declare const cr: number;
+/** 0x20 */
+export declare const space: number;
+/** 0x21 */
+export declare const exclamationMark: number;
+/** 0x22 */
+export declare const quotationMark: number;
+/** 0x23 */
+export declare const numberSign: number;
+/** 0x24 */
+export declare const dollarSign: number;
+/** 0x25 */
+export declare const percentSign: number;
+/** 0x26 */
+export declare const ampersand: number;
+/** 0x27 */
+export declare const apostrophe: number;
+/** 0x28 */
+export declare const leftParenthesis: number;
+/** 0x29 */
+export declare const rightParenthesis: number;
+/** 0x2A */
+export declare const asterisk: number;
+/** 0x2B */
+export declare const plusSign: number;
+/** 0x2C */
+export declare const comma: number;
+/** 0x2D */
+export declare const hyphenMinus: number;
+/** 0x2E */
+export declare const fullStop: number;
+/** 0x2F */
+export declare const solidus: number;
+/** 0x30..0x39 */
+export declare const digitRange: Range;
+/** 0x30 */
+export declare const digit0: number;
+/** 0x31 */
+export declare const digit1: number;
+/** 0x32 */
+export declare const digit2: number;
+/** 0x33 */
+export declare const digit3: number;
+/** 0x34 */
+export declare const digit4: number;
+/** 0x35 */
+export declare const digit5: number;
+/** 0x36 */
+export declare const digit6: number;
+/** 0x37 */
+export declare const digit7: number;
+/** 0x38 */
+export declare const digit8: number;
+/** 0x39 */
+export declare const digit9: number;
+/** 0x3A */
+export declare const colon: number;
+/** 0x3B */
+export declare const semicolon: number;
+/** 0x3C */
+export declare const lessThanSign: number;
+/** 0x3D */
+export declare const equalsSign: number;
+/** 0x3E */
+export declare const greaterThanSign: number;
+/** 0x3F */
+export declare const questionMark: number;
+/** 0x40 */
+export declare const commercialAt: number;
+/** 0x41..0x5A */
+export declare const latinCapitalLetterRange: Range;
+/** 0x41 */
+export declare const latinCapitalLetterA: number;
+/** 0x45 */
+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 */
+export declare const reverseSolidus: number;
+/** 0x5D */
+export declare const rightSquareBracket: number;
+/** 0x5E */
+export declare const circumflexAccent: number;
+/** 0x5F */
+export declare const lowLine: number;
+/** 0x60 */
+export declare const graveAccent: number;
+/** 0x61..0x7A */
+export declare const latinSmallLetterRange: Range;
+/** 0x61 */
+export declare const latinSmallLetterA: number;
+/** 0x62 */
+export declare const latinSmallLetterB: number;
+/** 0x65 */
+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 */
+export declare const latinSmallLetterR: number;
+/** 0x74 */
+export declare const latinSmallLetterT: number;
+/** 0x75 */
+export declare const latinSmallLetterU: number;
+/** 0x7A */
+export declare const latinSmallLetterZ: number;
+/** 0x7B */
+export declare const leftCurlyBracket: number;
+/** 0x7C */
+export declare const verticalLine: number;
+/** 0x7D */
+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

@@ -0,0 +1,272 @@
+/**
+ * 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 { contains } from '../../types/range/module.f.mjs'
+
+/** @type {(s: string) => (i: number) => number} */
+const at = s => i => {
+    const r = s.codePointAt(i)
+    if (r === void 0) { throw s }
+    return r
+}
+
+/** Returns the code point value of the first character in a string. @type {(s: string) => number} */
+export const one = s => at(s)(0)
+
+/** Returns an inclusive code point range from the first two characters in a string. @type {(s: string) => Range} */
+export const range = s => {
+    const f = at(s)
+    const f0 = f(0)
+    if (s.length === 1) { return [f0, f0] }
+    return [f0, f(1)]
+}
+
+// 0x00..
+
+/** 0x08 */
+export const backspace = one('\b')
+
+/** 0x09 */
+export const ht = one('\t')
+
+/** 0x0A */
+export const lf = one('\n')
+
+/** 0x0C */
+export const ff = one('\f')
+
+/** 0x0D */
+export const cr = one('\r')
+
+// 0x20..
+
+/** 0x20 */
+export const space = one(' ')
+
+/** 0x21 */
+export const exclamationMark = one('!')
+
+/** 0x22 */
+export const quotationMark = one('"')
+
+/** 0x23 */
+export const numberSign = one('#')
+
+/** 0x24 */
+export const dollarSign = one('$')
+
+/** 0x25 */
+export const percentSign = one('%')
+
+/** 0x26 */
+export const ampersand = one('&')
+
+/** 0x27 */
+export const apostrophe = one("'")
+
+/** 0x28 */
+export const leftParenthesis = one('(')
+
+/** 0x29 */
+export const rightParenthesis = one(')')
+
+/** 0x2A */
+export const asterisk = one('*')
+
+/** 0x2B */
+export const plusSign = one('+')
+
+/** 0x2C */
+export const comma = one(',')
+
+/** 0x2D */
+export const hyphenMinus = one('-')
+
+/** 0x2E */
+export const fullStop = one('.')
+
+/** 0x2F */
+export const solidus = one('/')
+
+// 0x30..
+
+/** 0x30..0x39 */
+export const digitRange = range('09')
+
+/** 0x30 */
+export const digit0 = one('0')
+
+/** 0x31 */
+export const digit1 = one('1')
+
+/** 0x32 */
+export const digit2 = one('2')
+
+/** 0x33 */
+export const digit3 = one('3')
+
+/** 0x34 */
+export const digit4 = one('4')
+
+/** 0x35 */
+export const digit5 = one('5')
+
+/** 0x36 */
+export const digit6 = one('6')
+
+/** 0x37 */
+export const digit7 = one('7')
+
+/** 0x38 */
+export const digit8 = one('8')
+
+/** 0x39 */
+export const digit9 = one('9')
+
+/** 0x3A */
+export const colon = one(':')
+
+/** 0x3B */
+export const semicolon = one(';')
+
+/** 0x3C */
+export const lessThanSign = one('<')
+
+/** 0x3D */
+export const equalsSign = one('=')
+
+/** 0x3E */
+export const greaterThanSign = one('>')
+
+/** 0x3F */
+export const questionMark = one('?')
+
+// 0x40..
+
+/** 0x40 */
+export const commercialAt = one('@')
+
+/** 0x41..0x5A */
+export const latinCapitalLetterRange = range('AZ')
+
+/** 0x41 */
+export const latinCapitalLetterA = one('A')
+
+/** 0x45 */
+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('[')
+
+/** 0x5C */
+export const reverseSolidus = one('\\')
+
+/** 0x5D */
+export const rightSquareBracket = one(']')
+
+/** 0x5E */
+export const circumflexAccent = one('^')
+
+/** 0x5F */
+export const lowLine = one('_')
+
+// 0x60..
+
+/** 0x60 */
+export const graveAccent = one('`')
+
+/** 0x61..0x7A */
+export const latinSmallLetterRange = range('az')
+
+/** 0x61 */
+export const latinSmallLetterA = one('a')
+
+/** 0x62 */
+export const latinSmallLetterB = one('b')
+
+/** 0x65 */
+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')
+
+/** 0x72 */
+export const latinSmallLetterR = one('r')
+
+/** 0x74 */
+export const latinSmallLetterT = one('t')
+
+/** 0x75 */
+export const latinSmallLetterU = one('u')
+
+/** 0x7A */
+export const latinSmallLetterZ = one('z')
+
+/** 0x7B */
+export const leftCurlyBracket = one('{')
+
+/** 0x7C */
+export const verticalLine = one('|')
+
+/** 0x7D */
+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

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