functionalscript 0.46.0 → 0.47.0

package/fjs/edag/types.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Type-level API for `fjs/edag/module.f.mjs`: `Exp`, the union of every EDAG
+ * node kind — see the union immediately below for the current list, rather
+ * than enumerating it here too, where it silently drifts stale as nodes are
+ * added — each pinned against its rtti schema in the sibling module with
+ * `Assert<Check<..., typeof ...>>`. Every tuple here is closed on both sides:
+ * none of the schemas says `open`, so these types are exact rather than the
+ * approximation `TupleTs` in `../types/rtti/ts/types.ts` describes.
+ */
+export type Exp = Primitive | Array | Object | Dot | Call | OptionDot | OptionCall | Comma | Op2 | Op1 | Op0;
+/**
+ * Bare constant values, not operation nodes — `undefined` is deliberately
+ * excluded, since `['undefined']` is a tagged `Op0` operation, not a bare
+ * value; see `primitive` in `module.f.mjs`.
+ */
+export type Primitive = null | boolean | number | string | bigint;
+export type Exps = readonly Exp[];
+export type Spread = readonly ['...', Exp];
+export type Items = Exp | Spread;
+export type Array = readonly ['[]', readonly Items[]];
+export type Property = readonly [':', Exp, Exp];
+export type Properties = Property | Spread;
+export type Object = readonly ['{}', readonly Properties[]];
+export type NumberCast = readonly ['Number', Exp];
+export type Index = number | NumberCast | string;
+/**
+ * The continuation of a `Dot`: a receiver is live, no region is open.
+ *
+ * Only a call can be here — a property step would waste the receiver with no
+ * region to keep it in, so `a.b.c` nests `Dot`s instead.
+ */
+export type PropertyLambda = null | readonly ['|()', Exp, null] | readonly ['|?.()', Exp, OptionLambda];
+/**
+ * The continuation of a step that produced a plain value inside an open
+ * region: `OptionCall`'s, and every call step that stays in its region.
+ */
+export type OptionLambda = null | readonly ['|()', Exp, OptionLambda] | readonly ['|.', Index, OptionPropertyLambda];
+/**
+ * The continuation of a property step inside an open region: both bits live,
+ * so this is the state with every production — the three ways a call can
+ * relate to the region it sits in, plus the property step the region keeps
+ * from leaving.
+ */
+export type OptionPropertyLambda = null | readonly ['|()', Exp, OptionLambda] | readonly ['|.', Index, OptionPropertyLambda] | readonly ['|?.()', Exp, OptionLambda] | readonly ['|!()', Exp, null];
+export type Call = readonly ['()', Exp, Exp];
+export type Dot = readonly ['.', Exp, Index, PropertyLambda];
+export type OptionDot = readonly ['?.', Exp, Index, OptionPropertyLambda];
+export type OptionCall = readonly ['?.()', Exp, Exp, OptionLambda];
+export type Comma = readonly [',', Exps];
+export type Op0Id = 'undefined' | 'args' | 'frame';
+export type Op0 = readonly [Op0Id];
+export type Op1Id = 'String' | 'Number' | 'neg' | '!' | '~';
+export type Op1 = readonly [Op1Id, Exp];
+export type Op2Id = '=>' | 'own' | '===' | '!==' | '>' | '>=' | '<' | '<=' | '+' | '-' | '*' | '/' | '%' | '**' | '&' | '|' | '^' | '<<' | '>>' | '>>>' | '&&' | '||' | '??';
+export type Op2 = readonly [Op2Id, Exp, Exp];

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

@@ -22,8 +22,42 @@ export type Uuid = () => string;
  * @type {(uuid?: Uuid) => MemoryOperationMap}
  */
 export declare const memoryOperationMap: (uuid?: Uuid) => MemoryOperationMap;
+export type MemoryRun = <T, E>(effect: Effect<MemOp, T, E>) => Promise<Result<T, E>>;
 /**
- * Runs a memory-only effect using a fresh memory store.
- * @type {<T, E>(effect: Effect<MemOp, T, E>) => Promise<Result<T, E>>}
+ * An {@link asyncRun} runner over {@link MemOp}: an effect in, its `Result` out.
+ * @typedef {<T, E>(effect: Effect<MemOp, T, E>) => Promise<Result<T, E>>} MemoryRun
  */
