functionalscript 0.44.0 → 0.46.0

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/package_json/module.f.d.mts

@@ -1,32 +0,0 @@
-/**
- * Helpers for reading package.json-style metadata without losing unrelated
- * fields before write-back.
- *
- * @module
- *
- * @import { ValidationError } from '../../types/rtti/common/types.ts'
- * @import { Ts } from '../../types/rtti/ts/types.ts'
- * @import { Result } from '../../types/result/types.ts'
- */
-import type { ValidationError } from '../../types/rtti/common/types.ts';
-import type { Ts } from '../../types/rtti/ts/types.ts';
-import type { Result } from '../../types/result/types.ts';
-export declare const packageJsonSchema: {
-    readonly name: import("../../types/rtti/types.ts").Or<readonly [import("../../types/rtti/types.ts")._Type0<"string">, undefined]>;
-    readonly version: import("../../types/rtti/types.ts").Or<readonly [import("../../types/rtti/types.ts")._Type0<"string">, undefined]>;
-    readonly scripts: import("../../types/rtti/types.ts").Or<readonly [import("../../types/rtti/types.ts").Type1<"record", import("../../types/rtti/types.ts")._Type0<"string">>, undefined]>;
-};
-export type PackageJson = Ts<typeof packageJsonSchema>;
-export type JsonTextError = string | ValidationError;
-/** @typedef {Ts<typeof packageJsonSchema>} PackageJson */
-/** @typedef {string | ValidationError} JsonTextError */
-export declare const validatePackageJson: import("../../types/rtti/common/types.ts").Validate<{
-    readonly name: import("../../types/rtti/types.ts").Or<readonly [import("../../types/rtti/types.ts")._Type0<"string">, undefined]>;
-    readonly version: import("../../types/rtti/types.ts").Or<readonly [import("../../types/rtti/types.ts")._Type0<"string">, undefined]>;
-    readonly scripts: import("../../types/rtti/types.ts").Or<readonly [import("../../types/rtti/types.ts").Type1<"record", import("../../types/rtti/types.ts")._Type0<"string">>, undefined]>;
-}>;
-/**
- * @param {string} text
- * @returns {Result<PackageJson, JsonTextError>}
- */
-export declare const validatePackageJsonText: (text: string) => Result<PackageJson, JsonTextError>;

package/fjs/dev/package_json/module.f.mjs

@@ -1,37 +0,0 @@
-/**
- * Helpers for reading package.json-style metadata without losing unrelated
- * fields before write-back.
- *
- * @module
- *
- * @import { ValidationError } from '../../types/rtti/common/types.ts'
- * @import { Ts } from '../../types/rtti/ts/types.ts'
- * @import { Result } from '../../types/result/types.ts'
- */
-
-import { parse as parseJsonText } from '../../media/json/module.f.mjs'
-import { option, record, string } from '../../types/rtti/module.f.mjs'
-import { validate as rttiValidate } from '../../types/rtti/validate/module.f.mjs'
-import { error, ok } from '../../types/result/module.f.mjs'
-
-export const packageJsonSchema = /** @type {const} */ ({
-    name: option(string),
-    version: option(string),
-    scripts: option(record(string)),
-})
-
-/** @typedef {Ts<typeof packageJsonSchema>} PackageJson */
-/** @typedef {string | ValidationError} JsonTextError */
-
-export const validatePackageJson = rttiValidate(packageJsonSchema)
-
-/**
- * @param {string} text
- * @returns {Result<PackageJson, JsonTextError>}
- */
-export const validatePackageJsonText = text => {
-    const [t, v] = parseJsonText(text)
-    if (t === 'error') { return error(v) }
-    const [t2, v2] = validatePackageJson(v)
-    return t2 === 'ok' ? ok(v2) : error(v2)
-}

package/fjs/dev/package_json/proof.f.d.mts

@@ -1,6 +0,0 @@
-export declare const proof: {
-    parseMetadata: () => void;
-    malformedJson: () => void;
-    validationError: () => void;
-    validatePreservesOriginalObject: () => void;
-};

package/fjs/dev/package_json/proof.f.mjs

