functionalscript 0.45.0 → 0.46.1

package/fjs/effects/module.mjs

@@ -5,6 +5,7 @@
  * @module
  *
  * @import { Effect, Operation, ToAsyncOperationMap } from './types.ts'
+ * @import { Result } from '../types/result/types.ts'
  */
 
 import { match } from './module.f.mjs'
@@ -12,7 +13,7 @@ import { match } from './module.f.mjs'
 /**
  * @template {Operation} O
  * @param {ToAsyncOperationMap<O>} map
- * @returns {<T>(effect: Effect<O, T>) => Promise<T>}
+ * @returns {<T, E>(effect: Effect<O, T, E>) => Promise<Result<T, E>>}
  */
 export const asyncRun = map => async effect => {
     const next = match(map)

package/fjs/effects/node/memory/module.d.mts

@@ -4,9 +4,11 @@
  * @module
  *
  * @import { Effect, ToAsyncOperationMap } from '../../types.ts'
+ * @import { Result } from '../../../types/result/types.ts'
  * @import { Key, MemOp } from '../../memory/types.ts'
  */
 import type { Effect, ToAsyncOperationMap } from '../../types.ts';
+import type { Result } from '../../../types/result/types.ts';
 import type { MemOp } from '../../memory/types.ts';
 export type MemoryOperationMap = ToAsyncOperationMap<MemOp>;
 export type Uuid = () => string;
@@ -22,6 +24,6 @@ export type Uuid = () => string;
 export declare const memoryOperationMap: (uuid?: Uuid) => MemoryOperationMap;
 /**
  * Runs a memory-only effect using a fresh memory store.
- * @type {<T>(effect: Effect<MemOp, T>) => Promise<T>}
+ * @type {<T, E>(effect: Effect<MemOp, T, E>) => Promise<Result<T, E>>}
  */
-export declare const run: <T>(effect: Effect<MemOp, T>) => Promise<T>;
+export declare const run: <T, E>(effect: Effect<MemOp, T, E>) => Promise<Result<T, E>>;

package/fjs/effects/node/memory/module.mjs

@@ -4,11 +4,13 @@
  * @module
  *
  * @import { Effect, ToAsyncOperationMap } from '../../types.ts'
+ * @import { Result } from '../../../types/result/types.ts'
  * @import { Key, MemOp } from '../../memory/types.ts'
  */
 
 import { randomUUID } from 'node:crypto'
 import { asyncRun } from '../../module.mjs'
+import { ok } from '../../../types/result/module.f.mjs'
 import { asBase, asNominal } from '../../memory/module.f.mjs'
 
 /** @typedef {ToAsyncOperationMap<MemOp>} MemoryOperationMap */
@@ -37,24 +39,25 @@ export const memoryOperationMap = (uuid = randomUUID) => {
             /** @type {Key<unknown>} */
             const key = asNominal(id)
             store.set(id, value)
-            return key
+            return ok(key)
         },
         memRead: async key => {
             const id = asBase(key)
             if (!store.has(id)) { throw missingKey(id) }
-            return store.get(id)
+            return ok(store.get(id))
         },
         memWrite: async (key, value) => {
             const id = asBase(key)
             if (!store.has(id)) { throw missingKey(id) }
             store.set(id, value)
+            return ok(undefined)
         },
     }
 }
 
 /**
  * Runs a memory-only effect using a fresh memory store.
- * @type {<T>(effect: Effect<MemOp, T>) => Promise<T>}
+ * @type {<T, E>(effect: Effect<MemOp, T, E>) => Promise<Result<T, E>>}
  */
 export const run = effect =>
     asyncRun(/** @type {ToAsyncOperationMap<MemOp>} */ (memoryOperationMap()))(effect)

package/fjs/effects/node/memory/proof.mjs

@@ -7,13 +7,15 @@
  */
 
 import { asyncRun } from '../../module.mjs'
+import { errorSummary } from '../module.f.mjs'
 import {
     asNominal,
     create, read, write,
 } from '../../memory/module.f.mjs'
 import { memoryOperationMap, run } from './module.mjs'
 import { assert, assertEq } from '../../../asserts/module.f.mjs'