-export declare const run: <T, E>(effect: Effect<MemOp, T, E>) => Promise<Result<T, E>>;
+/**
+ * Creates a runner owning a fresh memory store. Every effect passed to the
+ * *same* runner shares that store; a new runner starts empty.
+ *
+ * **The `MemoryRun` annotation is what types the `asyncRun` call.** `asyncRun`
+ * takes a `ToAsyncOperationMap<O>`, a mapped type keyed on `O[0]`, and
+ * TypeScript cannot infer `O` back out of one — only a homomorphic
+ * `{[K in keyof T]: …}` is reversed. Left to argument inference `O` falls back
+ * to its `Operation` constraint, whose payloads and outputs are `never`, and no
+ * real map is assignable to that; the call site then needs a cast. Annotating
+ * the result instead lets `O` be inferred from the return type, which is what
+ * gives the call a real `O` to check the argument against.
+ *
+ * **What that check is worth here is narrow, so it is worth stating exactly.**
+ * Each handler is already checked against `MemOp` by
+ * {@link memoryOperationMap}'s own annotation, and was before this call was
+ * written — a drifted handler is reported there, at the factory, either way.
+ * What the runner adds is agreement between the *declared map type* and
+ * `MemOp`: give `MemoryOperationMap` a narrower operation set and this line
+ * reports the missing handler, where an unchecked call site would leave it to
+ * whoever spreads the map next. The wider hazard — a cast stripping the
+ * contextual type from an object *literal*, so no handler is checked at all —
+ * is `runNodeEffect`'s (`../module.mjs`), which passes a literal; this call
+ * passes an already-annotated result.
+ * @type {(uuid?: Uuid) => MemoryRun}
+ */
+export declare const memoryRun: (uuid?: Uuid) => MemoryRun;
+/**
+ * Runs a memory-only effect using a fresh memory store — a store per call, so
+ * nothing written by one `run` is visible to the next. Use {@link memoryRun}
+ * to keep one.
+ * @type {MemoryRun}
+ */
+export declare const run: MemoryRun;

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

@@ -56,8 +56,42 @@ export const memoryOperationMap = (uuid = randomUUID) => {
 }
 
 /**
- * Runs a memory-only effect using a fresh memory store.
- * @type {<T, E>(effect: Effect<MemOp, T, E>) => Promise<Result<T, E>>}
+ * An {@link asyncRun} runner over {@link MemOp}: an effect in, its `Result` out.
+ * @typedef {<T, E>(effect: Effect<MemOp, T, E>) => Promise<Result<T, E>>} MemoryRun
  */
-export const run = effect =>
-    asyncRun(/** @type {ToAsyncOperationMap<MemOp>} */ (memoryOperationMap()))(effect)
+
+/**
+ * Creates a runner owning a fresh memory store. Every effect passed to the
+ * *same* runner shares that store; a new runner starts empty.
+ *
+ * **The `MemoryRun` annotation is what types the `asyncRun` call.** `asyncRun`
+ * takes a `ToAsyncOperationMap<O>`, a mapped type keyed on `O[0]`, and
+ * TypeScript cannot infer `O` back out of one — only a homomorphic
+ * `{[K in keyof T]: …}` is reversed. Left to argument inference `O` falls back
+ * to its `Operation` constraint, whose payloads and outputs are `never`, and no
+ * real map is assignable to that; the call site then needs a cast. Annotating
+ * the result instead lets `O` be inferred from the return type, which is what
+ * gives the call a real `O` to check the argument against.
+ *
+ * **What that check is worth here is narrow, so it is worth stating exactly.**
+ * Each handler is already checked against `MemOp` by
+ * {@link memoryOperationMap}'s own annotation, and was before this call was
+ * written — a drifted handler is reported there, at the factory, either way.
+ * What the runner adds is agreement between the *declared map type* and
+ * `MemOp`: give `MemoryOperationMap` a narrower operation set and this line
+ * reports the missing handler, where an unchecked call site would leave it to
+ * whoever spreads the map next. The wider hazard — a cast stripping the
+ * contextual type from an object *literal*, so no handler is checked at all —
+ * is `runNodeEffect`'s (`../module.mjs`), which passes a literal; this call
+ * passes an already-annotated result.
+ * @type {(uuid?: Uuid) => MemoryRun}
+ */
+export const memoryRun = (uuid = randomUUID) => asyncRun(memoryOperationMap(uuid))
+
+/**
+ * Runs a memory-only effect using a fresh memory store — a store per call, so
+ * nothing written by one `run` is visible to the next. Use {@link memoryRun}
+ * to keep one.
+ * @type {MemoryRun}
+ */
+export const run = effect => memoryRun()(effect)

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

