functionalscript 0.43.1 → 0.45.0

package/fjs/ci/rust/module.f.mjs

@@ -0,0 +1,108 @@
+/**
+ * CI step builder for the Rust crate: platform compatibility jobs run native
+ * tests and Clippy, Intel jobs also run 32-bit target tests and Clippy, and the
+ * canonical WASM job installs Wasmtime and Wasmer before exercising every WASM
+ * target.
+ *
+ * @module
+ *
+ * @import { Architecture, MetaStep, Os } from '../common/types.ts'
+ */
+
+import { wasmer, wasmtime } from '../config/module.f.mjs'
+import { install, test, uses } from '../common/module.f.mjs'
+
+/** @type {(tool: 'clippy' | 'test', target?: string, config?: string) => string} */
+const cargoCommand = (tool, target, config) => {
+    const to = target ? ` --target ${target}` : ''
+    const co = config ? ` --config ${config}` : ''
+    return `cargo ${tool}${to}${co}`
+}
+
+/** @type {(target?: string, config?: string) => MetaStep} */
+const cargoTest = (target, config) =>
+    test({ run: cargoCommand('test', target, config) })
+
+/** @type {(target?: string) => MetaStep} */
+const cargoClippy = target =>
+    test({ run: `${cargoCommand('clippy', target)} -- -D warnings` })
+
+/** @type {(target?: string) => MetaStep} */
+const cargoReleaseClippy = target =>
+    test({ run: `${cargoCommand('clippy', target)} --release -- -D warnings` })
+
+/** @type {(target: string, config?: string) => readonly MetaStep[]} */
+const cargoTestPair = (target, config) => {
+    const main = cargoCommand('test', target, config)
+    return [
+        cargoTest(target, config),
+        test({ run: `${main} --release` })
+    ]
+}
+
+/** @type {(target?: string) => MetaStep} */
+const cargoReleaseTest = target =>
+    test({ run: `${cargoCommand('test', target)} --release` })
+
+/** @type {(target?: string) => readonly MetaStep[]} */
+const targetChecks = target => [
+    cargoTest(target),
+    cargoReleaseTest(target),
+    cargoClippy(target),
+    cargoReleaseClippy(target)
+]
+
+/** @type {(target: string) => readonly MetaStep[]} */
+const rustTarget = target => [
+    { type: 'rust', target },
+    ...targetChecks(target)
+]
+
+/** @type {(target: string) => readonly MetaStep[]} */
+const wasmTarget = target => [
+    { type: 'rust', target },
+    ...targetChecks(target),
+    ...cargoTestPair(target, '.cargo/config.wasmer.toml')
+]
+
+// Wasmtime 47 removed wasi-threads, so the threads target runs under Wasmer
+// only; Clippy needs no runner and stays. See todo/blocked/wasmtime-threads.md.
+/** @type {(target: string) => readonly MetaStep[]} */
+const wasmerOnlyTarget = target => [
+    { type: 'rust', target },
+    cargoClippy(target),
+    cargoReleaseClippy(target),
+    ...cargoTestPair(target, '.cargo/config.wasmer.toml')
+]
+
+/** @type {(a: Architecture, v: Os) => readonly MetaStep[]} */
+const i686 = (a, v) => {
+    if (a === 'intel') {
+        switch (v) {
+            case 'windows': return rustTarget('i686-pc-windows-msvc')
+            case 'ubuntu': return [
+                { type: 'apt-get', package: 'libc6-dev-i386' },
+                ...rustTarget('i686-unknown-linux-gnu'),
+            ]
+        }
+    }
+    return []
+}
+
+/** @type {(v: Os, a: Architecture) => readonly MetaStep[]} */
+export const rustPlatformSteps = (v, a) => [
+    { type: 'rust' },
+    ...targetChecks(),
+    ...i686(a, v),
+]
+
+/** @type {readonly MetaStep[]} */
+export const rustWasmSteps = [
+    test({ run: 'cargo fmt -- --check' }),
+    install(uses('bytecodealliance/actions/wasmtime/setup', { version: wasmtime })),
+    install(uses('wasmerio/setup-wasmer', { version: `v${wasmer}` })),
+    ...wasmTarget('wasm32-wasip1'),
+    ...wasmTarget('wasm32-wasip2'),
+    ...wasmTarget('wasm32-unknown-unknown'),
+    ...wasmerOnlyTarget('wasm32-wasip1-threads'),
+]

