functionalscript 0.44.0 → 0.45.0

package/fjs/types/rtti/validate/module.f.mjs

@@ -28,11 +28,14 @@
  * See `./types.ts` for the `Path`/`Result`/`Validate`/`ValidationError` type-level API.
  *
  * @module
+ *
+ * @import { Unknown } from '../ts/types.ts'
+ * @import { Info1, Struct, Tag1, Tuple, Type } from '../types.ts'
+ * @import { StringMap } from '../../object/types.ts'
+ * @import { Container, IsContainer, Validate, ValidateE, Visitor } from '../common/types.ts'
  */
-/** @import { Unknown } from '../ts/types.ts' */
-/** @import { Info1, Struct, Tag1, Tuple, Type } from '../types.ts' */
+
 import { ok } from '../../result/module.f.mjs'
-/** @import { StringMap } from '../../object/types.ts' */
 import {
     constPrimitiveValidate,
     eachEntry,
@@ -43,7 +46,6 @@ import {
     verror,
     visit,
 } from '../common/module.f.mjs'
-/** @import { Container, IsContainer, Validate, ValidateE, Visitor } from '../common/types.ts' */
 
 export {
     constPrimitiveValidate,

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

@@ -2,12 +2,15 @@
  * Sorted immutable list helpers and merge operations.
  *
  * @module
+ *
+ * @import { Cmp } from '../function/compare/types.ts'
+ * @import { List } from '../list/types.ts'
+ * @import { ReduceOp, SortedList, _MergeReduce } from './types.ts'
  */
 import type { Cmp } from '../function/compare/types.ts';
 import type { List } from '../list/types.ts';
 import type { ReduceOp, SortedList, _MergeReduce } from './types.ts';
 export type _SortedArray<T> = readonly T[];
-/** @import { ReduceOp, SortedList, TailReduce, _MergeReduce } from './types.ts' */
 /** @template T @typedef {readonly T[]} _SortedArray */
 /**
  * Two-way sorted-list merge.

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

@@ -2,14 +2,15 @@
  * Sorted immutable list helpers and merge operations.
  *
  * @module
+ *
+ * @import { Cmp } from '../function/compare/types.ts'
+ * @import { List } from '../list/types.ts'
+ * @import { ReduceOp, SortedList, _MergeReduce } from './types.ts'
  */
 
 import { bsearch } from '../function/compare/module.f.mjs'
-/** @import { Cmp } from '../function/compare/types.ts' */
 import { next } from '../list/module.f.mjs'
-/** @import { List } from '../list/types.ts' */
 import { identity } from '../function/module.f.mjs'
-/** @import { ReduceOp, SortedList, TailReduce, _MergeReduce } from './types.ts' */
 
 /** @template T @typedef {readonly T[]} _SortedArray */
 
@@ -53,11 +54,7 @@ export const merge =
      * @param {Cmp<T>} cmp
      * @returns {(a: SortedList<T>) => (b: SortedList<T>) => SortedList<T>}
      */
-    cmp => {
-        /** @type {TailReduce<T, null>} */
-        const tailReduce = mergeTail
-        return genericMerge({ reduceOp: cmpReduce(cmp), tailReduce })(null)
-    }
+    cmp => genericMerge({ reduceOp: cmpReduce(cmp), tailReduce: keepTail })(null)
 
 const cmpReduce =
     /**
@@ -70,10 +67,22 @@ const cmpReduce =
         return [sign === 1 ? b : a, sign, null]
     }
 
-/** @type {() => <T>(tail: List<T>) => List<T>} */
-const mergeTail = () => identity
+/**
+ * The two tail policies `genericMerge` takes, named for what they do with the
+ * list that has not been exhausted yet: `merge` keeps it, because everything
+ * still there belongs in the union, and `intersect` drops it, because with one
+ * side exhausted nothing remaining can be matched.
+ *
+ * Both are left to inference deliberately. An explicit
+ * `() => <T>(tail: List<T>) => List<T>` compiles here but introduces its own
+ * type parameter, which `genericMerge` then collects as an inference candidate
+ * alongside `reduceOp`'s; the best common supertype of the two is `unknown`, so
+ * `T` widens and both call sites fail to match their declared return type. With
+ * no annotation there is no second candidate and `reduceOp` alone fixes `T`.
+ */
+const keepTail = () => identity
 
-const tailReduce = () => () => null
+const dropTail = () => () => null
 
 const intersectReduce =
     /**
@@ -92,7 +101,7 @@ export const intersect =
      * @param {Cmp<T>} cmp
      * @returns {(a: SortedList<T>) => (b: SortedList<T>) => SortedList<T>}
      */
-    cmp => genericMerge({ reduceOp: intersectReduce(cmp), tailReduce })(null)
+    cmp => genericMerge({ reduceOp: intersectReduce(cmp), tailReduce: dropTail })(null)
 
 export const find =
     /**

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

@@ -1,4 +1,6 @@
-/** @import { Unknown } from '../../media/json/types.ts' */
+/**
+ * @import { Unknown } from '../../media/json/types.ts'
+ */
 export declare const proof: {
     sortedMergre: (() => void)[];
     find: (() => void)[];

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

@@ -1,4 +1,6 @@
-/** @import { Unknown } from '../../media/json/types.ts' */
+/**
+ * @import { Unknown } from '../../media/json/types.ts'
+ */
 
 import { find, merge } from './module.f.mjs'
 import { stringify } from '../../media/json/module.f.mjs'

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

@@ -1,6 +1,36 @@
+/**
+ * A sorted set, implemented as a sorted array.
+ *
+ * @module
+ *
+ * @note
+ *
+ * All input arrays must be pre-sorted according to the provided comparison function (`Cmp<T>`).
+ * The correctness of these functions depend on this requirement.
+ *
+ * @example
+ *
+ * ```js
+ * import { union, intersect, has } from './module.f.mjs'
+ *
+ * const cmp = (a: number) => (b: number) => a < b ? -1 : a > b ? 1 : 0
+ *
+ * const setA = [1, 3, 5]
+ * const setB = [3, 4, 5]
+ *
+ * const unionSet = union(cmp)(setA)(setB) // [1, 3, 4, 5]
+ *
+ * const intersectionSet = intersect(cmp)(setA)(setB) // [3, 5]
+ *
+ * has(cmp)(3)(setA) // true
+ * has(cmp)(2)(setA) // false
+ * ```
+ *
+ * @import { Cmp } from '../function/compare/types.ts'
+ * @import { SortedSet } from './types.ts'
+ */
 import type { Cmp } from '../function/compare/types.ts';
 import type { SortedSet } from './types.ts';
-/** @import { SortedSet } from './types.ts' */
 export declare const union: <T>(
 /**
  * @template T

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

@@ -25,11 +25,13 @@
  * has(cmp)(3)(setA) // true
  * has(cmp)(2)(setA) // false
  * ```
+ *
+ * @import { Cmp } from '../function/compare/types.ts'
+ * @import { SortedSet } from './types.ts'
  */
-/** @import { Cmp } from '../function/compare/types.ts' */
+
 import { toArray } from "../list/module.f.mjs"
 import { merge, intersect as listIntersect, find } from '../sorted_list/module.f.mjs'
-/** @import { SortedSet } from './types.ts' */
 
 export const union =
     /**

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

@@ -1,4 +1,6 @@
-/** @import { Unknown } from '../../media/json/types.ts' */
+/**
+ * @import { Unknown } from '../../media/json/types.ts'
+ */
 export declare const proof: {
     example: () => void;
     union: (() => void)[];

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

@@ -1,4 +1,6 @@
-/** @import { Unknown } from '../../media/json/types.ts' */
+/**
+ * @import { Unknown } from '../../media/json/types.ts'
+ */
 
 import { has, intersect, union } from './module.f.mjs'
 import { stringify } from '../../media/json/module.f.mjs'

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

@@ -14,6 +14,10 @@
  * repeat('abc')(3) // 'abcabcabc'
  * cmp('apple')('banana') // -1
  * ```
+ *
+ * @import { List } from '../list/types.ts'
+ * @import { Sign } from '../function/compare/types.ts'
+ * @import { Reduce } from '../function/operator/types.ts'
  */
 import type { List } from '../list/types.ts';
 import type { Sign } from '../function/compare/types.ts';

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

@@ -14,14 +14,15 @@
  * repeat('abc')(3) // 'abcabcabc'
  * cmp('apple')('banana') // -1
  * ```
+ *
+ * @import { List } from '../list/types.ts'
+ * @import { Sign } from '../function/compare/types.ts'
+ * @import { Reduce } from '../function/operator/types.ts'
  */
 
-/** @import { List } from '../list/types.ts' */
 import { reduce as listReduce, repeat as listRepeat } from '../list/module.f.mjs'
 import { compose } from '../function/module.f.mjs'
-/** @import { Sign } from '../function/compare/types.ts' */
 import { cmp as uCmp } from '../function/compare/module.f.mjs'
-/** @import { Reduce } from '../function/operator/types.ts' */
 import { join as joinOp } from '../function/operator/module.f.mjs'
 import { fold } from '../../common/monoid/module.f.mjs'
 

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

@@ -19,10 +19,12 @@
  * mySet = remove('banana')(mySet);
  * if (contains('banana')(mySet)) { throw '4' }
  * ```
+ *
+ * @import { List } from '../list/types.ts'
+ * @import { StringSet } from './types.ts'
  */
 import type { List } from '../list/types.ts';
 import type { StringSet } from './types.ts';
-/** @import { StringSet } from './types.ts' */
 /** @type {(s: StringSet) => List<string>} */
 export declare const values: (s: StringSet) => List<string>;
 /** @type {null} */

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

@@ -19,6 +19,9 @@
  * mySet = remove('banana')(mySet);
  * if (contains('banana')(mySet)) { throw '4' }
  * ```
+ *
+ * @import { List } from '../list/types.ts'
+ * @import { StringSet } from './types.ts'
  */
 
 import { empty as btEmpty, values as btValues } from '../btree/module.f.mjs'
@@ -26,10 +29,8 @@ import { find, isFound } from '../btree/find/module.f.mjs'
 import { remove as btreeRemove } from '../btree/remove/module.f.mjs'
 import { set as btreeSet } from '../btree/set/module.f.mjs'
 import { cmp } from "../string/module.f.mjs"
-/** @import { List } from '../list/types.ts' */
 import { fold } from '../list/module.f.mjs'
 import { compose } from '../function/module.f.mjs'
-/** @import { StringSet } from './types.ts' */
 
 /** @type {(s: StringSet) => List<string>} */
 export const values = btValues

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

@@ -4,6 +4,8 @@
  * primitive literals, and unions as TypeScript type expressions.
  *
  * @module
+ *
+ * @import { Printer } from './types.ts'
  */
 import type { Printer } from './types.ts';
 /**

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

@@ -4,10 +4,10 @@
  * primitive literals, and unions as TypeScript type expressions.
  *
  * @module
+ *
+ * @import { Printer } from './types.ts'
  */
 
-/** @import { Printer } from './types.ts' */
-
 /** @type {(open: string, close: string) => (i: readonly string[]) => string} */
 const complex = (open, close) => i =>
     `${open}${i.join(',')}${close}`
@@ -24,7 +24,7 @@ export const printer = (mut = undefined) => {
     return {
         tuple: (mut ? complex('[', ']') : complex('readonly[', ']')),
         struct: fields =>
-            structX(fields.map(([k, v]) => `${ro}${JSON.stringify(k)}:${v}`)),
+            structX(fields.map(([k, v, opt]) => `${ro}${JSON.stringify(k)}${opt === true ? '?' : ''}:${v}`)),
         array: type => `${ro}(${type})[]`,
         // `[k:string]?:` is invalid TypeScript — optional keys on an infinite
         // key set require mapped-type syntax.

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

@@ -10,6 +10,7 @@ export declare const unionSingle: () => void;
 export declare const unionMulti: () => void;
 export declare const printerReadonlyTuple: () => void;
 export declare const printerReadonlyStruct: () => void;
+export declare const printerOptionalField: () => void;
 export declare const printerReadonlyArray: () => void;
 export declare const printerReadonlyRecord: () => void;
 export declare const printerMutableTuple: () => void;

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

@@ -64,6 +64,11 @@ export const printerReadonlyStruct = () => {
     if (r !== '{readonly"x":number,readonly"y":string}') { throw r }
 }
 
+export const printerOptionalField = () => {
+    const r = ro.struct([['x', 'number', true], ['y', 'string']])
+    if (r !== '{readonly"x"?:number,readonly"y":string}') { throw r }
+}
+
 export const printerReadonlyArray = () => {
     const r = ro.array('string')
     assertEq(r, 'readonly(string)[]')

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

@@ -5,12 +5,17 @@
  * @module
  */
 export type Equal<A, B> = (<T>() => T extends A ? 1 : 2) extends (<T>() => T extends B ? 1 : 2) ? true : false;
+/**
+ * A `struct` field: the key, its type expression, and — when the third
+ * element is `true` — an optional-key marker (`"key"?: type`).
+ */
+export type StructField = readonly [string, string, true?];
 /**
  * Functions for emitting TypeScript type expression strings.
  */
 export type Printer = {
     readonly tuple: (types: readonly string[]) => string;
-    readonly struct: (fields: readonly (readonly [string, string])[]) => string;
+    readonly struct: (fields: readonly StructField[]) => string;
     readonly array: (type: string) => string;
     readonly record: (type: string) => string;
 };

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

@@ -8,17 +8,28 @@
  * (e.g. `fromVec`/`toVec` when reading or writing files).
  *
  * @module
+ *
+ * @import { Vec } from '../bit_vec/types.ts'
+ * @import { List } from '../list/types.ts'
  */
 import type { Vec } from '../bit_vec/types.ts';
 import type { List } from '../list/types.ts';
+/**
+ * Concatenates a list of `Uint8Array` values into one MSB-first bit vector.
+ *
+ * Throws if the result would exceed `maxLength`. The bound is not precomputed:
+ * `tryU8ListToVec` attempts the real conversion and reports `null` when it does
+ * not fit (AGENTS.md §5.6).
+ *
+ * @type {(input: List<Uint8Array>) => Vec}
+ */
+export declare const listToVec: (input: List<Uint8Array>) => Vec;
 /**
  * Converts a Uint8Array into an MSB-first bit vector.
  *
  * @type {(input: Uint8Array) => Vec}
  */
 export declare const toVec: (input: Uint8Array) => Vec;
-/** @type {(input: List<Uint8Array>) => Vec} */
-export declare const listToVec: (input: List<Uint8Array>) => Vec;
 /**
  * Converts an MSB-first bit vector into a Uint8Array.
  *

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

@@ -8,36 +8,41 @@
  * (e.g. `fromVec`/`toVec` when reading or writing files).
  *
  * @module
+ *
+ * @import { Vec } from '../bit_vec/types.ts'
+ * @import { List } from '../list/types.ts'
  */
 
-import { assert, assertNotNullish } from '../../asserts/module.f.mjs'
+import { assertNotNullish } from '../../asserts/module.f.mjs'
 import { utf8, utf8ToString } from '../../text/module.f.mjs'
-import { maxLengthBytes, msb, tryU8ListToVec, u8List, u8ListToVec } from '../bit_vec/module.f.mjs'
-/** @import { Vec } from '../bit_vec/types.ts' */
+import { msb, tryU8ListToVec, u8List } from '../bit_vec/module.f.mjs'
 import { compose } from '../function/module.f.mjs'
 import { flat, fromArrayLike, iterable, map } from '../list/module.f.mjs'
-/** @import { List } from '../list/types.ts' */
 
-const u8ListToVecMsb = u8ListToVec(msb)
 const tryU8ListToVecMsb = tryU8ListToVec(msb)
 const u8ListMsb = u8List(msb)
 
+const m = map(fromArrayLike)
+
 /**
- * Converts a Uint8Array into an MSB-first bit vector.
+ * Concatenates a list of `Uint8Array` values into one MSB-first bit vector.
  *
- * @type {(input: Uint8Array) => Vec}
+ * Throws if the result would exceed `maxLength`. The bound is not precomputed:
+ * `tryU8ListToVec` attempts the real conversion and reports `null` when it does
+ * not fit (AGENTS.md §5.6).
+ *
+ * @type {(input: List<Uint8Array>) => Vec}
  */
-export const toVec = input => {
-    assert(input.length <= maxLengthBytes, "the array is too big")
-    return u8ListToVecMsb(fromArrayLike(input))
-}
-
-const m = map(fromArrayLike)
-
-/** @type {(input: List<Uint8Array>) => Vec} */
 export const listToVec = input =>
     assertNotNullish(tryU8ListToVecMsb(flat(m(input))), "the array is too big")
 
+/**
+ * Converts a Uint8Array into an MSB-first bit vector.
+ *
+ * @type {(input: Uint8Array) => Vec}
+ */
+export const toVec = input => listToVec([input])
+
 /**
  * Converts an MSB-first bit vector into a Uint8Array.
  *

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

@@ -2,6 +2,9 @@
  * Static website generation program for project landing content.
  *
  * @module
+ *
+ * @import { WriteFile } from '../effects/node/types.ts'
+ * @import { Effect } from '../effects/types.ts'
  */
 import type { WriteFile } from '../effects/node/types.ts';
 import type { Effect } from '../effects/types.ts';

package/fjs/website/module.f.mjs

@@ -2,13 +2,14 @@
  * Static website generation program for project landing content.
  *
  * @module
+ *
+ * @import { WriteFile } from '../effects/node/types.ts'
+ * @import { Effect } from '../effects/types.ts'
  */
 
 import { htmlUtf8 } from '../media/html/module.f.mjs'
 import { writeFile } from '../effects/node/module.f.mjs'
-/** @import { WriteFile } from '../effects/node/types.ts' */
 import { pure, step } from '../effects/module.f.mjs'
-/** @import { Effect } from '../effects/types.ts' */
 
 const html = htmlUtf8()(
     ['a',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "functionalscript",
-  "version": "0.44.0",
+  "version": "0.45.0",
   "type": "module",
   "files": [
     "**/*.js",
@@ -10,9 +10,9 @@
   ],
   "description": "FunctionalScript is a purely functional subset of JavaScript",
   "scripts": {
-    "prepack": "tsc --noEmit false --emitDeclarationOnly && tsc --noEmit false --declaration false",
+    "prepack": "tsc --noEmit false --emitDeclarationOnly && tsc",
     "test": "tsc && node ./fjs/module.mjs t",
-    "cov": "node --test --experimental-test-coverage --test-coverage-include=**/module.f.mjs fjs/emergent_testing/all.test.ts",
+    "cov": "node --test --experimental-test-coverage --test-coverage-include=**/module.f.mjs fjs/emergent_testing/all.test.mjs",
     "start": "node ./fjs/module.mjs",
     "ci-update": "node ./fjs/module.mjs ci && node ./fjs/module.mjs r ./fjs/nanvm/update/module.f.mjs",
     "dev-update": "node ./fjs/module.mjs r ./fjs/dev/update/module.f.mjs",

package/fjs/asn.1/types.js

@@ -1,6 +0,0 @@
-/**
- * Types for ASN.1 BER/DER encoding and decoding over bit vectors.
- *
- * @module
- */
-export {};

package/fjs/asserts/types.js

@@ -1,6 +0,0 @@
-/**
- * Type-level assertion helpers.
- *
- * @module
- */
-export {};

package/fjs/basen/types.js

@@ -1,6 +0,0 @@
-/**
- * Types for the shared bit-codec factory.
- *
- * @module
- */
-export {};

package/fjs/bnf/data/types.js

@@ -1,6 +0,0 @@
-/**
- * Types for the serializable BNF intermediate representation (IR).
- *
- * @module
- */
-export {};

package/fjs/bnf/descent/types.js

@@ -1,6 +0,0 @@
-/**
- * Types for the recursive descent matcher backend.
- *
- * @module
- */
-export {};

package/fjs/bnf/ll1/types.js

@@ -1,6 +0,0 @@
-/**
- * Types for the LL(1) dispatch/matcher backend.
- *
- * @module
- */
-export {};

package/fjs/bnf/token_symbol/types.js

@@ -1,6 +0,0 @@
-/**
- * Types for encoding multi-character token names as single BNF input symbols.
- *
- * @module
- */
-export {};

package/fjs/bnf/types.js

@@ -1,6 +0,0 @@
-/**
- * Type-level API for BNF grammar primitives and helpers.
- *
- * @module
- */
-export {};

package/fjs/cas/evo/types.js

@@ -1,7 +0,0 @@
-/**
- * Type-level API for `fjs/cas/evo/module.f.mjs`: the Evo cache shape and the
- * `Evo<O>` API surface it builds.
- *
- * @module
- */
-export {};

package/fjs/cas/types.js

@@ -1,6 +0,0 @@
-/**
- * Types for content-addressable storage utilities.
- *
- * @module
- */
-export {};

package/fjs/ci/common/types.js

@@ -1 +0,0 @@
-export {};

package/fjs/ci/nix/types.js

@@ -1,6 +0,0 @@
-/**
- * Types for generated CI Nix flakes.
- *
- * @module
- */
-export {};

package/fjs/ci/types.js

@@ -1,6 +0,0 @@
-/**
- * Types for the CI workflow generator.
- *
- * @module
- */
-export {};

package/fjs/cli/types.js

@@ -1,6 +0,0 @@
-/**
- * Types for the CLI command dispatch table.
- *
- * @module
- */
-export {};

package/fjs/common/monoid/types.js

@@ -1,6 +0,0 @@
-/**
- * The `Monoid<T>` algebraic structure.
- *
- * @module
- */
-export {};

package/fjs/crypto/pow/types.js

@@ -1,6 +0,0 @@
-/**
- * Types for Bitcoin-style proof-of-work verification.
- *
- * @module
- */
-export {};

package/fjs/crypto/secp/types.js

@@ -1,6 +0,0 @@
-/**
- * Types for short Weierstrass elliptic-curve arithmetic over a prime field.
- *
- * @module
- */
-export {};

package/fjs/crypto/sha2/types.js

@@ -1,6 +0,0 @@
-/**
- * Types for the SHA-2 family of hash functions.
- *
- * @module
- */
-export {};

package/fjs/crypto/sign/types.js

@@ -1,6 +0,0 @@
-/**
- * Type-level API for signing helpers built on secp256k1 and SHA-256 primitives.
- *
- * @module
- */
-export {};

package/fjs/crypto/vdf/types.js

@@ -1,6 +0,0 @@
-/**
- * Types for the Sloth verifiable delay function.
- *
- * @module
- */
-export {};

package/fjs/dev/types.js

@@ -1,6 +0,0 @@
-/**
- * Types for indexing modules and loading FunctionalScript files.
- *
- * @module
- */
-export {};