functionalscript 0.43.0 → 0.44.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/level/literal/types.js

@@ -0,0 +1,6 @@
+/**
+ * Type-level API for the literal SUL level encoding.
+ *
+ * @module
+ */
+export {};

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

@@ -0,0 +1,25 @@
+/**
+ * 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 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>;
+/** @import { Id } from './id/types.ts' */
+/** @import { InternalState } from '../types/patricia_trie/types.ts' */
+/** @import { EncodeState, Encode } from './types.ts' */
+/** @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,69 @@
+/**
+ * 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 { emptyPipelineState, pipelineStep } from './level/literal/module.f.mjs'
+import { encode as hashEncode } from './level/hash/module.f.mjs'
+/** @import { Add } from './level/hash/types.ts' */
+import { level3Id } from './id/module.f.mjs'
+/** @import { Id } from './id/types.ts' */
+/** @import { InternalState } from '../types/patricia_trie/types.ts' */
+/** @import { EncodeState, Encode } from './types.ts' */
+
+/** @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,11 @@
+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,62 @@
+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 */
+
+/** @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/sul/types.js

@@ -0,0 +1,6 @@
+/**
+ * Type-level API for the full SUL streaming encoder.
+ *
+ * @module
+ */
+export {};

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

@@ -0,0 +1,136 @@
+/**
+ * Provides ASCII code point constants and helpers for creating numeric code points and inclusive ranges.
+ *
+ * @module
+ */
+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;
+/** 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;
+/** 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;

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

@@ -0,0 +1,224 @@
+/**
+ * Provides ASCII code point constants and helpers for creating numeric code points and inclusive ranges.
+ *
+ * @module
+ */
+
+/** @import { Range } from '../../types/range/types.ts' */
+
+/** @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')
+
+/** 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')
+
+/** 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('~')

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

@@ -0,0 +1,16 @@
+import { 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)
+
+export const proof = {
+    range: () => {
+        const r = stringify(range("A"))
+        assertEq(r, '[65,65]')
+    },
+    throw: {
+        oneThrowsOnEmpty: () => one(''),
+    },
+}

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

@@ -0,0 +1,74 @@
+/**
+ * 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.
+ *
+ * @module
+ */
+import type { List } from '../../types/list/types.ts';
+import type { StateScan } from '../../types/function/operator/types.ts';
+/**
+ * Error mask used to tag invalid code points or encoding errors. A decoded
+ * value with this bit set represents a malformed unit rather than a valid
+ * code point.
+ */
+export declare const errorMask = 2147483648;
+/**
+ * Builds a streaming decoder from the two direction-specific steps.
+ *
+ * Decoding starts from the empty (`null`) state. The input is processed unit by
+ * unit through `byteOp`, then a trailing end-of-input marker drives `eofOp` to
+ * flush any leftover decoding state.
+ *
+ * @template Unit
+ * @template S
+ * @template Cp
+ * @param {StateScan<Unit, S | null, List<Cp>>} byteOp - The per-unit decoding step.
+ * @param {(state: S | null) => readonly [List<Cp>, S | null]} eofOp - The end-of-input step that flushes the remaining state.
+ * @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>;
+/**
+ * Checks whether the 16-bit word (U16) is a high surrogate.
+ * Range: 0xD800 - 0xDBFF.
+ */
+export declare const isHighSurrogate: (i: number) => boolean;
+/**
+ * Checks whether the 16-bit word (U16) is a low surrogate.
+ * Range: 0xDC00 - 0xDFFF.
+ */
+export declare const isLowSurrogate: (i: number) => boolean;
+/**
+ * Checks whether the code point is in the BMP range.
+ * BMP is the main Unicode plane that covers code points 0x0000 - 0xFFFF, except
+ * for the range of surrogates.
+ *
+ * @type {(codePoint: number) => boolean}
+ */
+export declare const isBmpCodePoint: (codePoint: number) => boolean;
+/**
+ * Checks whether the code point belongs to a supplementary (additional) Unicode
+ * plane. Supplementary planes cover code points from 0x010000 to 0x10FFFF.
+ */
+export declare const isSupplementaryPlane: (i: number) => boolean;
+/**
+ * Checks whether the code point is a valid scalar value: within the assignable
+ * Unicode range (0x0000 - 0x10FFFF) and not a surrogate.
+ *
+ * @type {(c: number) => boolean}
+ */
+export declare const isValidCodePoint: (c: number) => boolean;
+/**
+ * Checks whether the code point is a *text* code point — distinct from
+ * {@link isValidCodePoint}, which gates well-formedness for decoding. A code
+ * point is text unless it is a control character: the controls are 0x0000 -
+ * 0x001F, 0x007F (DEL), and 0x0080 - 0x009F (C1), minus the whitespace block
+ * 0x0009 - 0x000D (TAB, LF, VT, FF, CR), which is legitimate in text. Every
+ * code point at or above 0x0020 that is not DEL or a C1 control is text.
+ *
+ * @type {(c: number) => boolean}
+ */
+export declare const isTextCodePoint: (c: number) => boolean;