functionalscript 0.44.0 → 0.46.0

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

@@ -1,15 +1,16 @@
 /**
- * @import { Unknown as JsonValue } from '../types.ts'
  * @import { Unknown } from './module.f.mjs'
+ * @import { Data } from '../../../types/rtti/data/types.ts'
  */
 
-import { boolean, number, string, bigint, unknown, array, record, or, option } from '../../../types/rtti/module.f.mjs'
+import { boolean, number, string, bigint, never, unknown, array, record, or, option } from '../../../types/rtti/module.f.mjs'
 import { stringify } from '../module.f.mjs'
-import { toJsonSchema, unknown as schemaUnknown } from './module.f.mjs'
+import { dataToJsonSchema, toJsonSchema, unknown as schemaUnknown } from './module.f.mjs'
+import { unitBit } from '../../../types/rtti/data/module.f.mjs'
 import { assert, assertEq } from '../../../asserts/module.f.mjs'
 
 /** @type {(v: Unknown) => string} */
-const serialize = v => stringify(e => e)(/** @type {JsonValue} */ (/** @type {unknown} */ (v)))
+const serialize = v => stringify(e => e)(v)
 
 /** @type {(rtti: Parameters<typeof toJsonSchema>[0], expected: Unknown) => () => void} */
 const eq = (rtti, expected) => () => {
@@ -18,6 +19,46 @@ const eq = (rtti, expected) => () => {
     assertEq(result, exp, [result, exp])
 }
 
+/** @type {(data: Data, expected: Unknown) => () => void} */
+const eqData = (data, expected) => () => {
+    const result = serialize(dataToJsonSchema(data))
+    const exp = serialize(expected)
+    assertEq(result, exp, [result, exp])
+}
+
+/** A recursive list: `type _List = readonly _List[]`. */
+/** @typedef {() => readonly ['array', _List]} _List */
+/** @type {_List} */
+const list = () => ['array', list]
+
+/** Mutual recursion through a container. */
+/** @typedef {() => readonly ['or', typeof number, _Forest]} _Tree */
+/** @typedef {() => readonly ['array', _Tree]} _Forest */
+/** @type {_Tree} */
+const tree = () => ['or', number, forest]
+/** @type {_Forest} */
+const forest = () => ['array', tree]
+
+/** The recursive revision lock schema. Its cycle closes through the
+ * anonymous `or` thunk, which becomes the (empty-string-named) rule. */
+/** @typedef {() => readonly ['record', () => readonly ['or', typeof string, _Lock]]} _Lock */
+/** @type {_Lock} */
+const lock = () => ['record', or(string, lock)]
+
+/** Self-recursive record. */
+/** @typedef {() => readonly ['record', _Rec]} _Rec */
+/** @type {_Rec} */
+const rec = () => ['record', rec]
+
+const listRef = /** @type {const} */ ({ $ref: '#/$defs/list' })
+const treeRef = /** @type {const} */ ({ $ref: '#/$defs/tree' })
+
+/** @type {Unknown} */
+const listDef = { type: 'array', items: listRef }
+
+/** @type {Unknown} */
+const treeDef = { anyOf: [{ type: 'number' }, { type: 'array', items: treeRef }] }
+
 export const proof = {
     tag0: {
         boolean: eq(boolean, { type: 'boolean' }),
@@ -37,10 +78,12 @@ export const proof = {
     },
     array: eq(array(number), { type: 'array', items: { type: 'number' } }),
     record: eq(record(string), { type: 'object', additionalProperties: { type: 'string' } }),
-    or: eq(or(string, number), { anyOf: [{ type: 'string' }, { type: 'number' }] }),
+    // `anyOf` members follow the canonical kind order, not the operand order
+    or: eq(or(string, number), { anyOf: [{ type: 'number' }, { type: 'string' }] }),
     tuple: eq(/** @type {const} */ ([number, string]), {
         type: 'array',
         prefixItems: [{ type: 'number' }, { type: 'string' }],
+        minItems: 2,
         items: false,
     }),
     struct: {
@@ -58,16 +101,35 @@ export const proof = {
             type: 'object',
             properties: { x: { type: 'number' } },
         }),
-        empty: eq(/** @type {const} */ ({}), { type: 'object', properties: {} }),
+        // an unconstrained struct is the whole object kind
+        empty: eq(/** @type {const} */ ({}), { type: 'object' }),
         orOptional: eq(/** @type {const} */ ({ x: or(string, number, undefined) }), {
             type: 'object',
-            properties: { x: { anyOf: [{ type: 'string' }, { type: 'number' }] } },
+            properties: { x: { anyOf: [{ type: 'number' }, { type: 'string' }] } },
         }),
         withConst: eq(/** @type {const} */ ({ x: null, y: string }), {
             type: 'object',
             properties: { x: { const: null }, y: { type: 'string' } },
             required: ['x', 'y'],
         }),
+        optionalOfEveryKind: eq(/** @type {const} */ ({
+            a: option(number),
+            b: option(string),
+            c: option(bigint),
+            d: option(array(number)),
+            e: option(record(string)),
+            f: or(null, undefined),
+        }), {
+            type: 'object',
+            properties: {
+                a: { type: 'number' },
+                b: { type: 'string' },
+                c: { type: 'integer' },
+                d: { type: 'array', items: { type: 'number' } },
+                e: { type: 'object', additionalProperties: { type: 'string' } },
+                f: { const: null },
+            },
+        }),
     },
     schemaUnknownTag: () => {
         const r = schemaUnknown()
@@ -79,15 +141,164 @@ export const proof = {
             items: { type: 'object', additionalProperties: { type: 'boolean' } },
         }),
         orWithConst: eq(or(null, string, /** @type {const} */ (42)), {
-            anyOf: [{ const: null }, { type: 'string' }, { const: 42 }],
+            anyOf: [{ const: null }, { const: 42 }, { type: 'string' }],
         }),
         structWithOr: eq(/** @type {const} */ ({ id: or(string, number), name: option(string) }), {
             type: 'object',
             properties: {
-                id: { anyOf: [{ type: 'string' }, { type: 'number' }] },
+                id: { anyOf: [{ type: 'number' }, { type: 'string' }] },
                 name: { type: 'string' },
             },
             required: ['id'],
         }),
+        topInsideTuple: eq(/** @type {const} */ ([unknown, number]), {
+            type: 'array',
+            prefixItems: [{}, { type: 'number' }],
+            minItems: 2,
+            items: false,
+        }),
+    },
+    normalization: {
+        booleanFromConsts: eq(or(true, false), { type: 'boolean' }),
+        unitMembers: eq(or(null, undefined, true), {
+            anyOf: [{ const: null }, { not: {} }, { const: true }],
+        }),
+        literalAbsorbed: eq(or(/** @type {const} */ (42), number), { type: 'number' }),
+        duplicateLiteral: eq(or(/** @type {const} */ (1), /** @type {const} */ (1)), { const: 1 }),
+        never: eq(never, { not: {} }),
+        emptyTuple: eq(/** @type {const} */ ([]), { type: 'array', items: false }),
+        // `readonly [number] ⊂ readonly number[]` — the tuple pattern is dropped
+        coverageCollapse: eq(or(/** @type {const} */ ([number]), array(number)), {
+            type: 'array',
+            items: { type: 'number' },
+        }),
+        commutative: () => {
+            const a = serialize(toJsonSchema(or(string, number)))
+            const b = serialize(toJsonSchema(or(number, string)))
+            assertEq(a, b, [a, b])
+        },
+    },
+    recursion: {
+        selfList: eq(list, { ...listRef, $defs: { list: listDef } }),
+        mutualEntry: eq(tree, { ...treeRef, $defs: { tree: treeDef } }),
+        mutualInline: eq(forest, { type: 'array', items: treeRef, $defs: { tree: treeDef } }),
+        recursiveUnion: eq(or(number, list), {
+            anyOf: [{ type: 'number' }, { type: 'array', items: listRef }],
+            $defs: { list: listDef },
+        }),
+        recursiveRecord: eq(rec, {
+            $ref: '#/$defs/rec',
+            $defs: { rec: { type: 'object', additionalProperties: { $ref: '#/$defs/rec' } } },
+        }),
+        optionalRecursiveProperty: eq(/** @type {const} */ ({ p: option(list) }), {
+            type: 'object',
+            properties: { p: { type: 'array', items: listRef } },
+            $defs: { list: listDef },
+        }),
+        revisionLock: eq(lock, {
+            type: 'object',
+            additionalProperties: { $ref: '#/$defs/' },
+            $defs: {
+                '': {
+                    anyOf: [
+                        { type: 'string' },
+                        { type: 'object', additionalProperties: { $ref: '#/$defs/' } },
+                    ],
+                },
+            },
+        }),
+        sharedNonRecursive: () => {
+            // a shared, non-recursive definition is inlined at each use — no `$defs`
+            const person = /** @type {const} */ ({ name: string })
+            /** @type {Unknown} */
+            const personSchema = {
+                type: 'object',
+                properties: { name: { type: 'string' } },
+                required: ['name'],
+            }
+            eq(/** @type {const} */ ([person, person]), {
+                type: 'array',
+                prefixItems: [personSchema, personSchema],
+                minItems: 2,
+                items: false,
+            })()
+        },
+    },
+    data: (() => {
+        /** @type {Data} */
+        const tupleWithRest = [{}, { array: [{ prefix: [{ number: true }], rest: { string: true } }] }]
+        /** @type {Data} */
+        const structWithRest = [{}, {
+            object: [{ props: { a: { number: true } }, rest: { string: true } }],
+        }]
+        /** @type {Data} */
+        const optionalByReference = [
+            { r: { unit: unitBit(null) | unitBit(undefined), number: true } },
+            { object: [{ props: { p: 'r' } }] },
+        ]
+        return {
+            plain: eqData([{}, { number: true }], { type: 'number' }),
+            tupleWithRest: eqData(tupleWithRest, {
+                type: 'array',
+                prefixItems: [{ type: 'number' }],
+                minItems: 1,
+                items: { type: 'string' },
+            }),
+            structWithRest: eqData(structWithRest, {
+                type: 'object',
+                properties: { a: { type: 'number' } },
+                required: ['a'],
+                additionalProperties: { type: 'string' },
+            }),
+            // a referenced definition admitting `undefined` makes the key
+            // optional; the reference itself is kept as the property schema
+            optionalByReference: eqData(optionalByReference, {
+                type: 'object',
+                properties: { p: { $ref: '#/$defs/r' } },
+                $defs: { r: { anyOf: [{ const: null }, { not: {} }, { type: 'number' }] } },
+            }),
+        }
+    })(),
+    refEncoding: (() => {
+        /** @type {Data} */
+        const d = [
+            {
+                'a~b': { number: true },
+                'a/b': { number: true },
+                '%2F': { number: true },
+                'a b': { number: true },
+                'é': { number: true },
+            },
+            { array: [{ prefix: ['a~b', 'a/b', '%2F', 'a b', 'é'] }] },
+        ]
+        return eqData(d, {
+            type: 'array',
+            prefixItems: [
+                { $ref: '#/$defs/a~0b' },
+                { $ref: '#/$defs/a~1b' },
+                { $ref: '#/$defs/%252F' },
+                { $ref: '#/$defs/a%20b' },
+                { $ref: '#/$defs/%C3%A9' },
+            ],
+            minItems: 5,
+            items: false,
+            $defs: {
+                'a~b': { type: 'number' },
+                'a/b': { type: 'number' },
+                '%2F': { type: 'number' },
+                'a b': { type: 'number' },
+                'é': { type: 'number' },
+            },
+        })
+    })(),
+    throw: {
+        missingRootDefinition: () => dataToJsonSchema([{}, 'nope']),
+        // an `Object.prototype` member name is still a missing definition
+        missingPrototypeDefinition: () => dataToJsonSchema([{}, 'toString']),
+        missingNestedDefinition: () => {
+            /** @type {Data} */
+            const d = [{ a: { array: [{ prefix: [], rest: 'missing' }] } }, 'a']
+            return dataToJsonSchema(d)
+        },
     },
 }

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

