functionalscript 0.43.1 → 0.45.0

package/fjs/djs/tokenizer/types.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Type-level API for `fjs/djs/tokenizer/module.f.mjs`: the DJS token shapes
+ * `tokenize`/`tokenizeJs`/`tokenizeString` produce.
+ *
+ * @module
+ */
+import type { StringToken, NumberToken, ErrorToken, IdToken, BigIntToken, WhitespaceToken, NewLineToken, CommentToken, EofToken, TokenMetadata } from '../../js/tokenizer/types.ts';
+/**
+ * DJS-level token set: a narrower view of JsToken (only true/false/null/undefined survive
+ * as bare keywords; every other keyword becomes an id) plus its own punctuator kinds.
+ */
+export type DjsToken = {
+    readonly kind: 'true' | 'false' | 'null' | 'undefined';
+} | {
+    readonly kind: '{' | '}' | ':' | ',' | '[' | ']' | '.' | '=';
+} | StringToken | NumberToken | ErrorToken | IdToken | BigIntToken | WhitespaceToken | NewLineToken | CommentToken | EofToken;
+export type DjsTokenWithMetadata = {
+    readonly token: DjsToken;
+    readonly metadata: TokenMetadata;
+};

package/fjs/djs/transpiler/module.f.d.mts

@@ -0,0 +1,33 @@
+/**
+ * DJS transpiler for transforming parsed trees into JavaScript output.
+ *
+ * @module
+ *
+ * @import { Unknown } from '../types.ts'
+ * @import { Result } from '../../types/result/types.ts'
+ * @import { ParseError } from '../parser/types.ts'
+ * @import { AstModule } from '../ast/types.ts'
+ * @import { Effect } from '../../effects/types.ts'
+ * @import { ReadFile } from '../../effects/node/types.ts'
+ * @import { ParseContext } from './types.ts'
+ */
+import type { Unknown } from '../types.ts';
+import type { Result } from '../../types/result/types.ts';
+import type { ParseError } from '../parser/types.ts';
+import type { Effect } from '../../effects/types.ts';
+import type { ReadFile } from '../../effects/node/types.ts';
+/**
+ * Transpiles a DJS module graph rooted at `path` into a single `Unknown` value.
+ *
+ * Reads each file via the `ReadFile` effect, resolves imports recursively, and
+ * evaluates the AST. Returns `['ok', value]` on success, or `['error', ParseError]`
+ * on a parse failure or circular dependency.
+ *
+ * @type {(path: string) => Effect<ReadFile, Result<Unknown, ParseError>>}
+ */
+export declare const transpile: (path: string) => Effect<ReadFile, Result<Unknown, ParseError>>;
+export declare const proof: {
+    throw: {
+        mapDjsUnresolvedImport: () => Unknown;
+    };
+};

package/fjs/djs/transpiler/module.f.mjs

