functionalscript 0.43.1 → 0.45.0

package/fjs/types/object/proof.f.d.mts

@@ -0,0 +1,28 @@
+/**
+ * @import { OptionalMap, RequiredMap, StringMap } from './types.ts'
+ * @import { Assert } from '../../asserts/types.ts'
+ * @import { Equal } from '../ts/types.ts'
+ */
+import type { OptionalMap, RequiredMap, StringMap } from './types.ts';
+import type { Assert } from '../../asserts/types.ts';
+import type { Equal } from '../ts/types.ts';
+export type _StringMapIsOptional = Assert<Equal<StringMap<bigint>, {
+    readonly [k in string]?: bigint;
+}>>;
+export type _OptionalIsPartial = Assert<Equal<OptionalMap<'a' | 'b', bigint>, {
+    readonly a?: bigint;
+    readonly b?: bigint;
+}>>;
+export type _RequiredIsRequired = Assert<Equal<RequiredMap<'a' | 'b', bigint>, {
+    readonly a: bigint;
+    readonly b: bigint;
+}>>;
+export type _RequiredOverAnyStringIsNever = Assert<Equal<RequiredMap<string, bigint>, never>>;
+/** @typedef {Assert<Equal<StringMap<bigint>, { readonly [k in string]?: bigint }>>} _StringMapIsOptional */
+/** @typedef {Assert<Equal<OptionalMap<'a'|'b', bigint>, { readonly a?: bigint; readonly b?: bigint }>>} _OptionalIsPartial */
+/** @typedef {Assert<Equal<RequiredMap<'a'|'b', bigint>, { readonly a: bigint; readonly b: bigint }>>} _RequiredIsRequired */
+/** @typedef {Assert<Equal<RequiredMap<string, bigint>, never>>} _RequiredOverAnyStringIsNever */
+export declare const proof: {
+    ctor: () => void;
+    property: () => void;
+};

package/fjs/types/object/proof.f.mjs

@@ -0,0 +1,29 @@
+/**
+ * @import { OptionalMap, RequiredMap, StringMap } from './types.ts'
+ * @import { Assert } from '../../asserts/types.ts'
+ * @import { Equal } from '../ts/types.ts'
+ */
+
+import { at } from './module.f.mjs'
+import { assertEq } from '../../asserts/module.f.mjs'
+
+/** @typedef {Assert<Equal<StringMap<bigint>, { readonly [k in string]?: bigint }>>} _StringMapIsOptional */
+
+/** @typedef {Assert<Equal<OptionalMap<'a'|'b', bigint>, { readonly a?: bigint; readonly b?: bigint }>>} _OptionalIsPartial */
+
+/** @typedef {Assert<Equal<RequiredMap<'a'|'b', bigint>, { readonly a: bigint; readonly b: bigint }>>} _RequiredIsRequired */
+
+/** @typedef {Assert<Equal<RequiredMap<string, bigint>, never>>} _RequiredOverAnyStringIsNever */
+
+export const proof = {
+    ctor: () => {
+        const a = {}
+        const value = at('constructor')(a)
+        assertEq(value, null)
+    },
+    property: () => {
+        const a = { constructor: 42 }
+        const value = at('constructor')(a)
+        assertEq(value, 42)
+    }
+}

package/fjs/types/object/structurally_same/module.f.d.mts