@@ -1,4 +1,24 @@
+/**
+ * JSON serializer for deterministic string output: the atoms every JSON leaf
+ * is spelled with, and the one recursive walk over JSON's containers.
+ *
+ * `treeSerialize` is that walk. It knows objects and arrays and nothing about
+ * leaves, so a codec supplies its own leaf spelling — standard JSON and
+ * extended JSON differ only there, not in a second object/array walker.
+ *
+ * `stringSerialize` is FunctionalScript, not the host's `JSON.stringify`: it
+ * escapes over this repository's own UTF-16 decoder and reproduces the
+ * ECMAScript `QuoteJSONString` result exactly, lone surrogates included.
+ *
+ * @module
+ *
+ * @import { List } from '../../../types/list/types.ts'
+ * @import { Reduce } from '../../../types/function/operator/types.ts'
+ * @import { CodePoint } from '../../../text/utf16/types.ts'
+ * @import { Tree, TreeObject, TreeArray, TreeEntry, TreeEntries, TreeMapEntries } from '../types.ts'
+ */
 import type { List } from '../../../types/list/types.ts';
+import type { Tree, TreeMapEntries } from '../types.ts';
 /**
  * Serializes a string as a JSON string literal.
  *
@@ -25,3 +45,27 @@ export declare const objectWrap: (input: List<List<string>>) => List<string>;
  * @type {(input: List<List<string>>) => List<string>}
  */
 export declare const arrayWrap: (input: List<List<string>>) => List<string>;