-import { step } from '../../module.f.mjs'
+import { unwrap } from "../../../types/result/module.f.mjs"
+import { step, unwrapStep } from '../../module.f.mjs'
 
 export const proof = {
     nodeInterpreter: async () => {
@@ -22,13 +24,17 @@ export const proof = {
             key => step(
                 write(key, 2),
                 () => read(key)))
-        assertEq(await run(x), 2)
+        const r = await run(x)
+        assert(r[0] === 'ok', r)
+        assertEq(r[1], 2)
     },
     reusedOperationMapPersists: async () => {
         const runner = asyncRun(/** @type {import('../../types.ts').ToAsyncOperationMap<MemOp>} */ (memoryOperationMap()))
-        const key = await runner(create(1))
+        // `unwrapStep` empties the channel, so what the runner hands back is
+        // an `ok` and these unwraps are total.
+        const key = unwrap(await runner(unwrapStep(create(1), errorSummary)))
         await runner(write(key, 2))
-        const result = await runner(read(key))
+        const result = unwrap(await runner(unwrapStep(read(key), errorSummary)))
         assertEq(result, 2)
     },
     missingKeyThrows: async () => {

package/fjs/effects/node/module.d.mts

@@ -1,5 +1,5 @@
 /**
- * Node.js effect runner: interprets `Effect<NodeOp, T>` directly against the
+ * Node.js effect runner: interprets `Effect<NodeOp, T, E>` directly against the
  * Node globals and built-in modules (`fs`, `http`, `child_process`, `process`,
  * `fetch`, …).
  *
@@ -13,12 +13,13 @@
  * @module
  *
  * @import { Effect } from '../types.ts'
- * @import { Server as EffectServer, Headers, Module, NodeOp, RequestListener as Erl, NodeProgram, NodeProgramOptions, WriteConsoles, TestContext, TestFn, } from './types.ts'
+ * @import { IoResult, Server as EffectServer, Headers, Module, NodeOp, RequestListener as Erl, NodeProgram, NodeProgramOptions, WriteConsoles, TestContext, TestFn, } from './types.ts'
  * @import { Result } from '../../types/result/types.ts'
  * @import { StringMap } from '../../types/object/types.ts'
  */
 import type { Effect } from '../types.ts';
 import type { Headers, NodeOp, NodeProgram } from './types.ts';
+import type { Result } from '../../types/result/types.ts';
 import type { StringMap } from '../../types/object/types.ts';
 export type _Server = {
     readonly listen: (port: number) => void;
@@ -34,7 +35,7 @@ export type _ServerResponse = {
     readonly end: (body: Uint8Array) => void;
 };
 export type _RequestListener = (req: _IncomingMessage, res: _ServerResponse) => Promise<void>;
-export type _EffectToPromise = <T>(effect: Effect<NodeOp, T>) => Promise<T>;
+export type _EffectToPromise = <T, E>(effect: Effect<NodeOp, T, E>) => Promise<Result<T, E>>;
 export type _FrameworkRegister = (name: string, fn: () => Promise<void>) => Promise<void>;
 /**
  * Runs a `NodeProgram` against the real Node globals and process arguments,

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

@@ -11,37 +11,99 @@
  * @module
  *
  * @import { Vec } from '../../types/bit_vec/types.ts'
- * @import { Effect, Func, Operation } from '../types.ts'
+ * @import { Result } from '../../types/result/types.ts'
+ * @import { Commands, CommandSet, Effect, Func, NotImplemented, Operation } from '../types.ts'
  * @import { List } from '../list/types.ts'
- * @import { All, Access, Await, Console, CreateExclusive, CreateServer, Dirent, Engine, Env, Exec, ExecResult, Fetch, FileStat, Forever, Fs, Headers, Http, IncomingMessage, Import, IoResult, Listen, MakeDirectoryOptions, Mkdir, Module, Now, NodeOp, NodeProgramOptions, RandomInt, Read, ReadBytes, ReadConsoles, ReadFile, Readdir, ReaddirOptions, RequestListener, Rename, Rm, Sandbox, SandboxResult, Server, ServerResponse, Stat, Test, TestContext, TestFn, Write, WriteBytes, WriteConsoles, WriteFile, _UtfList, _WriteLoop, } from './types.ts'
+ * @import { All, Access, Await, Console, CreateExclusive, CreateServer, Dirent, Engine, Env, Exec, ExecResult, Fetch, FileStat, Forever, Fs, Headers, Http, IncomingMessage, Import, IoChannel, IoError, IoErrorInfo, Listen, MakeDirectoryOptions, Mkdir, Module, Now, NodeOp, NodeProgramOptions, RandomInt, Read, ReadBytes, ReadConsoles, ReadFile, Readdir, ReaddirOptions, RequestListener, Rename, Rm, Sandbox, SandboxResult, Server, ServerResponse, Stat, Test, TestContext, TestFn, Write, WriteBytes, WriteConsoles, WriteFile, _UtfList, _WriteLoop } from './types.ts'
  */
 import type { Vec } from '../../types/bit_vec/types.ts';
-import type { Effect, Func, Operation } from '../types.ts';
+import type { Result } from '../../types/result/types.ts';
+import type { Commands, Effect, Func, NotImplemented, Operation } from '../types.ts';
 import type { List } from '../list/types.ts';
-import type { All, Access, Await, Console, CreateExclusive, CreateServer, Engine, Exec, Fetch, Forever, Import, IoResult, Listen, Mkdir, Now, RandomInt, Read, ReadBytes, ReadConsoles, ReadFile, Readdir, RequestListener, Rename, Rm, Sandbox, Server, Stat, Test, Write, WriteBytes, WriteFile } from './types.ts';
+import type { All, Access, Await, Console, CreateExclusive, CreateServer, Engine, Exec, Fetch, Forever, Import, IoChannel, IoError, IoErrorInfo, Listen, Mkdir, Now, NodeOp, RandomInt, Read, ReadBytes, ReadConsoles, ReadFile, Readdir, RequestListener, Rename, Rm, Sandbox, Server, Stat, Test, Write, WriteBytes, WriteFile } from './types.ts';
+/**
+ * Builds a normalized host error. The constructor exists so the shape is
+ * written once: every runner reports its failures through it, and a consumer
+ * matching on `'ioError'` knows what the payload holds.
+ *
+ * @type {(info: IoErrorInfo) => IoError}
+ */
+export declare const ioError: (info: IoErrorInfo) => IoError;
+/**
+ * Normalizes a **thrown** value into an {@link IoError}: the OS error code when
+ * the host attached a string one, and a message that is the `Error`'s own or
+ * the value's string form.
+ *
+ * This is the boundary where an impure runner's `catch` becomes ordinary effect
+ * data. Nothing past it sees the thrown object, which is the point — a stack, a
+ * `cause`, and arbitrary own properties do not survive a wire hop, and a
+ * program that branched on them would be reading the host's implementation
+ * rather than the operation's contract.
+ *
+ * @type {(e: unknown) => IoError}
+ */
+export declare const toIoError: (e: unknown) => IoError;
 /**
  * True if `e` is a "file or directory does not exist" (`ENOENT`) error.
  *
- * Node's filesystem rejections are `Error`s carrying `code: 'ENOENT'`; the
- * virtual interpreter mirrors that shape for absent paths. Lets callers swallow
- * only the missing-path case (e.g. a fresh store) while propagating genuine
- * failures (permissions, corruption) rather than masking them.
+ * Node's filesystem rejections are `Error`s carrying `code: 'ENOENT'`, which
+ * {@link toIoError} keeps; the virtual interpreter reports the same code for
+ * absent paths. Lets callers swallow only the missing-path case (e.g. a fresh
+ * store) while propagating genuine failures (permissions, corruption) rather
+ * than masking them.
+ *
+ * A {@link NotImplemented} is never "not found": a runner that cannot perform
+ * the operation has not looked for the path at all, so the two must not
+ * collapse into one benign branch — which is exactly what a bare `unknown`
+ * error channel used to allow.
+ *
+ * @type {(e: IoChannel) => boolean}
+ */
+export declare const isNotFound: (e: IoChannel) => boolean;
+/**
+ * The commands of {@link nodeCommandSet}, in the form a partial runner tests
+ * membership against. The cast is the one `Object.keys` always needs: it
+ * answers `string[]` for a record whose keys the type system knows exactly.
  *
- * @type {(e: unknown) => boolean}
+ * @type {Commands<NodeOp>}
  */
-export declare const isNotFound: (e: unknown) => boolean;
+export declare const nodeCommands: Commands<NodeOp>;
 /**
  * To run the operation `O` should be known by the runner/engine.
- * This is the reason why we merge `O` with `All` in the resulted `Effect`.
+ * This is the reason why we merge `O` with `All` in the resulting effect.
  */
-export declare const all: <O extends Operation, T>(...a: readonly Effect<O, T>[]) => Effect<O | All, readonly T[]>;
+export declare const all: <O extends Operation, T, E>(...a: readonly Effect<O, T, E>[]) => Effect<O | All, readonly Result<T, E>[], NotImplemented>;
+/**
+ * {@link all} in the `ok` channel: collects the values when every effect
+ * succeeded, and answers with the first failure otherwise.
+ *
+ * `all` alone cannot serve a fallible chain. Its envelope is the runner's
+ * (`OpResult`, saying whether the *operation* could be dispatched), so handing
+ * it `Effect`s nests one `Result` inside another and the caller receives
+ * `readonly Result<T, E>[]`. That has to be collapsed before the chain can
+ * `step` again, and a continuation that forgets to is the value-discarding
+ * hazard this migration exists to remove — one level in, where it is harder to
+ * see.
+ *
+ * **Every effect still runs.** The short-circuit is in the *result*, not in the
+ * execution: `all` performs them concurrently and this reads the answers once
+ * they are all in, so a failure does not cancel its siblings the way it stops
+ * the sequential `forEachStep` in `./module.f.mjs`. The error channel
+ * unions the runner's
+ * `NotImplemented` with the effects' own `E` for the same reason every other
+ * step does — either can be what went wrong.
+ *
+ * @type {<O extends Operation, T, E>(...a: readonly Effect<O, T, E>[]) => Effect<O | All, readonly T[], NotImplemented | E>}
+ */
+export declare const allOk: <O extends Operation, T, E>(...a: readonly Effect<O, T, E>[]) => Effect<O | All, readonly T[], NotImplemented | E>;
 /**
  * @template {Operation} O0
  * @template T0
- * @param {Effect<O0, T0>} a
- * @returns {<O1 extends Operation, T1>(b: Effect<O1, T1>) => Effect<O0 | O1 | All, readonly[T0, T1]>}
+ * @template E0
+ * @param {Effect<O0, T0, E0>} a
+ * @returns {<O1 extends Operation, T1, E1>(b: Effect<O1, T1, E1>) => Effect<O0 | O1 | All, readonly[Result<T0, E0>, Result<T1, E1>], NotImplemented>}
  */
-export declare const both: <O0 extends Operation, T0>(a: Effect<O0, T0>) => <O1 extends Operation, T1>(b: Effect<O1, T1>) => Effect<O0 | O1 | All, readonly [T0, T1]>;
+export declare const both: <O0 extends Operation, T0, E0>(a: Effect<O0, T0, E0>) => <O1 extends Operation, T1, E1>(b: Effect<O1, T1, E1>) => Effect<O0 | O1 | All, readonly [Result<T0, E0>, Result<T1, E1>], NotImplemented>;
 /** @type {Func<Fetch>} */
 export declare const fetch: Func<Fetch>;
 /** @type {Func<Mkdir>} */
@@ -51,13 +113,13 @@ export declare const readFile: Func<ReadFile>;
 /**
  * Reads a file as UTF-8 text.
  *
- * Preserves the `IoResult` instead of unwrapping so callers can pattern-match
- * on errors (e.g. convert them into domain-specific errors) or `unwrap` at the
- * call site.
+ * Preserves the error channel instead of unwrapping so callers can
+ * pattern-match on it (e.g. convert a failure into a domain-specific error) or
+ * `unwrap` at the call site.
  *
- * @type {(path: string) => Effect<ReadFile, IoResult<string>>}
+ * @type {(path: string) => Effect<ReadFile, string, IoChannel>}
  */
-export declare const readUtf8File: (path: string) => Effect<ReadFile, IoResult<string>>;
+export declare const readUtf8File: (path: string) => Effect<ReadFile, string, IoChannel>;
 /** @type {Func<Readdir>} */
 export declare const readdir: Func<Readdir>;
 /** @type {Func<WriteFile>} */
@@ -65,9 +127,9 @@ export declare const writeFile: Func<WriteFile>;
 /**
  * Writes a string to `path` as UTF-8 bytes.
  *
- * @type {(path: string, content: string) => Effect<WriteFile, IoResult<void>>}
+ * @type {(path: string, content: string) => Effect<WriteFile, void, IoChannel>}
  */
-export declare const writeUtf8File: (path: string, content: string) => Effect<WriteFile, IoResult<void>>;
+export declare const writeUtf8File: (path: string, content: string) => Effect<WriteFile, void, IoChannel>;
 /** @type {Func<Rm>} */
 export declare const rm: Func<Rm>;
 /** @type {Func<Rename>} */
@@ -87,10 +149,10 @@ export declare const writeBytes: Func<WriteBytes>;
 /**
  * @template {Operation} O
  * @param {string} path
- * @param {List<O, IoResult<Vec>>} e
- * @returns {Effect<O | WriteBytes | CreateExclusive, IoResult<void>>}
+ * @param {List<O, Vec, IoChannel>} e
+ * @returns {Effect<O | WriteBytes | CreateExclusive, void, IoChannel>}
  */
-export declare const writeFromStream: <O extends Operation>(path: string, e: List<O, IoResult<Vec>>) => Effect<O | WriteBytes | CreateExclusive, IoResult<void>>;
+export declare const writeFromStream: <O extends Operation>(path: string, e: List<O, Vec, IoChannel>) => Effect<O | WriteBytes | CreateExclusive, void, IoChannel>;
 /** @type {Func<Stat>} */
 export declare const stat: Func<Stat>;
 export declare const createServer: <O extends Operation>(listener: RequestListener<O>) => Effect<O | CreateServer, Server>;
@@ -101,12 +163,16 @@ export declare const forever: Func<Forever>;
 /** @type {Func<Import>} */
 export declare const import_: Func<Import>;
 /** Emits a `Write` effect to the given named stream. */
+/** @type {Func<Write>} */
 export declare const write: Func<Write>;
 /** Writes a line to `stdout`. Replaces the retired `Log` effect. */
+/** @type {Console} */
 export declare const log: Console;
 /** Writes a line to `stderr`. Replaces the retired `Error` effect. */
+/** @type {Console} */
 export declare const error: Console;
 /** Emits a `Read` effect, yielding the next input byte or `null` at EOF. */
+/** @type {Func<Read>} */
 export declare const read: Func<Read>;
 /**
  * Reads one line from `stream` as a pure combinator over the byte-level
@@ -122,9 +188,12 @@ export declare const read: Func<Read>;
  * reversed and decoded once at the terminator, so a large line costs O(n)
  * rather than the O(n²) of copying a growing array on every byte.
  *
- * @type {(stream: ReadConsoles) => Effect<Read, string | null>}
+ * A failed `read` — a runner without the operation — propagates: the line is
+ * not silently truncated into a `null` that a caller would read as EOF.
+ *
+ * @type {(stream: ReadConsoles) => Effect<Read, string | null, NotImplemented>}
  */
-export declare const readLine: (stream: ReadConsoles) => Effect<Read, string | null>;
+export declare const readLine: (stream: ReadConsoles) => Effect<Read, string | null, NotImplemented>;
 /** @type {Func<Now>} */
 export declare const now: Func<Now>;
 /**
@@ -148,18 +217,84 @@ export declare const now: Func<Now>;
  * @type {Func<Sandbox>}
  */
 export declare const sandbox: Func<Sandbox>;
-/** @type {(p: unknown) => Effect<Await, unknown>} */
-export declare const awaitIfPromise: (p: unknown) => Effect<Await, unknown>;
+/** @type {(p: unknown) => Effect<Await, unknown, NotImplemented>} */
+export declare const awaitIfPromise: (p: unknown) => Effect<Await, unknown, NotImplemented>;
 /** @type {Func<Test>} */
 export declare const test: Func<Test>;
 /**
- * Writes an error line to `stderr` and yields exit code `1`. The canonical
+ * Writes an error line to `stderr` and fails with exit code `1`. The canonical
  * "fail with a message" program for a `NodeProgram`. For non-`1` exit codes,
- * compose `mapStep(error(s), () => n)` directly.
+ * compose `resultMapStep(error(s), () => resultError(n))` directly.
+ *
+ * **It never succeeds, and the type says so.** `E` is `number` and `T` is
+ * `never`, so `step`'s continuation takes a `never` and can never run. That is
+ * a continuation nobody reaches, not a compile error: writing one still type-
+ * checks, because a function accepting `never` accepts anything. What the type
+ * buys is that no *value* can be invented for the success branch, so nothing
+ * downstream can proceed as if this had succeeded.
+ *
+ * **The write's own outcome is deliberately discarded**, which is why this is
+ * `resultMapStep` rather than `mapStep`. The program is already failing and
+ * the exit code is `1` whether or not `stderr` accepted the bytes; propagating
+ * here would hand every caller a "failed to report a failure" branch with no
+ * better answer available to it than the one taken here.
+ *
+ * @type {(s: string) => Effect<Write, never, number>}
+ */
+export declare const errorExit: (s: string) => Effect<Write, never, number>;
+/**
+ * The exit code a {@link Program} answered, from whichever branch it came.
+ *
+ * `Result<0, number>` puts a number at `[1]` on both sides — `ok(0)` for
+ * success, `error(n)` for failure — so reading the code never asks which
+ * branch produced it, while a caller that cares *whether* it failed still asks
+ * `[0]`. That is why the success type is the literal `0` rather than `void`.
+ *
+ * A non-zero code belongs in the `error` branch and `0` in the `ok` branch; the
+ * type cannot say so, since there is no "non-zero number", and nothing depends
+ * on it — this reads `[1]` either way.
+ *
+ * @type {(r: Result<0, number>) => number}
+ */
+export declare const exitCode: (r: Result<0, number>) => number;
+/**
+ * Renders a channel error as a human line: an {@link IoError}'s own message, or
+ * the command name a runner could not dispatch.
+ *
+ * @type {(e: IoChannel) => string}
+ */
+export declare const errorMessage: (e: IoChannel) => string;
+/**
+ * Renders a channel error for a **remote** caller: the command name for a
+ * {@link NotImplemented}, the OS error code for an `IoError`, and nothing else.
+ *
+ * {@link errorMessage} is for the operator of the program, who is entitled to
+ * the host's own words — including the path that failed. A protocol client is
+ * not, and the difference is not stylistic: `payload.message` is where the
+ * host puts the absolute path it could not read, so answering an MCP tool call
+ * with it publishes the server's filesystem layout to whoever is on the other
+ * end. The code (`ENOENT`, `EACCES`) says *what* went wrong without saying
+ * *where*, which is the part a client can act on anyway.
+ *
+ * A host that attached no code leaves nothing safe to forward, so the answer is
+ * the bare kind. That is deliberate: guessing which part of a free-text message
+ * is path-free is exactly the mistake this exists to prevent.
+ *
+ * @type {(e: IoChannel) => string}
+ */
+export declare const errorSummary: (e: IoChannel) => string;
+/**
+ * Ends a program with an exit code that reflects `e`: `ok` yields `0`, and a
+ * failure is reported on `stderr` and yields `1` ({@link errorExit}).
+ *
+ * This is the exit-code policy a `NodeProgram` needs at the end of its chain,
+ * and the reason a program does not have to invent one per command. It is the
+ * counterpart of {@link isNotFound} at the other end of the channel: where that
+ * one asks which failure this is, this one stops asking and reports.
  *
- * @type {(s: string) => Effect<Write, number>}
+ * @type {<O extends Operation, T>(e: Effect<O, T, IoChannel>) => Effect<O | Write, 0, number>}
  */
-export declare const errorExit: (s: string) => Effect<Write, number>;
+export declare const exitStep: <O extends Operation, T>(e: Effect<O, T, IoChannel>) => Effect<O | Write, 0, number>;
 /**
  * Compares semantic versions numerically by major, minor, then patch.
  *