@@ -0,0 +1,39 @@
+/**
+ * Structural comparison for FunctionalScript data.
+ *
+ * `structurallySame` answers "do these two independently constructed values
+ * have the same shape and the same leaves?" — the question proofs really ask
+ * when they compare a computed value against an expected one. It is scoped to
+ * FunctionalScript data (primitives, arrays, and record-like objects) and
+ * deliberately says nothing about dates, maps, sets, typed arrays, prototypes,
+ * or property descriptors; see the README for what it does *not* promise.
+ *
+ * This module is a dependency-free leaf on purpose. `fjs/asserts` needs the
+ * comparison for `assertStructurallySame`, and the public object module
+ * (`../module.f.mjs`) reaches `fjs/asserts` through `types/nullable`, so
+ * importing anything here would close the cycle
+ * `asserts -> object -> nullable -> asserts`. Keep it importing nothing.
+ *
+ * @module
+ */
+/**
+ * Compares two values structurally.
+ *
+ * - `Object.is` decides first, so `NaN` equals itself, `0` and `-0` differ, and
+ *   an object is trivially the same as itself.
+ * - Anything else that is not a non-null object differs.
+ * - Arrays match arrays of the same length whose elements match pairwise; an
+ *   array never matches a non-array. Arrays are assumed dense — FunctionalScript
+ *   cannot build a sparse one; see the README.
+ * - Other objects match when their own enumerable string properties form the
+ *   same set — order is irrelevant — and every property's value matches. A
+ *   property whose value is `undefined` is a property: `{ a: undefined }` and
+ *   `{}` differ.
+ *
+ * There is no cycle detection: a self-referential value recurses until the
+ * stack runs out. FunctionalScript data is acyclic, and adding a seen-set would
+ * cost every ordinary comparison for a case that cannot arise.
+ *
+ * @type {(a: unknown, b: unknown) => boolean}
+ */
+export declare const structurallySame: (a: unknown, b: unknown) => boolean;

package/fjs/types/object/structurally_same/module.f.mjs

@@ -0,0 +1,59 @@
+/**
+ * Structural comparison for FunctionalScript data.
+ *
+ * `structurallySame` answers "do these two independently constructed values
+ * have the same shape and the same leaves?" — the question proofs really ask
+ * when they compare a computed value against an expected one. It is scoped to
+ * FunctionalScript data (primitives, arrays, and record-like objects) and
+ * deliberately says nothing about dates, maps, sets, typed arrays, prototypes,
+ * or property descriptors; see the README for what it does *not* promise.
+ *
+ * This module is a dependency-free leaf on purpose. `fjs/asserts` needs the
+ * comparison for `assertStructurallySame`, and the public object module
+ * (`../module.f.mjs`) reaches `fjs/asserts` through `types/nullable`, so
+ * importing anything here would close the cycle
+ * `asserts -> object -> nullable -> asserts`. Keep it importing nothing.
+ *
+ * @module
+ */
+
+const { entries, is } = Object
+
+/**
+ * Compares two values structurally.
+ *
+ * - `Object.is` decides first, so `NaN` equals itself, `0` and `-0` differ, and
+ *   an object is trivially the same as itself.
+ * - Anything else that is not a non-null object differs.
+ * - Arrays match arrays of the same length whose elements match pairwise; an
+ *   array never matches a non-array. Arrays are assumed dense — FunctionalScript
+ *   cannot build a sparse one; see the README.
+ * - Other objects match when their own enumerable string properties form the
+ *   same set — order is irrelevant — and every property's value matches. A
+ *   property whose value is `undefined` is a property: `{ a: undefined }` and
+ *   `{}` differ.
+ *
+ * There is no cycle detection: a self-referential value recurses until the
+ * stack runs out. FunctionalScript data is acyclic, and adding a seen-set would
+ * cost every ordinary comparison for a case that cannot arise.
+ *
+ * @type {(a: unknown, b: unknown) => boolean}
+ */
+export const structurallySame = (a, b) => {
+    if (is(a, b)) { return true }
+    if (
+        typeof a !== 'object' || a === null ||
+        typeof b !== 'object' || b === null
+    ) { return false }
+    if (a instanceof Array) {
+        return b instanceof Array
+            && a.length === b.length
+            && a.every((v, i) => structurallySame(v, b[i]))
+    }
+    if (b instanceof Array) { return false }
+    const ae = entries(a)
+    /** @type {ReadonlyMap<string, unknown>} */
+    const bm = new Map(entries(b))
+    return ae.length === bm.size
+        && ae.every(([k, v]) => bm.has(k) && structurallySame(v, bm.get(k)))
+}

package/fjs/types/object/structurally_same/proof.f.d.mts

@@ -0,0 +1,6 @@
+export declare const proof: {
+    primitives: (() => void)[];
+    identity: (() => void)[];
+    arrays: (() => void)[];
+    objects: (() => void)[];
+};

package/fjs/types/object/structurally_same/proof.f.mjs

