functionalscript 0.44.0 → 0.45.0

package/fjs/media/html/proof.f.mjs

@@ -1,5 +1,8 @@
+/**
+ * @import { Element } from './types.ts'
+ */
+
 import { htmlToString } from "./module.f.mjs"
-/** @import { Element } from './types.ts' */
 import { assertEq } from '../../asserts/module.f.mjs'
 
 export const proof = {

package/fjs/media/json/parser/module.f.d.mts

@@ -8,7 +8,7 @@
  * @import { List } from '../../../types/list/types.ts'
  * @import { Fold } from '../../../types/function/operator/types.ts'
  * @import { JsonToken } from '../tokenizer/types.ts'
- * @import { _JsonObject, _JsonArray, _StateParse, _JsonState, _JsonStack } from './types.ts'
+ * @import { _JsonObject, _JsonArray, _StateParse, _JsonState, _JsonStack, _ValueToken } from './types.ts'
  */
 import type { Unknown } from '../types.ts';
 import type { Result } from '../../../types/result/types.ts';

package/fjs/media/json/parser/module.f.mjs

@@ -8,7 +8,7 @@
  * @import { List } from '../../../types/list/types.ts'
  * @import { Fold } from '../../../types/function/operator/types.ts'
  * @import { JsonToken } from '../tokenizer/types.ts'
- * @import { _JsonObject, _JsonArray, _StateParse, _JsonState, _JsonStack } from './types.ts'
+ * @import { _JsonObject, _JsonArray, _StateParse, _JsonState, _JsonStack, _ValueToken } from './types.ts'
  */
 
 import { error, ok } from '../../../types/result/module.f.mjs'
@@ -63,9 +63,14 @@ const popStack = stack => {
         : { status: '', top: ne.first, stack: ne.tail }
 }
 
-/** @type {(state: _StateParse) => _JsonState} */
+/**
+ * `endArray` only ever runs while parsing the array `startArray` opened
+ * (status `'['`/`'[v'`), so `state.top` is always that array here.
+ *
+ * @type {(state: _StateParse) => _JsonState}
+ */
 const endArray = state => {
-    const array = state.top !== null ? toArray(state.top.values) : null
+    const array = toArray(/** @type {_JsonArray} */ (state.top).values)
     const newState = popStack(state.stack)
     return pushValue(newState)(array)
 }
@@ -76,14 +81,24 @@ const startObject = state => {
     return { status: '{', top: { kind: 'object', values: null, key: '' }, stack: newStack }
 }
 
-/** @type {(state: _StateParse) => _JsonState} */
+/**
+ * `endObject` only ever runs while parsing the object `startObject` opened
+ * (status `'{'`/`'{v'`), so `state.top` is always that object here.
+ *
+ * @type {(state: _StateParse) => _JsonState}
+ */
 const endObject = state => {
-    const obj = state.top?.kind === 'object' ? fromMap(state.top.values) : null
+    const obj = fromMap(/** @type {_JsonObject} */ (state.top).values)
     const newState = popStack(state.stack)
     return pushValue(newState)(obj)
 }
 
-/** @type {(token: JsonToken) => Unknown} */
+/**
+ * Only ever called on a token `isValueToken` has already confirmed carries a
+ * value, so the switch covers every `_ValueToken` case with no fallback arm.
+ *
+ * @type {(token: _ValueToken) => Unknown}
+ */
 const tokenToValue = token => {
     switch (token.kind) {
         case 'null': return null
@@ -91,11 +106,13 @@ const tokenToValue = token => {
         case 'true': return true
         case 'number': return parseFloat(token.value)
         case 'string': return token.value
-        default: return null
     }
 }
 
-/** @type {(token: JsonToken) => boolean} */
+/**
+ * @param {JsonToken} token
+ * @returns {token is _ValueToken}
+ */
 const isValueToken = token => {
     switch (token.kind) {
         case 'null':

package/fjs/media/json/parser/types.d.ts

@@ -6,6 +6,11 @@
 import type { Unknown } from '../types.ts';
 import type { OrderedMap } from '../../../types/ordered_map/types.ts';
 import type { List } from '../../../types/list/types.ts';
+import type { JsonToken } from '../tokenizer/types.ts';
+/** JSON tokens that carry a directly-usable value. */
+export type _ValueToken = Extract<JsonToken, {
+    readonly kind: 'null' | 'false' | 'true' | 'string' | 'number';
+}>;
 export type _JsonObject = {
     readonly kind: 'object';
     readonly values: OrderedMap<Unknown>;

package/fjs/media/json/rtti/proof.f.d.mts

@@ -2,6 +2,9 @@
  * Proof for the JSON rtti schemas.
  *
  * @module
+ *
+ * @import { ValidateE } from '../../../types/rtti/common/types.ts'
+ * @import { Unknown } from '../../../types/rtti/ts/types.ts'
  */
 export declare const proof: {
     primitive: {

package/fjs/media/json/rtti/proof.f.mjs

@@ -2,15 +2,15 @@
  * Proof for the JSON rtti schemas.
  *
  * @module
+ *
+ * @import { ValidateE } from '../../../types/rtti/common/types.ts'
+ * @import { Unknown } from '../../../types/rtti/ts/types.ts'
  */
 
 import { assertEq } from '../../../asserts/module.f.mjs'
 import { validate } from '../../../types/rtti/validate/module.f.mjs'
 import { primitive, unknown, object, array } from './module.f.mjs'
 
-/** @import { ValidateE } from '../../../types/rtti/common/types.ts' */
-/** @import { Unknown } from '../../../types/rtti/ts/types.ts' */
-
 // Reduces a validation to its `ok`/`error` tag: these schemas are about what is
 // accepted, not about the payload, which validation returns unchanged. The
 // erased `ValidateE` keeps the shared helper from re-instantiating each

package/fjs/media/json/schema/module.f.d.mts

@@ -1,31 +1,33 @@
 /**
  * Converts an rtti schema to a JSON Schema (draft 2020-12) object.
  *
- * Driven by `fjs/types/rtti/common/module.f.mjs`'s `visit`, the same shared
- * `Type`-ADT walker used by `validate` and `parse`.
+ * {@link toJsonSchema} routes through the serializable RTTI data form
+ * (`fjs/types/rtti/data`): `thunk RTTI → toData → dataToJsonSchema`. The data
+ * form is a finite graph, so recursive schemas — which the thunk graph
+ * represents as self-referencing functions with no leaves — terminate:
+ * every named rule is emitted exactly once under `$defs` and every graph
+ * edge becomes a local `$ref`.
+ *
+ * Graph discovery, canonical identity, and definition naming belong to the
+ * RTTI data layer; this module only translates the finite graph, so the
+ * output is deterministic for equal canonical data: `anyOf` members follow
+ * the data form's kind order (`null`, `undefined`, booleans, numbers,
+ * strings, bigints, arrays, objects), and `properties`/`required` follow
+ * its sorted key order.
  *
  * @module
  *
- * @import { Struct, Tuple, Type as RttiType } from '../../../types/rtti/types.ts'
- * @import { Visitor } from '../../../types/rtti/common/types.ts'
- * @import { Primitive } from '../../../djs/types.ts'
+ * @import { Type as RttiType } from '../../../types/rtti/types.ts'
+ * @import { ArraySet, Data, KindSet, Node, ObjectSet, RuleSet, UnionSet } from '../../../types/rtti/data/types.ts'
  * @import { Ts } from '../../../types/rtti/ts/types.ts'
  * @import { Phantom } from '../../../types/phantom/types.ts'
  */
 import type { Type as RttiType } from '../../../types/rtti/types.ts';
+import type { Data } from '../../../types/rtti/data/types.ts';
 import type { Ts } from '../../../types/rtti/ts/types.ts';
 import type { Phantom } from '../../../types/phantom/types.ts';
-declare const unknownThunk: () => readonly ['const', {
-    readonly type: import("../../../types/rtti/types.ts").Or<["boolean", "number", "string", "integer", "array", "object", undefined]>;
-    readonly const: import("../../../types/rtti/types.ts").Or<readonly [() => readonly ['or', typeof import("../rtti/module.f.mjs").primitive, typeof import("../rtti/module.f.mjs").object, typeof import("../rtti/module.f.mjs").array], undefined]>;
-    readonly not: import("../../../types/rtti/types.ts").Or<readonly [Phantom<() => readonly ['const', /*elided*/ any], _UnknownConst>, undefined]>;
-    readonly anyOf: import("../../../types/rtti/types.ts").Or<readonly [import("../../../types/rtti/types.ts").Type1<"array", Phantom<() => readonly ['const', any], _UnknownConst>>, undefined]>;
-    readonly items: import("../../../types/rtti/types.ts").Or<[Phantom<() => readonly ['const', any], _UnknownConst>, false, undefined]>;
-    readonly prefixItems: import("../../../types/rtti/types.ts").Or<readonly [import("../../../types/rtti/types.ts").Type1<"array", Phantom<() => readonly ['const', any], _UnknownConst>>, undefined]>;
-    readonly properties: import("../../../types/rtti/types.ts").Or<readonly [import("../../../types/rtti/types.ts").Type1<"record", Phantom<() => readonly ['const', any], _UnknownConst>>, undefined]>;
-    readonly required: import("../../../types/rtti/types.ts").Or<readonly [import("../../../types/rtti/types.ts").Type1<"array", import("../../../types/rtti/types.ts")._Type0<"string">>, undefined]>;
-    readonly additionalProperties: import("../../../types/rtti/types.ts").Or<readonly [Phantom<() => readonly ['const', any], _UnknownConst>, undefined]>;
-}];
+/** @type {() => readonly ['const', typeof unknownConst]} */
+declare const unknownThunk: () => readonly ['const', typeof unknownConst];
 /**
  * rtti schema for a JSON Schema (draft 2020-12) document.
  * @type {Phantom<typeof unknownThunk, _UnknownConst>}
@@ -35,43 +37,75 @@ export type Unknown = Ts<typeof unknown>;
 /** A JSON Schema (draft 2020-12) document — the subset of keywords that `toJsonSchema` emits. */
 /** @typedef {Ts<typeof unknown>} Unknown */
 declare const unknownConst: {
+    readonly $schema: import("../../../types/rtti/types.ts").Or<readonly [import("../../../types/rtti/types.ts")._Type0<"string">, undefined]>;
+    readonly $ref: import("../../../types/rtti/types.ts").Or<readonly [import("../../../types/rtti/types.ts")._Type0<"string">, undefined]>;
+    readonly $defs: import("../../../types/rtti/types.ts").Or<readonly [import("../../../types/rtti/types.ts").Type1<"record", Phantom<() => readonly ['const', typeof unknownConst], _UnknownConst>>, undefined]>;
     readonly type: import("../../../types/rtti/types.ts").Or<["boolean", "number", "string", "integer", "array", "object", undefined]>;
     readonly const: import("../../../types/rtti/types.ts").Or<readonly [() => readonly ['or', typeof import("../rtti/module.f.mjs").primitive, typeof import("../rtti/module.f.mjs").object, typeof import("../rtti/module.f.mjs").array], undefined]>;
-    readonly not: import("../../../types/rtti/types.ts").Or<readonly [Phantom<typeof unknownThunk, _UnknownConst>, undefined]>;
-    readonly anyOf: import("../../../types/rtti/types.ts").Or<readonly [import("../../../types/rtti/types.ts").Type1<"array", Phantom<typeof unknownThunk, _UnknownConst>>, undefined]>;
-    readonly items: import("../../../types/rtti/types.ts").Or<[Phantom<typeof unknownThunk, _UnknownConst>, false, undefined]>;
-    readonly prefixItems: import("../../../types/rtti/types.ts").Or<readonly [import("../../../types/rtti/types.ts").Type1<"array", Phantom<typeof unknownThunk, _UnknownConst>>, undefined]>;
-    readonly properties: import("../../../types/rtti/types.ts").Or<readonly [import("../../../types/rtti/types.ts").Type1<"record", Phantom<typeof unknownThunk, _UnknownConst>>, undefined]>;
+    readonly not: import("../../../types/rtti/types.ts").Or<readonly [Phantom<() => readonly ['const', typeof unknownConst], _UnknownConst>, undefined]>;
+    readonly anyOf: import("../../../types/rtti/types.ts").Or<readonly [import("../../../types/rtti/types.ts").Type1<"array", Phantom<() => readonly ['const', typeof unknownConst], _UnknownConst>>, undefined]>;
+    readonly items: import("../../../types/rtti/types.ts").Or<[Phantom<() => readonly ['const', typeof unknownConst], _UnknownConst>, false, undefined]>;
+    readonly prefixItems: import("../../../types/rtti/types.ts").Or<readonly [import("../../../types/rtti/types.ts").Type1<"array", Phantom<() => readonly ['const', typeof unknownConst], _UnknownConst>>, undefined]>;
+    readonly minItems: import("../../../types/rtti/types.ts").Or<readonly [import("../../../types/rtti/types.ts")._Type0<"number">, undefined]>;
+    readonly properties: import("../../../types/rtti/types.ts").Or<readonly [import("../../../types/rtti/types.ts").Type1<"record", Phantom<() => readonly ['const', typeof unknownConst], _UnknownConst>>, undefined]>;
     readonly required: import("../../../types/rtti/types.ts").Or<readonly [import("../../../types/rtti/types.ts").Type1<"array", import("../../../types/rtti/types.ts")._Type0<"string">>, undefined]>;
-    readonly additionalProperties: import("../../../types/rtti/types.ts").Or<readonly [Phantom<typeof unknownThunk, _UnknownConst>, undefined]>;
+    readonly additionalProperties: import("../../../types/rtti/types.ts").Or<readonly [Phantom<() => readonly ['const', typeof unknownConst], _UnknownConst>, undefined]>;
 };
 export type _UnknownConst = {
+    readonly $schema?: Ts<typeof unknownConst.$schema>;
+    readonly $ref?: Ts<typeof unknownConst.$ref>;
+    readonly $defs?: Ts<typeof unknownConst.$defs>;
     readonly type?: Ts<typeof unknownConst.type>;
     readonly const?: Ts<typeof unknownConst.const>;
     readonly not?: Ts<typeof unknownConst.not>;
     readonly anyOf?: Ts<typeof unknownConst.anyOf>;
     readonly items?: Ts<typeof unknownConst.items>;
     readonly prefixItems?: Ts<typeof unknownConst.prefixItems>;
+    readonly minItems?: Ts<typeof unknownConst.minItems>;
     readonly properties?: Ts<typeof unknownConst.properties>;
     readonly required?: Ts<typeof unknownConst.required>;
     readonly additionalProperties?: Ts<typeof unknownConst.additionalProperties>;
 };
 /**
- * Converts an rtti `Type` to a JSON Schema (draft 2020-12) object.
+ * Converts a serializable RTTI {@link Data} (from `toData`) to a JSON Schema
+ * (draft 2020-12) object.
+ *
+ * Every named rule is emitted exactly once under `$defs` and each reference
+ * becomes a local `$ref` — self- and mutual recursion terminate, and the
+ * root itself is a `$ref` when the entry is a named definition. Definition
+ * names come from the data form (deterministic for equal canonical data)
+ * and are JSON Pointer-escaped, then percent-encoded, for the `$ref`
+ * fragment. A reference naming a missing definition panics.
+ *
+ * @type {(data: Data) => Unknown}
+ */
+export declare const dataToJsonSchema: (data: Data) => Unknown;
+/**
+ * Converts an rtti `Type` to a JSON Schema (draft 2020-12) object, through
+ * the canonical data form: `toData` first, then {@link dataToJsonSchema}.
  *
  * | rtti                                          | JSON Schema                                                                         |
  * |-----------------------------------------------|-------------------------------------------------------------------------------------|
  * | `boolean` / `number` / `string`               | `{ "type": "..." }`                                                                 |
  * | `bigint`                                      | `{ "type": "integer" }` (lossy; JSON integers are IEEE-754 doubles)                 |
  * | `unknown`                                     | `{}` (always-true schema)                                                           |
- * | primitive const (`42`, `'x'`, `true`, `null`) | `{ "const": <value> }`                                                              |
+ * | `never` / `or()`                              | `{ "not": {} }` (no JSON value satisfies this)                                      |
+ * | primitive const (`42`, `'x'`, `null`)         | `{ "const": <value> }`                                                              |
+ * | `or(true, false)`                             | `{ "type": "boolean" }` (the union normalizes to the whole kind)                    |
  * | `bigint` const                                | `{ "const": Number(value) }` (lossy for \|value\| > MAX_SAFE_INTEGER)               |
- * | `undefined` const                             | `{ "not": {} }` (no JSON value satisfies this)                                      |
+ * | `undefined` const                             | `{ "not": {} }`                                                                     |
  * | struct `{ a: T, … }`                          | `{ "type": "object", "properties": { "a": …T… }, "required": [non-optional keys] }` |
- * | tuple `[A, B]`                                | `{ "type": "array", "prefixItems": […A…, …B…], "items": false }`                    |
+ * | tuple `[A, B]`                                | `{ "type": "array", "prefixItems": […A…, …B…], "minItems": 2, "items": false }`     |
  * | `array(T)`                                    | `{ "type": "array", "items": …T… }`                                                 |
  * | `record(T)`                                   | `{ "type": "object", "additionalProperties": …T… }`                                 |
- * | `or(...types)`                                | `{ "anyOf": […each…] }`                                                             |
+ * | `or(...types)`                                | `{ "anyOf": […each…] }`, normalized and in canonical kind order                     |
+ * | recursive schema                              | `{ "$ref": "#/$defs/<name>", "$defs": { "<name>": … } }`                            |
+ *
+ * The union rows follow the data form's normalization: operands are merged
+ * kind-wise, literals covered by their whole kind are absorbed
+ * (`or(42, number)` is all numbers), subsumed patterns are dropped, and
+ * duplicates collapse — so structurally different but equivalent thunk
+ * schemas produce the same JSON Schema.
  *
  * @type {(rtti: RttiType) => Unknown}
  */