functionalscript 0.43.1 → 0.45.0

package/fjs/effects/node/virtual/proof.f.mjs

@@ -0,0 +1,238 @@
+/**
+ * @import { Dir, JsModule } from './types.ts'
+ */
+
+import { assert, assertEq } from '../../../asserts/module.f.mjs'
+import { access, awaitIfPromise, fetch, rm, writeFile, readFile, readdir, import_, rename, readBytes, writeBytes, stat } from '../module.f.mjs'
+import { maxLengthBytes, vec, vec8 } from '../../../types/bit_vec/module.f.mjs'
+import { emptyState, virtual } from './module.f.mjs'
+
+export const proof = {
+    rm: {
+        success: () => {
+            /** @type {Dir} */
+            const root = { 'a.txt': [vec8(0x42n)] }
+            const [, result] = virtual({ ...emptyState, root })(rm('a.txt'))
+            assert(result[0] === 'ok')
+        },
+        notFound: () => {
+            const [, result] = virtual(emptyState)(rm('notexist.txt'))
+            assert(result[0] === 'error')
+        },
+        isDirectory: () => {
+            /** @type {Dir} */
+            const inner = {}
+            /** @type {Dir} */
+            const root = { 'mydir': inner }
+            const [, result] = virtual({ ...emptyState, root })(rm('mydir'))
+            assert(result[0] === 'error')
+        },
+    },
+    writeFileOnDirectory: () => {
+        /** @type {Dir} */
+        const inner = {}
+        /** @type {Dir} */
+        const root = { 'mydir': inner }
+        const [, result] = virtual({ ...emptyState, root })(writeFile('mydir', vec8(0x42n)))
+        assert(result[0] === 'error')
+    },
+    writeFileOverJsModule: () => {
+        // writeFile onto a path currently holding a JsModule (function) covers the
+        // `!Array.isArray(file)` branch of writeFileOp: the entry exists but is
+        // neither undefined nor an array.
+        /** @type {Dir} */
+        const root = { 'a.f.ts': /** @type {JsModule} */ (() => ({})) }
+        const [, result] = virtual({ ...emptyState, root })(writeFile('a.f.ts', vec8(0x42n)))
+        assert(result[0] === 'error')
+    },
+    readdirRecursive: () => {
+        const file = /** @type {const} */ ([vec8(0x42n)])
+        /** @type {Dir} */
+        const sub = { 'file.txt': file }
+        /** @type {Dir} */
+        const outer = { 'sub': sub }
+        /** @type {Dir} */
+        const root = { 'mydir': outer }
+        const [, result] = virtual({ ...emptyState, root })(readdir('mydir', { recursive: true }))
+        assert(result[0] === 'ok')
+        assert(result[0] === 'ok', result)
+        assertEq(result[1].length, 2)
+    },
+    accessNestedPathThroughFile: () => {
+        // 'a/b/c' where 'a' is a file: the operation wrapper's "not a directory"
+        // fallback passes the full remaining path through unchanged, covering the
+        // path.length !== 1 branch of the access op (only path.length === 0 was
+        // otherwise exercised).
+        /** @type {Dir} */
+        const root = { 'a': [vec8(0x42n)] }
+        const [, result] = virtual({ ...emptyState, root })(access('a/b/c'))
+        assert(result[0] === 'error')
+    },
+    readFileIntoDir: () => {
+        // 'a/b' where both 'a' and 'b' are directories
+        // hits path.length === 0 in operation's f and path.length !== 1 in readFile op
+        /** @type {Dir} */
+        const inner = {}
+        /** @type {Dir} */
+        const outer = { 'b': inner }
+        /** @type {Dir} */
+        const root = { 'a': outer }
+        const [, result] = virtual({ ...emptyState, root })(readFile('a/b'))
+        assert(result[0] === 'error')
+    },
+    awaitNonPromise: () => {
+        // a non-promise value passes through the virtual `await` handler as-is
+        const [, result] = virtual(emptyState)(awaitIfPromise(42))
+        assertEq(result, 42)
+    },
+    fetchNotFound: () => {
+        // covers the `result === undefined` branch of the `fetch` handler
+        const [, result] = virtual(emptyState)(fetch('https://example.com/missing'))
+        assert(result[0] === 'error')
+    },
+    importNestedPath: () => {
+        // import_ on a path whose parent does not exist covers the
+        // path.length !== 1 branch of the import_ op
+        const [, result] = virtual(emptyState)(import_('a/b'))
+        assert(result[0] === 'error')
+    },
+    importNonModule: () => {
+        // import_ on a Vec (not a JsModule) covers typeof entry !== 'function' branch
+        /** @type {Dir} */
+        const root = { 'module.f.ts': [vec8(0x42n)] }
+        const [, result] = virtual({ ...emptyState, root })(import_('module.f.ts'))
+        assert(result[0] === 'error')
+    },
+    throw: {
+        readFileOnJsModule: () => {
+            // readFile on a JsModule path covers typeof file === 'function' branch
+            /** @type {Dir} */
+            const root = { 'a.f.ts': /** @type {JsModule} */ (() => ({})) }
+            virtual({ ...emptyState, root })(readFile('a.f.ts'))
+        },
+    },
+    renameSamePath: () => {
+        // rename('a', 'a') should succeed as a no-op, not reject
+        /** @type {Dir} */
+        const root = { 'a': [vec8(0x42n)] }
+        const [, result] = virtual({ ...emptyState, root })(rename('a', 'a'))
+        assert(result[0] === 'ok')
+    },
+    renameIntoOwnSubtree: () => {
+        // rename('a', 'a/b') should fail (dst inside src's subtree)
+        /** @type {Dir} */
+        const root = { 'a': { 'b': [vec8(0x42n)] } }
+        const [, result] = virtual({ ...emptyState, root })(rename('a', 'a/b'))
+        assert(result[0] === 'error')
+    },
+    renameOntoOwnAncestor: () => {
+        // rename('a/b', 'a') should fail (src inside dst's subtree)
+        /** @type {Dir} */
+        const root = { 'a': { 'b': [vec8(0x42n)] } }
+        const [, result] = virtual({ ...emptyState, root })(rename('a/b', 'a'))
+        assert(result[0] === 'error')
+    },
+    renameNonEmptyDirOverEmptyDir: () => {
+        // rename a directory onto an empty directory should succeed
+        /** @type {Dir} */
+        const root = { 'src': { 'file': [vec8(0x42n)] }, 'dst': {} }
+        const [, result] = virtual({ ...emptyState, root })(rename('src', 'dst'))
+        assert(result[0] === 'ok')
+    },
+    renameEmptyDirOverNonEmptyDir: () => {
+        // rename an empty directory onto a non-empty directory should fail
+        /** @type {Dir} */
+        const root = { 'src': {}, 'dst': { 'file': [vec8(0x42n)] } }
+        const [, result] = virtual({ ...emptyState, root })(rename('src', 'dst'))
+        assert(result[0] === 'error')
+    },
+    renameFileOntoDirectory: () => {
+        // rename a file to a path that is already an existing directory should fail
+        /** @type {Dir} */
+        const root = { 'myfile': [vec8(0x42n)], 'mydir': {} }
+        const [, result] = virtual({ ...emptyState, root })(rename('myfile', 'mydir'))
+        assert(result[0] === 'error')
+    },
+    readFileTooLarge: () => {
+        // a file stored as two max-size chunks exceeds the limit; readFile must return an error
+        const chunk0 = vec(maxLengthBytes * 8n)(0n)
+        const chunk1 = vec(1n)(1n)
+        /** @type {Dir} */
+        const root = { 'big': [chunk0, chunk1] }
+        const [, result] = virtual({ ...emptyState, root })(readFile('big'))
+        assert(result[0] === 'error')
+    },
+    readBytesNegativeSize: () => {
+        // readBytes with negative size should fail
+        /** @type {Dir} */
+        const root = { 'file': [vec8(0x42n)] }
+        const [, result] = virtual({ ...emptyState, root })(readBytes('file', 0, -1))
+        assert(result[0] === 'error')
+    },
+    readBytesZeroSize: () => {
+        // readBytes with zero size should succeed and return empty vec
+        /** @type {Dir} */
+        const root = { 'file': [vec8(0x42n)] }
+        const [, result] = virtual({ ...emptyState, root })(readBytes('file', 0, 0))
+        assert(result[0] === 'ok')
+    },
+    readBytesNegativeOffset: () => {
+        // readBytes with negative offset should fail
+        /** @type {Dir} */
+        const root = { 'file': [vec8(0x42n)] }
+        const [, result] = virtual({ ...emptyState, root })(readBytes('file', -1, 1))
+        assert(result[0] === 'error')
+    },
+    readBytesFractionalSize: () => {
+        // readBytes with fractional size should fail rather than throw RangeError
+        /** @type {Dir} */
+        const root = { 'file': [vec8(0x42n)] }
+        const [, result] = virtual({ ...emptyState, root })(readBytes('file', 0, 1.5))
+        assert(result[0] === 'error')
+    },
+    readBytesFractionalOffset: () => {
+        // readBytes with fractional offset should fail rather than throw RangeError
+        /** @type {Dir} */
+        const root = { 'file': [vec8(0x42n)] }
+        const [, result] = virtual({ ...emptyState, root })(readBytes('file', 0.5, 1))
+        assert(result[0] === 'error')
+    },
+    readBytesAcrossChunkBoundary: () => {
+        // Two 128 KiB chunks; read 2 bytes spanning the boundary (last byte of chunk 0, first of chunk 1).
+        const chunkSize = Number(maxLengthBytes)
+        const chunk0 = vec(maxLengthBytes * 8n)(0xAAn)
+        const chunk1 = vec(maxLengthBytes * 8n)(0xBBn)
+        /** @type {Dir} */
+        const root = { 'big': [chunk0, chunk1] }
+        const [, result] = virtual({ ...emptyState, root })(readBytes('big', chunkSize - 1, 2))
+        assert(result[0] === 'ok')
+    },
+    writeBytesWrongOffset: () => {
+        // writeBytes is append-only; an offset that doesn't match the current
+        // file size must fail rather than silently create a hole.
+        /** @type {Dir} */
+        const root = { 'file': [vec8(0x42n)] }
+        const [, result] = virtual({ ...emptyState, root })(writeBytes('file', 5, vec8(0x43n)))
+        assert(result[0] === 'error')
+    },
+    statOnJsModule: () => {
+        // stat on a JsModule entry (neither an array nor a descendable
+        // directory) covers the !Array.isArray(file) branch of statOp.
+        /** @type {Dir} */
+        const root = { 'a.f.ts': /** @type {JsModule} */ (() => ({})) }
+        const [, result] = virtual({ ...emptyState, root })(stat('a.f.ts'))
+        assert(result[0] === 'error')
+        assertEq(result[1], `'a.f.ts' is not a file`)
+    },
+    largeFileReadBytes: () => {
+        // A file stored as two 128 KiB chunks is larger than maxLengthBytes.
+        // readBytes within the second chunk (offset = 128 KiB, size = 1) should succeed.
+        const chunkSize = Number(maxLengthBytes)
+        const chunk0 = vec(maxLengthBytes * 8n)(0n)
+        const chunk1 = vec(maxLengthBytes * 8n)(0xFFn)
+        /** @type {Dir} */
+        const root = { 'large': [chunk0, chunk1] }
+        const [, result] = virtual({ ...emptyState, root })(readBytes('large', chunkSize, 1))
+        assert(result[0] === 'ok')
+    },
+}