@@ -0,0 +1,73 @@
+import { assert } from '../../../asserts/module.f.mjs'
+import { structurallySame } from './module.f.mjs'
+
+/** @type {(a: unknown, b: unknown) => void} */
+const same = (a, b) => assert(structurallySame(a, b), ['same', a, b])
+
+/** @type {(a: unknown, b: unknown) => void} */
+const differ = (a, b) => assert(!structurallySame(a, b), ['differ', a, b])
+
+export const proof = {
+    primitives: [
+        // `Object.is` decides, so `NaN` is its own equal...
+        () => same(Number.NaN, Number.NaN),
+        () => same(42, 42),
+        () => same('a', 'a'),
+        () => same(undefined, undefined),
+        () => same(null, null),
+        // ...and the two zeros are not.
+        () => differ(0, -0),
+        () => differ(1, 2),
+        () => differ('a', 'b'),
+        () => differ(null, undefined),
+        // a non-object on either side ends it
+        () => differ(1, {}),
+        () => differ({}, 1),
+        () => differ(null, {}),
+        () => differ({}, null),
+    ],
+    identity: [
+        // the same reference short-circuits before any traversal
+        () => {
+            const a = /** @type {const} */ ({ x: [1, 2] })
+            same(a, a)
+        },
+    ],
+    arrays: [
+        () => same([], []),
+        () => same([1, { a: 2 }], [1, { a: 2 }]),
+        // length first, then elementwise
+        () => differ([1], [1, 2]),
+        () => differ([1, 2], [2, 1]),
+        // an array is never the same as a non-array, in either position.
+        // `differ([], {})` alone does not pin this: it already fails on
+        // `0 === undefined`, so only an array-like with a matching `length`
+        // reaches the `b instanceof Array` check.
+        () => differ([], {}),
+        () => differ({}, []),
+        () => differ([1, 2], { 0: 1, 1: 2, length: 2 }),
+        // an explicitly `undefined` element is an ordinary element, so it
+        // counts towards the length
+        () => same([undefined], [undefined]),
+        () => differ([undefined], [1]),
+        () => differ([undefined], []),
+    ],
+    objects: [
+        () => same({}, {}),
+        // property order is not part of the structure
+        () => same({ a: 1, b: { c: 2 } }, { b: { c: 2 }, a: 1 }),
+        // same count, different names. The first is settled by the values
+        // (`1` vs `undefined`); only the second — disjoint names *and*
+        // `undefined` on both sides — pins the key-set check itself.
+        () => differ({ a: 1 }, { b: 1 }),
+        () => differ({ a: undefined }, { b: undefined }),
+        // same names, different values
+        () => differ({ a: 1 }, { a: 2 }),
+        () => differ({ a: { b: 1 } }, { a: { b: 2 } }),
+        // different counts
+        () => differ({ a: 1 }, { a: 1, b: 2 }),
+        // an `undefined`-valued property is still a property
+        () => differ({ a: undefined }, {}),
+        () => differ({}, { a: undefined }),
+    ],
+}

package/fjs/types/object/types.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Types for plain-object helpers: the `OptionalMap`/`RequiredMap`/`StringMap`
+ * record shapes and `Entry<T>`, and the `OneKey`/`SingleProperty`/`NotUnion`
+ * utility types.
+ *
+ * @module
+ */
+/** A record over the keys of `K`, each value possibly missing at runtime. */
+export type OptionalMap<K extends string, T> = {
+    readonly [k in K]?: T;
+};
+/**
+ * A record over the keys of `K`, each value required.
+ *
+ * `K` has to be a finite union of string literals: `RequiredMap<string, T>` is
+ * `never`, because no object can carry every string as a key. Use `StringMap<T>`
+ * for an open key set — its values are optional, which is what such a key set
+ * means at runtime.
+ *
+ * There is no known way to ask TypeScript whether `K` is finite, so the guard
+ * approximates it with `string extends K`, which holds exactly when `K` is
+ * `string`. Other infinite key sets are not caught: a template literal such as
+ * `x-${string}` yields a template index signature instead of `never`, and its
+ * reads are typed `T` while the runtime value is `undefined`. Keep `K` a union
+ * of string literals.
+ */
+export type RequiredMap<K extends string, T> = string extends K ? never : {
+    readonly [k in K]: T;
+};
+/** A record with an open key set. Every value can be missing at runtime. */
+export type StringMap<T> = OptionalMap<string, T>;
+export type Entry<T> = readonly [string, T];
+/**
+ * A set of objects with a single key.
+ *
+ * See also
+ * https://stackoverflow.com/questions/57571664/typescript-type-for-an-object-with-only-one-key-no-union-type-allowed-as-a-key
+ */
+export type OneKey<K extends string, V> = {
+    [P in K]: (RequiredMap<P, V> & OptionalMap<Exclude<K, P>, never>) extends infer O ? {
+        [Q in keyof O]: O[Q];
+    } : never;
+}[K];
+/**
+ * https://stackoverflow.com/questions/61112584/typing-a-single-record-entry
+ */
+export type NotUnion<T, U = T> = T extends unknown ? [
+    U
+] extends [T] ? T : never : never;
+export type SingleProperty<T extends StringMap<never>> = keyof T extends NotUnion<keyof T> ? T : never;

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

