functionalscript 0.45.0 → 0.46.0

package/fjs/effects/eff/proof.f.mjs

@@ -1,69 +0,0 @@
-/**
- * @import { Effect, OperationMap } from '../types.ts'
- */
-
-import { do_, match, pure } from '../module.f.mjs'
-import { assert, assertEq } from '../../asserts/module.f.mjs'
-import { assertPure } from '../proof.f.mjs'
-import { eff } from './module.f.mjs'
-
-/** @typedef {readonly['add', (a: number, b: number) => number]} _AddOp */
-
-/** @type {(command: 'add') => (a: number, b: number) => Effect<_AddOp, number>} */
-const doAdd = do_
-
-const next = match(/** @type {OperationMap<_AddOp, number>} */ ({ add: (a, b) => a + b }))
-
-export const proof = {
-    value: () => {
-        assertPure(eff(pure(5)).value, 5)
-    },
-    pure: () => {
-        assertPure(pure(5), 5)
-    },
-    chain: () => {
-        const x = eff(pure(5))
-            .step(v => pure(v + 1))
-            .step(v => pure(v * 2))
-            .value
-        assertPure(x, 12)
-    },
-    overDo: () => {
-        const e = eff(doAdd('add')(2, 3))
-            .step(r => pure(r + 1))
-            .value
-        const r = next(e)
-        assert(r[0] === 'cont', r)
-        assertEq(r[1], 5)
-        assertPure(r[2](r[1]), 6)
-    },
-    map: {
-        chain: () => {
-            const x = eff(pure(5))
-                .map(v => v + 1)
-                .map(v => v * 2)
-                .value
-            assertPure(x, 12)
-        },
-        // `.map` grows the history exactly as `.step` does, so a callback after
-        // it still reaches the pre-`map` value. This is the contract that makes
-        // rewriting `.step(v => pure(f(v)))` into `.map(f)` a pure readability
-        // change rather than one that alters what later callbacks receive.
-        growsHistory: () => {
-            const x = eff(pure(5))
-                .map(v => v + 1)
-                .step((v, prev) => pure(`${prev}${v}`))
-                .value
-            assertPure(x, '56')
-        },
-        overDo: () => {
-            const e = eff(doAdd('add')(2, 3))
-                .map(r => r + 1)
-                .value
-            const r = next(e)
-            assert(r[0] === 'cont', r)
-            assertEq(r[1], 5)
-            assertPure(r[2](r[1]), 6)
-        },
-    },
-}

package/fjs/effects/eff/types.d.ts