package/fjs/ci/types.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Types for the CI workflow generator.
+ *
+ * @module
+ */
+import type { MetaStep, Os } from './common/types.ts';
+export type Setup = {
+    readonly nodeExtra: (os: Os) => readonly MetaStep[];
+};

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

@@ -0,0 +1,16 @@
+/**
+ * CLI command dispatch table.
+ *
+ * See `./types.ts` for the type-level API.
+ *
+ * @module
+ *
+ * @import { NodeOp, NodeProgramOptions, Write } from '../effects/node/types.ts'
+ * @import { Effect } from '../effects/types.ts'
+ * @import { Commands } from './types.ts'
+ */
+import type { NodeOp, NodeProgramOptions, Write } from '../effects/node/types.ts';
+import type { Effect } from '../effects/types.ts';
+import type { Commands } from './types.ts';
+/** @type {<O extends NodeOp>(commands: Commands<O>) => (options: NodeProgramOptions) => Effect<O | Write, number>} */
+export declare const dispatch: <O extends NodeOp>(commands: Commands<O>) => (options: NodeProgramOptions) => Effect<O | Write, number>;

package/fjs/cli/module.f.mjs

@@ -0,0 +1,51 @@
+/**
+ * CLI command dispatch table.
+ *
+ * See `./types.ts` for the type-level API.
+ *
+ * @module
+ *
+ * @import { NodeOp, NodeProgramOptions, Write } from '../effects/node/types.ts'
+ * @import { Effect } from '../effects/types.ts'
+ * @import { Commands } from './types.ts'
+ */
+
+import { errorExit, log } from '../effects/node/module.f.mjs'
+import { pure, step } from '../effects/module.f.mjs'
+import { at, fromEntries } from '../types/object/module.f.mjs'
+
+const helpMeta = { names: ['help', 'h', '?'], description: 'Print this help message' }
+
+/** @type {<O extends NodeOp>(commands: Commands<O>) => (options: NodeProgramOptions) => Effect<O | Write, number>} */
+export const dispatch = commands => options => {
+    const [cmd, ...rest] = options.args
+    const rows = [...commands, helpMeta]
+    const nameCol = rows.map(({names}) => names.join(', '))
+    const width = Math.max(...nameCol.map(({length}) => length))
+    const helpText = [
+        'Available commands:',
+        ...rows.map(({description}, i) => `  ${nameCol[i].padEnd(width)}  ${description}`)
+    ].join('\n')
+    const map = fromEntries(commands.flatMap(c => c.names.map(n => /** @type {const} */ ([n, c]))))
+    if (cmd === undefined) {
+        return errorExit(`Error: command is required.\n${helpText}`)
+    }
+    if (helpMeta.names.includes(cmd)) {
+        const [target] = rest
+        if (target !== undefined) {
+            const targetCmd = at(target)(map)
+            if (targetCmd !== null && typeof targetCmd.handler !== 'function') {
+                return dispatch(targetCmd.handler)({ ...options, args: ['help'] })
+            }
+        }
+        return step(
+            log(helpText),
+            () => pure(0))
+    }
+    const found = at(cmd)(map)
+    if (found === null) {
+        return errorExit(`Error: unknown command "${cmd}".\n${helpText}`)
+    }
+    const { handler } = found
+    return (typeof handler === 'function' ? handler : dispatch(handler))({ ...options, args: rest })
+}

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

@@ -0,0 +1,18 @@
+/**
+ * @import { NodeOp, NodeProgramOptions } from '../effects/node/types.ts'
+ * @import { Commands } from './types.ts'
+ */
+export declare const proof: {
+    knownCommand: () => void;
+    alias: () => void;
+    noArgs: () => void;
+    unknownCommand: () => void;
+    help: () => void;
+    errorIncludesAvailable: () => void;
+    handlerReceivesRemainingArgs: () => void;
+    nestedCommands: () => void;
+    nestedHelp: () => void;
+    prototypeNameIsUnknownCommand: () => void;
+    helpPrototypeSafe: () => void;
+    helpWithTarget: () => void;
+};

package/fjs/cli/proof.f.mjs

