functionalscript 0.45.0 → 0.46.0

package/fjs/types/rtti/parse/proof.f.mjs

@@ -109,32 +109,32 @@ export const proof = {
             error: () => assertError(parse(/** @type {const} */ (42))(43)),
         },
         nan: {
-            ok: () => assertOk(parse(/** @type {number} */ (NaN))(NaN)),
+            ok: () => assertOk(parse(NaN)(NaN)),
             error: () => {
-                assertError(parse(/** @type {number} */ (NaN))(0))
+                assertError(parse(NaN)(0))
                 assertError(parse(/** @type {const} */ (0))(NaN))
                 assertError(parse(/** @type {const} */ (42))(NaN))
             },
         },
         infinity: {
             ok: () => {
-                assertOk(parse(/** @type {number} */ (Infinity))(Infinity))
-                assertOk(parse(/** @type {number} */ (-Infinity))(-Infinity))
+                assertOk(parse(Infinity)(Infinity))
+                assertOk(parse(-Infinity)(-Infinity))
             },
             error: () => {
-                assertError(parse(/** @type {number} */ (Infinity))(-Infinity))
-                assertError(parse(/** @type {number} */ (Infinity))(0))
+                assertError(parse(Infinity)(-Infinity))
+                assertError(parse(Infinity)(0))
             },
         },
         signedZero: {
             // `Object.is` distinguishes +0 and -0; `===` treats them equal.
             distinct: () => {
                 assertError(parse(/** @type {const} */ (0))(-0))
-                assertError(parse(/** @type {number} */ (-0))(0))
+                assertError(parse(-0)(0))
             },
             self: () => {
                 assertOk(parse(/** @type {const} */ (0))(0))
-                assertOk(parse(/** @type {number} */ (-0))(-0))
+                assertOk(parse(-0)(-0))
             },
         },
         string: {
@@ -155,14 +155,31 @@ export const proof = {
                 const r = parse(t)([42, 'hello'])
                 assertStructurallySame(unwrap(r), [42, 'hello'])
             },
-            // The key behavior change vs `validate`: extra tuple elements are dropped.
-            extraItemsDropped: () => {
+            // A tuple is OPEN: a longer array is accepted, and the extras are
+            // absent from what `parse` builds. This is deliberate — see
+            // "Structs and tuples are open" in ../README.md. Do not add a
+            // length check here on the strength of `Ts<readonly [42]>` being
+            // an exact tuple; that mapping is exact only because TypeScript
+            // could not express the open one (see ../ts/types.ts `TupleTs`),
+            // and reading it as a design decision is what produced #1622.
+            extraItemsAcceptedAndDropped: () => {
                 const r = parse(/** @type {const} */ ([42]))([42, 'extra'])
                 assertStructurallySame(unwrap(r), [42])
+                const long = parse(/** @type {const} */ ([42]))([42, 1, 2, 3])
+                assertStructurallySame(unwrap(long), [42])
+            },
+            // An absent member reads as `undefined`, so a position is required
+            // exactly when its set excludes `undefined` — the same rule the
+            // data form states for object keys, applied to arrays.
+            shortArrayFillsAnOptionalPosition: () => {
+                const r = parse([number, option(string)])([42])
+                assertStructurallySame(unwrap(r), [42, undefined])
             },
             error: () => {
                 assertError(parse(/** @type {const} */ ([42]))([99]))
                 assertError(parse(/** @type {const} */ ([42]))({}))
+                // `42` excludes `undefined`, so position 0 is required.
+                assertError(parse(/** @type {const} */ ([42]))([]))
             },
         },
         struct: {
@@ -171,8 +188,10 @@ export const proof = {
                 const r = parse(t)({ a: 42, b: 'hello' })
                 assertStructurallySame(unwrap(r), { a: 42, b: 'hello' })
             },
-            // Undeclared properties are dropped from the constructed value.
-            extraKeysDropped: () => {
+            // A struct is OPEN, on the same terms as a tuple: undeclared
+            // properties are accepted and absent from what `parse` builds.
+            // See "Structs and tuples are open" in ../README.md.
+            extraKeysAcceptedAndDropped: () => {
                 const r = parse(/** @type {const} */ ({ a: /** @type {const} */ (42) }))({ a: 42, b: 'extra' })
                 assertStructurallySame(unwrap(r), { a: 42 })
             },
@@ -196,7 +215,7 @@ export const proof = {
             const input = [1, 2, 3]
             /** @type {readonly number[]} */
             const out = unwrap(parse(array(number))(input))
-            assert(out !== /** @type {unknown} */ (input), 'expected a fresh array')
+            assert(out !== input, 'expected a fresh array')
             assertStructurallySame(out, [1, 2, 3])
         },
         error: () => {
@@ -224,7 +243,7 @@ export const proof = {
             const input = { a: 1, b: 2 }
             /** @type {Record<string, number>} */
             const out = unwrap(parse(record(number))(input))
-            assert(out !== /** @type {unknown} */ (input), 'expected a fresh record')
+            assert(out !== input, 'expected a fresh record')
             assertStructurallySame(out, { a: 1, b: 2 })
         },
         error: () => {

package/fjs/types/rtti/proof.f.mjs

@@ -2,6 +2,8 @@
  * @import { StringMap } from '../object/types.ts'
  */
 
+import { assertNotNullish } from '../../asserts/module.f.mjs'
+
 /** @typedef {StringMap<readonly unknown[]>} _Tests */
 
 /** @type {_Tests} */
@@ -16,7 +18,7 @@ const tests = {
 }
 
 export const proof = {
-    typeof: Object.fromEntries(Object.entries(tests).map(([k, a]) => [k, /** @type {readonly unknown[]} */ (a).map(v => () => {
+    typeof: Object.fromEntries(Object.entries(tests).map(([k, a]) => [k, assertNotNullish(a).map(v => () => {
         if (typeof v !== k) { throw `typeof ${v} !== ${k}` }
     })])),
 }

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

@@ -19,6 +19,7 @@
  */
 
 import { assertNotNullish } from '../../../asserts/module.f.mjs'
+import { reservedWords, strictModeReservedWords } from '../../../js/keywords/module.f.mjs'
 import { at, definedEntries } from '../../object/module.f.mjs'
 import { primitive, union, printer as tsPrinter } from '../../ts/module.f.mjs'
 import { cmp, toData, unitBit, unknown as top } from '../data/module.f.mjs'
@@ -30,27 +31,22 @@ const trueBit = unitBit(true)
 const booleanBits = falseBit | trueBit
 
 /**
- * Names that cannot name a TypeScript type alias: the predefined type
- * names (`TS2457`), the ECMAScript reserved words — those reserved only in
- * strict-mode code included, since every module is strict-mode code
- * (`TS1214`) — and the type keywords that fail in the alias-name position.
+ * Names that cannot name a TypeScript type alias: the ECMAScript reserved
+ * words — from the one source of truth for JavaScript keywords,
+ * `fjs/js/keywords`, the strict-mode ones included since every module is
+ * strict-mode code (`TS1214`) — plus TypeScript's predefined type names
+ * (`TS2457`) and the type keywords that fail in the alias-name position.
  */
-const reserved = /** @type {const} */ ([
+/** @type {readonly string[]} */
+const reserved = [
+    ...reservedWords,
+    ...strictModeReservedWords,
     // predefined type names
-    'any', 'bigint', 'boolean', 'false', 'never', 'null', 'number', 'object',
-    'string', 'symbol', 'true', 'undefined', 'unknown', 'void',
-    // ECMAScript reserved words
-    'await', 'break', 'case', 'catch', 'class', 'const', 'continue',
-    'debugger', 'default', 'delete', 'do', 'else', 'enum', 'export',
-    'extends', 'finally', 'for', 'function', 'if', 'import', 'in',
-    'instanceof', 'new', 'return', 'super', 'switch', 'this', 'throw', 'try',
-    'typeof', 'var', 'while', 'with',
-    // reserved in strict-mode code — and every module is strict-mode code
-    'implements', 'interface', 'let', 'package', 'private', 'protected',
-    'public', 'static', 'yield',
+    'any', 'bigint', 'boolean', 'never', 'number', 'object', 'string',
+    'symbol', 'undefined', 'unknown',
     // type-operator keywords, and `intrinsic` (TS2795 outside lib.d.ts)
     'infer', 'intrinsic', 'keyof', 'readonly', 'unique',
-])
+]
 
 /** @type {(c: string) => boolean} */
 const isIdStart = c => (c >= 'a' && c <= 'z') || (c >= 'A' && c <= 'Z') || c === '_' || c === '$'

package/fjs/types/rtti/ts/types.d.ts

@@ -51,7 +51,20 @@ export type ArrayTs<T extends Type> = ReadonlyArray<Ts<T>>;
 export type RecordTs<T extends Type> = {
     readonly [K in string]?: Ts<T>;
 };
-/** Maps a tuple schema to a readonly tuple of resolved types. */
+/**
+ * Maps a tuple schema to a readonly tuple of resolved types.
+ *
+ * **The commented-out line is the accurate mapping.** A tuple schema is *open*
+ * — a longer array is a member of the set it describes (see "Structs and
+ * tuples are open" in `../README.md`) — and the open form below says so. It is
+ * commented out because TypeScript could not handle it, so this renders the
+ * closed approximation instead.
+ *
+ * That is a limitation of this renderer, **not** a statement about the value
+ * model. Do not cite the exact mapping as evidence that tuples are closed and
+ * add a length check to `../parse/module.f.mjs`; that inference is what
+ * produced #1622.
+ */
 export type TupleTs<T extends Tuple> = {
     readonly [K in keyof T]: Ts<T[K]>;
 };

package/fjs/types/sorted_set/module.f.d.mts

@@ -52,3 +52,21 @@ export declare const has: <T>(
  * @returns {(value: T) => (set: SortedSet<T>) => boolean}
  */
 cmp: Cmp<T>) => (value: T) => (set: SortedSet<T>) => boolean;
+/**
+ * A canonical key for a set of strings: equal sets always produce the same
+ * key, and unequal sets never produce the same one. Useful wherever a set has
+ * to index a `StringMap` — the subset construction in `fjs/fsm`, say.
+ *
+ * Each element is written length-prefixed (`3:abc`) and the parts are
+ * concatenated. Joining on a separator would **not** be canonical: elements
+ * are arbitrary strings, so `['a,b']` and `['a', 'b']` would both produce
+ * `a,b` and two different sets would share one key. A length prefix is
+ * readable back — take the digits, the `:`, then exactly that many code
+ * units — so the encoding is injective without an escaping table.
+ *
+ * The key is canonical for the *set* only because `SortedSet` is sorted:
+ * element order is fixed by the set's own invariant, not by this function.
+ *
+ * @type {(set: SortedSet<string>) => string}
+ */
+export declare const toKey: (set: SortedSet<string>) => string;

package/fjs/types/sorted_set/module.f.mjs

@@ -56,3 +56,25 @@ export const has =
      * @returns {(value: T) => (set: SortedSet<T>) => boolean}
      */
     cmp => value => set => find(cmp)(value)(set) === value
+
+/** @type {(s: string) => string} */
+const lengthPrefixed = s => `${s.length}:${s}`
+
+/**
+ * A canonical key for a set of strings: equal sets always produce the same
+ * key, and unequal sets never produce the same one. Useful wherever a set has
+ * to index a `StringMap` — the subset construction in `fjs/fsm`, say.
+ *
+ * Each element is written length-prefixed (`3:abc`) and the parts are
+ * concatenated. Joining on a separator would **not** be canonical: elements
+ * are arbitrary strings, so `['a,b']` and `['a', 'b']` would both produce
+ * `a,b` and two different sets would share one key. A length prefix is
+ * readable back — take the digits, the `:`, then exactly that many code
+ * units — so the encoding is injective without an escaping table.
+ *
+ * The key is canonical for the *set* only because `SortedSet` is sorted:
+ * element order is fixed by the set's own invariant, not by this function.
+ *
+ * @type {(set: SortedSet<string>) => string}
+ */
+export const toKey = set => set.map(lengthPrefixed).join('')

package/fjs/types/sorted_set/proof.f.d.mts

@@ -2,6 +2,7 @@
  * @import { Unknown } from '../../media/json/types.ts'
  */
 export declare const proof: {
+    toKey: (() => void)[];
     example: () => void;
     union: (() => void)[];
     intersect: (() => void)[];

package/fjs/types/sorted_set/proof.f.mjs

@@ -2,7 +2,7 @@
  * @import { Unknown } from '../../media/json/types.ts'
  */
 
-import { has, intersect, union } from './module.f.mjs'
+import { has, intersect, toKey, union } from './module.f.mjs'
 import { stringify } from '../../media/json/module.f.mjs'
 import { sort } from '../object/module.f.mjs'
 import { toArray, countdown, length } from '../list/module.f.mjs'
@@ -16,6 +16,21 @@ const str = a => stringify(sort)(a)
 const reverseCmp = flip(cmp)
 
 export const proof = {
+    toKey: [
+        () => assertEq(toKey([]), ''),
+        () => assertEq(toKey(['']), '0:'),
+        () => assertEq(toKey(['a']), '1:a'),
+        () => assertEq(toKey(['a', 'b']), '1:a1:b'),
+        // The reason the key is length-prefixed rather than separator-joined:
+        // these two sets are different and must not share a key, but any
+        // fixed separator that can occur in an element collapses them.
+        () => assert(toKey(['a,b']) !== toKey(['a', 'b']), 'comma'),
+        () => assert(toKey(['a:b']) !== toKey(['a', 'b']), 'colon'),
+        () => assert(toKey(['a\nb']) !== toKey(['a', 'b']), 'newline'),
+        // A prefix of one element must not be confused with a shorter one.
+        () => assert(toKey(['ab']) !== toKey(['a']), 'prefix'),
+        () => assert(toKey(['']) !== toKey([]), 'empty element vs empty set'),
+    ],
     example: () => {
         const cmp = (/** @type {number} */ a) => (/** @type {number} */ b) => a < b ? -1 : a > b ? 1 : 0
 

package/fjs/types/uint8array/module.f.d.mts

@@ -19,7 +19,7 @@ import type { List } from '../list/types.ts';
  *
  * Throws if the result would exceed `maxLength`. The bound is not precomputed:
  * `tryU8ListToVec` attempts the real conversion and reports `null` when it does
- * not fit (AGENTS.md §5.6).
+ * not fit (`DESIGN.md` §6).
  *
  * @type {(input: List<Uint8Array>) => Vec}
  */

package/fjs/types/uint8array/module.f.mjs

@@ -29,7 +29,7 @@ const m = map(fromArrayLike)
  *
  * Throws if the result would exceed `maxLength`. The bound is not precomputed:
  * `tryU8ListToVec` attempts the real conversion and reports `null` when it does
- * not fit (AGENTS.md §5.6).
+ * not fit (`DESIGN.md` §6).
  *
  * @type {(input: List<Uint8Array>) => Vec}
  */

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.0",
   "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;
-    };
-};