@@ -1,32 +0,0 @@
-import { assert, assertEq } from '../../asserts/module.f.mjs'
-import { unwrap } from '../../types/result/module.f.mjs'
-import {
-    validatePackageJson,
-    validatePackageJsonText,
-} from './module.f.mjs'
-
-export const proof = {
-    parseMetadata: () => {
-        const result = unwrap(validatePackageJsonText('{"name":"x","version":"1.0.0","scripts":{"test":"node test.js"}}'))
-        assertEq(result.name, 'x', result)
-        assertEq(result.version, '1.0.0', result)
-        assertEq(result.scripts?.test, 'node test.js', result)
-    },
-    malformedJson: () => {
-        const result = validatePackageJsonText('{')
-        assert(result[0] === 'error', result)
-    },
-    validationError: () => {
-        // valid JSON but `name` is a number, not a string — validation should fail
-        const result = validatePackageJsonText('{"name": 42}')
-        assert(result[0] === 'error', result)
-    },
-    validatePreservesOriginalObject: () => {
-        const object = /** @type {const} */ ({ name: 'x', version: '1.0.0', private: true })
-        const metadata = unwrap(validatePackageJson(object))
-        assertEq(metadata.name, 'x', metadata)
-        assertEq(metadata.version, '1.0.0', metadata)
-        assert(Object.is(metadata, object), metadata)
-        assertEq(object.private, true, object)
-    },
-}

package/fjs/dev/types.js

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

package/fjs/djs/ast/types.js

@@ -1,8 +0,0 @@
-/**
- * Type-level API for `fjs/djs/ast/module.f.mjs`: the AST shape `run`
- * evaluates — `AstModule`, `AstConst`, `AstModuleRef`, `AstArray`,
- * `AstObject`, and `AstBody`.
- *
- * @module
- */
-export {};

package/fjs/djs/parser/types.js

@@ -1,7 +0,0 @@
-/**
- * Type-level API for `fjs/djs/parser/module.f.mjs`: the `ParseError` shape
- * `parseFromTokens` reports.
- *
- * @module
- */
-export {};

package/fjs/djs/tokenizer/types.js

@@ -1,7 +0,0 @@
-/**
- * Type-level API for `fjs/djs/tokenizer/module.f.mjs`: the DJS token shapes
- * `tokenize`/`tokenizeJs`/`tokenizeString` produce.
- *
- * @module
- */
-export {};

package/fjs/djs/types.js

@@ -1,7 +0,0 @@
-/**
- * DJS's own value model: `Primitive`, `Unknown`, `Object`, and `Array`,
- * layered on top of JSON's `Primitive` with `bigint` and `undefined` added.
- *
- * @module
- */
-export {};

package/fjs/effects/eff/module.f.d.mts

@@ -1,10 +0,0 @@
-import type { Effect, Operation } from '../types.ts';
-import type { Eff } from './types.ts';
-/**
- * Wraps a raw {@link Effect}; the bridge into the `Eff` world, with an empty
- * history. The empty tuple is spelled out because {@link Eff} deliberately has
- * no default for `P` — see its docs.
- *
- * @type {<O extends Operation, T>(value: Effect<O, T>) => Eff<O, T, readonly[]>}
- */
-export declare const eff: <O extends Operation, T>(value: Effect<O, T>) => Eff<O, T, readonly []>;

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

@@ -1,68 +0,0 @@
-/**
- * A fluent, method-chaining wrapper over the raw `Effect`.
- *
- * See `./types.ts` for the `Eff` type-level API.
- *
- * @module
- */
-import { history, historyStep, mapStep, pure } from '../module.f.mjs'
-/** @import { Effect, Operation } from '../types.ts' */
-/** @import { Eff } from './types.ts' */
-
-/**
- * Builds an `Eff` from two views of the same chain: `value`, the effect for the
- * current value alone, and `h`, a thunk for the `[current, ...history]` tuple.
- *
- * **The two must denote the same computation** — `value` has to be what `h()`
- * produces with the history dropped. Nothing enforces it. The
- * redundancy is deliberate: `value` used to be derived from `h` on demand,
- * which made disagreement impossible but also forced the entry case to rebuild
- * an effect it was already holding. Passing it in is what lets {@link eff} hand
- * the original back.
- *
- * The asymmetry between the two — one built, one deferred — is the point.
- * `value` is either already in hand ({@link eff} was given it) or already built
- * (`.step` has just composed the chain it projects from), so storing it costs
- * no more than the projection itself. `h` is different: nothing needs the
- * history tuple until a later `.step` asks for it, and composing effects is
- * eager, so holding a thunk is the only way to not compose it yet. That keeps
- * `eff(e)` free of work entirely.
- *
- * `.step` calls `h()` once and closes over the effect, so everything built
- * from that link shares it. `eff`'s thunk is not memoized, so calling `.step`
- * twice on the same `eff(e)` rebuilds and re-forces `e` — harmless under
- * `Pure`'s contract, which requires the thunk to be pure and to tolerate
- * repeat calls.
- *
- * @template {Operation} O
- * @template T
- * @template {readonly unknown[]} P
- * @param {Effect<O, T>} value
- * @param {() => Effect<O, readonly[T, ...P]>} h
- * @returns {Eff<O, T, P>}
- */
-const create = (value, h) => {
-    // `self` is named so `.map` can be *defined* as the `.step` call it is
-    // documented to equal, rather than as a second copy of `.step`'s body that
-    // has to be re-checked against it.
-    /** @type {Eff<O, T, P>} */
-    const self = {
-        value,
-        step: f => {
-            const x1 = historyStep(h(), f)
-            return create(mapStep(x1, ([t]) => t), () => x1)
-        },
-        map: f => self.step((...tp) => pure(f(...tp)))
-    }
-    return self
-}
-
-/**
- * Wraps a raw {@link Effect}; the bridge into the `Eff` world, with an empty
- * history. The empty tuple is spelled out because {@link Eff} deliberately has
- * no default for `P` — see its docs.
- *
- * @type {<O extends Operation, T>(value: Effect<O, T>) => Eff<O, T, readonly[]>}
- */
-export const eff = value =>
-    create(value, () => history(value))