package/fjs/effects/node/virtual/types.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Types for the virtual Node-effect operations used by filesystem and
+ * process tests.
+ *
+ * @module
+ */
+import type { Vec } from '../../../types/bit_vec/types.ts';
+import type { Module } from '../types.ts';
+/**
+ * In-memory JS module entry. When `import_` is called on the path, the
+ * function is invoked and its return value is the module value (with a
+ * `default` export and optional named exports). Using a function (not a
+ * plain value) lets the entry be distinguished from `Vec`/`Dir` at runtime
+ * via `typeof === 'function'`, and lets the fixture compute the module on
+ * each import for closures/state.
+ */
+export type JsModule = () => Module;
+/** @internal */
+export type _Entity = readonly Vec[] | Dir | JsModule;
+export type Dir = {
+    readonly [name in string]?: _Entity;
+};
+export type State = {
+    stdout: string;
+    stderr: string;
+    /** Remaining stdin bytes; each `read` pops the first, `null` at EOF. */
+    stdin: readonly number[];
+    root: Dir;
+    internet: {
+        readonly [url: string]: Vec;
+    };
+    epochNs: number;
+    memoryNext: number;
+    memoryValues: {
+        readonly [key: string]: unknown;
+    };
+    /** Monotonically increasing counter returned by `randomInt`; starts at 0. */
+    randomNext: number;
+};

