functionalscript 0.29.1 → 0.31.0

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

@@ -26,7 +26,7 @@ import type { Primitive, Unknown } from '../../../djs/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';
+import { type StringMap } 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`. */
@@ -41,7 +41,7 @@ export type Validate<T extends Type> = (value: Unknown) => Result<T>;
 /** Builds an error result with empty path and the given message. */
 export declare const verror: (message: string) => Error<ValidationError>;
 /** Prepends `key` to the error's path, used to build the path bottom-up. */
-export declare const prependPath: (key: string, r: Error<ValidationError>) => Error<ValidationError>;
+export declare const prependPath: (key: string, [, r]: Error<ValidationError>) => Error<ValidationError>;
 /** Validates a `Tag0` primitive schema using `typeof`. */
 export declare const primitive0Validate: <K extends Primitive0, T extends Info0<K>>(tag: K) => Validate<T>;
 /**
@@ -69,11 +69,11 @@ export type Visitor<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>;
+export type Container<K extends Tag1> = K extends 'array' ? ReadonlyArray<Unknown> : StringMap<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>>;
+export declare const isObject: IsContainer<StringMap<string, Unknown>>;
 /**
  * Visits a schema `Type` by dispatching to the matching handler in `v`.
  *

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

@@ -5,7 +5,7 @@ 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. */
-export const prependPath = (key, r) => error({ path: [key, ...r[1].path], message: r[1].message });
+export const prependPath = (key, [, r]) => error({ path: [key, ...r.path], message: r.message });
 /** Validates a `Tag0` primitive schema using `typeof`. */
 export const primitive0Validate = (tag) => value => typeof value === tag ? ok(value) : verror('unexpected value');
 /**

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

@@ -1,13 +1,12 @@
 import { type Includes } from '../array/module.f.ts';
+import type { StringMap } from '../object/module.f.ts';
 /** A constant schema: a primitive literal, a struct object, or a tuple. */
 export type Const = null | boolean | number | string | undefined | bigint | {
     readonly [K in string]: Type;
 } | readonly Type[];
 export type ConstObject = Struct | Tuple;
 /** A struct schema: plain object whose values are nested `Type`s. */
-export type Struct = {
-    readonly [K in string]: Type;
-};
+export type Struct = StringMap<string, Type>;
 /** A tuple schema: readonly array whose elements are nested `Type`s. */
 export type Tuple = readonly Type[];
 declare const primitive0List: readonly ["bigint", "boolean", "number", "string"];

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

@@ -28,7 +28,6 @@
  */
 import {} from "../module.f.js";
 import { ok } from "../../result/module.f.js";
-import {} from "../../object/module.f.js";
 import { find, map as listMap } from "../../list/module.f.js";
 import { constPrimitiveValidate, isArray, isObject, prependPath, primitive0Validate, verror, visit, } from "../common/module.f.js";
 export {} from "../common/module.f.js";

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

@@ -1,5 +1,6 @@
 import type { Tag0, Tag1, Struct, Tuple, Type } from '../module.f.ts';
-import type { ReadonlyRecord } from '../../object/module.f.ts';
+import type { phantomKey } from '../../phantom/module.f.ts';
+import type { StringMap } from '../../object/module.f.ts';
 /**
  * The set of primitive literal types representable as rtti `Const` values.
  * Defined here rather than imported from `djs` to keep rtti free of djs dependencies
@@ -19,20 +20,20 @@ export type Unknown = Primitive | Array | Object;
 export type Array = readonly Unknown[];
 /** A read-only record of {@link Unknown} values. */
 export type Object = {
-    readonly [k in string]: Unknown;
+    readonly [k in string]?: Unknown;
 };
 /** Maps a `Tag0` to its TypeScript type. */
 export type Info0Ts<T extends Tag0> = T extends 'boolean' ? boolean : T extends 'number' ? number : T extends 'string' ? string : T extends 'bigint' ? bigint : T extends 'unknown' ? Unknown : never;
 /** Maps a `Const` schema to its TypeScript type. */
-export type ConstTs<T> = T extends readonly Type[] ? TupleTs<T> : T extends {
-    readonly [k in string]: Type;
-} ? StructTs<T> : T;
+export type ConstTs<T> = T extends readonly Type[] ? TupleTs<T> : T extends StringMap<string, Type> ? StructTs<T> : T;
 /** Maps a `Tag1` and inner type to its TypeScript type. */
 export type Info1Ts<K extends Tag1, T extends Type> = K extends 'array' ? ArrayTs<T> : K extends 'record' ? RecordTs<T> : never;
 /** Maps an array schema `T` to `readonly Ts<T>[]`. */
 export type ArrayTs<T extends Type> = ReadonlyArray<Ts<T>>;
-/** Maps a record schema `T` to `{ readonly[K in string]: Ts<T> }`. */
-export type RecordTs<T extends Type> = ReadonlyRecord<string, Ts<T>>;
+/** Maps a record schema `T` to `{ readonly[K in string]?: Ts<T> }`. */
+export type RecordTs<T extends Type> = {
+    readonly [K in string]?: Ts<T>;
+};
 /** Maps a tuple schema to a readonly tuple of resolved types. */
 export type TupleTs<T extends Tuple> = {
     readonly [K in keyof T]: Ts<T[K]>;
@@ -45,33 +46,26 @@ type RequiredFields<T extends Struct> = {
 };
 /** Maps a struct schema to a readonly object of resolved types, with optional fields for schemas that include `undefined`. */
 export type StructTs<T extends Struct> = (keyof OptionalFields<T> extends never ? unknown : OptionalFields<T>) & (keyof RequiredFields<T> extends never ? unknown : RequiredFields<T>);
-/**
- * Private unique symbol used as the phantom key in WithOut.
- * A symbol key is excluded from string index signatures ({ readonly [K in string]: Type }),
- * so WithOut<Struct, Out> is valid for any Out regardless of whether Out extends Type.
- */
-declare const withOutKey: unique symbol;
-/**
- * Attaches a phantom output type `Out` to a schema `S`.
- *
- * `Ts<WithOut<S, Out>>` short-circuits to `Out` via the `withOutKey` branch without
- * recursing through the schema body — solving TS2589 for recursive struct schemas
- * where `StructTs` would otherwise expand infinitely.
- *
- * The `withOutKey` field is phantom: it is `undefined` at runtime and only exists in the
- * type system. Using a unique symbol as the key means it cannot conflict with struct
- * schemas' string index signature (`{ readonly [K in string]: Type }`), so `WithOut`
- * is valid for any schema `S`, not just thunks.
- */
-export type WithOut<S, Out> = S & {
-    readonly [withOutKey]?: Out;
-};
 /**
  * Converts a schema `Type` to its corresponding TypeScript type.
  *
  * - `Thunk` → evaluates the returned `Info` via `InfoTs`
  * - `Const` → resolves via `ConstTs` (primitives map to themselves; structs/tuples recurse)
  *
+ * **Recursive schemas and TS2589:** when a schema is self-referential, `StructTs` would
+ * expand infinitely and TypeScript raises TS2589. Break the cycle by annotating the
+ * schema value with `Phantom<typeof myThunk, MyType>` from `fs/types/phantom/module.f.ts`.
+ * `Ts<>` detects the phantom key and returns `MyType` directly without recursing:
+ *
+ * ```ts
+ * import { type Phantom } from '../types/phantom/module.f.ts'
+ *
+ * type MyType = { readonly self?: MyType }
+ * const myThunk = () => ['const', myConst] as const
+ * export const my: Phantom<typeof myThunk, MyType> = myThunk
+ * // Ts<typeof my>  →  MyType
+ * ```
+ *
  * @example
  * ```ts
  * type A = Ts<typeof string>          // string