package/fjs/effects/eff/proof.f.d.mts

@@ -1,12 +0,0 @@
-export type _AddOp = readonly ['add', (a: number, b: number) => number];
-export declare const proof: {
-    value: () => void;
-    pure: () => void;
-    chain: () => void;
-    overDo: () => void;
-    map: {
-        chain: () => void;
-        growsHistory: () => void;
-        overDo: () => void;
-    };
-};

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

@@ -1,66 +0,0 @@
-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'
-/** @import { Effect, OperationMap } from '../types.ts' */
-
-/** @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/effects/eff/types.js

@@ -1,6 +0,0 @@
-/**
- * Types for the `Eff` fluent, method-chaining monad.
- *
- * @module
- */
-export {};

package/fjs/effects/list/types.js

@@ -1,6 +0,0 @@
-/**
- * Types for the effectful cons-list.
- *
- * @module
- */
-export {};

package/fjs/effects/memory/types.js

@@ -1,6 +0,0 @@
-/**
- * Types for typed key-value memory effects.
- *
- * @module
- */
-export {};

package/fjs/effects/mock/types.js

@@ -1,6 +0,0 @@
-/**
- * Types for mock effect runtimes.
- *
- * @module
- */
-export {};

package/fjs/effects/node/types.js

@@ -1,6 +0,0 @@
-/**
- * Types for Node.js effect operations.
- *
- * @module
- */
-export {};

package/fjs/effects/node/virtual/types.js

@@ -1,7 +0,0 @@
-/**
- * Types for the virtual Node-effect operations used by filesystem and
- * process tests.
- *
- * @module
- */
-export {};

package/fjs/effects/types.js

@@ -1,6 +0,0 @@
-/**
- * Types for the core effect system.
- *
- * @module
- */
-export {};

package/fjs/emergent_testing/all.test.d.ts

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

package/fjs/emergent_testing/all.test.js

@@ -1,5 +0,0 @@
-import { runEffect } from '../effects/node/module.mjs';
-import { register } from './module.f.mjs';
-// Top-level `await`: every proof must be registered before the runner starts
-// collecting tests.
-await runEffect(register);

package/fjs/emergent_testing/scenarios/all.d.ts

@@ -1 +0,0 @@
-import '../all.test.ts';

package/fjs/emergent_testing/scenarios/all.js

@@ -1 +0,0 @@
-import '../all.test.js';

package/fjs/emergent_testing/scenarios/async-subtests.fail.d.ts

@@ -1,6 +0,0 @@
-export declare const proof: {
-    withSubtests: () => Promise<{
-        sub1: () => void;
-        sub2: () => never;
-    }>;
-};

package/fjs/emergent_testing/scenarios/async-subtests.fail.js

@@ -1,9 +0,0 @@
-export const proof = {
-    withSubtests: async () => {
-        await new Promise(resolve => setTimeout(resolve, 10));
-        return {
-            sub1: () => { },
-            sub2: () => { throw 'sub-test failure'; },
-        };
-    }
-};

package/fjs/emergent_testing/scenarios/async-subtests.pass.d.ts

@@ -1,6 +0,0 @@
-export declare const proof: {
-    withSubtests: () => Promise<{
-        sub1: () => void;
-        sub2: () => void;
-    }>;
-};

package/fjs/emergent_testing/scenarios/async-subtests.pass.js

@@ -1,9 +0,0 @@
-export const proof = {
-    withSubtests: async () => {
-        await new Promise(resolve => setTimeout(resolve, 10));
-        return {
-            sub1: () => { },
-            sub2: () => { },
-        };
-    }
-};

package/fjs/emergent_testing/scenarios/async.fail.d.ts

@@ -1,3 +0,0 @@
-export declare const proof: {
-    sleep_fail: () => Promise<never>;
-};

package/fjs/emergent_testing/scenarios/async.fail.js

@@ -1,6 +0,0 @@
-export const proof = {
-    sleep_fail: async () => {
-        await new Promise(resolve => setTimeout(resolve, 10));
-        throw 'async failure';
-    }
-};