@@ -1,71 +0,0 @@
-/**
- * Types for the `Eff` fluent, method-chaining monad.
- *
- * @module
- */
-import type { Effect, Operation } from '../types.ts';
-/**
- * A fluent, method-chaining monad over a raw `Effect` that also
- * accumulates the history of every value the chain has produced. `.step(f)`
- * is bind — `f` receives the current value followed by every prior value,
- * most recent first (`f(t, ...p)`), and returns a raw `Effect`; `.step`
- * re-wraps the result together with that history so `.step(f).step(g)`
- * chains and stays in the `Eff` world throughout. `.map(f)` is the functor
- * map — the same thing for an `f` that returns a plain value rather than an
- * effect, so it is exactly `.step((...tp) => pure(f(...tp)))`. `P` is the
- * tuple of prior values available to the *next* `.step` call; it grows by one
- * element (the current `T`) on every step, starting empty at `eff`.
- * `.value` is the exit back to a raw `Effect`, discarding the history. An
- * `Eff` is not assignable to `Effect`; unwrap through `.value`.
- *
- * **`.map` grows the history just as `.step` does, and does not widen `O`.**
- * Both follow from it being that `.step` call and nothing else: a chain
- * rewritten from `.step(v => pure(f(v)))` to `.map(f)` must hand later
- * callbacks the same prior values it did before, and a projection performs no
- * command, so it contributes no operation for a runner to interpret.
- *
- * **The history is positional, so every parameter a callback declares is
- * meaningful.** `f` is applied as `f(...tp)`, so a callback written
- * `(v, n = 1) => …` or `(v, ...rest) => …` receives prior chain values in `n` /
- * `rest` rather than the default or an empty rest — and where the types line up,
- * TypeScript will not object. Declare exactly as many parameters as the callback
- * intends to read; a defaulted or rest parameter after the current value is a
- * bug, not a convenience. This is what makes `.map(g)` a *different* call from
- * `.step(v => pure(g(v)))` whenever `g` is not genuinely unary — the lambda
- * pins the arity at one, while passing `g` point-free exposes it to the prior
- * values, the way `['1', '2', '3'].map(parseInt)` does.
- *
- * **`.value` is always an already-built `Effect`.** Reading it composes
- * nothing: the projection that drops the history tuple to its current value is
- * performed by the `.step` that produced the link, not deferred to the read.
- * An `Eff` is a record to look into, not an object with a method that quietly
- * does work when called.
- *
- * That costs one projection per link, paid whether or not the link is ever
- * unwrapped — an n-link chain builds n of them where a deferred `.result()`
- * method would build one. It is a constant factor on construction, with no
- * extra forcing of the wrapped effect and no change in growth rate, bought in
- * exchange for a uniform rule at the boundary every caller touches.
- *
- * At the entry it costs nothing at all: `eff(e).value` **is** `e`, because
- * `eff` stores what it was handed rather than rebuilding it from the
- * history, so wrapping and unwrapping round-trip to identity. `h` is still a
- * thunk, so `eff(e)` composes nothing and never forces `e`: an `Eff` that is
- * built and only read does no work at all.
- *
- * **`P` has no default, on purpose.** A default of `readonly[]` would make
- * `Eff<O, T>` a spelling that silently erases history: an
- * `Eff<O, T, readonly[A]>` is assignable to it, because `f` sits in a
- * contravariant position and TypeScript accepts a callback declaring fewer
- * parameters than the type it is checked against. The next `.step` callback
- * would then be typed as receiving no prior values while the runtime still
- * passes them, and any callback destructuring a rest parameter would be handed
- * entries its type says cannot exist. Requiring the third argument means that
- * erasure cannot be written at all, rather than merely being discouraged;
- * `eff` spells `readonly[]` itself.
- */
-export type Eff<O extends Operation, T, P extends readonly unknown[]> = {
-    readonly value: Effect<O, T>;
-    readonly step: <Q extends Operation, R>(f: (...tp: readonly [T, ...P]) => Effect<Q, R>) => Eff<O | Q, R, readonly [T, ...P]>;
-    readonly map: <R>(f: (...tp: readonly [T, ...P]) => R) => Eff<O, R, readonly [T, ...P]>;
-};

package/fjs/types/rtti/validate/module.f.d.mts

@@ -1,41 +0,0 @@
-/**
- * Runtime validation of unknown values against RTTI schemas.
- *
- * The main entry point is `validate(rtti)`, which takes a schema `Type` and returns
- * a `Validate<T>` function. When called with an unknown value, it returns a `Result`
- * that is either `['ok', typedValue]` or `['error', { path, message }]`.
- *
- * ## Error path
- *
- * On failure, the error carries a `path` pointing at the offending sub-value:
- * each step is the string property name (for structs/records) or the stringified
- * index (for tuples/arrays). The path is empty when the failure is at the root.
- *
- * ## Dispatch strategy
- *
- * Schema recognition is delegated to `visit` in `../common/module.f.mjs`,
- * which routes each `Type` variant to a handler in the `Visitor` record
- * defined below. `validate` returns the original value on success — no
- * fresh allocation — which is the only behavior that distinguishes it
- * from `parse`.
- *
- * ## Recursion safety
- *
- * For `array` and `record` schemas, the inner item validator is instantiated lazily —
- * only after confirming the container is non-empty. This prevents infinite recursion
- * when validating recursive schemas like `const list = () => ['array', list]`.
- *
- * 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 type { Type } from '../types.ts';
-import type { Validate } from '../common/types.ts';
-export { constPrimitiveValidate, prependPath, primitive0Validate, verror, } from '../common/module.f.mjs';
-/** @type {<T extends Type>(rtti: T) => Validate<T>} */
-export declare const validate: <T extends Type>(rtti: T) => Validate<T>;

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

