functionalscript 0.45.0 → 0.46.1

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

@@ -3,9 +3,9 @@
  *
  * @module
  *
- * @import { WriteFile } from '../effects/node/types.ts'
+ * @import { Write, WriteFile } from '../effects/node/types.ts'
  * @import { Effect } from '../effects/types.ts'
  */
-import type { WriteFile } from '../effects/node/types.ts';
+import type { Write, WriteFile } from '../effects/node/types.ts';
 import type { Effect } from '../effects/types.ts';
-export declare const main: () => Effect<WriteFile, number>;
+export declare const main: () => Effect<Write | WriteFile, 0, number>;

package/fjs/website/module.f.mjs

@@ -3,13 +3,12 @@
  *
  * @module
  *
- * @import { WriteFile } from '../effects/node/types.ts'
+ * @import { Write, 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 { pure, step } from '../effects/module.f.mjs'
+import { exitStep, writeFile } from '../effects/node/module.f.mjs'
 
 const html = htmlUtf8()(
     ['a',
@@ -17,9 +16,7 @@ const html = htmlUtf8()(
         'GitHub Repository'
     ])
 
-/** @type {Effect<WriteFile, number>} */
-const program = step(
-    writeFile('index.html', html),
-    () => pure(0))
+/** @type {Effect<WriteFile | Write, 0, number>} */
+const program = exitStep(writeFile('index.html', html))
 
 export const main = () => program

package/fjs/website/proof.f.mjs

@@ -1,3 +1,4 @@
+import { exitCode } from '../effects/node/module.f.mjs'
 import { main } from './module.f.mjs'
 import { emptyState, virtual } from '../effects/node/virtual/module.f.mjs'
 import { assertEq, assertNotNullish } from '../asserts/module.f.mjs'
@@ -9,6 +10,6 @@ export const proof = {
     run: () => {
         const state = { ...emptyState, root: { '.github': { workflows: {} } } }
         const [_, result] = virtual(state)(main())
-        assertEq(result, 0)
+        assertEq(exitCode(result), 0)
     },
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "functionalscript",
-  "version": "0.45.0",
+  "version": "0.46.1",
   "type": "module",
   "files": [
     "**/*.js",
@@ -12,7 +12,7 @@
   "scripts": {
     "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.mjs",
+    "cov": "node --test --experimental-test-coverage --test-coverage-include=**/module.f.mjs --test-coverage-lines=100 --test-coverage-branches=100 --test-coverage-functions=100",
     "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/dev/package_json/module.f.d.mts

@@ -1,39 +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]>;
-}>;
-/**
- * Parses `text` as JSON and validates it against {@link packageJsonSchema}.
- *
- * Both failures reach the caller as they were raised: a parse failure is a
- * `string`, a schema failure a `ValidationError`, and `JsonTextError` is
- * exactly that union — which is what `okThen` produces from the two steps'
- * own error types, with no rewrapping to widen either one.
- *
- * @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,40 +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 { okThen } 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)
-
-/**
- * Parses `text` as JSON and validates it against {@link packageJsonSchema}.
- *
- * Both failures reach the caller as they were raised: a parse failure is a
- * `string`, a schema failure a `ValidationError`, and `JsonTextError` is
- * exactly that union — which is what `okThen` produces from the two steps'
- * own error types, with no rewrapping to widen either one.
- *
- * @param {string} text
- * @returns {Result<PackageJson, JsonTextError>}
- */
-export const validatePackageJsonText = text =>
-    okThen(validatePackageJson)(parseJsonText(text))

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

@@ -1,20 +0,0 @@
-/**
- * A fluent, method-chaining wrapper over the raw `Effect`.
- *
- * See `./types.ts` for the `Eff` type-level API.
- *
- * @module
- *
- * @import { Effect, Operation } from '../types.ts'
- * @import { Eff } from './types.ts'
- */
-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,70 +0,0 @@
-/**
- * A fluent, method-chaining wrapper over the raw `Effect`.
- *
- * See `./types.ts` for the `Eff` type-level API.
- *
- * @module
- *
- * @import { Effect, Operation } from '../types.ts'
- * @import { Eff } from './types.ts'
- */
-
-import { history, historyStep, mapStep, pure } from '../module.f.mjs'
-
-/**
- * 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,15 +0,0 @@
-/**
- * @import { Effect, OperationMap } from '../types.ts'
- */
-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,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/types.d.ts

@@ -1,6 +0,0 @@
-/**
- * Type-level API for RTTI validation.
- *
- * @module
- */
-export type { Path, Result, Validate, ValidationError } from '../common/types.ts';