+/**
+ * The separator between a serialized property key and its value. Shared with
+ * the DJS serializer, which builds the same `key : value` fragment.
+ *
+ * @type {List<string>}
+ */
+export declare const colon: List<string>;
+/**
+ * The recursive walk over a JSON-shaped tree: objects, arrays, and a leaf
+ * spelling supplied by the codec.
+ *
+ * Every leaf of `Tree<P>` reaches `leafSerialize` — containers are the only
+ * thing this function recognizes — so a codec that adds a leaf type (extended
+ * JSON's `bigint`) or respells one (extended JSON's `3.0` for a whole-valued
+ * `number`) changes `leafSerialize` alone.
+ *
+ * Object entries whose value is `undefined` are dropped: `undefined` is a
+ * missing property, not a leaf of any of these trees.
+ *
+ * @template P
+ * @param {(value: P) => List<string>} leafSerialize
+ * @returns {(sort: TreeMapEntries<P>) => (value: Tree<P>) => List<string>}
+ */
+export declare const treeSerialize: <P>(leafSerialize: (value: P) => List<string>) => (sort: TreeMapEntries<P>) => (value: Tree<P>) => List<string>;

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

@@ -1,26 +1,35 @@
 /**
- * JSON serializer for deterministic string output.
+ * JSON serializer for deterministic string output: the atoms every JSON leaf
+ * is spelled with, and the one recursive walk over JSON's containers.
+ *
+ * `treeSerialize` is that walk. It knows objects and arrays and nothing about
+ * leaves, so a codec supplies its own leaf spelling — standard JSON and
+ * extended JSON differ only there, not in a second object/array walker.
  *
  * `stringSerialize` is FunctionalScript, not the host's `JSON.stringify`: it
  * escapes over this repository's own UTF-16 decoder and reproduces the
  * ECMAScript `QuoteJSONString` result exactly, lone surrogates included.
  *
  * @module
+ *
+ * @import { List } from '../../../types/list/types.ts'
+ * @import { Reduce } from '../../../types/function/operator/types.ts'
+ * @import { CodePoint } from '../../../text/utf16/types.ts'
+ * @import { Tree, TreeObject, TreeArray, TreeEntry, TreeEntries, TreeMapEntries } from '../types.ts'
  */