@@ -1,171 +0,0 @@
-/**
- * Runtime validation of unknown values against RTTI schemas.
- *
- * The main entry point is `validate(rtti)`, which takes a schema `Type` and returns
- * a `Validate<T>` function. When called with an unknown value, it returns a `Result`
- * that is either `['ok', typedValue]` or `['error', { path, message }]`.
- *
- * ## Error path
- *
- * On failure, the error carries a `path` pointing at the offending sub-value:
- * each step is the string property name (for structs/records) or the stringified
- * index (for tuples/arrays). The path is empty when the failure is at the root.
- *
- * ## Dispatch strategy
- *
- * Schema recognition is delegated to `visit` in `../common/module.f.mjs`,
- * which routes each `Type` variant to a handler in the `Visitor` record
- * defined below. `validate` returns the original value on success — no
- * fresh allocation — which is the only behavior that distinguishes it
- * from `parse`.
- *
- * ## Recursion safety
- *
- * For `array` and `record` schemas, the inner item validator is instantiated lazily —
- * only after confirming the container is non-empty. This prevents infinite recursion
- * when validating recursive schemas like `const list = () => ['array', list]`.
- *
- * 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 { ok } from '../../result/module.f.mjs'
-import {
-    constPrimitiveValidate,
-    eachEntry,
-    isArray,
-    isObject,
-    orVisit,
-    primitive0Validate,
-    verror,
-    visit,
-} from '../common/module.f.mjs'
-
-export {
-    constPrimitiveValidate,
-    prependPath,
-    primitive0Validate,
-    verror,
-} from '../common/module.f.mjs'
-
-const { entries } = Object
-
-/** `validate` has nothing to collect from a successful entry — only pass/fail matters. */
-const noAccumulate = () => undefined
-
-/**
- * Builds a validator for `array` or `record` schemas.
- * The inner item validator is instantiated lazily (only when the container is
- * non-empty) to avoid infinite recursion with recursive schemas.
- */
-const containerValidate =
-    /**
-     * @template {Tag1} K
-     * @param {IsContainer<Container<K>>} isContainer
-     * @returns {<I extends Type>(item: I) => Validate<Info1<K, I>>}
-     */
-    isContainer =>
-    item => value => {
-        if (!isContainer(value)) {
-            return verror('unexpected value')
-        }
-        const e = entries(value)
-        if (e.length === 0) {
-            return ok(value)
-        }
-        // Note: we shouldn't instantiate `itemValidate` until we make sure `entries` is not empty.
-        //       Otherwise, we can get infinite recursion on empty arrays and objects
-        const itemValidate = validate(item)
-        const r = eachEntry(e, (_k, v) => itemValidate(v), undefined, noAccumulate)
-        // `value` is Container<K>, but Ts<Info1<K,I>> = readonly Ts<I>[] | Record<string,Ts<I>>.
-        // TypeScript can't narrow the container's element types through the validation loop.
-        return r[0] === 'error' ? r : /** @type {any} */ (ok(value))
-    }
-
-const arrayValidate = containerValidate(isArray)
-
-const recordValidate = containerValidate(isObject)
-
-/**
- * Builds a validator for `Tuple` or `Struct` const schemas.
- * Iterates over the schema's entries and validates each corresponding
- * element/property of the value.
- */
-const constContainerValidate =
-    /**
-     * @template {Unknown} C
-     * @param {IsContainer<C>} isContainer
-     * @param {(value: C, k: string) => Unknown} getItem
-     * @returns {<T extends Tuple | Struct>(rtti: T) => Validate<T>}
-     */
-    (isContainer, getItem) =>
-    rtti => value => {
-        if (!isContainer(value)) {
-            return verror('unexpected value')
-        }
-        const r = eachEntry(
-            Object.entries(rtti),
-            (k, v) => /** @type {any} */ (validate(v))(getItem(value, k)),
-            undefined,
-            noAccumulate,
-        )
-        // `value` is C (Unknown container), but Ts<T> for T extends Tuple|Struct is not
-        // structurally equivalent to C — TypeScript can't narrow element types through the loop.
-        return r[0] === 'error' ? r : /** @type {any} */ (ok(value))
-    }
-
-const tupleValidate = constContainerValidate(
-    isArray,
-    (value, k) => value[Number(k)]
-)
-
-const structValidate = constContainerValidate(
-    isObject,
-    (value, k) => value[k]
-)
-
-const orValidate =
-    /**
-     * @template {readonly Type[]} T
-     * @param {T} rtti
-     * @returns {Validate<() => readonly ['or', ...T]>}
-     */
-    rtti =>
-        /** @type {any} */ (orVisit(/** @type {(t: Type) => ValidateE} */ (/** @type {any} */ (validate)))(rtti))
-
-/**
- * Creates a validator function for the given RTTI schema.
- *
- * @param rtti - A schema `Type`: a `Thunk` for tag-based schemas, or a `Const`
- *   (primitive literal, tuple, or struct) for exact-value schemas.
- * @returns A `Validate<T>` function that checks an unknown value and returns
- *   `['ok', value]` or `['error', { path, message }]`.
- *
- * @example
- * ```js
- * const v = validate(array(number))
- * v([1, 2, 3])         // ['ok', [1, 2, 3]]
- * v([1, 'two'])        // ['error', { path: ['1'], message: 'unexpected value' }]
- * v(['a'])             // ['error', { path: ['0'], message: 'unexpected value' }]
- * ```
- */
-const validateVisitor = /** @type {any} */ ({
-    tuple: tupleValidate,
-    struct: structValidate,
-    array: arrayValidate,
-    record: recordValidate,
-    or: orValidate,
-    constPrimitive: constPrimitiveValidate,
-    primitive0: primitive0Validate,
-    unknown: () => ok,
-})
-
-/** @type {<T extends Type>(rtti: T) => Validate<T>} */
-export const validate = rtti =>
-    /** @type {any} */ (visit(validateVisitor)(rtti))

