functionalscript 0.17.0 → 0.19.0

package/fs/types/effects/node/test.f.js

@@ -64,11 +64,11 @@ export default {
                 throw result;
             }
             const tmp = state.root.tmp;
-            if (tmp === undefined || isVec(tmp)) {
+            if (typeof tmp !== 'object') {
                 throw state.root;
             }
             const cache = tmp.cache;
-            if (cache === undefined || isVec(cache)) {
+            if (typeof cache !== 'object') {
                 throw tmp;
             }
         },
@@ -294,7 +294,7 @@ export default {
                 throw result;
             }
             const tmp = state.root.tmp;
-            if (tmp === undefined || isVec(tmp)) {
+            if (typeof tmp !== 'object') {
                 throw state.root;
             }
             if (tmp.cache !== undefined) {
@@ -333,8 +333,11 @@ export default {
         }
     },
     sandbox: {
+        // Virtual `sandbox` is now a pass-through: the function is expected
+        // to return a `SandboxResult` directly. Fixtures dictate the result
+        // (and `duration`) instead of the runner measuring.
         ok: () => {
-            const [_, { result, duration }] = virtual(emptyState)(sandbox(() => 42));
+            const [_, { result, duration }] = virtual(emptyState)(sandbox(() => ({ result: ['ok', 42], duration: 0 })));
             if (result[0] !== 'ok') {
                 throw result;
             }
@@ -347,7 +350,7 @@ export default {
         },
         error: () => {
             const err = new Error('fail');
-            const [_, { result }] = virtual(emptyState)(sandbox(() => { throw err; }));
+            const [_, { result }] = virtual(emptyState)(sandbox(() => ({ result: ['error', err], duration: 0 })));
             if (result[0] !== 'error') {
                 throw result;
             }

package/fs/types/effects/node/virtual/module.f.d.ts

@@ -1,8 +1,18 @@
 import { type Vec } from '../../../bit_vec/module.f.ts';
 import { type RunInstance } from '../../mock/module.f.ts';
-import type { NodeOp } from '../module.f.ts';
+import type { Module, NodeOp } from '../module.f.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;
+export type Entity = Vec | Dir | JsModule;
 export type Dir = {
-    readonly [name in string]?: Dir | Vec;
+    readonly [name in string]?: Entity;
 };
 export type State = {
     stdout: string;

package/fs/types/effects/node/virtual/module.f.js

@@ -3,8 +3,9 @@
  *
  * @module
  */
-import { todo } from "../../../../dev/module.f.js";
+import { assert, todo } from "../../../../dev/module.f.js";
 import { parse } from "../../../../path/module.f.js";
+import { utf8ToString } from "../../../../text/module.f.js";
 import { isVec } from "../../../bit_vec/module.f.js";
 import { error, ok } from "../../../result/module.f.js";
 import { run } from "../../mock/module.f.js";
@@ -22,7 +23,7 @@ const operation = (op) => {
         }
         const [first, ...rest] = path;
         const subDir = dir[first];
-        if (subDir === undefined || isVec(subDir)) {
+        if (typeof subDir !== 'object') {
             return op(dir, path);
         }
         const [newSubDir, r] = f(subDir, rest);
@@ -54,11 +55,24 @@ const readFile = readOperation((dir, path) => {
         return readFileError;
     }
     const file = dir[path[0]];
+    if (typeof file === 'function') {
+        throw new Error(`'${path[0]}' is a JsModule; readFile not supported`);
+    }
     if (!isVec(file)) {
         return error(`'${path[0]}' is not a file`);
     }
     return ok(file);
 });
+const import_ = readOperation((dir, path) => {
+    if (path.length !== 1) {
+        return error('no such file');
+    }
+    const entry = dir[path[0]];
+    if (typeof entry !== 'function') {
+        return error(`'${path[0]}' is not a JsModule`);
+    }
+    return ok(entry());
+});
 const writeFileError = error('invalid file');
 const writeFile = (payload) => operation((dir, path) => {
     if (path.length !== 1) {
@@ -85,7 +99,7 @@ const readdir = (base, recursive) => readOperation((dir, path) => {
             if (content === undefined) {
                 continue;
             }
-            const isFile = isVec(content);
+            const isFile = typeof content !== 'object';
             result = [...result, { name, parentPath, isFile }];
             if (!isFile && recursive) {
                 result = [...result, ...f(`${parentPath}/${name}`, content)];
@@ -113,13 +127,12 @@ const rm = operation((dir, path) => {
     if (entry === undefined) {
         return [dir, error('no such file')];
     }
-    if (!isVec(entry)) {
+    if (typeof entry === 'object') {
         return [dir, error('is a directory')];
     }
     const { [name]: _, ...rest } = dir;
     return [rest, okVoid];
 });
-const console = (name) => (state, payload) => [{ ...state, [name]: `${state[name]}${payload}\n` }, undefined];
 const map = {
     all: (state, ...a) => {
         let e = [];
@@ -130,8 +143,6 @@ const map = {
         }
         return [state, e];
     },
-    error: console('stderr'),
-    log: console('stdout'),
     fetch: (state, url) => {
         const result = state.internet[url];
         return result === undefined ? [state, error('not found')] : [state, ok(result)];
@@ -141,22 +152,25 @@ const map = {
     readdir: (state, path, { recursive }) => readdir(path, recursive === true)(state, path),
     writeFile: (state, path, payload) => writeFile(payload)(state, path),
     access,
-    import: todo,
+    import: import_,
     rm,
     exec: todo,
     createServer: todo,
     listen: todo,
     forever: todo,
     now: (state) => [state, state.epochNs],
-    sandbox: (state, f) => {
-        let result;
-        try {
-            result = ok(f());
-        }
-        catch (e) {
-            result = error(e);
-        }
-        return [state, { result, duration: 0 }];
+    // Virtual sandbox is a pass-through: the fixture's test function is
+    // expected to return a `SandboxResult` directly (encoding pass/fail and a
+    // chosen duration), so the handler invokes it without try/catch or clock
+    // reads. This makes test outcomes deterministic — fixtures dictate the
+    // result instead of the runner measuring real execution. A genuine
+    // exception in a fixture propagates loudly as a bug in the fixture.
+    // See: issues/156-tf-virtual-tests.md
+    sandbox: (state, f) => [state, f()],
+    test: todo,
+    write: (state, stream, data) => {
+        const s = utf8ToString(data);
+        return [{ ...state, [stream]: `${state[stream]}${s}` }, undefined];
     },
 };
 export const virtual = run(map);

package/fs/types/function/compare/module.f.d.ts

@@ -6,6 +6,7 @@
 import type { Index3, Index5, Array2 } from '../../array/module.f.ts';
 export type Sign = -1 | 0 | 1;
 export type Compare<T> = (_: T) => Sign;
+export type Cmp<T> = (a: T) => Compare<T>;
 export declare const index3: <T>(cmp: Compare<T>) => (value: T) => Index3;
 export declare const index5: <T>(cmp: Compare<T>) => (v2: Array2<T>) => Index5;
 export type Cmp1 = boolean | string | number | bigint;
@@ -23,3 +24,14 @@ export type Cmp2<A, B> = [
     B
 ] extends [bigint, bigint] ? bigint : never;
 export declare const cmp: <A extends Cmp1>(a: A) => <B extends Cmp2<A, B>>(b: B) => Sign;
+/**
+ * Binary search over `[0, len)`. `probe(mid)` returns the sign of the search
+ * key relative to the element at `mid` (`-1` before, `0` at, `1` after). On a
+ * hit it returns the matching index; on a miss it returns the converged lower
+ * bound `b` (the insertion point), which may equal `len`.
+ *
+ * `probe` must be monotonic over `[0, len)`: scanning indices left to right its
+ * result is non-increasing — a run of `1`s, then `0`s, then `-1`s. A
+ * non-monotonic probe yields an undefined position.
+ */
+export declare const bsearch: (len: number) => (probe: (mid: number) => Sign) => number;

package/fs/types/function/compare/module.f.js

@@ -4,3 +4,36 @@ export const index5 = cmp => ([v0, v1]) => {
     return (_0 <= 0 ? _0 + 1 : cmp(v1) + 3);
 };
 export const cmp = (a) => (b) => a < b ? -1 : a > b ? 1 : 0;
+/**
+ * Binary search over `[0, len)`. `probe(mid)` returns the sign of the search
+ * key relative to the element at `mid` (`-1` before, `0` at, `1` after). On a
+ * hit it returns the matching index; on a miss it returns the converged lower
+ * bound `b` (the insertion point), which may equal `len`.
+ *
+ * `probe` must be monotonic over `[0, len)`: scanning indices left to right its
+ * result is non-increasing — a run of `1`s, then `0`s, then `-1`s. A
+ * non-monotonic probe yields an undefined position.
+ */
+export const bsearch = (len) => (probe) => {
+    let b = 0;
+    let e = len - 1;
+    while (true) {
+        if (e < b) {
+            return b;
+        }
+        const mid = b + (e - b >> 1);
+        switch (probe(mid)) {
+            case -1: {
+                e = mid - 1;
+                break;
+            }
+            case 0: {
+                return mid;
+            }
+            case 1: {
+                b = mid + 1;
+                break;
+            }
+        }
+    }
+};

package/fs/types/function/operator/test.f.d.ts

@@ -0,0 +1,10 @@
+export declare const joinTest: () => void;
+export declare const concatTest: () => void;
+export declare const logicalNotTest: () => void;
+export declare const strictEqualTest: () => void;
+export declare const additionTest: () => void;
+export declare const minTest: () => void;
+export declare const maxTest: () => void;
+export declare const incrementTest: () => void;
+export declare const foldToScanTest: () => void;
+export declare const reduceToScanTest: () => void;

package/fs/types/function/operator/test.f.js

@@ -0,0 +1,81 @@
+import { join, concat, logicalNot, strictEqual, addition, min, max, increment, foldToScan, reduceToScan, } from "./module.f.js";
+export const joinTest = () => {
+    const result = join(', ')('world')('hello');
+    if (result !== 'hello, world') {
+        throw result;
+    }
+};
+export const concatTest = () => {
+    const result = concat('world')('hello');
+    if (result !== 'helloworld') {
+        throw result;
+    }
+};
+export const logicalNotTest = () => {
+    if (logicalNot(true) !== false) {
+        throw 'expected false';
+    }
+    if (logicalNot(false) !== true) {
+        throw 'expected true';
+    }
+};
+export const strictEqualTest = () => {
+    if (!strictEqual(1)(1)) {
+        throw 'expected true';
+    }
+    if (strictEqual(1)(2)) {
+        throw 'expected false';
+    }
+};
+export const additionTest = () => {
+    const result = addition(3)(4);
+    if (result !== 7) {
+        throw result;
+    }
+};
+export const minTest = () => {
+    if (min(3)(5) !== 3) {
+        throw 'min(3)(5)';
+    }
+    if (min(7)(2) !== 2) {
+        throw 'min(7)(2)';
+    }
+};
+export const maxTest = () => {
+    if (max(3)(5) !== 5) {
+        throw 'max(3)(5)';
+    }
+    if (max(7)(2) !== 7) {
+        throw 'max(7)(2)';
+    }
+};
+export const incrementTest = () => {
+    if (increment(4) !== 5) {
+        throw 'increment(4)';
+    }
+    if (increment(0) !== 1) {
+        throw 'increment(0)';
+    }
+};
+export const foldToScanTest = () => {
+    const scan = foldToScan(addition)(0);
+    const [v1, scan2] = scan(3);
+    if (v1 !== 3) {
+        throw v1;
+    }
+    const [v2] = scan2(4);
+    if (v2 !== 7) {
+        throw v2;
+    }
+};
+export const reduceToScanTest = () => {
+    const scan = reduceToScan(addition);
+    const [v0, scan2] = scan(10);
+    if (v0 !== 10) {
+        throw v0;
+    }
+    const [v1] = scan2(5);
+    if (v1 !== 15) {
+        throw v1;
+    }
+};

package/fs/types/nullable/test.f.js

@@ -1,4 +1,4 @@
-import { map, toOption } from "./module.f.js";
+import { map, match, toOption } from "./module.f.js";
 export default [
     () => {
         const optionSq = map((v) => v * v);
@@ -20,5 +20,14 @@ export default [
         if (opt2.length !== 0) {
             throw opt2;
         }
+    },
+    () => {
+        const double = match((v) => v * 2)(() => -1);
+        if (double(3) !== 6) {
+            throw double(3);
+        }
+        if (double(null) !== -1) {
+            throw double(null);
+        }
     }
 ];

package/fs/types/range_map/module.f.js

@@ -37,6 +37,7 @@
 import { genericMerge } from "../sorted_list/module.f.js";
 import { next } from "../list/module.f.js";
 import { cmp } from "../number/module.f.js";
+import { bsearch } from "../function/compare/module.f.js";
 const reduceOp = ({ union, equal }) => state => ([aItem, aMax]) => ([bItem, bMax]) => {
     const sign = cmp(aMax)(bMax);
     const min = sign === 1 ? bMax : aMax;
@@ -59,24 +60,8 @@ const tailReduce = equal => state => tail => {
 };
 export const merge = op => genericMerge({ reduceOp: reduceOp(op), tailReduce: tailReduce(op.equal) })(null);
 export const get = def => value => rm => {
-    const len = rm.length;
-    let b = 0;
-    let e = len - 1;
-    while (true) {
-        if (b >= len) {
-            return def;
-        }
-        if (e - b < 0) {
-            return rm[b][0];
-        }
-        const mid = b + (e - b >> 1);
-        if (value <= rm[mid][1]) {
-            e = mid - 1;
-        }
-        else {
-            b = mid + 1;
-        }
-    }
+    const pos = bsearch(rm.length)(mid => value <= rm[mid][1] ? -1 : 1);
+    return pos < rm.length ? rm[pos][0] : def;
 };
 export const fromRange = def => ([a, b]) => v => [[def, a - 1], [v, b]];
 /**

package/fs/types/result/module.f.d.ts

@@ -51,3 +51,7 @@ export declare const error: <E>(e: E) => Error<E>;
  * @returns The value if the result is successful. Otherwise, throws the error.
  */
 export declare const unwrap: <T, E>([kind, v]: Result<T, E>) => T;
+/**
+ * Swaps the `ok` and `error` cases of a result.
+ */
+export declare const invert: <T, E>([k, v]: Result<T, E>) => Result<E, T>;

package/fs/types/result/module.f.js

@@ -44,3 +44,7 @@ export const unwrap = ([kind, v]) => {
     }
     return v;
 };
+/**
+ * Swaps the `ok` and `error` cases of a result.
+ */
+export const invert = ([k, v]) => k === 'ok' ? error(v) : ok(v);

package/fs/types/result/test.f.d.ts

@@ -1,4 +1,2 @@
-declare const _default: {
-    example: () => void;
-};
-export default _default;
+export declare const example: () => void;
+export declare const invertTest: () => void;

package/fs/types/result/test.f.js

@@ -1,18 +1,26 @@
-import { error, ok, unwrap } from "./module.f.js";
-export default {
-    example: () => {
-        const success = ok(42);
-        const failure = error('Something went wrong');
-        if (unwrap(success) !== 42) {
-            throw 'error';
-        }
-        const [kind, v] = failure;
-        if (kind !== 'error') {
-            throw 'error';
-        }
-        // `v` is inferred as `string` here
-        if (v !== 'Something went wrong') {
-            throw 'error';
-        }
+import { error, ok, unwrap, invert } from "./module.f.js";
+export const example = () => {
+    const success = ok(42);
+    const failure = error('Something went wrong');
+    if (unwrap(success) !== 42) {
+        throw 'error';
+    }
+    const [kind, v] = failure;
+    if (kind !== 'error') {
+        throw 'error';
+    }
+    // `v` is inferred as `string` here
+    if (v !== 'Something went wrong') {
+        throw 'error';
+    }
+};
+export const invertTest = () => {
+    const [k0, v0] = invert(ok(42));
+    if (k0 !== 'error' || v0 !== 42) {
+        throw [k0, v0];
+    }
+    const [k1, v1] = invert(error('oops'));
+    if (k1 !== 'ok' || v1 !== 'oops') {
+        throw [k1, v1];
     }
 };

package/fs/types/rtti/common/module.f.d.ts

@@ -23,9 +23,10 @@
  * @module
  */
 import type { Primitive, Unknown } from '../../../djs/module.f.ts';
-import { type Info0, type Primitive0, type Struct, type Tuple, type Type } from '../module.f.ts';
+import { type Info0, type Primitive0, type Struct, type Tag1, type Tuple, type Type } from '../module.f.ts';
 import { type Error, type Result as CommonResult } from '../../result/module.f.ts';
 import type { Ts } from '../ts/module.f.ts';
+import { type ReadonlyRecord } from '../../object/module.f.ts';
 /** A path to a sub-value within the validated structure. Each step is an object key or stringified array index. */
 export type Path = readonly string[];
 /** Detailed validation failure: the offending `path` plus a short `message`. */
@@ -65,6 +66,14 @@ export type Visitor<R> = {
     readonly primitive0: (tag: Primitive0) => R;
     readonly unknown: () => R;
 };
+/** Type guard narrowing `Unknown` to a specific container type `C`. */
+export type IsContainer<C extends Unknown> = (value: Unknown) => value is C;
+/** Maps a `Tag1` to its runtime container type. */
+export type Container<K extends Tag1> = K extends 'array' ? ReadonlyArray<Unknown> : ReadonlyRecord<string, Unknown>;
+/** `IsContainer` guard for arrays, shared by `validate` and `parse`. */
+export declare const isArray: IsContainer<ReadonlyArray<Unknown>>;
+/** `IsContainer` guard for records/structs, shared by `validate` and `parse`. */
+export declare const isObject: IsContainer<ReadonlyRecord<string, Unknown>>;
 /**
  * Visits a schema `Type` by dispatching to the matching handler in `v`.
  *

package/fs/types/rtti/common/module.f.js

@@ -1,6 +1,7 @@
 import {} from "../module.f.js";
 import { error, ok } from "../../result/module.f.js";
-import { isArray } from "../../array/module.f.js";
+import { isArray as commonIsArray } from "../../array/module.f.js";
+import { isObject as commonIsObject } from "../../object/module.f.js";
 /** Builds an error result with empty path and the given message. */
 export const verror = (message) => error({ path: [], message });
 /** Prepends `key` to the error's path, used to build the path bottom-up. */
@@ -18,8 +19,12 @@ export const constPrimitiveValidate = (rtti) => value => Object.is(rtti, value)
     ? ok(value)
     : verror('unexpected value');
 const visitConst = (v) => (c) => typeof c === 'object' && c !== null
-    ? (isArray(c) ? v.tuple(c) : v.struct(c))
+    ? (commonIsArray(c) ? v.tuple(c) : v.struct(c))
     : v.constPrimitive(c);
+/** `IsContainer` guard for arrays, shared by `validate` and `parse`. */
+export const isArray = value => commonIsArray(value);
+/** `IsContainer` guard for records/structs, shared by `validate` and `parse`. */
+export const isObject = value => commonIsObject(value);
 /**
  * Visits a schema `Type` by dispatching to the matching handler in `v`.
  *

package/fs/types/rtti/parse/module.f.js

@@ -1,71 +1,60 @@
 import {} from "../module.f.js";
 import { ok } from "../../result/module.f.js";
-import { isArray as commonIsArray } from "../../array/module.f.js";
-import { isObject as commonIsObject } from "../../object/module.f.js";
+import {} from "../../object/module.f.js";
 import { find, map as listMap } from "../../list/module.f.js";
-import { constPrimitiveValidate, prependPath, primitive0Validate, verror, visit, } from "../common/module.f.js";
+import { constPrimitiveValidate, isArray, isObject, prependPath, primitive0Validate, verror, visit, } from "../common/module.f.js";
 export {} from "../common/module.f.js";
-const indexedFirstError = (results) => {
-    // TODO: findIndex breaks type inference,
-    //       we should replace it with something else.
-    const i = results.findIndex(r => r[0] === 'error');
-    return i < 0 ? null : [i, results[i]];
-};
+const { entries } = Object;
 const keyedFirstError = (results) => {
     const e = results.find(([, r]) => r[0] === 'error');
     return e === undefined ? null : [e[0], e[1]];
 };
-const arrayParse = (item) => value => {
-    if (!commonIsArray(value)) {
-        return verror('unexpected value');
-    }
-    if (value.length === 0) {
-        return ok([]);
-    }
-    // Note: we shouldn't instantiate `itemParse` until we know the array is non-empty.
-    //       Otherwise, we can get infinite recursion on empty arrays for recursive schemas.
-    const itemParse = parse(item);
-    const results = value.map(itemParse);
-    const err = indexedFirstError(results);
-    return (err === null
-        ? ok(results.map(r => r[1]))
-        : prependPath(String(err[0]), err[1]));
-};
-const recordParse = (item) => value => {
-    if (!commonIsObject(value)) {
+const arrayRebuild = entries => entries.map(([, v]) => v);
+const recordRebuild = entries => Object.fromEntries(entries);
+/** Drops the `'ok'` tag from each result, yielding the rebuild's `[key, value]` entries. */
+const okEntries = (results) => results.map(([k, r]) => [k, r[1]]);
+/**
+ * Builds a parser for `array` or `record` schemas. Mirrors `validate`'s
+ * `containerValidate`, but rebuilds a fresh container from each item's parsed
+ * result instead of returning the value unchanged. The inner item parser is
+ * instantiated lazily (only when the container is non-empty) so recursive
+ * schemas don't recurse forever on empty containers.
+ */
+const containerParse = (isContainer, rebuild) => (item) => value => {
+    if (!isContainer(value)) {
         return verror('unexpected value');
     }
-    const entries = Object.entries(value);
-    if (entries.length === 0) {
-        return ok({});
+    const e = entries(value);
+    if (e.length === 0) {
+        return ok(rebuild([]));
     }
     const itemParse = parse(item);
-    const results = entries.map(([k, v]) => [k, itemParse(v)]);
+    const results = e.map(([k, v]) => [k, itemParse(v)]);
     const err = keyedFirstError(results);
     return (err === null
-        ? ok(Object.fromEntries(results.map(([k, r]) => [k, r[1]])))
+        ? ok(rebuild(okEntries(results)))
         : prependPath(err[0], err[1]));
 };
-const tupleParse = (rtti) => value => {
-    if (!commonIsArray(value)) {
-        return verror('unexpected value');
-    }
-    const results = rtti.map((t, i) => parse(t)(value[i]));
-    const err = indexedFirstError(results);
-    return (err === null
-        ? ok(results.map(r => r[1]))
-        : prependPath(String(err[0]), err[1]));
-};
-const structParse = (rtti) => value => {
-    if (!commonIsObject(value)) {
+const arrayParse = containerParse(isArray, arrayRebuild);
+const recordParse = containerParse(isObject, recordRebuild);
+/**
+ * Builds a parser for `Tuple` or `Struct` const schemas. Mirrors `validate`'s
+ * `constContainerValidate`: it iterates the schema's entries (so extra tuple
+ * elements and undeclared struct keys are dropped) and rebuilds the result
+ * from each parsed item.
+ */
+const constContainerParse = (isContainer, getItem, rebuild) => (rtti) => value => {
+    if (!isContainer(value)) {
         return verror('unexpected value');
     }
-    const results = Object.entries(rtti).map(([k, t]) => [k, parse(t)(value[k])]);
+    const results = entries(rtti).map(([k, t]) => [k, parse(t)(getItem(value, k))]);
     const err = keyedFirstError(results);
     return (err === null
-        ? ok(Object.fromEntries(results.map(([k, r]) => [k, r[1]])))
+        ? ok(rebuild(okEntries(results)))
         : prependPath(err[0], err[1]));
 };
+const tupleParse = constContainerParse(isArray, (value, k) => value[Number(k)], arrayRebuild);
+const structParse = constContainerParse(isObject, (value, k) => value[k], recordRebuild);
 const findFirst = find(verror('no match'))((k) => k[0] === 'ok');
 const orParse = (rtti) => value => findFirst(listMap(t => parse(t)(value))(rtti));
 /**