@@ -0,0 +1,122 @@
+/**
+ * DJS transpiler for transforming parsed trees into JavaScript output.
+ *
+ * @module
+ *
+ * @import { Unknown } from '../types.ts'
+ * @import { Result } from '../../types/result/types.ts'
+ * @import { ParseError } from '../parser/types.ts'
+ * @import { AstModule } from '../ast/types.ts'
+ * @import { Effect } from '../../effects/types.ts'
+ * @import { ReadFile } from '../../effects/node/types.ts'
+ * @import { ParseContext } from './types.ts'
+ */
+
+import { error, ok } from '../../types/result/module.f.mjs'
+import { drop, map as listMap, toArray, includes } from '../../types/list/module.f.mjs'
+import { tokenize } from '../tokenizer/module.f.mjs'
+import { setReplace, at } from '../../types/ordered_map/module.f.mjs'
+import { stringToList } from '../../text/utf16/module.f.mjs'
+import { concat as pathConcat } from '../../path/module.f.mjs'
+import { parseFromTokens } from '../parser/module.f.mjs'
+import { run } from '../ast/module.f.mjs'
+import { foldStep, pure, step } from '../../effects/module.f.mjs'
+import { readUtf8File } from '../../effects/node/module.f.mjs'
+
+/** @type {(context: ParseContext) => (path: string) => Unknown} */
+const mapDjs = context => path => {
+    const res = at(path)(context.complete)
+    if (res === null)
+    {
+        throw 'unexpected behaviour'
+    }
+    return res.djs
+}
+
+/** @type {(path: string) => Effect<ReadFile, Result<AstModule, ParseError>>} */
+const parseModule = path => step(
+    readUtf8File(path),
+    result => {
+        if (result[0] === 'error') {
+            return pure(error({ message: 'file not found', metadata: null }))
+        }
+        const tokens = tokenize(stringToList(result[1]))(path)
+        return pure(parseFromTokens(tokens))
+    })
+
+/** @type {(path: string) => (parseModuleResult: Result<AstModule, ParseError>) => (context: ParseContext) => Effect<ReadFile, ParseContext>} */
+const transpileWithImports = path => parseModuleResult => context => {
+    if (parseModuleResult[0] === 'ok') {
+        const dir = pathConcat(path)('..')
+        const pathsCombine = listMap(pathConcat(dir))(parseModuleResult[1][0])
+        const pathsArray = toArray(pathsCombine)
+        const contextWithStack = { ...context, stack: { first: path, tail: context.stack } }
+        const x0 = foldStep(pure(pathsArray), contextWithStack, foldNextModuleOp)
+        return step(
+            x0,
+            contextWithImports => {
+                if (contextWithImports.error !== null) {
+                    return pure(contextWithImports)
+                }
+                const args = toArray(listMap(mapDjs(contextWithImports))(pathsCombine))
+                const djs = { djs: run(parseModuleResult[1][1])(args) }
+                return pure({
+                    ...contextWithImports,
+                    stack: drop(1)(contextWithImports.stack),
+                    complete: setReplace(path)(djs)(contextWithImports.complete),
+                })
+            })
+    }
+    return pure({ ...context, error: parseModuleResult[1] })
+}
+
+/** @type {(path: string) => (context: ParseContext) => Effect<ReadFile, ParseContext>} */
+const foldNextModuleOp = path => context => {
+    if (context.error !== null) {
+        return pure(context)
+    }
+
+    if (includes(path)(context.stack)) {
+        return pure({ ...context, error: { message: 'circular dependency', metadata: null } })
+    }
+
+    if (at(path)(context.complete) !== null) {
+        return pure(context)
+    }
+
+    return step(
+        parseModule(path),
+        parseModuleResult => transpileWithImports(path)(parseModuleResult)(context))
+}
+
+/**
+ * Transpiles a DJS module graph rooted at `path` into a single `Unknown` value.
+ *
+ * Reads each file via the `ReadFile` effect, resolves imports recursively, and
+ * evaluates the AST. Returns `['ok', value]` on success, or `['error', ParseError]`
+ * on a parse failure or circular dependency.
+ *
+ * @type {(path: string) => Effect<ReadFile, Result<Unknown, ParseError>>}
+ */
+export const transpile = path => step(
+    foldNextModuleOp(path)({ stack: null, complete: null, error: null }),
+    /** @type {(context: ParseContext) => Effect<ReadFile, Result<Unknown, ParseError>>} */
+    (context) => {
+        if (context.error !== null) {
+            return pure(error(context.error))
+        }
+        const result = at(path)(context.complete)?.djs
+        return pure(ok(result))
+    })
+
+// ── Tests ────────────────────────────────────────────────────────────────────
+
+export const proof = {
+    throw: {
+        // `mapDjs` is only ever called with an import path that `foldNextModuleOp`
+        // has already resolved into `context.complete`, so the `res === null`
+        // guard is an internal-invariant check unreachable through `transpile`'s
+        // public API. Call it directly with an empty `complete` map to cover it.
+        mapDjsUnresolvedImport: () => mapDjs({ complete: null, stack: null, error: null })('missing.djs'),
+    },
+}