package/fjs/types/rtti/validate/proof.f.d.mts

@@ -1,125 +0,0 @@
-/**
- * @import { ValidationError } from '../common/types.ts'
- * @import { Equal } from '../../ts/types.ts'
- * @import { Ts } from '../ts/types.ts'
- * @import { Unknown as DjsUnknown } from '../../../djs/types.ts'
- * @import { Assert } from '../../../asserts/types.ts'
- */
-export declare const proof: {
-    boolean: {
-        ok: () => void;
-        error: () => void;
-    };
-    number: {
-        ok: () => void;
-        error: () => void;
-    };
-    string: {
-        ok: () => void;
-        error: () => void;
-    };
-    bigint: {
-        ok: () => void;
-        error: () => void;
-    };
-    unknown: {
-        ok: () => void;
-    };
-    const: {
-        null: {
-            ok: () => void;
-            error: () => void;
-        };
-        undefined: {
-            ok: () => void;
-            error: () => void;
-        };
-        number: {
-            ok: () => void;
-            error: () => void;
-        };
-        nan: {
-            ok: () => void;
-            error: () => void;
-        };
-        infinity: {
-            ok: () => void;
-            error: () => void;
-        };
-        signedZero: {
-            distinct: () => void;
-            self: () => void;
-        };
-        string: {
-            ok: () => void;
-            error: () => void;
-        };
-        bigint: {
-            ok: () => void;
-            error: () => void;
-        };
-        boolean: {
-            ok: () => void;
-            error: () => void;
-        };
-        tuple: {
-            ok: () => void;
-            extraItems: () => void;
-            error: () => void;
-        };
-        struct: {
-            ok: () => void;
-            extraKeys: () => void;
-            error: () => void;
-        };
-    };
-    array: {
-        empty: () => void;
-        ok: () => void;
-        error: () => void;
-        nested: () => void;
-    };
-    record: {
-        empty: () => void;
-        ok: () => void;
-        error: () => void;
-    };
-    constThunk: {
-        primitive: () => void;
-    };
-    or: {
-        consts: {
-            ok: () => void;
-            error: () => void;
-        };
-        thunks: {
-            ok: () => void;
-            error: () => void;
-        };
-        mixed: {
-            ok: () => void;
-            error: () => void;
-        };
-    };
-    option: {
-        ok: () => void;
-        error: () => void;
-    };
-    path: {
-        rootMismatch: () => void;
-        arrayIndex: () => void;
-        recordKey: () => void;
-        nestedArray: () => void;
-        tupleIndex: () => void;
-        structKey: () => void;
-        deepStruct: () => void;
-        recursiveSchema: () => void;
-        orRoot: () => void;
-    };
-    recursive: {
-        arrayOfArrays: () => void;
-        recordOfRecords: () => void;
-    };
-    funcParam: () => () => void;
-    funcObj: () => () => void;
-};