functionalscript 0.13.0 → 0.14.0

package/fs/sul/level/hash/test.f.js

@@ -0,0 +1,112 @@
+import { assert, assertEq } from "../../../dev/module.f.js";
+import { compress, level3Id } from "../../id/module.f.js";
+import { emptyEncodeState, encode } from "./module.f.js";
+const add = (l, r, m, isSymbol, s) => [...s, [l, r, m, isSymbol]];
+const enc = encode(add);
+const initial = emptyEncodeState([]);
+// Run a complete valid word from a clean state; throws if no output is produced.
+const runWord = (symbols) => {
+    let state = initial;
+    for (const s of symbols) {
+        const [out, newState] = enc(s, state);
+        state = newState;
+        if (out !== undefined) {
+            return [out, state[0]];
+        }
+    }
+    throw symbols;
+};
+// Every stored triple must satisfy m === compress(l, r).
+const verifyStorage = (storage) => {
+    for (const [l, r, m] of storage) {
+        assertEq(m, compress(l, r));
+    }
+};
+const s0 = level3Id(0n);
+const s1 = level3Id(1n);
+export default {
+    // Minimum word [s0, t] with t == s0
+    min_equal: () => {
+        const [out, storage] = runWord([s0, s0]);
+        assertEq(out, compress(s0, s0));
+        assertEq(storage.length, 1);
+        verifyStorage(storage);
+    },
+    // Minimum word [s0, t] with t > s0
+    min_greater: () => {
+        const [out, storage] = runWord([s0, s1]);
+        assertEq(out, compress(s0, s1));
+        assertEq(storage.length, 1);
+        verifyStorage(storage);
+    },
+    // All symbols before the terminator return undefined
+    intermediate_undefined: () => {
+        const [r0, st0] = enc(s1, initial);
+        assert(r0 === undefined);
+        const [r1, st1] = enc(s0, st0);
+        assert(r1 === undefined);
+        const [r2] = enc(s1, st1);
+        assert(r2 !== undefined);
+    },
+    // Three-symbol word [s0, s1, t]: end merges (s0,s1), then create merges (root, t)
+    three_symbol: () => {
+        const [out, storage] = runWord([s1, s0, s0]);
+        assertEq(out, compress(compress(s1, s0), s0));
+        assertEq(storage.length, 2);
+        verifyStorage(storage);
+        // first add: merge of the two decreasing-prefix symbols during end
+        assertEq(storage[0][0], s1);
+        assertEq(storage[0][1], s0);
+        // second add: merge of trie root with terminator
+        assertEq(storage[1][0], compress(s1, s0));
+        assertEq(storage[1][1], s0);
+    },
+    // Output equals the merged value in the last add call
+    output_is_last_add: () => {
+        const [out, storage] = runWord([s1, s0, s1]);
+        assertEq(out, storage.at(-1)[2]);
+    },
+    // Stack is empty after flush; storage is preserved
+    state_reset: () => {
+        const st1 = enc(s0, initial)[1];
+        const [, st2] = enc(s0, st1);
+        assertEq(st2[1].length, 0);
+        assertEq(st2[0].length, 1);
+    },
+    // Storage grows across consecutive words (not wiped on flush)
+    storage_accumulates: () => {
+        const st1 = enc(s0, initial)[1];
+        const st2 = enc(s1, st1)[1]; // flush [s0, s1]
+        const st3 = enc(s0, st2)[1];
+        const [, st4] = enc(s0, st3); // flush [s0, s0]
+        assertEq(st4[0].length, 2);
+        verifyStorage(st4[0]);
+    },
+    // Two consecutive words encode independently and correctly
+    two_words: () => {
+        const st1 = enc(s0, initial)[1];
+        const [r1, st2] = enc(s1, st1);
+        assertEq(r1, compress(s0, s1));
+        const st3 = enc(s0, st2)[1];
+        const [r2] = enc(s0, st3);
+        assertEq(r2, compress(s0, s0));
+    },
+    // Different words produce different hashes
+    non_commutative: () => {
+        const [out1] = runWord([s0, s1]);
+        const [out2] = runWord([s1, s0, s1]);
+        assert(out1 !== out2);
+    },
+    // Trie-internal merges have isSymbol=false; only the terminal merge has isSymbol=true
+    isSymbol_terminal_only: () => {
+        const [, storage] = runWord([s1, s0, s0]);
+        assert(storage[0][3] === false); // Patricia trie merge
+        assert(storage[1][3] === true); // terminal compress(root, t)
+    },
+    // Single-step word: no trie merges, exactly one isSymbol=true
+    isSymbol_min_word: () => {
+        const [, storage] = runWord([s0, s0]);
+        assertEq(storage.length, 1);
+        assert(storage[0][3] === true);
+    },
+};

package/fs/sul/level/literal/module.f.d.ts