@@ -0,0 +1,132 @@
+/**
+ * @import { NodeOp, NodeProgramOptions } from '../effects/node/types.ts'
+ * @import { Commands } from './types.ts'
+ */
+
+import { pure } from '../effects/module.f.mjs'
+import { defaultNodeProgramOptions, emptyState, virtual } from '../effects/node/virtual/module.f.mjs'
+import { dispatch } from './module.f.mjs'
+import { assert, assertEq } from '../asserts/module.f.mjs'
+
+/** @type {(args: readonly string[]) => NodeProgramOptions} */
+const makeOptions = args =>
+    ({ ...defaultNodeProgramOptions, args })
+
+/** @type {Commands<NodeOp>} */
+const echoCommands = [
+    {
+        names: ['echo', 'e'],
+        description: 'Print the first argument',
+        handler: ({ args: [arg = ''] }) => pure(arg.length),
+    },
+]
+
+const run = (/** @type {Commands<NodeOp>} */ commands) => (/** @type {readonly string[]} */ args) =>
+    virtual(emptyState)(dispatch(commands)(makeOptions(args)))
+
+export const proof = {
+    knownCommand: () => {
+        const [, code] = run(echoCommands)(['echo', 'hello'])
+        assertEq(code, 5, ['expected length 5', code])
+    },
+    alias: () => {
+        const [, code] = run(echoCommands)(['e', 'hi'])
+        assertEq(code, 2, ['expected length 2', code])
+    },
+    noArgs: () => {
+        const [state, code] = run(echoCommands)([])
+        assertEq(code, 1, ['expected exit 1', code])
+        assert(state.stderr.length !== 0, 'expected error in stderr')
+    },
+    unknownCommand: () => {
+        const [state, code] = run(echoCommands)(['bogus'])
+        assertEq(code, 1, ['expected exit 1', code])
+        assert(state.stderr.length !== 0, 'expected error in stderr')
+    },
+    help: () => {
+        const [state, code] = run(echoCommands)(['help'])
+        assertEq(code, 0, ['expected exit 0', code])
+        assert(state.stdout.includes('echo'), 'expected command name in stdout')
+        assert(state.stdout.includes('help'), 'expected help entry in stdout')
+    },
+    errorIncludesAvailable: () => {
+        const [state] = run(echoCommands)(['bogus'])
+        assert(state.stderr.includes('echo'), 'expected available commands in error')
+    },
+    handlerReceivesRemainingArgs: () => {
+        /** @type {string[]} */
+        const captured = []
+        /** @type {Commands<NodeOp>} */
+        const commands = [{
+            names: ['grab'],
+            description: 'Capture args',
+            handler: (/** @type {{ args: readonly string[] }} */ { args }) => {
+                captured.push(...args)
+                return pure(0)
+            },
+        }]
+        run(commands)(['grab', 'a', 'b', 'c'])
+        assertEq(captured.join(','), 'a,b,c', ['unexpected args', captured])
+    },
+    nestedCommands: () => {
+        /** @type {Commands<NodeOp>} */
+        const inner = [{
+            names: ['ping'],
+            description: 'Inner ping',
+            handler: () => pure(42),
+        }]
+        /** @type {Commands<NodeOp>} */
+        const outer = [{
+            names: ['sub'],
+            description: 'Subcommand group',
+            handler: inner,
+        }]
+        const [, code] = run(outer)(['sub', 'ping'])
+        assertEq(code, 42, ['expected 42', code])
+    },
+    nestedHelp: () => {
+        /** @type {Commands<NodeOp>} */
+        const inner = [{
+            names: ['ping'],
+            description: 'Inner ping',
+            handler: () => pure(0),
+        }]
+        /** @type {Commands<NodeOp>} */
+        const outer = [{
+            names: ['sub'],
+            description: 'Subcommand group',
+            handler: inner,
+        }]
+        const [state, code] = run(outer)(['sub', 'help'])
+        assertEq(code, 0, ['expected exit 0', code])
+        assert(state.stdout.includes('ping'), 'expected inner command in help')
+    },
+    prototypeNameIsUnknownCommand: () => {
+        const [state, code] = run(echoCommands)(['toString'])
+        assertEq(code, 1, ['expected exit 1 for prototype-name command', code])
+        assert(state.stderr.includes('unknown command'), 'expected unknown-command error in stderr')
+    },
+    helpPrototypeSafe: () => {
+        const [state, code] = run(echoCommands)(['help', 'toString'])
+        assertEq(code, 0, ['expected exit 0, not a throw', code])
+        assert(state.stdout.includes('echo'), 'expected top-level help for unknown target')
+    },
+    helpWithTarget: () => {
+        /** @type {Commands<NodeOp>} */
+        const inner = [{
+            names: ['ping'],
+            description: 'Inner ping',
+            handler: () => pure(0),
+        }]
+        /** @type {Commands<NodeOp>} */
+        const outer = [{
+            names: ['sub'],
+            description: 'Subcommand group',
+            handler: inner,
+        }]
+        const [state, code] = run(outer)(['help', 'sub'])
+        assertEq(code, 0, ['expected exit 0', code])
+        assert(state.stdout.includes('ping'), 'expected inner command in help')
+        assert(!(state.stdout.includes('Subcommand group')), 'expected inner help, not outer')
+    },
+}