package/fjs/djs/transpiler/proof.f.mjs

@@ -0,0 +1,76 @@
+/**
+ * @import { Dir } from '../../effects/node/virtual/types.ts'
+ * @import { Result } from '../../types/result/types.ts'
+ * @import { Unknown } from '../types.ts'
+ * @import { ParseError } from '../parser/types.ts'
+ */
+import { sort } from '../../types/object/module.f.mjs'
+import { transpile } from './module.f.mjs'
+import { stringifyAsTree } from '../serializer/module.f.mjs'
+import { virtual, emptyState } from '../../effects/node/virtual/module.f.mjs'
+import { utf8 } from '../../text/module.f.mjs'
+import { assert, assertEq } from '../../asserts/module.f.mjs'
+
+/** @type {(root: Dir) => (path: string) => Result<Unknown, ParseError>} */
+const run = root => path => {
+    const [, result] = virtual({ ...emptyState, root })(transpile(path))
+    return result
+}
+
+export const proof = {
+    parse: () => {
+        const result = run({ a: [utf8('export default 1')] })('a')
+        assert(result[0] !== 'error', result[1])
+        const s = stringifyAsTree(sort)(result[1])
+        assertEq(s, '1')
+    },
+    parseWithSubModule: () => {
+        const result = run({ a: { b: [utf8('import c from "c"\nexport default c')], c: [utf8('export default 2')] } })('a/b')
+        assert(result[0] !== 'error', result[1])
+        const s = stringifyAsTree(sort)(result[1])
+        assertEq(s, '2')
+    },
+    parseWithSubModules: () => {
+        const result = run({
+            a: [utf8('import b from "b"\nimport c from "c"\nexport default [b,c,b]')],
+            b: [utf8('import d from "d"\nexport default [0,d]')],
+            c: [utf8('import d from "d"\nexport default [1,d]')],
+            d: [utf8('export default 2')],
+        })('a')
+        assert(result[0] !== 'error', result[1])
+        const s = stringifyAsTree(sort)(result[1])
+        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')
+        assert(result[0] === 'error', result)
+        assertEq(result[1].message, 'file not found', result)
+    },
+    parseWithCycleError: () => {
+        const result = run({
+            a: [utf8('import b from "b"\nimport c from "c"\nexport default [b,c,b]')],
+            b: [utf8('import c from "c"\nexport default c')],
+            c: [utf8('import b from "b"\nexport default b')],
+        })('a')
+        assert(result[0] === 'error', result)
+        assertEq(result[1].message, 'circular dependency', result)
+    },
+}

package/fjs/djs/transpiler/types.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Types for the DJS transpiler.
+ *
+ * @module
+ */
+import type { Unknown } from '../types.ts';
+import type { List } from '../../types/list/types.ts';
+import type { OrderedMap } from '../../types/ordered_map/types.ts';
+import type { ParseError } from '../parser/types.ts';
+/** The evaluated DJS value produced for one successfully transpiled module. */
+export type djsResult = {
+    djs: Unknown;
+};
+/**
+ * State threaded through the recursive transpilation of a DJS module graph.
+ *
+ * - `complete`: modules that have been fully parsed and evaluated, keyed by path.
+ * - `stack`: import chain currently being resolved (used to detect circular dependencies).
+ * - `error`: the first parse error encountered, or `null` while everything is clean.
+ */
+export type ParseContext = {
+    readonly complete: OrderedMap<djsResult>;
+    readonly stack: List<string>;
+    readonly error: ParseError | null;
+};

package/fjs/djs/types.d.ts