@@ -81,9 +75,9 @@ export type WithOut<S, Out> = S & {
  * ```
  */
 export type Ts<T extends Type> = unknown extends T ? Unknown : T extends {
-    readonly [withOutKey]?: infer O;
+    readonly [phantomKey]?: infer O;
 } ? Exclude<O, undefined> : T extends () => infer I ? (I extends readonly ['const', infer C] ? ConstTs<C> : I extends readonly ['boolean'] ? boolean : I extends readonly ['number'] ? number : I extends readonly ['string'] ? string : I extends readonly ['bigint'] ? bigint : I extends readonly ['unknown'] ? Unknown : I extends readonly ['array', infer E extends Type] ? readonly Ts<E>[] : I extends readonly ['record', infer E extends Type] ? {
-    readonly [K in string]: Ts<E>;
+    readonly [k in string]?: Ts<E>;
 } : I extends readonly ['or', ...infer A extends readonly Type[]] ? Ts<A[number]> : never) : ConstTs<T>;
 /**
  * Creates a printer that converts an RTTI schema `Type` to its TypeScript type expression as a string.
@@ -102,7 +96,7 @@ export type Ts<T extends Type> = unknown extends T ? Unknown : T extends {
  * const toTs = printer()
  * toTs(boolean)                    // 'boolean'
  * toTs(array(number))              // 'readonly(number)[]'
- * toTs(record(string))             // '{readonly[k:string]:string}'
+ * toTs(record(string))             // '{readonly[k in string]?:string}'
  * toTs(or(string, number))         // 'string|number'
  * toTs(42)                         // '42'
  * toTs('hello')                    // '"hello"'
@@ -111,7 +105,7 @@ export type Ts<T extends Type> = unknown extends T ? Unknown : T extends {
  *
  * const toTsMut = printer(true)
  * toTsMut(array(number))           // '(number)[]'
- * toTsMut(record(string))          // '{[k:string]:string}'
+ * toTsMut(record(string))          // '{[k in string]?:string}'
  * ```
  */
 export declare const printer: (mut?: true) => (rtti: Type) => string;

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

@@ -25,7 +25,7 @@ import { primitive, union, printer as tsPrinter } from "../../ts/module.f.js";
  * const toTs = printer()
  * toTs(boolean)                    // 'boolean'
  * toTs(array(number))              // 'readonly(number)[]'
- * toTs(record(string))             // '{readonly[k:string]:string}'
+ * toTs(record(string))             // '{readonly[k in string]?:string}'
  * toTs(or(string, number))         // 'string|number'
  * toTs(42)                         // '42'
  * toTs('hello')                    // '"hello"'
@@ -34,7 +34,7 @@ import { primitive, union, printer as tsPrinter } from "../../ts/module.f.js";
  *
  * const toTsMut = printer(true)
  * toTsMut(array(number))           // '(number)[]'
- * toTsMut(record(string))          // '{[k:string]:string}'
+ * toTsMut(record(string))          // '{[k in string]?:string}'
  * ```
  */
 export const printer = (mut) => {

package/fs/types/rtti/ts/proof.f.js

@@ -29,8 +29,8 @@ export const proof = {
             union: () => eq(array(or(number, string)), 'readonly(number|string)[]'),
         },
         record: {
-            primitive: () => eq(record(string), '{readonly[k:string]:string}'),
-            nested: () => eq(record(record(number)), '{readonly[k:string]:{readonly[k:string]:number}}'),
+            primitive: () => eq(record(string), '{readonly[k in string]?:string}'),
+            nested: () => eq(record(record(number)), '{readonly[k in string]?:{readonly[k in string]?:number}}'),
         },
     },
     const: {
@@ -68,7 +68,7 @@ export const proof = {
     mut: {
         array: () => eqMut(array(number), '(number)[]'),
         nestedArray: () => eqMut(array(array(boolean)), '((boolean)[])[]'),
-        record: () => eqMut(record(string), '{[k:string]:string}'),
+        record: () => eqMut(record(string), '{[k in string]?:string}'),
         tuple: () => eqMut([12, true], '[12,true]'),
         struct: () => eqMut({ a: number, b: string }, '{"a":number,"b":string}'),
     },

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

@@ -1,6 +1,5 @@
 import {} from "../module.f.js";
 import { ok } from "../../result/module.f.js";
-import {} from "../../object/module.f.js";
 import { constPrimitiveValidate, isArray, isObject, prependPath, primitive0Validate, verror, visit, } from "../common/module.f.js";
 export { constPrimitiveValidate, prependPath, primitive0Validate, verror, } from "../common/module.f.js";
 const { entries } = Object;

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

@@ -14,7 +14,13 @@ type MergeReduce<T, S> = {
     readonly reduceOp: ReduceOp<T, S>;
     readonly tailReduce: TailReduce<T, S>;
 };
+/**
+ * Two-way sorted-list merge.
+ * `reduceOp` returns `[output, sign, nextState]` where sign `-1` advances `a`, `1` advances `b`, `0` advances both; `null` output skips emission.
+ * `tailReduce` drains the non-exhausted list with current state once the other ends.
+ */
 export declare const genericMerge: <T, S>({ reduceOp, tailReduce }: MergeReduce<T, S>) => (state: S) => (a: List<T>) => (b: List<T>) => List<T>;
 export declare const merge: <T>(cmp: Cmp<T>) => (a: SortedList<T>) => (b: SortedList<T>) => SortedList<T>;
+export declare const intersect: <T>(cmp: Cmp<T>) => (a: SortedList<T>) => (b: SortedList<T>) => SortedList<T>;
 export declare const find: <T>(cmp: Cmp<T>) => (value: T) => (array: SortedArray<T>) => T | null;
 export {};

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

@@ -6,6 +6,11 @@
 import { bsearch } from "../function/compare/module.f.js";
 import { next } from "../list/module.f.js";
 import { identity } from "../function/module.f.js";
+/**
+ * Two-way sorted-list merge.
+ * `reduceOp` returns `[output, sign, nextState]` where sign `-1` advances `a`, `1` advances `b`, `0` advances both; `null` output skips emission.
+ * `tailReduce` drains the non-exhausted list with current state once the other ends.
+ */
 export const genericMerge = ({ reduceOp, tailReduce }) => {
     const f = (state) => (a) => (b) => () => {
         const aResult = next(a);
@@ -33,6 +38,12 @@ const cmpReduce = (cmp) => () => a => b => {
     return [sign === 1 ? b : a, sign, null];
 };
 const mergeTail = () => identity;
+const tailReduce = () => () => null;
+const intersectReduce = (cmp) => () => a => b => {
+    const sign = cmp(a)(b);
+    return [sign === 0 ? a : null, sign, null];
+};
+export const intersect = (cmp) => genericMerge({ reduceOp: intersectReduce(cmp), tailReduce })(null);
 export const find = (cmp) => (value) => (array) => {
     const cmpValue = cmp(value);
     const pos = bsearch(array.length)(mid => cmpValue(array[mid]));

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

@@ -1,11 +1,5 @@
 import { toArray } from "../list/module.f.js";
-import { merge, genericMerge, find } from "../sorted_list/module.f.js";
+import { merge, intersect as listIntersect, find } from "../sorted_list/module.f.js";
 export const union = cmp => a => b => toArray(merge(cmp)(a)(b));
-export const intersect = cmp => a => b => toArray(intersectMerge(cmp)(a)(b));
-const tailReduce = () => () => null;
-const intersectMerge = cmp => genericMerge({ reduceOp: intersectReduce(cmp), tailReduce })(null);
-const intersectReduce = cmp => state => a => b => {
-    const sign = cmp(a)(b);
-    return [sign === 0 ? a : null, sign, state];
-};
+export const intersect = cmp => a => b => toArray(listIntersect(cmp)(a)(b));
 export const has = cmp => value => set => find(cmp)(value)(set) === value;

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

@@ -14,7 +14,7 @@ export type Printer = {
     readonly struct: (fields: readonly (readonly [string, string])[]) => string;
     /** Emits an array type: `readonly(T)[]` or `(T)[]` when mutable. */
     readonly array: (type: string) => string;
-    /** Emits an index-signature record type: `{readonly[k:string]:T}` or `{[k:string]:T}` when mutable. */
+    /** Emits an index-signature record type: `{readonly[k in string]?:T}` or `{[k in string]?:T}` when mutable. */
     readonly record: (type: string) => string;
 };
 /** Creates a `Printer`. Pass `true` to emit mutable (non-`readonly`) types. */

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

@@ -7,7 +7,9 @@ export const printer = (mut) => {
         tuple: (mut ? complex('[', ']') : complex('readonly[', ']')),
         struct: (fields) => structX(fields.map(([k, v]) => `${ro}${JSON.stringify(k)}:${v}`)),
         array: (type) => `${ro}(${type})[]`,
-        record: (type) => structX([`${ro}[k:string]:${type}`]),
+        // `[k:string]?:` is invalid TypeScript — optional keys on an infinite
+        // key set require mapped-type syntax.
+        record: (type) => structX([`${ro}[k in string]?:${type}`]),
     };
 };
 export const primitive = (c) => {

package/fs/types/ts/proof.f.js

@@ -81,7 +81,7 @@ export const printerReadonlyArray = () => {
 };
 export const printerReadonlyRecord = () => {
     const r = ro.record('number');
-    if (r !== '{readonly[k:string]:number}') {
+    if (r !== '{readonly[k in string]?:number}') {
         throw r;
     }
 };
@@ -105,8 +105,9 @@ export const printerMutableArray = () => {
 };
 export const printerMutableRecord = () => {
     const r = mut.record('number');
-    if (r !== '{[k:string]:number}') {
+    if (r !== '{[k in string]?:number}') {
         throw r;
     }
 };
 export const proof = { primitiveNull, primitiveBigint, primitiveString, primitiveNumberFinite, primitiveNumberInfinite, primitiveUndefined, primitiveBoolean, unionEmpty, unionSingle, unionMulti, printerReadonlyTuple, printerReadonlyStruct, printerReadonlyArray, printerReadonlyRecord, printerMutableTuple, printerMutableStruct, printerMutableArray, printerMutableRecord };
+// type T4 = {[k:string]?: bigint} //< compilation error.

package/fs/website/proof.f.d.ts

@@ -1,3 +1,4 @@
 export declare const proof: {
     main: () => void;
+    run: () => void;
 };

package/fs/website/proof.f.js

@@ -1,9 +1,16 @@
 import { main } from "./module.f.js";
+import { emptyState, virtual } from "../effects/node/virtual/module.f.js";
+import { assert } from "../asserts/module.f.js";
 export const proof = {
     main: () => {
         const program = main();
         if (program === undefined) {
             throw 'expected a program effect';
         }
-    }
+    },
+    run: () => {
+        const state = { ...emptyState, root: { '.github': { workflows: {} } } };
+        const [_, result] = virtual(state)(main());
+        assert(result === 0, result);
+    },
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "functionalscript",
-  "version": "0.29.1",
+  "version": "0.31.0",
   "type": "module",
   "files": [
     "**/*.js",
@@ -43,8 +43,8 @@
   },
   "homepage": "https://github.com/functionalscript/functionalscript#readme",
   "devDependencies": {
-    "@playwright/test": "1.60.0",
-    "@types/node": "25.9.2",
+    "@playwright/test": "1.61.0",
+    "@types/node": "25.9.3",
     "typescript": "6.0.3"
   }
 }