@@ -0,0 +1,26 @@
+/**
+ * Ordered map operations with deterministic key traversal.
+ *
+ * @module
+ *
+ * @import { Sign } from '../function/compare/types.ts'
+ * @import { List } from '../list/types.ts'
+ * @import { Reduce } from '../function/operator/types.ts'
+ * @import { Entry, OrderedMap } from './types.ts'
+ */
+import type { List } from '../list/types.ts';
+import type { Reduce } from '../function/operator/types.ts';
+import type { Entry, OrderedMap } from './types.ts';
+/** @type {(name: string) => <T>(map: OrderedMap<T>) => T | null} */
+export declare const at: (name: string) => <T>(map: OrderedMap<T>) => T | null;
+/** @type {<T>(reduce: Reduce<T>) => (name: string) => (value: T) => (map: OrderedMap<T>) => OrderedMap<T>} */
+export declare const setReduce: <T>(reduce: Reduce<T>) => (name: string) => (value: T) => (map: OrderedMap<T>) => OrderedMap<T>;
+/** @type {(name: string) => <T>(value: T) => (map: OrderedMap<T>) => OrderedMap<T>} */
+export declare const setReplace: (name: string) => <T>(value: T) => (map: OrderedMap<T>) => OrderedMap<T>;
+/** @type {<T>(map: OrderedMap<T>) => List<Entry<T>>} */
+export declare const entries: <T>(map: OrderedMap<T>) => List<Entry<T>>;
+/** @type {<T>(entries: List<Entry<T>>) => OrderedMap<T>} */
+export declare const fromEntries: <T>(entries: List<Entry<T>>) => OrderedMap<T>;
+/** @type {(name: string) => <T>(map: OrderedMap<T>) => OrderedMap<T>} */
+export declare const remove: (name: string) => <T>(map: OrderedMap<T>) => OrderedMap<T>;
+export declare const empty: null;

package/fjs/types/ordered_map/module.f.mjs