@@ -0,0 +1,13 @@
+/**
+ * DJS's own value model: `Primitive`, `Unknown`, `Object`, and `Array`,
+ * layered on top of JSON's `Primitive` with `bigint` and `undefined` added.
+ *
+ * @module
+ */
+import type { Primitive as JsonPrimitive } from '../media/json/types.ts';
+export type Object = {
+    readonly [k in string]?: Unknown;
+};
+export type Array = readonly Unknown[];
+export type Primitive = JsonPrimitive | bigint | undefined;
+export type Unknown = Primitive | Object | Array;

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

@@ -0,0 +1,20 @@
+/**
+ * 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

@@ -0,0 +1,70 @@
+/**
+ * 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

@@ -0,0 +1,15 @@
+/**
+ * @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

@@ -0,0 +1,69 @@
+/**
+ * @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

@@ -0,0 +1,71 @@
+/**
+ * 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/list/module.f.d.mts

@@ -0,0 +1,32 @@
+/**
+ * Effectful cons-list construction.
+ *
+ * See `./types.ts` for the type-level API.
+ *
+ * @module
+ *
+ * @import { Effect, Operation } from "../types.ts"
+ * @import { List, Next } from "./types.ts"
+ */
+import type { Effect, Operation } from "../types.ts";
+import type { List, Next } from "./types.ts";
+/**
+ * The empty `List`: a pure end-of-stream marker (`undefined`).
+ *
+ * The explicit `Effect<O, Next<O, T>>` return type lets the contextual type drive the
+ * check, so the recursive payload type-checks without a cast. Construct streams through
+ * these two combinators.
+ *
+ * Note: we use `Effect<O, Next<O, T>>` because TypeScript can't convert `pure(...)` to
+ *       `List<O, T>`.
+ *
+ * @type {<O extends Operation, T>() => Effect<O, Next<O, T>>}
+ */
+export declare const empty: <O extends Operation, T>() => Effect<O, Next<O, T>>;
+/**
+ * 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}.
+ *
+ * @type {<O extends Operation, T>(first: T, tail: List<O, T>) => Effect<O, Next<O, T>>}
+ */
+export declare const nonEmpty: <O extends Operation, T>(first: T, tail: List<O, T>) => Effect<O, Next<O, T>>;

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

@@ -0,0 +1,36 @@
+/**
+ * Effectful cons-list construction.
+ *
+ * See `./types.ts` for the type-level API.
+ *
+ * @module
+ *
+ * @import { Effect, Operation } from "../types.ts"
+ * @import { List, Next } from "./types.ts"
+ */
+
+import { pure } from "../module.f.mjs"
+
+/**
+ * The empty `List`: a pure end-of-stream marker (`undefined`).
+ *
+ * The explicit `Effect<O, Next<O, T>>` return type lets the contextual type drive the
+ * check, so the recursive payload type-checks without a cast. Construct streams through
+ * these two combinators.
+ *
+ * Note: we use `Effect<O, Next<O, T>>` because TypeScript can't convert `pure(...)` to
+ *       `List<O, T>`.
+ *
+ * @type {<O extends Operation, T>() => Effect<O, Next<O, T>>}
+ */
+export const empty = () =>
+    pure(undefined)
+
+/**
+ * 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}.
+ *
+ * @type {<O extends Operation, T>(first: T, tail: List<O, T>) => Effect<O, Next<O, T>>}
+ */
+export const nonEmpty = (first, tail) =>
+    pure({ first, tail })

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

@@ -0,0 +1,26 @@
+/**
+ * Types for the effectful cons-list.
+ *
+ * @module
+ */
+import type { Effect, Operation } from '../types.ts';
+export type NonEmpty<O extends Operation, T> = {
+    readonly first: T;
+    readonly tail: List<O, T>;
+};
+/**
+ * The payload of a `List` effect: the next cons cell, or `undefined` at
+ * end-of-stream.
+ *
+ * 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 `empty`).
+ */
+export type Next<O extends Operation, T> = NonEmpty<O, T> | undefined;
+export type List<O extends Operation, T> = Effect<O, Next<O, T>>;