@@ -3,10 +3,13 @@
  *
  * @module
  *
- * @import { Key, MemOp } from '../../memory/types.ts'
+ * @import { Key } from '../../memory/types.ts'
+ * @import { Uuid } from './module.mjs'
  */
 export declare const proof: {
     nodeInterpreter: () => Promise<void>;
-    reusedOperationMapPersists: () => Promise<void>;
+    reusedRunnerPersists: () => Promise<void>;
+    runnersDoNotShareStore: () => Promise<void>;
+    runIsPerCall: () => Promise<void>;
     missingKeyThrows: () => Promise<void>;
 };

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

@@ -3,16 +3,16 @@
  *
  * @module
  *
- * @import { Key, MemOp } from '../../memory/types.ts'
+ * @import { Key } from '../../memory/types.ts'
+ * @import { Uuid } from './module.mjs'
  */
 
-import { asyncRun } from '../../module.mjs'
 import { errorSummary } from '../module.f.mjs'
 import {
-    asNominal,
+    asBase, asNominal,
     create, read, write,
 } from '../../memory/module.f.mjs'
-import { memoryOperationMap, run } from './module.mjs'
+import { memoryRun, run } from './module.mjs'
 import { assert, assertEq } from '../../../asserts/module.f.mjs'
 import { unwrap } from "../../../types/result/module.f.mjs"
 import { step, unwrapStep } from '../../module.f.mjs'
@@ -28,8 +28,8 @@ export const proof = {
         assert(r[0] === 'ok', r)
         assertEq(r[1], 2)
     },