package/fjs/effects/proof.f.d.mts

@@ -0,0 +1,65 @@
+/**
+ * @import { Effect, Operation, OperationMap } from './types.ts'
+ */
+import type { Effect, Operation } from './types.ts';
+/**
+ * Asserts that `e` yields `expected` without performing a command. Exported so
+ * `eff/proof.f.ts` shares this definition instead of repeating it.
+ *
+ * Not `assertEq(runPure(e), [expected])`: `assertEq` compares with `===`, so a
+ * freshly allocated `[expected]` is never equal to the returned option. Assert
+ * the option's shape first, then compare the value inside it.
+ * @template {Operation} O
+ * @template T
+ * @param {Effect<O, T>} e
+ * @param {T} expected
+ */
+export declare const assertPure: <O extends Operation, T>(e: Effect<O, T>, expected: T) => void;
+export type _AddOp = readonly ['add', (a: number, b: number) => number];
+export type _AnyOp = readonly [string, (a: number) => number];
+export declare const proof: {
+    foldStep: {
+        empty: () => void;
+        threadsState: () => void;
+        order: () => void;
+    };
+    forEachStep: {
+        empty: () => void;
+        runs: () => void;
+    };
+    okStep: {
+        ok: () => void;
+        error: () => void;
+    };
+    runPure: {
+        pure: () => void;
+        pureNull: () => void;
+        do_: () => void;
+    };
+    doNode: () => void;
+    match: {
+        done: () => void;
+        cont: () => void;
+        ownCommand: () => void;
+        throw: {
+            constructorCommand: () => void;
+            toStringCommand: () => void;
+        };
+    };
+    step: {
+        pure: () => void;
+        chain: () => void;
+        overDo: () => void;
+    };
+    mapStep: {
+        pure: () => void;
+        constant: () => void;
+        overDo: () => void;
+    };
+    historyStep: {
+        pure: () => void;
+        overDo: () => void;
+        chain: () => void;
+        fReceivesWholeHistory: () => void;
+    };
+};