@@ -0,0 +1,55 @@
+/**
+ * Ordered map operations with deterministic key traversal.
+ *
+ * @module
+ *
+ * @import { Sign } from '../function/compare/types.ts'
+ * @import { List } from '../list/types.ts'
+ * @import { Reduce } from '../function/operator/types.ts'
+ * @import { Entry, OrderedMap } from './types.ts'
+ */
+
+import { value, find } from '../btree/find/module.f.mjs'
+import { set } from '../btree/set/module.f.mjs'
+import { remove as btreeRemove } from '../btree/remove/module.f.mjs'
+import { values } from '../btree/module.f.mjs'
+import { cmp } from '../string/module.f.mjs'
+import { fold } from '../list/module.f.mjs'
+
+/** @type {(a: string) => <T>(b: Entry<T>) => Sign} */
+const keyCmp = a => ([b]) => cmp(a)(b)
+
+/** @type {(name: string) => <T>(map: OrderedMap<T>) => T | null} */
+export const at = name => map => {
+    if (map === null) { return null }
+    const result = value(find(keyCmp(name))(map).first)
+    return result === null ? null : result[1]
+}
+
+/** @type {<T>(reduce: Reduce<T>) => (entry: Entry<T>) => (map: OrderedMap<T>) => OrderedMap<T>} */
+const setReduceEntry = reduce => entry =>
+    set(keyCmp(entry[0]))(old => old === null ? entry : [old[0], reduce(old[1])(entry[1])])
+
+/** @type {<T>(reduce: Reduce<T>) => (name: string) => (value: T) => (map: OrderedMap<T>) => OrderedMap<T>} */
+export const setReduce =
+    reduce => name => value => setReduceEntry(reduce)([name, value])
+
+/** @type {<T>(a: T) => (b: T) => T} */
+const replace = () => b => b
+
+/** @type {(name: string) => <T>(value: T) => (map: OrderedMap<T>) => OrderedMap<T>} */
+export const setReplace =
+    name => value => setReduceEntry(replace)([name, value])
+
+/** @type {<T>(map: OrderedMap<T>) => List<Entry<T>>} */
+export const entries = values
+
+/** @type {<T>(entries: List<Entry<T>>) => OrderedMap<T>} */
+export const fromEntries =
+    fold(setReduceEntry(replace))(null)
+
+/** @type {(name: string) => <T>(map: OrderedMap<T>) => OrderedMap<T>} */
+export const remove =
+    name => btreeRemove(keyCmp(name))
+
+export const empty = null

package/fjs/types/ordered_map/proof.f.d.mts

@@ -0,0 +1,8 @@
+/**
+ * @import { OrderedMap } from './types.ts'
+ */
+export declare const proof: {
+    main: (() => void)[];
+    fromEntries: () => void;
+    stress: () => void;
+};

package/fjs/types/ordered_map/proof.f.mjs

@@ -0,0 +1,91 @@
+/**
+ * @import { OrderedMap } from './types.ts'
+ */
+
+import { at, setReplace, setReduce, empty, entries, remove, fromEntries } from './module.f.mjs'
+import { toArray } from '../list/module.f.mjs'
+import { assertEq } from '../../asserts/module.f.mjs'
+
+export const proof = {
+    main: [
+        () => {
+            let m = setReplace('a')(1)(null)
+
+            assertEq(at('a')(m), 1)
+            assertEq(at('b')(m), null)
+
+            m = setReplace('b')(2)(m)
+
+            assertEq(at('a')(m), 1)
+            assertEq(at('b')(m), 2)
+            assertEq(at('c')(m), null)
+
+            m = setReplace('z')(3)(m)
+
+            assertEq(at('a')(m), 1)
+            assertEq(at('b')(m), 2)
+            assertEq(at('z')(m), 3)
+            assertEq(at('')(m), null)
+
+            m = setReplace('')(4)(m)
+
+            assertEq(at('a')(m), 1)
+            assertEq(at('b')(m), 2)
+            assertEq(at('z')(m), 3)
+            assertEq(at('')(m), 4)
+            assertEq(at('Hello world!')(m), null)
+
+            m = setReplace('Hello world!')(42)(m)
+
+            assertEq(at('a')(m), 1)
+            assertEq(at('b')(m), 2)
+            assertEq(at('z')(m), 3)
+            assertEq(at('')(m), 4)
+            assertEq(at('Hello world!')(m), 42)
+            assertEq(at('x')(m), null)
+
+            // console.log(Array.from(m.entries()))
+            m = remove('Hello world!')(m)
+            assertEq(at('Hello world!')(m), null)
+
+            m = setReduce((/** @type {number} */a) => (/** @type {number} */b) => a + b)('a')(43)(m)
+            assertEq(at('a')(m), 44)
+        },
+        () => {
+            let m = setReplace('x')(12)(null)
+            m = setReplace('y')(44)(m)
+            assertEq(at('x')(m), 12)
+            assertEq(at('y')(m), 44)
+            assertEq(at('a')(m), null)
+            const e = toArray(entries(m))
+            assertEq(e.length, 2)
+        },
+    ],
+    fromEntries: () => {
+        /** @type {readonly (readonly [string, number])[]} */
+        const list = [['a', 1], ['b', 2], ['c', 3]]
+        const m = fromEntries(list)
+        assertEq(at('a')(m), 1)
+        assertEq(at('b')(m), 2)
+        assertEq(at('c')(m), 3)
+        assertEq(at('d')(m), null)
+        // duplicate key: last one wins
+        const m2 = fromEntries(/** @type {const} */([['x', 10], ['x', 20]]))
+        assertEq(at('x')(m2), 20)
+    },
+    stress: () => {
+        /** @type {OrderedMap<number>} */
+        let m = empty
+        for (let i = 0; i < 100_000; ++i) {
+            m = setReplace((i * i).toString())(i)(m)
+            /*
+            console.log()
+            console.log(`# ${i}`)
+            console.log()
+            for (const e of m.struct()) {
+                console.log(e)
+            }
+            */
+        }
+    }
+}