package/fjs/cli/types.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Types for the CLI command dispatch table.
+ *
+ * @module
+ */
+import type { NodeOp, NodeProgramOptions } from '../effects/node/types.ts';
+import type { Effect } from '../effects/types.ts';
+type Handler<O extends NodeOp> = (options: NodeProgramOptions) => Effect<O, number>;
+export type Command<O extends NodeOp> = {
+    readonly names: readonly string[];
+    readonly description: string;
+    readonly handler: Handler<O> | Commands<O>;
+};
+export type Commands<O extends NodeOp> = readonly Command<O>[];
+export {};

package/fjs/common/monoid/module.f.d.mts

@@ -0,0 +1,145 @@
+/**
+ * Monoids: the `Monoid<T>` algebraic structure (identity plus associative
+ * binary operation), `repeat`, which applies the operation `n` times using
+ * exponentiation by squaring, and `fold`, which applies it across every element
+ * of a list as a balanced binary tree.
+ *
+ * @module
+ *
+ * @import { Fold, Reduce } from '../../types/function/operator/types.ts'
+ * @import { Accumulator, List } from  '../../types/list/types.ts'
+ * @import { Absorbing, Monoid } from './types.ts'
+ */
+import type { Fold } from '../../types/function/operator/types.ts';
+import type { List } from '../../types/list/types.ts';
+import type { Absorbing, Monoid } from './types.ts';
+/**
+ * Repeats a monoid operation `n` times on the given element `a`.
+ * This function efficiently performs the operation using exponentiation by squaring.
+ *
+ * @template T The type of the elements in the monoid.
+ * @param {Monoid<T>} monoid The monoid structure, including the identity and binary operation.
+ * @returns {Fold<bigint, T>} A function that takes an element `a` and a repetition count `n`,
+ * and returns the result of applying the operation `n` times.
+ *
+ * See also {@link https://en.wikipedia.org/wiki/Exponentiation_by_squaring}.
+ *
+ * @example
+ *
+ * ```ts
+ * const add: Monoid<number> = {
+ *     identity: 0,
+ *     operation: a => b => a + b,
+ * };
+ *
+ * const resultAdd = repeat(add)(10n)(2) // 20
+ *
+ * const concat: Monoid<string> = {
+ *     identity: '',
+ *     operation: a => b => a + b,
+ * };
+ *
+ * const resultConcat = repeat(concat)(3n)('ha') // 'hahaha'
+ * ```
+ */
+export declare const repeat: <T>({ identity, operation }: Monoid<T>) => Fold<bigint, T>;
+export type _Run<T> = {
+    readonly size: number;
+    readonly value: T;
+    readonly rest: _Stack<T>;
+};
+export type _Stack<T> = _Run<T> | null;
+/**
+ * Reduces a `List<T>` with the monoid's associative `operation`, seeded at its
+ * `identity`. An empty list folds to `identity`.
+ *
+ * `fold` is the reduction companion of {@link repeat}: where `repeat` applies
+ * the operation a fixed number of times to a single element, `fold` applies it
+ * across every element of a list. Together they let list reductions such as
+ * `sum`, `product`, and string `concat` be expressed directly as monoid folds,
+ * so the identity paired with each operation is stated once at the call site
+ * instead of hand-seeding a raw `reduce`.
+ *
+ * The reduction is **balanced**, not a left fold: `[a, b, c, d]` folds to
+ * `(a op b) op (c op d)`, not `((a op b) op c) op d`. A `Monoid`'s
+ * associativity is what licenses the re-grouping — `list.reduce` takes an
+ * arbitrary operation with no such contract and therefore stays strictly
+ * left-to-right. Balancing matters for size-growing exact operations
+ * (`bigint.product`, `string`/`bit_vec` concatenation): a left fold grows the
+ * accumulator while every new operand stays small, so step *k* costs work
+ * proportional to *k* and the total is O(n²), while merging runs of comparable
+ * size costs O(n log n). It is the list-shaped sibling of {@link repeat}'s
+ * exponentiation by squaring.
+ *
+ * Only the grouping changes, never the order: each merge keeps the earlier
+ * operand on the left, so `fold` stays correct for non-commutative monoids
+ * (e.g. string concatenation as `a => b => a + b`).
+ *
+ * Re-grouping does move the rounding of an inexact operation. IEEE-754 addition
+ * is not truly associative, so `number.sum` returns a (marginally more
+ * accurate — O(log n · ε) instead of O(n · ε)) different value than a left fold
+ * for some inputs. That is a consequence of the uniform treatment, not a goal:
+ * a `Monoid` promises associativity, and every monoid folds the same way.
+ *
+ * @template T The type of the elements in the monoid.
+ * @param {Monoid<T>} monoid The monoid structure, including the identity and binary operation.
+ * @returns {(list: List<T>) => T} A function that reduces a `List<T>` to a single `T`.
+ *
+ * @example
+ *
+ * ```ts
+ * const add: Monoid<number> = {
+ *     identity: 0,
+ *     operation: a => b => a + b,
+ * };
+ *
+ * fold(add)([1, 2, 3, 4]) // 10
+ * fold(add)([])           // 0
+ *
+ * const concat: Monoid<string> = {
+ *     identity: '',
+ *     operation: a => b => a + b,
+ * };
+ *
+ * fold(concat)(['a', 'b', 'c']) // 'abc' — order preserved
+ * ```
+ */
+export declare const fold: <T>(monoid: Monoid<T>) => (list: List<T>) => T;
+/**
+ * {@link fold} for a monoid with an absorbing element, stopping at the first
+ * element that reaches it.
+ *
+ * The result is the same as `fold`'s — combining `absorbing` with the rest of
+ * the list is `absorbing` again — but the rest of the list is never read. That
+ * is what makes it usable on an unbounded lazy `List`, where `fold` keeps
+ * pulling elements forever after the answer is already decided.
+ *
+ * It stops as soon as a **run** reaches `absorbing`: immediately when an element
+ * is absorbing on its own (`0` in a product), otherwise at the merge that first
+ * produces it. When only a combination is absorbing — `bit_vec`'s length cap —
+ * that merge can lag the element that actually decided the answer, because runs
+ * merge at power-of-two boundaries: at most one doubling, so under twice as many
+ * elements as a left fold's per-element check would read. Bounded either way,
+ * which is the property that matters against an unbounded list.
+ *
+ * Grouping, order, and the `log2(n)` stack bound are `fold`'s; only the walk
+ * gains an exit. `foldAbsorbing(a)(list)` and `fold(a.monoid)(list)` agree on
+ * every finite list, including one whose folded value is itself `null`.
+ *
+ * @template T The type of the elements in the monoid.
+ * @param {Absorbing<T>} absorbing The monoid together with its absorbing element.
+ * @returns {(list: List<T>) => T} A function that reduces a `List<T>` to a single `T`.
+ *
+ * @example
+ *
+ * ```ts
+ * const multiply: Absorbing<number> = {
+ *     monoid: { identity: 1, operation: a => b => a * b },
+ *     absorbing: 0,
+ * }
+ *
+ * foldAbsorbing(multiply)([2, 3, 4]) // 24
+ * foldAbsorbing(multiply)([2, 0, 4]) // 0 — `4` is never read
+ * ```
+ */
+export declare const foldAbsorbing: <T>({ monoid, absorbing }: Absorbing<T>) => (list: List<T>) => T;