-    reusedOperationMapPersists: async () => {
-        const runner = asyncRun(/** @type {import('../../types.ts').ToAsyncOperationMap<MemOp>} */ (memoryOperationMap()))
+    reusedRunnerPersists: async () => {
+        const runner = memoryRun()
         // `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)))
@@ -37,6 +37,36 @@ export const proof = {
         const result = unwrap(await runner(unwrapStep(read(key), errorSummary)))
         assertEq(result, 2)
     },
+    runnersDoNotShareStore: async () => {
+        // Both runners mint the *same* key id, so the id cannot be what tells
+        // them apart — only store ownership can. A store shared between
+        // runners (module-level rather than per call) passes every other proof
+        // here; this is the one that fails it.
+        /** @type {Uuid} */
+        const uuid = () => 'fixed'
+        const a = memoryRun(uuid)
+        const b = memoryRun(uuid)
+        const key = unwrap(await a(unwrapStep(create(1), errorSummary)))
+        const result = await b(read(key)).then(
+            () => undefined,
+            error => error,
+        )
+        assert(result instanceof Error, result)
+        assertEq(result.message, 'memory key not found: fixed', result)
+    },
+    runIsPerCall: async () => {
+        // `run` builds a runner per call, so the store the first call wrote to
+        // is gone by the second. One runner shared across every `run` — the
+        // other half of the store-ownership mutant — passes every other proof
+        // here, including `runnersDoNotShareStore`.
+        const key = unwrap(await run(unwrapStep(create(1), errorSummary)))
+        const result = await run(read(key)).then(
+            () => undefined,
+            error => error,
+        )
+        assert(result instanceof Error, result)
+        assertEq(result.message, `memory key not found: ${asBase(key)}`, result)
+    },
     missingKeyThrows: async () => {
         /** @type {Key<number>} */
         const key = asNominal('missing')

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

@@ -16,13 +16,20 @@
  * @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 { Nullable } from '../../types/nullable/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 _Socket = {
+    readonly end: (data: string) => void;
+};
 export type _Server = {
-    readonly listen: (port: number) => void;
+    readonly listen: (port: number, host: string) => void;
+    readonly once: (event: string, f: (e: unknown) => void) => void;
+    on(event: string, f: (req: unknown, socket: _Socket) => void): void;
+    readonly removeListener: (event: string, f: (e: unknown) => void) => void;
 };
 export type _Readable = AsyncIterable<Uint8Array>;
 export type _IncomingMessage = _Readable & {
@@ -33,6 +40,7 @@ export type _IncomingMessage = _Readable & {
 export type _ServerResponse = {
     readonly writeHead: (status: number, headers: StringMap<string>) => _ServerResponse;
     readonly end: (body: Uint8Array) => void;
+    readonly headersSent: boolean;
 };
 export type _RequestListener = (req: _IncomingMessage, res: _ServerResponse) => Promise<void>;
 export type _EffectToPromise = <T, E>(effect: Effect<NodeOp, T, E>) => Promise<Result<T, E>>;

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

@@ -29,6 +29,45 @@ import type { All, Access, Await, Console, CreateExclusive, CreateServer, Engine
  * @type {(info: IoErrorInfo) => IoError}
  */
 export declare const ioError: (info: IoErrorInfo) => IoError;
+/**
+ * The host a {@link Listen} refuses.
+ *
+ * Node treats `''` exactly as it treats an omitted argument and binds the
+ * unspecified address — measured on Linux with Node 22.22.2, where
+ * `listen(0, '')` reports `0.0.0.0`, and on Darwin with Node 23.11.0, where it
+ * reports `::`. **Which** unspecified address is the platform's business; that
+ * it is one of them is universal. `Listen` takes the host precisely so that
+ * an address is stated rather than inherited, and a missing configuration value
+ * arriving as `''` inherits the widest one there is. Every runner refuses it, so
+ * a program proven against the virtual one binds where the Node one binds.
+ *
+ * @type {string}
+ */
+export declare const emptyHost: string;
+/**
+ * Node's own code for an argument it rejects, reported here for a value Node
+ * itself accepts: a caller reading `IoError.code` should not have to learn a
+ * second vocabulary for a refusal that is the runner's own.
+ *
+ * @type {string}
+ */
+export declare const emptyHostCode: string;
+/** Node's message shape for {@link emptyHostCode} — `The argument '<name>'
+ * <reason>. Received <value>`.
+ *
+ * @type {string}
+ */
+export declare const emptyHostMessage: string;
+/**
+ * The failure a runner reports for {@link emptyHost}.
+ *
+ * The virtual runner answers with this value and the Node runner throws an
+ * `Error` carrying the same two literals, which is what keeps the two from
+ * drifting apart on a refusal neither inherits from Node.
+ *
+ * @type {IoError}
+ */
+export declare const emptyHostError: 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

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

@@ -37,6 +37,52 @@ import {
  */
 export const ioError = info => ['ioError', info]
 
+/**
+ * The host a {@link Listen} refuses.
+ *
+ * Node treats `''` exactly as it treats an omitted argument and binds the
+ * unspecified address — measured on Linux with Node 22.22.2, where
+ * `listen(0, '')` reports `0.0.0.0`, and on Darwin with Node 23.11.0, where it
+ * reports `::`. **Which** unspecified address is the platform's business; that
+ * it is one of them is universal. `Listen` takes the host precisely so that
+ * an address is stated rather than inherited, and a missing configuration value
+ * arriving as `''` inherits the widest one there is. Every runner refuses it, so
+ * a program proven against the virtual one binds where the Node one binds.
+ *
+ * @type {string}
+ */
+export const emptyHost = ''
+
+/**
+ * Node's own code for an argument it rejects, reported here for a value Node
+ * itself accepts: a caller reading `IoError.code` should not have to learn a
+ * second vocabulary for a refusal that is the runner's own.
+ *
+ * @type {string}
+ */
+export const emptyHostCode = 'ERR_INVALID_ARG_VALUE'
+
+/** Node's message shape for {@link emptyHostCode} — `The argument '<name>'
+ * <reason>. Received <value>`.
+ *
+ * @type {string}
+ */
+export const emptyHostMessage = `The argument 'host' must not be empty. Received ''`
+
+/**
+ * The failure a runner reports for {@link emptyHost}.
+ *
+ * The virtual runner answers with this value and the Node runner throws an
+ * `Error` carrying the same two literals, which is what keeps the two from
+ * drifting apart on a refusal neither inherits from Node.
+ *
+ * @type {IoError}
+ */
+export const emptyHostError = ioError({
+    code: emptyHostCode,
+    message: emptyHostMessage,
+})
+
 /**
  * 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