-/** @import { List } from '../../../types/list/types.ts' */
+
 import { flat, map, reduce, empty } from '../../../types/list/module.f.mjs'
-/** @import { Reduce } from '../../../types/function/operator/types.ts' */
 import { concat } from '../../../types/string/module.f.mjs'
-/** @import { CodePoint } from '../../../text/utf16/types.ts' */
 import { codePointToString, stringToCodePointList } from '../../../text/utf16/module.f.mjs'
 import { errorMask } from '../../../text/code_point/module.f.mjs'
+import { definedEntries, isObject } from '../../../types/object/module.f.mjs'
+import { compose, fn } from '../../../types/function/module.f.mjs'
 import {
     backspace,
     cr,
-    digit0,
     ff,
+    hexDigitCodePoint,
     ht,
-    latinSmallLetterA,
     lf,
     quotationMark,
     reverseSolidus,
@@ -46,8 +55,7 @@ const escapeTable = /** @type {const} */ ({
 })
 
 /** @type {(value: number) => string} */
-const hexDigit = value =>
-    fromCharCode(value < 10 ? digit0 + value : latinSmallLetterA + value - 10)
+const hexDigit = value => fromCharCode(hexDigitCodePoint(value))
 
 /**
  * `\uXXXX` with lowercase hex digits, matching ECMAScript's `UnicodeEscape`.
@@ -68,7 +76,7 @@ const unicodeEscape = unit =>
 const escapeCodePoint = codePoint =>
     (codePoint & errorMask) !== 0
         ? unicodeEscape(codePoint & 0xffff)
-        : escapeTable[/** @type {keyof typeof escapeTable} */ (codePoint)]
+        : escapeTable[codePoint]
             ?? (codePoint < space ? unicodeEscape(codePoint) : codePointToString(codePoint))
 
 /**
@@ -129,3 +137,57 @@ export const objectWrap
  */
 export const arrayWrap
     = wrap('[')(']')
