functionalscript 0.37.0 → 0.39.0

package/{fs → fjs}/djs/transpiler/module.f.js

@@ -12,7 +12,7 @@ import { stringToList } from '../../text/utf16/module.f.js';
 import { concat as pathConcat } from '../../path/module.f.js';
 import { parseFromTokens } from '../parser/module.f.js';
 import { run } from '../ast/module.f.js';
-import { foldStep, pure } from '../../effects/module.f.js';
+import { foldStep, pure, step } from '../../effects/module.f.js';
 import { readUtf8File } from '../../effects/node/module.f.js';
 const mapDjs = context => path => {
     const res = at(path)(context.complete);
@@ -21,7 +21,7 @@ const mapDjs = context => path => {
     }
     return res.djs;
 };
-const parseModule = path => readUtf8File(path).step(result => {
+const parseModule = path => step(readUtf8File(path), result => {
     if (result[0] === 'error') {
         return pure(error({ message: 'file not found', metadata: null }));
     }
@@ -34,8 +34,8 @@ const transpileWithImports = path => parseModuleResult => context => {
         const pathsCombine = listMap(pathConcat(dir))(parseModuleResult[1][0]);
         const pathsArray = toArray(pathsCombine);
         const contextWithStack = { ...context, stack: { first: path, tail: context.stack } };
-        return foldStep(foldNextModuleOp)(contextWithStack)(pathsArray)
-            .step(contextWithImports => {
+        const x0 = foldStep(pure(pathsArray), contextWithStack, foldNextModuleOp);
+        return step(x0, contextWithImports => {
             if (contextWithImports.error !== null) {
                 return pure(contextWithImports);
             }
@@ -60,7 +60,7 @@ const foldNextModuleOp = path => context => {
     if (at(path)(context.complete) !== null) {
         return pure(context);
     }
-    return parseModule(path).step(parseModuleResult => transpileWithImports(path)(parseModuleResult)(context));
+    return step(parseModule(path), parseModuleResult => transpileWithImports(path)(parseModuleResult)(context));
 };
 /**
  * Transpiles a DJS module graph rooted at `path` into a single `Unknown` value.
@@ -69,7 +69,7 @@ const foldNextModuleOp = path => context => {
  * evaluates the AST. Returns `['ok', value]` on success, or `['error', ParseError]`
  * on a parse failure or circular dependency.
  */
-export const transpile = path => foldNextModuleOp(path)({ stack: null, complete: null, error: null }).step((context) => {
+export const transpile = path => step(foldNextModuleOp(path)({ stack: null, complete: null, error: null }), (context) => {
     if (context.error !== null) {
         return pure(error(context.error));
     }

package/{fs → fjs}/djs/transpiler/proof.f.d.ts

@@ -2,6 +2,9 @@ export declare const proof: {
     parse: () => void;
     parseWithSubModule: () => void;
     parseWithSubModules: () => void;
+    parseWithIdentifierKeys: () => void;
+    parseWithConstIdentifier: () => void;
+    parseWithUnaryMinusOperator: () => void;
     parseWithFileNotFoundError: () => void;
     parseWithCycleError: () => void;
 };

package/{fs → fjs}/djs/transpiler/proof.f.js

@@ -3,6 +3,7 @@ import { transpile } from './module.f.js';
 import { stringifyAsTree } from '../serializer/module.f.js';
 import { virtual, emptyState } from '../../effects/node/virtual/module.f.js';
 import { utf8 } from '../../text/module.f.js';
+import { assert, assertEq } from '../../asserts/module.f.js';
 const run = (root) => (path) => {
     const [_, result] = virtual({ ...emptyState, root })(transpile(path));
     return result;
@@ -10,23 +11,15 @@ const run = (root) => (path) => {
 export const proof = {
     parse: () => {
         const result = run({ a: [utf8('export default 1')] })('a');
-        if (result[0] === 'error') {
-            throw result[1];
-        }
+        assert(result[0] !== 'error', result[1]);
         const s = stringifyAsTree(sort)(result[1]);
-        if (s !== '1') {
-            throw s;
-        }
+        assertEq(s, '1');
     },
     parseWithSubModule: () => {
         const result = run({ a: { b: [utf8('import c from "c"\nexport default c')], c: [utf8('export default 2')] } })('a/b');
-        if (result[0] === 'error') {
-            throw result[1];
-        }
+        assert(result[0] !== 'error', result[1]);
         const s = stringifyAsTree(sort)(result[1]);
-        if (s !== '2') {
-            throw s;
-        }
+        assertEq(s, '2');
     },
     parseWithSubModules: () => {
         const result = run({
@@ -35,22 +28,32 @@ export const proof = {
             c: [utf8('import d from "d"\nexport default [1,d]')],
             d: [utf8('export default 2')],
         })('a');
-        if (result[0] === 'error') {
-            throw result[1];
-        }
+        assert(result[0] !== 'error', result[1]);
         const s = stringifyAsTree(sort)(result[1]);
-        if (s !== '[[0,2],[1,2],[0,2]]') {
-            throw s;
-        }
+        assertEq(s, '[[0,2],[1,2],[0,2]]');
+    },
+    parseWithIdentifierKeys: () => {
+        const result = run({ a: [utf8('export default {a:1,b:2}')] })('a');
+        assert(result[0] !== 'error', result[1]);
+        const s = stringifyAsTree(sort)(result[1]);
+        assertEq(s, '{"a":1,"b":2}');
+    },
+    parseWithConstIdentifier: () => {
+        const result = run({ a: [utf8('const a = 1\nconst b = a\nexport default {x:a,y:b}')] })('a');
+        assert(result[0] !== 'error', result[1]);
+        const s = stringifyAsTree(sort)(result[1]);
+        assertEq(s, '{"x":1,"y":1}');
+    },
+    parseWithUnaryMinusOperator: () => {
+        const result = run({ a: [utf8('export default [-1,2,-3]')] })('a');
+        assert(result[0] !== 'error', result[1]);
+        const s = stringifyAsTree(sort)(result[1]);
+        assertEq(s, '[-1,2,-3]');
     },
     parseWithFileNotFoundError: () => {
         const result = run({ a: [utf8('import b from "b"\nexport default b')] })('a');
-        if (result[0] !== 'error') {
-            throw result;
-        }
-        if (result[1].message !== 'file not found') {
-            throw result;
-        }
+        assert(result[0] === 'error', result);
+        assertEq(result[1].message, 'file not found', result);
     },
     parseWithCycleError: () => {
         const result = run({
@@ -58,11 +61,7 @@ export const proof = {
             b: [utf8('import c from "c"\nexport default c')],
             c: [utf8('import b from "b"\nexport default b')],
         })('a');
-        if (result[0] !== 'error') {
-            throw result;
-        }
-        if (result[1].message !== 'circular dependency') {
-            throw result;
-        }
+        assert(result[0] === 'error', result);
+        assertEq(result[1].message, 'circular dependency', result);
     },
 };

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

@@ -0,0 +1,72 @@
+import { type Effect, type Operation } from '../module.f.ts';
+/**
+ * A fluent, method-chaining monad over a raw {@link 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 {@link 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
+ * {@link 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;
+ * {@link 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]>;
+};
+/**
+ * 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.
+ */
+export declare const eff: <O extends Operation, T>(value: Effect<O, T>) => Eff<O, T, readonly []>;

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

@@ -0,0 +1,46 @@
+import { history, historyStep, mapStep, pure } from '../module.f.js';
+/**
+ * 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.
+ */
+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.
+    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.
+ */
+export const eff = (value) => create(value, () => history(value));

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

@@ -0,0 +1,11 @@
+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.js

@@ -0,0 +1,58 @@
+import { do_, match, pure } from '../module.f.js';
+import { assert, assertEq } from '../../asserts/module.f.js';
+import { assertPure } from '../proof.f.js';
+import { eff } from './module.f.js';
+const next = match({ 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(do_('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(do_('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/{fs → fjs}/effects/list/module.f.d.ts

@@ -7,10 +7,15 @@ export type NonEmpty<O extends Operation, T> = {
  * The payload of a `List` effect: the next cons cell, or `undefined` at
  * end-of-stream.
  *
- * Since `Pure<T>` is now itself a lazy thunk (`() => T`), the effect alone is the
- * suspension point and the cell needs no extra wrapping thunk. `Effect<O, Next<O, T>>`
- * is used directly in places where `List<O, T>` cannot be written as a return type
- * (see {@link empty}).
+ * A `List` suspends only where a `Do` node does. `Pure` is a thunk, but that
+ * thunk is a discriminator rather than a suspension, and {@link nonEmpty} takes
+ * `tail` as an ordinary argument — already evaluated by the time the cell is
+ * built. A chain of pure cells is therefore constructed in full, up front;
+ * streaming comes from cells produced inside a command's continuation, where
+ * the tail is not reached until a runner performs the command.
+ *
+ * `Effect<O, Next<O, T>>` is used directly in places where `List<O, T>` cannot
+ * be written as a return type (see {@link empty}).
  */
 export type Next<O extends Operation, T> = NonEmpty<O, T> | undefined;
 export type List<O extends Operation, T> = Effect<O, Next<O, T>>;
@@ -26,6 +31,7 @@ export type List<O extends Operation, T> = Effect<O, Next<O, T>>;
  */
 export declare const empty: <O extends Operation, T>() => Effect<O, Next<O, T>>;
 /**
- * Prepends `head` to a `ListEffect` `tail`, as a pure cons cell. See {@link empty}.
+ * Prepends `first` to a {@link List} `tail`, as a pure cons cell. `tail` is an
+ * ordinary argument, so it is built before the cell is — see {@link Next}.
  */
 export declare const nonEmpty: <O extends Operation, T>(first: T, tail: List<O, T>) => Effect<O, Next<O, T>>;

package/{fs → fjs}/effects/list/module.f.js

@@ -11,6 +11,7 @@ import { pure } from "../module.f.js";
  */
 export const empty = () => pure(undefined);
 /**
- * Prepends `head` to a `ListEffect` `tail`, as a pure cons cell. See {@link empty}.
+ * Prepends `first` to a {@link List} `tail`, as a pure cons cell. `tail` is an
+ * ordinary argument, so it is built before the cell is — see {@link Next}.
  */
 export const nonEmpty = (first, tail) => pure({ first, tail });

package/{fs → fjs}/effects/memory/proof.f.js

@@ -1,5 +1,6 @@
+import { assert, assertEq } from '../../asserts/module.f.js';
 import { run } from '../mock/module.f.js';
-import { pure } from '../module.f.js';
+import { pure, step } from '../module.f.js';
 import { asBase, asNominal, create, read, write, } from './module.f.js';
 const initial = { next: 0, values: {} };
 const mock = {
@@ -14,48 +15,33 @@ const mock = {
     memRead: key => state => [state, state.values[asBase(key)]],
     memWrite: (key, value) => state => {
         const id = asBase(key);
-        if (!(id in state.values)) {
-            throw id;
-        }
+        assert(id in state.values, id);
         return [{
                 ...state,
                 values: { ...state.values, [id]: value },
             }, undefined];
     },
 };
-const program = create(1).step(key => read(key).step(value => write(key, value + 41).step(() => read(key))));
+const program = step(create(1), key => {
+    const x = step(read(key), value => write(key, value + 41));
+    return step(x, () => read(key));
+});
 export const proof = {
     roundTrip: () => {
         const [state, result] = run(mock)(initial)(program);
-        if (result !== 42) {
-            throw result;
-        }
-        if (state.values.k0 !== 42) {
-            throw state;
-        }
+        assertEq(result, 42);
+        assertEq(state.values.k0, 42, state);
     },
     allocatesFreshKeys: () => {
-        const effect = create('a').step(a => create('b').step(b => pure([
-            asBase(a),
-            asBase(b),
-        ])));
+        const effect = step(create('a'), a => step(create('b'), b => pure([asBase(a), asBase(b)])));
         const [state, [a, b]] = run(mock)(initial)(effect);
-        if (a !== 'k0') {
-            throw a;
-        }
-        if (b !== 'k1') {
-            throw b;
-        }
-        if (state.values.k0 !== 'a') {
-            throw state;
-        }
-        if (state.values.k1 !== 'b') {
-            throw state;
-        }
+        assertEq(a, 'k0');
+        assertEq(b, 'k1');
+        assertEq(state.values.k0, 'a', state);
+        assertEq(state.values.k1, 'b', state);
     },
     typeTest: () => {
-        // const e = create(1).step(k => write(k, 'bad').step(() => read(k)))
-        create(1).step(k => write(k, 5).step(() => read(k)));
+        step(create(1), k => step(write(k, 5), () => read(k)));
     },
     throw: () => {
         const key = asNominal('missing');