functionalscript 0.16.1 → 0.18.0

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

@@ -1,6 +1,6 @@
 import { empty, isVec, uint, vec8 } from "../../bit_vec/module.f.js";
 import { pure } from "../module.f.js";
-import { fetch, mkdir, now, readdir, readFile, rm, writeFile } from "./module.f.js";
+import { fetch, mkdir, now, readdir, readFile, rm, sandbox, writeFile } from "./module.f.js";
 import { emptyState, virtual } from "./virtual/module.f.js";
 export default {
     map: () => {
@@ -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) {
@@ -327,9 +327,36 @@ export default {
         },
     },
     now: () => {
-        const [_, result] = virtual({ ...emptyState, epochNs: 1000000n })(now());
-        if (result !== 1000000n) {
+        const [_, result] = virtual({ ...emptyState, epochNs: 1_000_000 })(now());
+        if (result !== 1_000_000) {
             throw result;
         }
     },
+    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(() => ({ result: ['ok', 42], duration: 0 })));
+            if (result[0] !== 'ok') {
+                throw result;
+            }
+            if (result[1] !== 42) {
+                throw result[1];
+            }
+            if (duration !== 0) {
+                throw duration;
+            }
+        },
+        error: () => {
+            const err = new Error('fail');
+            const [_, { result }] = virtual(emptyState)(sandbox(() => ({ result: ['error', err], duration: 0 })));
+            if (result[0] !== 'error') {
+                throw result;
+            }
+            if (result[1] !== err) {
+                throw result[1];
+            }
+        },
+    },
 };

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

@@ -1,8 +1,17 @@
 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 Dir = {
-    readonly [name in string]?: Dir | Vec;
+    readonly [name in string]?: Dir | Vec | JsModule;
 };
 export type State = {
     stdout: string;
@@ -11,7 +20,7 @@ export type State = {
     internet: {
         readonly [url: string]: Vec;
     };
-    epochNs: bigint;
+    epochNs: number;
 };
 export declare const emptyState: State;
 export declare const virtual: RunInstance<NodeOp, State>;

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";
@@ -13,7 +14,7 @@ export const emptyState = {
     stderr: '',
     root: {},
     internet: {},
-    epochNs: 0n,
+    epochNs: 0,
 };
 const operation = (op) => {
     const f = (dir, path) => {
@@ -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,12 +152,24 @@ 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],
+    // 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()],
+    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/monoid/module.f.d.ts

@@ -1,3 +1,10 @@
+/**
+ * Monoids: the `Monoid<T>` algebraic structure (identity plus associative
+ * binary operation) and `repeat`, which applies the operation `n` times using
+ * exponentiation by squaring.
+ *
+ * @module
+ */
 import type { Fold, Reduce } from '../function/operator/module.f.ts';
 /**
  * Represents a monoid, an algebraic structure with a binary operation

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

@@ -1,3 +1,9 @@
+/**
+ * Numeric list reductions (`sum`, `min`, `max`), comparison via `cmp`, and
+ * `countOnes` for 32-bit population count using SWAR.
+ *
+ * @module
+ */
 import { type List } from '../list/module.f.ts';
 import { type Sign } from '../function/compare/module.f.ts';
 export declare const sum: (input: List<number>) => number;

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

@@ -1,3 +1,9 @@
+/**
+ * Numeric list reductions (`sum`, `min`, `max`), comparison via `cmp`, and
+ * `countOnes` for 32-bit population count using SWAR.
+ *
+ * @module
+ */
 import { reduce } from "../list/module.f.js";
 import { addition, min as minOp, max as maxOp } from "../function/operator/module.f.js";
 import { cmp as uCmp } from "../function/compare/module.f.js";

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

@@ -1,3 +1,10 @@
+/**
+ * Plain-object helpers and types: `Map<T>`/`Entry<T>` shapes, safe property
+ * lookup via `at`, conversions between entries and `OrderedMap`, and the
+ * `OneKey`/`SingleProperty`/`NotUnion` utility types.
+ *
+ * @module
+ */
 import { isArray } from "../array/module.f.js";
 import { iterable } from "../list/module.f.js";
 import { entries as mapEntries, fromEntries as mapFromEntries } from "../ordered_map/module.f.js";

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

@@ -1,3 +1,11 @@
+/**
+ * Prime field arithmetic over `bigint`: `prime_field(p)` builds a `PrimeField`
+ * with negation, addition, subtraction, multiplication, division via modular
+ * inverse, and exponentiation; `sqrt` returns a square-root function when
+ * `p % 4 === 3`.
+ *
+ * @module
+ */
 import type { Unary, Reduce } from '../bigint/module.f.ts';
 /**
  * A type representing a prime field and its associated operations.

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`.
  *