+
+/**
+ * The separator between a serialized property key and its value. Shared with
+ * the DJS serializer, which builds the same `key : value` fragment.
+ *
+ * @type {List<string>}
+ */
+export const colon = [':']
+
+/**
+ * The recursive walk over a JSON-shaped tree: objects, arrays, and a leaf
+ * spelling supplied by the codec.
+ *
+ * Every leaf of `Tree<P>` reaches `leafSerialize` — containers are the only
+ * thing this function recognizes — so a codec that adds a leaf type (extended
+ * JSON's `bigint`) or respells one (extended JSON's `3.0` for a whole-valued
+ * `number`) changes `leafSerialize` alone.
+ *
+ * Object entries whose value is `undefined` are dropped: `undefined` is a
+ * missing property, not a leaf of any of these trees.
+ *
+ * @template P
+ * @param {(value: P) => List<string>} leafSerialize
+ * @returns {(sort: TreeMapEntries<P>) => (value: Tree<P>) => List<string>}
+ */
+export const treeSerialize = leafSerialize => sort => {
+    // `definedEntries` is generic; naming it at `P` here is what keeps the leaf
+    // type through the `fn(...)` composition below, which would otherwise
+    // instantiate it at `unknown`.
+    /** @type {(object: TreeObject<P>) => TreeEntries<P>} */
+    const objectEntries = definedEntries
+    /** @type {(kv: TreeEntry<P>) => List<string>} */
+    const propertySerialize = ([k, v]) => flat([
+        stringSerialize(k),
+        colon,
+        f(v)
+    ])
+    const mapPropertySerialize = map(propertySerialize)
+    /** @type {(object: TreeObject<P>) => List<string>} */
+    const objectSerialize = fn(objectEntries)
+        .map(sort)
+        .map(mapPropertySerialize)
+        .map(objectWrap)
+        .result
+    /** @type {(value: Tree<P>) => List<string>} */
+    const f = value => {
+        if (value instanceof Array) { return arraySerialize(value) }
+        if (isObject(value)) { return objectSerialize(value) }
+        return leafSerialize(value)
+    }
+    /** @type {(value: TreeArray<P>) => List<string>} */
+    const arraySerialize = compose(map(f))(arrayWrap)
+    return f
+}

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

@@ -2,6 +2,11 @@
  * Tokenizer for JSON lexical analysis.
  *
  * @module
+ *
+ * @import { StateScan } from '../../../types/function/operator/types.ts'
+ * @import { List } from '../../../types/list/types.ts'
+ * @import { JsToken } from '../../../js/tokenizer/types.ts'
+ * @import { JsonToken, _ScanState, _ScanInput } from './types.ts'
  */
 import type { List } from '../../../types/list/types.ts';
 import type { JsonToken } from './types.ts';