@@ -0,0 +1,64 @@
+/**
+ * Bijective encoding between words of level-k symbols and single symbols of level k+1,
+ * for the first three literal SUL levels.
+ *
+ * @module
+ */
+import { type Vec } from '../../../types/bit_vec/module.f.ts';
+import type { Func } from '../../../types/function/module.f.ts';
+import { type Equal, type StateScan } from '../../../types/function/operator/module.f.ts';
+import { type List } from '../../../types/list/module.f.ts';
+export declare const symbolToString: (s: bigint) => string;
+export type Word = readonly bigint[];
+export declare const wordToString: (word: List<bigint>) => string;
+export declare const wordEqual: Equal<List<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];
+/** Initial encoder state: no symbols seen, zero offset. */
+export declare const emptyEncodeState: EncodeState;
+/**
+ * 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>;
+};
+/**
+ * Creates a {@link Level} for alphabet size `n = 2^e + 1`.
+ *
+ * The first three levels for a tree starting from a binary alphabet:
+ *
+ * | `e`  | `n`    |
+ * |------|--------|
+ * | `0`  | `2`    |
+ * | `2`  | `5`    |
+ * | `7`  | `0x81` |
+ *
+ * @param e `log2(n - 1)`
+ */
+export declare const level: (e: bigint) => Level;
+/** Combined encoder state for the three-level literal pipeline (L1 → L2 → L3). */
+export type PipelineState = readonly [EncodeState, EncodeState, EncodeState];
+/** Initial state for the three-level literal pipeline. */
+export declare const emptyPipelineState: PipelineState;
+/**
+ * Advances the three-level literal pipeline by one bit.
+ * Returns a level-3 symbol whenever the pipeline emits, otherwise `undefined`.
+ */
+export declare const pipelineStep: StateScan<bigint, PipelineState, bigint | undefined>;
+export type LiteralToVec = Func<bigint, Vec>;
+/** Decodes a level-1 symbol to its canonical MSB bit vector. */
+export declare const literal1ToVec: LiteralToVec;
+/** Decodes a level-2 symbol to its canonical MSB bit vector (via level-1 decoding). */
+export declare const literal2ToVec: LiteralToVec;
+/** Decodes a level-3 symbol to its canonical MSB bit vector (via level-2 and level-1 decoding). */
+export declare const literal3ToVec: LiteralToVec;

package/fs/sul/level/literal/module.f.js

@@ -0,0 +1,88 @@
+/**
+ * Bijective encoding between words of level-k symbols and single symbols of level k+1,
+ * for the first three literal SUL levels.
+ *
+ * @module
+ */
+import { log2 } from "../../../types/bigint/module.f.js";
+import { listToVec, msb, vec } from "../../../types/bit_vec/module.f.js";
+import { strictEqual } from "../../../types/function/operator/module.f.js";
+import { equal, map } from "../../../types/list/module.f.js";
+import { join } from "../../../types/string/module.f.js";
+export const symbolToString = (s) => s.toString(16);
+export const wordToString = (word) => join(',')(map(symbolToString)(word));
+export const wordEqual = equal(strictEqual);
+/** Initial encoder state: no symbols seen, zero offset. */
+export const emptyEncodeState = [undefined, 0n];
+/**
+ * Creates a {@link Level} for alphabet size `n = 2^e + 1`.
+ *
+ * The first three levels for a tree starting from a binary alphabet:
+ *
+ * | `e`  | `n`    |
+ * |------|--------|
+ * | `0`  | `2`    |
+ * | `2`  | `5`    |
+ * | `7`  | `0x81` |
+ *
+ * @param e `log2(n - 1)`
+ */
+export const level = (e) => {
+    // m = n - 1
+    const m = 1n << e;
+    const n = m + 1n;
+    // k = n - 2
+    const k = m - 1n;
+    // m2 = 2 * m
+    const m2 = m << 1n;
+    const e1 = e + 1n;
+    const sum = (i) => (m2 << i) + i - k;
+    const decode = (i) => () => {
+        const r = log2((i + k) >> e1);
+        const s0 = sum(r) > i ? r : r + 1n;
+        const s1 = i - sum(s0) + n;
+        return s1 >= s0 ? [s0, s1] : {
+            first: s0,
+            tail: decode(i - sum(s0 - 1n))
+        };
+    };
+    return {
+        sum,
+        decode,
+        encode: (i, [last, part]) => last === undefined ? [undefined, [i, 0n]] :
+            last > i ? [undefined, [i, part + sum(last - 1n)]] :
+                [part + sum(last) + i - n, emptyEncodeState]
+    };
+};
+const l1 = level(0n);
+const l2 = level(2n);
+const l3 = level(7n);
+/** Initial state for the three-level literal pipeline. */
+export const emptyPipelineState = [emptyEncodeState, emptyEncodeState, emptyEncodeState];
+/**
+ * Advances the three-level literal pipeline by one bit.
+ * Returns a level-3 symbol whenever the pipeline emits, otherwise `undefined`.
+ */
+export const pipelineStep = (bit, [l1s, l2s, l3s]) => {
+    const [l1Out, newL1s] = l1.encode(bit, l1s);
+    if (l1Out === undefined)
+        return [undefined, [newL1s, l2s, l3s]];
+    const [l2Out, newL2s] = l2.encode(l1Out, l2s);
+    if (l2Out === undefined)
+        return [undefined, [newL1s, newL2s, l3s]];
+    const [l3Out, newL3s] = l3.encode(l2Out, l3s);
+    return [l3Out, [newL1s, newL2s, newL3s]];
+};
+const concat = listToVec(msb);
+const vec1 = vec(1n);
+const literalToVec = (prior, e) => {
+    const m = map(prior);
+    const { decode } = level(e);
+    return literal => concat(m(decode(literal)));
+};
+/** Decodes a level-1 symbol to its canonical MSB bit vector. */
+export const literal1ToVec = literalToVec(vec1, 0n);
+/** Decodes a level-2 symbol to its canonical MSB bit vector (via level-1 decoding). */
+export const literal2ToVec = literalToVec(literal1ToVec, 2n);
+/** Decodes a level-3 symbol to its canonical MSB bit vector (via level-2 and level-1 decoding). */
+export const literal3ToVec = literalToVec(literal2ToVec, 7n);

package/fs/sul/level/literal/test.f.d.ts

@@ -0,0 +1,12 @@
+declare const _default: {
+    x2: () => void;
+    x5: () => void;
+    x81: () => void;
+    toVec: {
+        level1: () => void;
+        level2: () => void;
+        level3: () => void;
+    };
+    pipeline: () => void;
+};
+export default _default;