functionalscript 0.43.1 → 0.44.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/ci/types.js

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

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,16 @@
+/** @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,130 @@
+/** @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/cli/types.js

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

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

@@ -0,0 +1,87 @@
+/**
+ * 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.
+ *
+ * @module
+ *
+ * @import { Fold } from '../../types/function/operator/types.ts'
+ * @import { List } from  '../../types/list/types.ts'
+ * @import { Monoid } from './types.ts'
+ */
+import type { Fold } from '../../types/function/operator/types.ts';
+import type { List } from '../../types/list/types.ts';
+import type { 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>;
+/**
+ * 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`.
+ *
+ * Like `repeat`, `fold` applies the operation **accumulator-first**:
+ * `operation(accumulator)(element)`, seeded at `identity`, so
+ * `[a, b, c]` folds to `((identity op a) op b) op c`. Left-to-right order is
+ * therefore preserved and `fold` is correct for non-commutative monoids (e.g.
+ * string concatenation as `a => b => a + b`). `list.reduce` calls its reducer
+ * element-first, so the operation is `flip`ped before it is handed over.
+ *
+ * @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>({ identity, operation }: Monoid<T>) => (list: List<T>) => T;

package/fjs/common/monoid/module.f.mjs

@@ -0,0 +1,104 @@
+/**
+ * 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.
+ *
+ * @module
+ *
+ * @import { Fold } from '../../types/function/operator/types.ts'
+ * @import { List } from  '../../types/list/types.ts'
+ * @import { Monoid } from './types.ts'
+ */
+
+import { reduce } from '../../types/list/module.f.mjs'
+import { flip } from '../../types/function/module.f.mjs'
+
+/**
+ * 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 const repeat = ({ identity, operation }) => n => a => {
+    let ai = a
+    let ni = n
+    let result = identity
+    while (true) {
+        if ((ni & 1n) !== 0n) {
+            result = operation(result)(ai)
+        }
+        ni >>= 1n
+        if (ni === 0n) {
+            return result
+        }
+        ai = operation(ai)(ai)
+    }
+}
+
+/**
+ * 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`.
+ *
+ * Like `repeat`, `fold` applies the operation **accumulator-first**:
+ * `operation(accumulator)(element)`, seeded at `identity`, so
+ * `[a, b, c]` folds to `((identity op a) op b) op c`. Left-to-right order is
+ * therefore preserved and `fold` is correct for non-commutative monoids (e.g.
+ * string concatenation as `a => b => a + b`). `list.reduce` calls its reducer
+ * element-first, so the operation is `flip`ped before it is handed over.
+ *
+ * @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 const fold = ({ identity, operation }) =>
+    reduce(flip(operation))(identity)

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

@@ -0,0 +1,10 @@
+/** @import { Monoid } from './types.ts' */
+export declare const proof: {
+    numberAdd: () => void;
+    stringConcat: () => void;
+    fold: {
+        nonEmpty: () => void;
+        order: () => void;
+        empty: () => void;
+    };
+};

package/fjs/common/monoid/proof.f.mjs

@@ -0,0 +1,58 @@
+/** @import { Monoid } from './types.ts' */
+
+import { repeat, fold } from './module.f.mjs'
+import { assertEq } from '../../asserts/module.f.mjs'
+
+export const proof = {
+    numberAdd: () => {
+        /** @type {Monoid<number>} */
+        const add = {
+             identity: 0,
+             operation: a => b => a + b,
+        };
+        const resultAdd = repeat(add)(10n)(2) // 20
+        assertEq(resultAdd, 20)
+
+        const id = repeat(add)(0n)(42)
+        assertEq(id, 0)
+    },
+    stringConcat: () => {
+        /** @type {Monoid<string>} */
+        const concat = {
+             identity: '',
+             operation: a => b => a + b,
+        };
+
+        const resultConcat = repeat(concat)(3n)('ha') // 'hahaha'
+        assertEq(resultConcat, 'hahaha')
+    },
+    fold: {
+        nonEmpty: () => {
+            /** @type {Monoid<number>} */
+            const add = {
+                identity: 0,
+                operation: a => b => a + b,
+            };
+            assertEq(fold(add)([1, 2, 3, 4]), 10)
+        },
+        order: () => {
+            // a non-commutative monoid: `fold` must preserve left-to-right order
+            // (`((('' + 'a') + 'b') + 'c')`), not reverse it to `'cba'`.
+            /** @type {Monoid<string>} */
+            const concat = {
+                identity: '',
+                operation: a => b => a + b,
+            };
+            assertEq(fold(concat)(['a', 'b', 'c']), 'abc')
+        },
+        empty: () => {
+            /** @type {Monoid<string>} */
+            const concat = {
+                identity: '',
+                operation: a => b => a + b,
+            };
+            // an empty list folds to the identity
+            assertEq(fold(concat)([]), '')
+        },
+    }
+}

package/fjs/common/monoid/types.d.ts

@@ -0,0 +1,50 @@
+/**
+ * The `Monoid<T>` algebraic structure.
+ *
+ * @module
+ */
+import type { Reduce } from '../../types/function/operator/types.ts';
+/**
+ * Represents a monoid, an algebraic structure with a binary operation
+ * and an identity (neutral) element.
+ *
+ * A monoid satisfies the following properties:
+ * 1. **Associativity**: The operation must be associative.
+ *    For all `a`, `b`, and `c` in the set, `(a operation b) operation c = a operation (b operation c)`.
+ *    {@link https://en.wikipedia.org/wiki/Associative_property Learn more about associativity}.
+ * 2. **Identity Element**: There exists an element (called the identity) such that,
+ *    when combined with any other element under the operation, it leaves the other element unchanged.
+ *    {@link https://en.wikipedia.org/wiki/Identity_element Learn more about identity elements}.
+ *
+ * Learn more about monoids: {@link https://en.wikipedia.org/wiki/Monoid}.
+ *
+ * @property identity
+ *
+ * The identity (neutral) element for the monoid.
+ * When combined with any value under the `operation`, it leaves the other value unchanged.
+ *
+ * Examples:
+ * - `0` for addition
+ * - `1` for multiplication
+ * - `""` for string concatenation
+ * - `[]` for array concatenation
+ *
+ * Learn more: {@link https://en.wikipedia.org/wiki/Identity_element}
+ *
+ * @property operation
+ *
+ * The associative binary operation of the monoid.
+ * Takes one value of type `T` and returns a function that takes another value of type `T`,
+ * producing a result of type `T`.
+ *
+ * Examples:
+ * - `(a, b) => a + b` for addition
+ * - `(a, b) => a * b` for multiplication
+ * - `(a, b) => a.concat(b)` for arrays or strings
+ *
+ * Learn more: {@link https://en.wikipedia.org/wiki/Binary_operation}
+ */
+export type Monoid<T> = {
+    readonly identity: T;
+    readonly operation: Reduce<T>;
+};