@@ -15,3 +20,6 @@ import type { JsonToken } from './types.ts';
  * @type {(input: List<number>) => List<JsonToken>}
  */
 export declare const tokenize: (input: List<number>) => List<JsonToken>;
+export declare const proof: {
+    parseMinusStateEof: () => void;
+};

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

@@ -2,15 +2,16 @@
  * Tokenizer for JSON lexical analysis.
  *
  * @module
+ *
+ * @import { StateScan } from '../../../types/function/operator/types.ts'
+ * @import { List } from '../../../types/list/types.ts'
+ * @import { JsToken } from '../../../js/tokenizer/types.ts'
+ * @import { JsonToken, _ScanState, _ScanInput } from './types.ts'
  */
 
-/** @import { StateScan } from '../../../types/function/operator/types.ts' */
-/** @import { List } from '../../../types/list/types.ts' */
-import { concat, empty, flat, stateScan } from '../../../types/list/module.f.mjs'
-import { multiply } from '../../../types/bigfloat/module.f.mjs'
+import { concat, empty, flat, stateScan, toArray } from '../../../types/list/module.f.mjs'
 import { tokenize as jsTokenize } from '../../../js/tokenizer/module.f.mjs'
-/** @import { JsToken } from '../../../js/tokenizer/types.ts' */
-/** @import { JsonToken, _ScanState, _ScanInput } from './types.ts' */
+import { assertEq } from '../../../asserts/module.f.mjs'
 
 /** @type {(input: JsToken) => List<JsonToken>} */
 const mapToken = input => {
@@ -47,8 +48,13 @@ const parseDefaultState = input => {
 const parseMinusState = input => {
     if (input === null) return [[{ kind: 'error', message: 'invalid token' }], { kind: 'def' }]
     switch (input.token.kind) {
-        case '-': return [[{ kind: 'error', message: 'invalid token' }], { kind: '-' }]
-        case 'number': return [[{ kind: 'number', bf: multiply(input.token.bf)(-1n), value: `-${input.token.value}` }], { kind: 'def' }]
+        // negation is lexical: the minus sign joins the lexeme, so the token
+        // stays the exact source text of the JSON number.
+        case 'number': return [[{ kind: 'number', value: `-${input.token.value}` }], { kind: 'def' }]
+        // No `'-'` case: the underlying JS tokenizer always merges adjacent
+        // `-` characters into a single `'--'` token (see `js/tokenizer`), so
+        // this state never sees a second `'-'` — a run of `-` past the first
+        // always falls through to the `default` arm below instead.
         default: return [{ first: { kind: 'error', message: 'invalid token' }, tail: mapToken(input.token) }, { kind: 'def' }]
     }
 }
@@ -75,3 +81,20 @@ export const tokenize = input => {
     const jsTokens = jsTokenize(input)('')
     return flat(stateScan(scanToken)({ kind: 'def' })(concat(jsTokens)([null])))
 }
+
+export const proof = {
+    // `parseMinusState` only sees `null` if the JSON tokenizer's own EOF
+    // sentinel arrives while still in state '-' — i.e. input ends right after
+    // a lone `-`. Unreachable through the public `tokenize`: the underlying
+    // JS tokenizer always emits its own `eof` token first, and consuming that
+    // (the default branch, any kind other than '-' or 'number') resets state
+    // to 'def' before the sentinel `null` is ever seen. Call the private
+    // state handler directly to cover the branch anyway.
+    parseMinusStateEof: () => {
+        const [tokens, state] = parseMinusState(null)
+        assertEq(state.kind, 'def')
+        const a = toArray(tokens)
+        assertEq(a.length, 1)
+        assertEq(a[0].kind, 'error')
+    },
+}

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

@@ -5,4 +5,10 @@ export declare const proof: {
     json: (() => void)[];
     id: (() => void)[];
     keywords: (() => void)[];
+    lossless: {
+        oversizedCoefficient: () => void;
+        unboundedExponent: () => void;
+        negativeUnboundedExponent: () => void;
+        negativeOversized: () => void;
+    };
 };