functionalscript 0.24.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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "functionalscript",
-  "version": "0.24.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",