functionalscript 0.44.0 → 0.46.0

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

@@ -1,11 +1,24 @@
-/** @import { Dir, JsModule } from './types.ts' */
+/**
+ * @import { Dir } from './types.ts'
+ * @import { NodeOp } from '../types.ts'
+ * @import { Effect } from '../../types.ts'
+ * @import { IoChannel } from '../types.ts'
+ */
 export declare const proof: {
+    unimplemented: {
+        declaredButAbsent: () => void;
+        programChoosesAFallback: () => void;
+        throw: {
+            undeclaredCommand: () => void;
+        };
+    };
     rm: {
         success: () => void;
         notFound: () => void;
-        isDirectory: () => void;
+        onDirectory: () => void;
     };
     writeFileOnDirectory: () => void;
+    writeFileOverJsModule: () => void;
     readdirRecursive: () => void;
     accessNestedPathThroughFile: () => void;
     readFileIntoDir: () => void;
@@ -15,7 +28,23 @@ export declare const proof: {
     importNonModule: () => void;
     throw: {
         readFileOnJsModule: () => void;
+        readBytesOnJsModule: () => void;
     };
+    readFileSkipsEmptyChunk: () => void;
+    readdirSkipsUndefinedEntry: () => void;
+    renameEmptySrc: () => void;
+    renameSrcThroughFile: () => void;
+    renameSrcThreeLevelsMissing: () => void;
+    renameDstMissingIntermediate: () => void;
+    renameDstThroughFile: () => void;
+    renameDstNestedError: () => void;
+    createExclusiveNestedMissing: () => void;
+    writeBytesNestedMissing: () => void;
+    writeBytesMissingFile: () => void;
+    writeBytesOnJsModule: () => void;
+    writeBytesNegativeOffset: () => void;
+    statNestedMissing: () => void;
+    statMissingFile: () => void;
     renameSamePath: () => void;
     renameIntoOwnSubtree: () => void;
     renameOntoOwnAncestor: () => void;

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

@@ -1,10 +1,64 @@
+/**
+ * @import { Dir } from './types.ts'
+ * @import { NodeOp } from '../types.ts'
+ * @import { Effect } from '../../types.ts'
+ * @import { IoChannel } 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 { access, awaitIfPromise, exec, fetch, log, rm, writeFile, readFile, readdir, import_, rename, readBytes, writeBytes, stat, createExclusive } from '../module.f.mjs'
+import { empty, length, maxLengthBytes, vec, vec8 } from '../../../types/bit_vec/module.f.mjs'
 import { emptyState, virtual } from './module.f.mjs'
-/** @import { Dir, JsModule } from './types.ts' */
+import { do_ } from '../../module.f.mjs'
+import { catchStep } from '../../module.f.mjs'
+
+/**
+ * Asserts that a channel error is a host failure carrying `message` — the
+ * normalized shape every runner reports, virtual and Node alike.
+ * @type {(e: IoChannel, message: string) => void}
+ */
+const assertIoMessage = (e, message) => {
+    assert(e[0] === 'ioError', e)
+    assertEq(e[1].message, message)
+}
 
 export const proof = {
+    // The two ways a command can have no handler here, which are not the same
+    // failure and must not answer alike.
+    unimplemented: {
+        // `exec` is a `NodeOp` this runner deliberately lacks — an in-memory
+        // filesystem has no subprocesses. It used to be a `todo` handler that
+        // threw; the program now gets its control back and can decide.
+        declaredButAbsent: () => {
+            const [, result] = virtual(emptyState)(exec('ls'))
+            assert(result[0] === 'error', result)
+            assertEq(result[1][0], 'notImplemented', result[1])
+            assertEq(result[1][1], 'exec', result[1])
+        },
+        // What the whole stage is for: the program receives control back and
+        // chooses. `exec` is unavailable here, so this one falls back to
+        // writing a note instead of dying, and the run completes normally.
+        programChoosesAFallback: () => {
+            const e = catchStep(exec('ls'), () => log('exec unavailable'))
+            const [state, result] = virtual(emptyState)(e)
+            assert(result[0] === 'ok', result)
+            assertEq(state.stdout, 'exec unavailable\n')
+        },
+        // A `command` that is not a `NodeOp` at all is a malformed node: the
+        // type said it was one, so something built it from data that was never
+        // checked. That stays a panic — collapsing it into `notImplemented`
+        // would turn a probable bug into a routine outcome.
+        throw: {
+            undeclaredCommand: () => {
+                // `do_` cannot build this from a well-typed call — that is the
+                // point: only a node assembled outside the type system reaches
+                // an interpreter with a command like this.
+                const bogus = /** @type {Effect<NodeOp, never, never>} */ (
+                    /** @type {any} */ (do_)('nope')())
+                virtual(emptyState)(bogus)
+            },
+        },
+    },
     rm: {
         success: () => {
             /** @type {Dir} */
@@ -16,7 +70,10 @@ export const proof = {
             const [, result] = virtual(emptyState)(rm('notexist.txt'))
             assert(result[0] === 'error')
         },
-        isDirectory: () => {
+        onDirectory: () => {
+            // `operation`'s wrapper descends into 'mydir' (a plain object),
+            // so rmOp itself runs with an empty remaining path and rejects
+            // via its `path.length !== 1` guard, not a directory-specific one.
             /** @type {Dir} */
             const inner = {}
             /** @type {Dir} */
@@ -33,6 +90,15 @@ export const proof = {
         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': () => ({}) }
+        const [, result] = virtual({ ...emptyState, root })(writeFile('a.f.ts', vec8(0x42n)))
+        assert(result[0] === 'error')
+    },
     readdirRecursive: () => {
         const file = /** @type {const} */ ([vec8(0x42n)])
         /** @type {Dir} */
@@ -71,7 +137,8 @@ export const proof = {
     awaitNonPromise: () => {
         // a non-promise value passes through the virtual `await` handler as-is
         const [, result] = virtual(emptyState)(awaitIfPromise(42))
-        assertEq(result, 42)
+        assert(result[0] === 'ok', result)
+        assertEq(result[1], 42)
     },
     fetchNotFound: () => {
         // covers the `result === undefined` branch of the `fetch` handler
@@ -95,9 +162,135 @@ export const proof = {
         readFileOnJsModule: () => {
             // readFile on a JsModule path covers typeof file === 'function' branch
             /** @type {Dir} */
-            const root = { 'a.f.ts': /** @type {JsModule} */ (() => ({})) }
+            const root = { 'a.f.ts': () => ({}) }
             virtual({ ...emptyState, root })(readFile('a.f.ts'))
         },
+        readBytesOnJsModule: () => {
+            // readBytes on a JsModule path covers typeof file === 'function' branch
+            /** @type {Dir} */
+            const root = { 'a.f.ts': () => ({}) }
+            virtual({ ...emptyState, root })(readBytes('a.f.ts', 0, 1))
+        },
+    },
+    readFileSkipsEmptyChunk: () => {
+        // A file stored with a zero-length chunk ahead of real data: readFile's
+        // loop must skip it (`chunkLen === 0n`) rather than concatenating it.
+        /** @type {Dir} */
+        const root = { 'f': [empty, vec8(0x42n)] }
+        const [, result] = virtual({ ...emptyState, root })(readFile('f'))
+        assert(result[0] === 'ok', result)
+        assertEq(length(result[1]), 8n)
+    },
+    readdirSkipsUndefinedEntry: () => {
+        // `Dir`'s index signature is optional (`{[name]?: _Entity}`), so an
+        // entry can legitimately be present with value `undefined` (e.g. after
+        // a rename leaves a stale key in some future refactor). readdir's loop
+        // must skip such entries rather than reporting them.
+        /** @type {Dir} */
+        const root = { 'd': { 'a': undefined, 'b': [vec8(0x42n)] } }
+        const [, result] = virtual({ ...emptyState, root })(readdir('d', {}))
+        assert(result[0] === 'ok', result)
+        assertEq(result[1].length, 1)
+    },
+    renameEmptySrc: () => {
+        // rename('', dst): src parses to the root path itself.
+        const [, result] = virtual(emptyState)(rename('', 'dst'))
+        assert(result[0] === 'error')
+        assertIoMessage(result[1], 'cannot extract root')
+    },
+    renameSrcThroughFile: () => {
+        // rename('a/b', dst) where 'a' is a file, not a directory: the
+        // intermediate segment can't be descended into.
+        /** @type {Dir} */
+        const root = { 'a': [vec8(0x42n)] }
+        const [, result] = virtual({ ...emptyState, root })(rename('a/b', 'dst'))
+        assert(result[0] === 'error')
+    },
+    renameSrcThreeLevelsMissing: () => {
+        // rename('a/b/c', dst) where 'a/b' exists but 'c' doesn't: the error
+        // from the deepest extractEntity call propagates through two levels
+        // of recursion.
+        /** @type {Dir} */
+        const root = { 'a': { 'b': {} } }
+        const [, result] = virtual({ ...emptyState, root })(rename('a/b/c', 'dst'))
+        assert(result[0] === 'error')
+    },
+    renameDstMissingIntermediate: () => {
+        // rename(src, 'missingdir/x'): the destination's parent doesn't exist.
+        /** @type {Dir} */
+        const root = { 'src': [vec8(0x42n)] }
+        const [, result] = virtual({ ...emptyState, root })(rename('src', 'missingdir/x'))
+        assert(result[0] === 'error')
+    },
+    renameDstThroughFile: () => {
+        // rename(src, 'blocker/x') where 'blocker' is a file, not a directory.
+        /** @type {Dir} */
+        const root = { 'src': [vec8(0x42n)], 'blocker': [vec8(0x1n)] }
+        const [, result] = virtual({ ...emptyState, root })(rename('src', 'blocker/x'))
+        assert(result[0] === 'error')
+        assertIoMessage(result[1], 'not a directory')
+    },
+    renameDstNestedError: () => {
+        // rename(src, 'a/b/c') where 'a/b' is a file: insertEntityAt's error
+        // one level down propagates through the outer recursive call.
+        /** @type {Dir} */
+        const root = { 'src': [vec8(0x1n)], 'a': { 'b': [vec8(0x2n)] } }
+        const [, result] = virtual({ ...emptyState, root })(rename('src', 'a/b/c'))
+        assert(result[0] === 'error')
+        assertIoMessage(result[1], 'not a directory')
+    },
+    createExclusiveNestedMissing: () => {
+        // createExclusive('a/b') where 'a' doesn't exist: the operation
+        // wrapper falls through with the full remaining path. Start from a
+        // non-empty root and check it survives untouched, so a mutant that
+        // returns the right error tag alongside a wiped dir would be caught.
+        /** @type {Dir} */
+        const root = { keep: [vec8(0x1n)] }
+        const [state, result] = virtual({ ...emptyState, root })(createExclusive('a/b'))
+        assert(result[0] === 'error')
+        assertEq(Object.keys(state.root).length, 1)
+    },
+    writeBytesNestedMissing: () => {
+        // writeBytes('a/b', ...) where 'a' doesn't exist. Non-empty root, as above.
+        /** @type {Dir} */
+        const root = { keep: [vec8(0x1n)] }
+        const [state, result] = virtual({ ...emptyState, root })(writeBytes('a/b', 0, vec8(0x1n)))
+        assert(result[0] === 'error')
+        assertEq(Object.keys(state.root).length, 1)
+    },
+    writeBytesMissingFile: () => {
+        // writeBytes on a path that doesn't exist at all: writeBytes never
+        // creates. Non-empty root, as above.
+        /** @type {Dir} */
+        const root = { keep: [vec8(0x1n)] }
+        const [state, result] = virtual({ ...emptyState, root })(writeBytes('missing', 0, vec8(0x1n)))
+        assert(result[0] === 'error')
+        assertEq(Object.keys(state.root).length, 1)
+    },
+    writeBytesOnJsModule: () => {
+        // writeBytes on a JsModule entry covers the `!Array.isArray(file)`
+        // branch (unlike readFile/readBytes, writeBytes has no separate throw
+        // for JsModule, so this is the reachable way to hit "not a file").
+        /** @type {Dir} */
+        const root = { 'a.f.ts': () => ({}) }
+        const [, result] = virtual({ ...emptyState, root })(writeBytes('a.f.ts', 0, vec8(0x1n)))
+        assert(result[0] === 'error')
+    },
+    writeBytesNegativeOffset: () => {
+        /** @type {Dir} */
+        const root = { 'file': [vec8(0x1n)] }
+        const [, result] = virtual({ ...emptyState, root })(writeBytes('file', -1, vec8(0x2n)))
+        assert(result[0] === 'error')
+        assertIoMessage(result[1], 'Offset -1 is invalid')
+    },
+    statNestedMissing: () => {
+        // stat('a/b') where 'a' doesn't exist.
+        const [, result] = virtual(emptyState)(stat('a/b'))
+        assert(result[0] === 'error')
+    },
+    statMissingFile: () => {
+        const [, result] = virtual(emptyState)(stat('missing'))
+        assert(result[0] === 'error')
     },
     renameSamePath: () => {
         // rename('a', 'a') should succeed as a no-op, not reject
@@ -207,10 +400,10 @@ export const proof = {
         // 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 root = { 'a.f.ts': () => ({}) }
         const [, result] = virtual({ ...emptyState, root })(stat('a.f.ts'))
         assert(result[0] === 'error')
-        assertEq(result[1], `'a.f.ts' is not a file`)
+        assertIoMessage(result[1], `'a.f.ts' is not a file`)
     },
     largeFileReadBytes: () => {
         // A file stored as two 128 KiB chunks is larger than maxLengthBytes.

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

@@ -1,39 +1,22 @@
-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
+ * @import { Effect, Func, Operation } from './types.ts'
+ * @import { Result } from '../types/result/types.ts'
  */
-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];
+import type { Result } from '../types/result/types.ts';
+export type _AddOp = readonly ['add', (a: number, b: number) => Result<number, string>];
+export type _AnyOp = readonly [string, (a: number) => Result<number, string>];
+export type _DivOp = readonly ['div', (a: number, b: number) => Result<number, string>];
+export type _NegOp = readonly ['neg', (a: number) => Result<number, string>];
+export type _Op = _DivOp | _NegOp;
 export declare const proof: {
-    foldStep: {
-        empty: () => void;
-        threadsState: () => void;
-        order: () => void;
-    };
-    forEachStep: {
-        empty: () => void;
-        runs: () => void;
-    };
-    okStep: {
+    runPure: {
         ok: () => void;
         error: () => void;
-    };
-    runPure: {
-        pure: () => void;
         pureNull: () => void;
         do_: () => void;
     };
     doNode: () => void;
+    failedCommandResumes: () => void;
     match: {
         done: () => void;
         cont: () => void;
@@ -43,20 +26,72 @@ export declare const proof: {
             toStringCommand: () => void;
         };
     };
+    partialMatch: {
+        implemented: () => void;
+        declined: () => void;
+        throw: {
+            unknownCommand: () => void;
+        };
+    };
+    pureOk: () => void;
+    pureError: () => void;
     step: {
-        pure: () => void;
+        ok: () => void;
+        propagates: () => void;
+        errorTupleIsUnchanged: () => void;
         chain: () => void;
         overDo: () => void;
+        overFailedDo: () => void;
+        joinsOperations: () => void;
+        mixedErrorsOk: () => void;
+        mixedErrorsFirst: () => void;
+        mixedErrorsSecond: () => void;
     };
-    mapStep: {
-        pure: () => void;
-        constant: () => void;
+    catchStep: {
+        recovers: () => void;
+        preservesOk: () => void;
+        overFailedDo: () => void;
+        unionsSuccess: () => void;
+    };
+    resultStep: {
+        ok: () => void;
+        error: () => void;
         overDo: () => void;
     };
     historyStep: {
-        pure: () => void;
-        overDo: () => void;
         chain: () => void;
-        fReceivesWholeHistory: () => void;
+        carriesValues: () => void;
+        propagates: () => void;
+        propagatesFromHead: () => void;
+        overDo: () => void;
+    };
+    foldStep: {
+        empty: () => void;
+        threadsState: () => void;
+        shortCircuits: () => void;
+    };
+    forEachStep: {
+        empty: () => void;
+        runs: () => void;
+        stopsAtTheFirstError: () => void;
+    };
+    unwrapStep: {
+        ok: () => void;
+        throw: {
+            error: () => void;
+        };
+    };
+    mapStep: {
+        ok: () => void;
+        error: () => void;
+        overDo: () => void;
+    };
+    resultMapStep: {
+        ok: () => void;
+        error: () => void;
+        absorbs: () => void;
+        rejects: () => void;
+        overDo: () => void;
+        overFailedDo: () => void;
     };
 };