package/fjs/effects/proof.f.mjs

@@ -0,0 +1,234 @@
+/**
+ * @import { Effect, Operation, OperationMap } from './types.ts'
+ */
+
+import { step, do_, foldStep, forEachStep, mapStep, match, okStep, history, pure, runPure, historyStep } from './module.f.mjs'
+import { error, ok } from '../types/result/module.f.mjs'
+import { assert, assertEq } from '../asserts/module.f.mjs'
+
+/**
+ * Asserts that `e` yields `expected` without performing a command. Exported so
+ * `eff/proof.f.ts` shares this definition instead of repeating it.
+ *
+ * Not `assertEq(runPure(e), [expected])`: `assertEq` compares with `===`, so a
+ * freshly allocated `[expected]` is never equal to the returned option. Assert
+ * the option's shape first, then compare the value inside it.
+ * @template {Operation} O
+ * @template T
+ * @param {Effect<O, T>} e
+ * @param {T} expected
+ */
+export const assertPure = (e, expected) => {
+    const o = runPure(e)
+    assert(o.length === 1, e)
+    assertEq(o[0], expected)
+}
+
+/** @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 }))
+
+/**
+ * An operation set whose command is any `string`, which is what a `Do` node
+ * decoded from external input effectively is: `command` is runtime data, so
+ * nothing stops it naming a member `map` inherits from `Object.prototype`
+ * rather than an own handler. `match` must refuse those, and this type is how a
+ * proof says so without an `as` cast.
+ * @typedef {readonly[string, (a: number) => number]} _AnyOp
+ */
+
+/** @type {(command: string) => (a: number) => Effect<_AnyOp, number>} */
+const doAny = do_
+
+const anyNext = match(/** @type {OperationMap<_AnyOp, number>} */ ({ add: a => a + 1 }))
+
+export const proof = {
+    foldStep: {
+        empty: () => {
+            const e = foldStep(pure(/** @type {readonly number[]} */ ([])), 10, x => s => pure(s + x))
+            assertPure(e, 10)
+        },
+        threadsState: () => {
+            const e = foldStep(pure([1, 2, 3, 4]), 0, x => s => pure(s + x))
+            assertPure(e, 10)
+        },
+        order: () => {
+            const e = foldStep(pure(['a', 'b', 'c']), '', x => s => pure(s + x))
+            assertPure(e, 'abc')
+        },
+    },
+    forEachStep: {
+        empty: () => {
+            const e = forEachStep(pure(/** @type {readonly number[]} */ ([])), () => pure(undefined))
+            assertPure(e, undefined)
+        },
+        runs: () => {
+            const e = forEachStep(pure([1, 2, 3]), () => pure(undefined))
+            assertPure(e, undefined)
+        },
+    },
+    okStep: {
+        ok: () => {
+            const e = step(pure(ok(5)), okStep((/** @type {number} */ v) => pure(ok(v * 2))))
+            const o = runPure(e)
+            assert(o.length === 1, e)
+            const [r] = o
+            assert(r[0] === 'ok', r)
+            assertEq(r[1], 10)
+        },
+        error: () => {
+            const e = step(
+                pure(error(/** @type {string} */ ('oops'))),
+                okStep(/** @type {(value: number) => Effect<never, import('../types/result/types.ts').Result<number, string>>} */
+                    (v => pure(ok(v * 2)))))
+            const o = runPure(e)
+            assert(o.length === 1, e)
+            const [r] = o
+            assert(r[0] === 'error', r)
+            assertEq(r[1], 'oops')
+        },
+    },
+    runPure: {
+        pure: () => {
+            const o = runPure(pure(5))
+            assert(o.length === 1, o)
+            assertEq(o[0], 5)
+        },
+        // A pure `null` is `[null]`, never `[]`. Collapsing the two is what a
+        // `T | null` result would do, and why the option is tagged.
+        pureNull: () => {
+            const o = runPure(pure(null))
+            assertEq(o.length, 1, o)
+            assertEq(o[0], null)
+        },
+        do_: () => {
+            assertEq(runPure(doAdd('add')(2, 3)).length, 0)
+        },
+    },
+    // The one place a `Do` node is opened on purpose: `do_` builds the command,
+    // the payload it was called with, and a continuation that resumes with the
+    // command's output. Everything else goes through `step`, `match`, or
+    // `runPure`.
+    doNode: () => {
+        const e = doAdd('add')(2, 3)
+        assert(typeof e !== 'function', e)
+        const { command, payload, continuation } = e
+        assertEq(command, 'add')
+        const [a, b] = payload
+        assertEq(a, 2, payload)
+        assertEq(b, 3, payload)
+        assertPure(continuation(5), 5)
+    },
+    match: {
+        done: () => {
+            const r = next(pure(7))
+            assert(r[0] === 'done', r)
+            assertEq(r[1], 7)
+        },
+        cont: () => {
+            const r = next(doAdd('add')(2, 3))
+            assert(r[0] === 'cont', r)
+            assertEq(r[1], 5)
+            const r2 = next(r[2](r[1]))
+            assert(r2[0] === 'done', r2)
+            assertEq(r2[1], 5)
+        },
+        ownCommand: () => {
+            // The same map the two cases below dispatch against: an own
+            // property still resolves, so what they prove is refusal of
+            // inherited names, not a map that dispatches nothing.
+            const r = anyNext(doAny('add')(41))
+            assert(r[0] === 'cont', r)
+            assertEq(r[1], 42)
+        },
+        // A `command` naming an `Object.prototype` member must not dispatch to
+        // the inherited value. `map['constructor']` is `Object` and
+        // `map['toString']` is `Function.prototype.toString` — both callable,
+        // neither a handler — so a plain index read would call one of them with
+        // the node's payload instead of throwing.
+        throw: {
+            constructorCommand: () => {
+                anyNext(doAny('constructor')(1))
+            },
+            toStringCommand: () => {
+                anyNext(doAny('toString')(1))
+            },
+        },
+    },
+    step: {
+        pure: () => {
+            assertPure(step(pure(3), v => pure(v + 1)), 4)
+        },
+        chain: () => {
+            // Chains as step(step(e, f), g), raw effect in and out.
+            assertPure(step(step(pure(3), v => pure(v + 1)), v => pure(v * 2)), 8)
+        },
+        overDo: () => {
+            // Stepping a Do node preserves the command and threads the result
+            // through the rebuilt continuation.
+            const e = step(doAdd('add')(2, 3), r => pure(r * 10))
+            const r = next(e)
+            assert(r[0] === 'cont', r)
+            assertEq(r[1], 5)
+            assertPure(r[2](r[1]), 50)
+        },
+    },
+    mapStep: {
+        pure: () => {
+            assertPure(mapStep(pure(3), v => v + 1), 4)
+        },
+        constant: () => {
+            // The `() => v` shape a `constStep` would have covered.
+            assertPure(mapStep(pure('ignored'), () => 1), 1)
+        },
+        overDo: () => {
+            // A projection over a `Do` node keeps the command intact and is
+            // applied to the command's output when the continuation resumes.
+            const r = next(mapStep(doAdd('add')(2, 3), v => v * 10))
+            assert(r[0] === 'cont', r)
+            assertEq(r[1], 5)
+            assertPure(r[2](r[1]), 50)
+        },
+    },
+    historyStep: {
+        pure: () => {
+            const o = runPure(historyStep(history(pure(3)), v => pure(v * 2)))
+            assert(o.length === 1, o)
+            const [[result, param]] = o
+            assertEq(param, 3)
+            assertEq(result, 6)
+        },
+        overDo: () => {
+            // The captured value survives a command boundary: the history is
+            // rebuilt inside the continuation rather than lost when `e` is a Do.
+            const c = next(historyStep(history(doAdd('add')(2, 3)), r => pure(r * 10)))
+            assert(c[0] === 'cont', c)
+            assertEq(c[1], 5)
+            const o = runPure(c[2](c[1]))
+            assert(o.length === 1, o)
+            const [[result, param]] = o
+            assertEq(param, 5)
+            assertEq(result, 50)
+        },
+        chain: () => {
+            // `historyStep` takes a history and returns one, so link two is
+            // spelled exactly like link one. The tuple is newest first, so a
+            // destructuring reads reverse-chronologically.
+            const a = historyStep(history(pure(1)), x => pure(x + 1))
+            const b = historyStep(a, (result, param) => pure(result + param))
+            assertPure(
+                step(b, ([z, y, x]) => pure(`${x}${y}${z}`)),
+                '123')
+        },
+        fReceivesWholeHistory: () => {
+            // `f` is handed the whole history spread as arguments, not just the
+            // most recent value - which is what lets a later link reach back.
+            const a = historyStep(history(pure(1)), x => pure(x + 1))
+            const b = historyStep(a, (...p) => pure(p[1] * 100 + p[0]))
+            assertPure(step(b, ([result]) => pure(result)), 102)
+        },
+    },
+}