package/fjs/types/ordered_map/types.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Types for the ordered map data structure.
+ *
+ * @module
+ */
+import type { Tree } from '../btree/types/types.ts';
+export type Entry<T> = readonly [string, T];
+export type OrderedMap<T> = Tree<Entry<T>>;

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

@@ -0,0 +1,20 @@
+/**
+ * Streaming Patricia trie for building content-addressed binary trees from sorted leaf sequences.
+ *
+ * @module
+ *
+ * @import { Candidate, Create, PatriciaTrie } from './types.ts'
+ */
+import type { Create, PatriciaTrie } from './types.ts';
+/**
+ * Creates a Patricia trie whose node merging is delegated to `create`.
+ *
+ * @type {<S, T>(create: Create<S, T>) => PatriciaTrie<S, T>}
+ */
+export declare const patriciaTrie: <S, T>(create: Create<S, T>) => PatriciaTrie<S, T>;
+/**
+ * Constructs the initial state from a storage value.
+ *
+ * @type {<S>(storage: S) => readonly [S, readonly []]}
+ */
+export declare const emptyState: <S>(storage: S) => readonly [S, readonly []];

package/fjs/types/patricia_trie/module.f.mjs

@@ -0,0 +1,43 @@
+/**
+ * Streaming Patricia trie for building content-addressed binary trees from sorted leaf sequences.
+ *
+ * @module
+ *
+ * @import { Candidate, Create, PatriciaTrie } from './types.ts'
+ */
+
+/**
+ * Creates a Patricia trie whose node merging is delegated to `create`.
+ *
+ * @type {<S, T>(create: Create<S, T>) => PatriciaTrie<S, T>}
+ */
+export const patriciaTrie = create => ({
+    push: (c, [storage, stack]) => {
+        const [u] = c
+        while (stack.length >= 2) {
+            const [rLeaf, rHash] = stack[stack.length - 1]
+            const [lLeaf, lHash] = stack[stack.length - 2]
+            if ((lLeaf ^ rLeaf) >= (rLeaf ^ u)) { break }
+            const [h, newS] = create(lHash, rHash, storage)
+            storage = newS
+            stack = [...stack.slice(0, -2), [rLeaf, h]]
+        }
+        return [storage, [...stack, c]]
+    },
+    end: ([storage, stack]) => {
+        if (stack.length === 0) { return [undefined, storage] }
+        let h = stack[stack.length - 1][1]
+        for (let i = stack.length - 2; i >= 0; i--) {
+            const lHash = stack[i][1];
+            [h, storage] = create(lHash, h, storage)
+        }
+        return [h, storage]
+    }
+})
+
+/**
+ * Constructs the initial state from a storage value.
+ *
+ * @type {<S>(storage: S) => readonly [S, readonly []]}
+ */
+export const emptyState = storage => [storage, []]

package/fjs/types/patricia_trie/proof.f.d.mts

@@ -0,0 +1,17 @@
+/**
+ * @import { State } from './types.ts'
+ */
+export type _NodeList = readonly [bigint, bigint, bigint][];
+declare const empty: () => void;
+declare const singleLeaf: () => void;
+declare const twoLeaves: () => void;
+declare const descending: () => void;
+declare const ascending: () => void;
+export declare const proof: {
+    empty: typeof empty;
+    singleLeaf: typeof singleLeaf;
+    twoLeaves: typeof twoLeaves;
+    descending: typeof descending;
+    ascending: typeof ascending;
+};
+export {};