functionalscript 0.23.0 → 0.25.0

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

@@ -1,8 +1,28 @@
-import type { Unknown as DjsUnknown } from '../../../djs/module.f.ts';
 import type { Tag0, Tag1, Struct, Tuple, Type } from '../module.f.ts';
 import type { ReadonlyRecord } 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
+ * (djs depends on rtti, not the other way around — see [i665-rtti-defines-types]).
+ */
+export type Primitive = null | boolean | number | string | undefined | bigint;
+/**
+ * The TypeScript type that rtti's `unknown` schema validates — any value that
+ * an rtti schema can represent: a primitive, an array, or an object.
+ *
+ * Currently equivalent to `djs.Unknown`, but defined here to keep `rtti` free
+ * of `djs` dependencies. May be extended to include functions or other
+ * non-JSON-primitives in the future.
+ */
+export type Unknown = Primitive | Array | Object;
+/** A read-only array of {@link Unknown} values. */
+export type Array = readonly Unknown[];
+/** A read-only record of {@link Unknown} values. */
+export type Object = {
+    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' ? DjsUnknown : never;
+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;
@@ -25,6 +45,27 @@ 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.
  *
@@ -39,7 +80,9 @@ export type StructTs<T extends Struct> = (keyof OptionalFields<T> extends never
  * type D = Ts<{ x: typeof boolean }>  // { readonly x: boolean }
  * ```
  */
-export type Ts<T extends Type> = 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'] ? DjsUnknown : I extends readonly ['array', infer E extends Type] ? readonly Ts<E>[] : I extends readonly ['record', infer E extends Type] ? {
+export type Ts<T extends Type> = unknown extends T ? Unknown : T extends {
+    readonly [withOutKey]?: 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>;
 } : I extends readonly ['or', ...infer A extends readonly Type[]] ? Ts<A[number]> : never) : ConstTs<T>;
 /**

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

@@ -26,6 +26,8 @@ const containerValidate = (isContainer) => (item) => value => {
             return prependPath(k, r);
         }
     }
+    // `value` is Container<K>, but Ts<Info1<K,I>> = readonly Ts<I>[] | Record<string,Ts<I>>.
+    // TypeScript can't narrow the container's element types through the validation loop.
     return ok(value);
 };
 const arrayValidate = containerValidate(isArray);
@@ -46,6 +48,8 @@ const constContainerValidate = (isContainer, getItem) => (rtti) => value => {
             return prependPath(k, r);
         }
     }
+    // `value` is C (Unknown container), but Ts<T> for T extends Tuple|Struct is not
+    // structurally equivalent to C — TypeScript can't narrow element types through the loop.
     return ok(value);
 };
 const tupleValidate = constContainerValidate(isArray, (value, k) => value[Number(k)]);
@@ -54,6 +58,7 @@ const orValidate = (rtti) => {
     const all = rtti.map(r => validate(r));
     return value => {
         for (const i of all) {
+            // `i` is Validate<Type>; calling without cast forces Ts<Type> evaluation → TS2589.
             const r = i(value);
             if (r[0] === 'ok') {
                 return r;

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

@@ -1,4 +1,4 @@
-import { type WriteFile } from '../types/effects/node/module.f.ts';
-import { type Effect } from '../types/effects/module.f.ts';
+import { type WriteFile } from '../effects/node/module.f.ts';
+import { type Effect } from '../effects/module.f.ts';
 declare const _default: () => Effect<WriteFile, number>;
 export default _default;

package/fs/website/module.f.js

@@ -4,8 +4,8 @@
  * @module
  */
 import { htmlUtf8 } from "../html/module.f.js";
-import { writeFile } from "../types/effects/node/module.f.js";
-import { pure } from "../types/effects/module.f.js";
+import { writeFile } from "../effects/node/module.f.js";
+import { pure } from "../effects/module.f.js";
 const html = htmlUtf8()(['a',
     { href: 'https://github.com/functionalscript/functionalscript' },
     'GitHub Repository'

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "functionalscript",
-  "version": "0.23.0",
+  "version": "0.25.0",
   "type": "module",
   "files": [
     "**/*.js",
@@ -9,9 +9,9 @@
   "description": "FunctionalScript is a purely functional subset of JavaScript",
   "scripts": {
     "prepack": "tsc --NoEmit false",
-    "test": "tsc && node --test --experimental-test-coverage --test-coverage-include=**/module.f.ts",
+    "test": "tsc && node ./fs/fjs/module.ts t",
+    "cov": "node --test --experimental-test-coverage --test-coverage-include=**/module.f.ts",
     "index": "node ./fs/fjs/module.ts r ./fs/dev/index/module.f.ts",
-    "fst": "node ./fs/fjs/module.ts t",
     "start": "node ./fs/fjs/module.ts",
     "ci-update": "node ./fs/fjs/module.ts r ./fs/ci/module.f.ts",
     "update": "npm install && npm run index && npm run ci-update",

package/fs/emergent_testing/module.d.ts

@@ -1 +0,0 @@
-export {};

package/fs/emergent_testing/module.js

@@ -1,4 +0,0 @@
-import { runEffect } from "../io/module.js";
-import { register } from "./module.f.js";
-// we need `await` for Playwright.
-await runEffect(register);

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

@@ -1,134 +0,0 @@
-import { type Effect } from '../types/effects/module.f.ts';
-import { type Headers, type Module, type NodeOp, type Env, type SandboxResult, type NodeProgram, type WriteConsoles, type TestContext, type Engine } from '../types/effects/node/module.f.ts';
-import type { Vec } from '../types/bit_vec/module.f.ts';
-import { type Result } from '../types/result/module.f.ts';
-/**
- * Represents a directory entry (file or directory) in the filesystem
- * @see https://nodejs.org/api/fs.html#class-fsdirent
- */
-export type Dirent = {
-    readonly name: string;
-    readonly parentPath: string;
-    readonly isDirectory: () => boolean;
-    readonly isFile: () => boolean;
-};
-export type RmOptions = {
-    readonly force?: boolean;
-    readonly recursive?: boolean;
-};
-export type MakeDirectoryOptions = {
-    readonly recursive?: boolean;
-};
-export type ReadDir = ((path: string, options: {
-    withFileTypes: true;
-}) => Promise<Dirent[]>) & ((path: string, options: {
-    recursive?: true;
-}) => Promise<readonly string[]>);
-/**
- * File system operations interface
- * @see https://nodejs.org/api/fs.html
- */
-export type Fs = {
-    readonly writeSync: (fd: number, s: string) => void;
-    readonly writeFileSync: (file: string, data: Uint8Array) => void;
-    readonly readFileSync: (path: string) => Uint8Array | null;
-    readonly promises: {
-        readonly readFile: (path: string) => Promise<Uint8Array>;
-        readonly writeFile: (path: string, data: Uint8Array) => Promise<void>;
-        readonly readdir: ReadDir;
-        readonly rm: (path: string, options?: RmOptions) => Promise<void>;
-        readonly mkdir: (path: string, options?: MakeDirectoryOptions) => Promise<string | undefined>;
-        readonly copyFile: (src: string, dest: string) => Promise<void>;
-        readonly access: (path: string) => Promise<void>;
-    };
-};
-/**
- * Console operations interface
- * @see https://nodejs.org/api/console.html
- */
-export type Console = {
-    readonly log: (...d: unknown[]) => void;
-    readonly error: (...d: unknown[]) => void;
-};
-/**
- * High-resolution time measurement interface
- * @see https://nodejs.org/api/perf_hooks.html#performance-now
- */
-export type Performance = {
-    readonly now: () => number;
-};
-export type Writable = {
-    readonly fd: number;
-    readonly isTTY: boolean;
-};
-/**
- * Node.js Process interface
- * @see https://nodejs.org/api/process.html
- */
-export type Process = {
-    readonly argv: string[];
-    readonly env: Env;
-    readonly exit: (code: number) => never;
-    readonly cwd: () => string;
-    readonly stdout: Writable;
-    readonly stderr: Writable;
-};
-export type TryCatch = <T>(f: () => T) => Result<T, unknown>;
-export type Sandbox = <T>(f: () => T) => Promise<SandboxResult<T>>;
-export type Server = {
-    readonly listen: (port: number) => void;
-};
-export type Readable = AsyncIterable<Uint8Array>;
-export type IncomingMessage = Readable & {
-    readonly method: string;
-    readonly url: string;
-    readonly headers: Headers;
-};
-export type ServerResponse = {
-    readonly writeHead: (status: number, headers: Record<string, string>) => ServerResponse;
-    readonly end: (body: Uint8Array) => void;
-};
-export type RequestListener = (req: IncomingMessage, res: ServerResponse) => Promise<void>;
-export type Http = {
-    readonly createServer: (_: RequestListener) => Server;
-};
-export type ChildProcess = {
-    readonly exec: (command: string, callback: (error: unknown, stdout: string, stderr: string) => void) => {
-        readonly stdin: null | {
-            readonly end: (data?: string) => void;
-        };
-    };
-};
-/**
- * Core IO operations interface providing access to system resources
- */
-export type Io = {
-    readonly console: Console;
-    readonly fs: Fs;
-    readonly process: Process;
-    readonly asyncImport: (s: string) => Promise<Module>;
-    readonly performance: Performance;
-    readonly fetch: (url: string) => Promise<Response>;
-    readonly tryCatch: TryCatch;
-    readonly asyncTryCatch: <T>(f: () => Promise<T>) => Promise<Result<T, unknown>>;
-    readonly http: Http;
-    readonly childProcess: ChildProcess;
-    readonly now: () => number;
-    readonly sandbox: Sandbox;
-    readonly write: (stream: WriteConsoles, data: Vec) => Promise<void>;
-    readonly testContext: TestContext;
-    readonly bunTestContext: TestContext;
-    readonly playwrightTestContext: TestContext;
-    readonly engine: Engine;
-    readonly await: (p: unknown) => Promise<readonly [unknown]>;
-};
-export type App = (io: Io) => Promise<number>;
-export type Run = (f: App) => Promise<never>;
-/**
- * Runs a function and exits the process with the returned code
- * Handles errors by exiting with code 1
- */
-export declare const run: (io: Io) => Run;
-export type EffectToPromise = <T>(effect: Effect<NodeOp, T>) => Promise<T>;
-export declare const fromIo: ({ fs: { promises: { mkdir, readFile, readdir, writeFile, rm, access } }, fetch, http: { createServer }, childProcess, asyncImport, now: ioNow, sandbox, write, await: awaitPromise, }: Io) => EffectToPromise;
-export declare const runProgram: (io: Io) => (args: readonly string[]) => (program: NodeProgram) => Promise<number>;

package/fs/io/module.f.js

@@ -1,113 +0,0 @@
-/**
- * Legacy `Io` interface and adapter (`fromIo`) bridging the old IO API to the
- * effect runner.
- *
- * @deprecated Use `fs/types/effects/node` (see issue
- * [i139](../../issues/README.md)).
- *
- * @module
- */
-import { normalize } from "../path/module.f.js";
-import {} from "../types/effects/module.f.js";
-import { asyncRun } from "../types/effects/module.js";
-import {} from "../types/effects/node/module.f.js";
-import { asBase, asNominal } from "../types/nominal/module.f.js";
-import { error, ok } from "../types/result/module.f.js";
-import { fromVec, listToVec, toVec } from "../types/uint8array/module.f.js";
-/**
- * Runs a function and exits the process with the returned code
- * Handles errors by exiting with code 1
- */
-export const run = (io) => {
-    const exitCode = ([x, b]) => {
-        if (x === 'error') {
-            io.console.error(b);
-            return 1;
-        }
-        else {
-            return b;
-        }
-    };
-    return async (f) => io.process.exit(exitCode(await io.asyncTryCatch(() => f(io))));
-};
-const tc = async (f) => {
-    try {
-        return ok(await f());
-    }
-    catch (e) {
-        return error(e);
-    }
-};
-const collect = async (v) => {
-    let result = [];
-    for await (const a of v) {
-        result = [...result, a];
-    }
-    return result;
-};
-export const fromIo = ({ fs: { promises: { mkdir, readFile, readdir, writeFile, rm, access } }, fetch, http: { createServer }, childProcess, asyncImport, now: ioNow, sandbox, write, await: awaitPromise, }) => {
-    const result = asyncRun({
-        all: async (...effects) => await Promise.all(effects.map(result)),
-        fetch: async (url) => tc(async () => {
-            const response = await fetch(url);
-            if (!response.ok) {
-                throw new Error(`Fetch error: ${response.status} ${response.statusText}`);
-            }
-            return toVec(new Uint8Array(await response.arrayBuffer()));
-        }),
-        mkdir: (...p) => tc(async () => { await mkdir(...p); }),
-        readFile: path => tc(async () => toVec(await readFile(path))),
-        readdir: (path, r) => tc(async () => (await readdir(path, { ...r, withFileTypes: true }))
-            .map(v => ({
-            name: v.name,
-            parentPath: normalize(v.parentPath),
-            isFile: v.isFile()
-        }))),
-        writeFile: (path, data) => tc(() => writeFile(path, fromVec(data))),
-        rm: path => tc(() => rm(path)),
-        access: path => tc(() => access(path)),
-        import: path => tc(() => asyncImport(path)),
-        exec: (command, stdin) => new Promise(resolve => {
-            const child = childProcess.exec(command, (e, stdout, stderr) => resolve(e !== null ? ['error', e] : ok({ stdout, stderr })));
-            child.stdin?.end(stdin);
-        }),
-        createServer: async (requestListener) => {
-            const erl = requestListener;
-            const nodeRl = async (req, res) => {
-                const reqBody = await collect(req);
-                const { method, url, headers } = req;
-                const { status, headers: outHeaders, body: outBody } = await result(erl({
-                    method,
-                    url,
-                    headers,
-                    body: listToVec(reqBody)
-                }));
-                res
-                    .writeHead(status, outHeaders)
-                    .end(fromVec(outBody));
-            };
-            const server = asNominal(createServer(nodeRl));
-            return server;
-        },
-        listen: async (server, port) => {
-            const s = asBase(server);
-            s.listen(port);
-        },
-        forever: () => new Promise(() => { }),
-        now: async () => ioNow(),
-        sandbox,
-        await: awaitPromise,
-        write,
-        test: async (ctx, name, expectFailure, test) => ctx.test(name, { expectFailure }, async (t) => result(test(t))),
-    });
-    return result;
-};
-export const runProgram = (io) => {
-    const { process: { env, stdout, stderr }, testContext, bunTestContext, playwrightTestContext, engine } = io;
-    const std = { stdout, stderr };
-    const f = fromIo(io);
-    return args => {
-        const options = { args, env, std, testContext, bunTestContext, playwrightTestContext, engine };
-        return program => f(program(options));
-    };
-};