functionalscript 0.44.0 → 0.46.0

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

@@ -0,0 +1,42 @@
+/**
+ * @import { Unknown } from './types.ts'
+ */
+export declare const proof: {
+    bigint: {
+        positive: () => void;
+        negative: () => void;
+        zero: () => void;
+        beyondSafeInteger: () => void;
+        oversized: () => void;
+    };
+    number: {
+        negativeZero: () => void;
+        fraction: () => void;
+        wholeFraction: () => void;
+        exponent: () => void;
+        capitalExponent: () => void;
+        negativeExponent: () => void;
+        underflow: () => void;
+        exponentSpelling: () => void;
+    };
+    overflow: {
+        exponent: () => void;
+        negativeExponent: () => void;
+        unboundedExponent: () => void;
+        malformed: () => void;
+    };
+    containers: {
+        array: () => void;
+        object: () => void;
+        undefinedProperty: () => void;
+    };
+    nonFinite: {
+        nan: () => void;
+        infinity: () => void;
+        negativeInfinity: () => void;
+    };
+    serialize: {
+        oneToOne: () => void;
+        largeBigintHasNoExponent: () => void;
+    };
+};

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

@@ -0,0 +1,127 @@
+/**
+ * @import { Unknown } from './types.ts'
+ */
+
+import { parse, stringify as extendedStringify } from './module.f.mjs'
+import { sort } from '../../../types/object/module.f.mjs'
+import { unwrap } from '../../../types/result/module.f.mjs'
+import { assert, assertEq, assertStructurallySame } from '../../../asserts/module.f.mjs'
+
+const stringify = extendedStringify(sort)
+
+/**
+ * The runtime type a token parses to, and the text that value serializes back
+ * to — the two halves of the extended codec's round trip.
+ *
+ * @type {(text: string) => readonly [string, string]}
+ */
+const parsed = text => {
+    const value = unwrap(parse(text))
+    return [typeof value, stringify(value)]
+}
+
+/** @type {(text: string) => Unknown} */
+const parseValue = text => unwrap(parse(text))
+
+/** @type {(text: string) => string} */
+const parseError = text => {
+    const [tag, message] = parse(text)
+    assertEq(tag, 'error')
+    return `${message}`
+}
+
+// Long enough that `Number` of it is `Infinity` and `10 ** exponent` is not a
+// computation anyone can afford.
+const hugeExp = '99999999999999999999'
+
+export const proof = {
+    // bare integer syntax is `bigint`, whatever the magnitude
+    bigint: {
+        positive: () => assertStructurallySame(parsed('123'), ['bigint', '123']),
+        negative: () => assertStructurallySame(parsed('-123'), ['bigint', '-123']),
+        zero: () => assertStructurallySame(parsed('0'), ['bigint', '0']),
+        // beyond `Number.MAX_SAFE_INTEGER`, so a materializer that went
+        // through `number` first would round here
+        beyondSafeInteger: () => {
+            assertEq(parseValue('12345678901234567890123'), 12345678901234567890123n)
+            assertEq(parseValue('-12345678901234567890123'), -12345678901234567890123n)
+        },
+        // an integer of a size no `number` can even approximate
+        oversized: () => {
+            const digits = `1${'0'.repeat(2000)}`
+            assertStructurallySame(parsed(digits), ['bigint', digits])
+            assertEq(parseValue(digits), 10n ** 2000n)
+        },
+    },
+    // `.`/`e`/`E` means `number`, even when the value is a whole number
+    number: {
+        negativeZero: () => {
+            assertStructurallySame(parsed('-0'), ['number', '-0'])
+            // the sign is the whole point: `bigint` has no negative zero
+            assert(Object.is(parseValue('-0'), -0))
+        },
+        fraction: () => assertStructurallySame(parsed('1.5'), ['number', '1.5']),
+        wholeFraction: () => assertStructurallySame(parsed('1.0'), ['number', '1.0']),
+        exponent: () => assertStructurallySame(parsed('1e3'), ['number', '1000.0']),
+        capitalExponent: () => assertStructurallySame(parsed('1E3'), ['number', '1000.0']),
+        negativeExponent: () => assertStructurallySame(parsed('1e-3'), ['number', '0.001']),
+        // ordinary `number` rounding is not an error: an exponent below the
+        // range is zero, as it is everywhere else in JavaScript
+        underflow: () => assertStructurallySame(parsed('1e-400'), ['number', '0.0']),
+        // a `number` big enough to spell itself with an exponent keeps that
+        // spelling — appending `.0` to it would not even be valid JSON
+        exponentSpelling: () => assertStructurallySame(parsed('1e21'), ['number', '1e+21']),
+    },
+    // a valid token the extended domain cannot represent is an ordinary
+    // parse error, never `Infinity` and never a throw
+    overflow: {
+        exponent: () => assertEq(
+            parseError('1e400'),
+            'number is out of the finite range: 1e400'),
+        negativeExponent: () => assertEq(
+            parseError('-1e400'),
+            'number is out of the finite range: -1e400'),
+        // exponent text far beyond `number` precision: the tokenizer keeps
+        // every digit, and the policy rejects the token rather than losing them
+        unboundedExponent: () => assertEq(
+            parseError(`1e${hugeExp}`),
+            `number is out of the finite range: 1e${hugeExp}`),
+        // malformed input is still an ordinary error
+        malformed: () => assertEq(parseError('{'), 'unexpected end'),
+    },
+    containers: {
+        array: () => assertEq(
+            stringify(parseValue('[1,2.0,-0,"x",true,false,null]')),
+            '[1,2.0,-0,"x",true,false,null]'),
+        object: () => assertEq(
+            stringify(parseValue('{"b":[1e2],"a":{"c":-7}}')),
+            '{"a":{"c":-7},"b":[100.0]}'),
+        // a missing property is not a leaf
+        undefinedProperty: () => assertEq(stringify({ a: 1n, b: undefined }), '{"a":1}'),
+    },
+    // programmatic values: JSON has no syntax for these, so the serializer
+    // spells them `null` — the same choice `JSON.stringify` makes
+    nonFinite: {
+        nan: () => assertEq(stringify(NaN), 'null'),
+        infinity: () => assertEq(stringify(Infinity), 'null'),
+        negativeInfinity: () => assertEq(stringify(-Infinity), 'null'),
+    },
+    // the spellings that keep `number` and `bigint` apart across a round trip
+    serialize: {
+        oneToOne: () => {
+            assertEq(stringify(0n), '0')
+            assertEq(stringify(0), '0.0')
+            assertEq(stringify(-0), '-0')
+            assertEq(stringify(3n), '3')
+            assertEq(stringify(3), '3.0')
+            assertEq(stringify(1.5), '1.5')
+        },
+        // a bigint is never shortened to exponent notation, however large:
+        // that syntax would parse back as a `number`
+        largeBigintHasNoExponent: () => {
+            const text = stringify(10n ** 30n)
+            assertEq(text, `1${'0'.repeat(30)}`)
+            assertStructurallySame(parsed(text), ['bigint', text])
+        },
+    },
+}

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

@@ -0,0 +1,23 @@
+/**
+ * TypeScript counterparts of the extended JSON data model: ordinary JSON's
+ * containers with `bigint` added to the primitive leaf set.
+ *
+ * This is a runtime representation, not a new syntax: an extended value's
+ * serialized form is ordinary valid JSON text, with no `123n` literal, tagged
+ * object, or quoted-integer convention.
+ *
+ * @module
+ */
+import type { Primitive as JsonPrimitive, Tree, TreeObject, TreeArray, TreeMapEntries } from '../types.ts';
+/**
+ * `null | boolean | string | number | bigint`.
+ *
+ * `bigint` carries JSON's bare integer syntax exactly, whatever its
+ * magnitude; `number` carries decimal and exponent syntax, and the one bare
+ * integer that `bigint` cannot represent — negative zero.
+ */
+export type Primitive = JsonPrimitive | bigint;
+export type Unknown = Tree<Primitive>;
+export type Object = TreeObject<Primitive>;
+export type Array = TreeArray<Primitive>;
+export type _MapEntries = TreeMapEntries<Primitive>;

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

@@ -9,11 +9,17 @@
  * [`./types.ts`](./types.ts), and the rtti schemas they are pinned against in
  * [`./rtti/module.f.mjs`](./rtti/module.f.mjs).
  *
+ * This is the standard, bigint-free codec: numbers are JavaScript `number`s.
+ * [`./extended/module.f.mjs`](./extended/module.f.mjs) is the sibling codec
+ * that keeps JSON's bare integer syntax as `bigint`. Both are numeric policies
+ * over the same tokenizer and the same structural parser — see
+ * [`./README.md`](./README.md).
+ *
  * @module
  *
- * @import { StringMap } from '../../types/object/types.ts'
  * @import { Result } from '../../types/result/types.ts'
- * @import { _MapEntries, Object, Unknown, } from './types.ts'
+ * @import { _MapEntries, Primitive, Unknown, } from './types.ts'
+ * @import { NumberPolicy } from './parser/types.ts'
  * @import { List } from '../../types/list/types.ts'
  */
 import type { Result } from '../../types/result/types.ts';

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

@@ -9,22 +9,29 @@
  * [`./types.ts`](./types.ts), and the rtti schemas they are pinned against in
  * [`./rtti/module.f.mjs`](./rtti/module.f.mjs).
  *
+ * This is the standard, bigint-free codec: numbers are JavaScript `number`s.
+ * [`./extended/module.f.mjs`](./extended/module.f.mjs) is the sibling codec
+ * that keeps JSON's bare integer syntax as `bigint`. Both are numeric policies
+ * over the same tokenizer and the same structural parser — see
+ * [`./README.md`](./README.md).
+ *
  * @module
  *
- * @import { StringMap } from '../../types/object/types.ts'
  * @import { Result } from '../../types/result/types.ts'
- * @import { _MapEntries, Object, Unknown, } from './types.ts'
+ * @import { _MapEntries, Primitive, Unknown, } from './types.ts'
+ * @import { NumberPolicy } from './parser/types.ts'
  * @import { List } from '../../types/list/types.ts'
  */
 
-import { next, flat, map } from '../../types/list/module.f.mjs'
+import { next } from '../../types/list/module.f.mjs'
 import { concat } from '../../types/string/module.f.mjs'
 import { stringToList } from '../../text/utf16/module.f.mjs'
 import { parse as parseTokens } from './parser/module.f.mjs'
 import { tokenize } from './tokenizer/module.f.mjs'
-import { at, definedEntries } from '../../types/object/module.f.mjs'
-import { compose, fn } from '../../types/function/module.f.mjs'
-import { objectWrap, arrayWrap, stringSerialize, numberSerialize, nullSerialize, boolSerialize } from './serializer/module.f.mjs'
+import { at } from '../../types/object/module.f.mjs'
+import { compose } from '../../types/function/module.f.mjs'
+import { ok } from '../../types/result/module.f.mjs'
+import { treeSerialize, stringSerialize, numberSerialize, nullSerialize, boolSerialize } from './serializer/module.f.mjs'
 
 // ── JSON utilities ────────────────────────────────────────────────────────────
 
@@ -43,42 +50,23 @@ export const setProperty = value => {
     return f
 }
 
-const colon = [':']
-
-/** @type {(cmd: StringMap<Unknown>) => readonly (readonly [string, Unknown])[]} */
-const df = definedEntries
+/**
+ * The standard codec's leaf spelling. The containers around it are
+ * `treeSerialize`'s, shared with every other JSON codec.
+ *
+ * @type {(value: Primitive) => List<string>}
+ */
+const primitiveSerialize = value => {
+    switch (typeof value) {
+        case 'boolean': { return boolSerialize(value) }
+        case 'number': { return numberSerialize(value) }
+        case 'string': { return stringSerialize(value) }
+        default: { return nullSerialize }
+    }
+}
 
 /** @type {(mapEntries: _MapEntries) => (value: Unknown) => List<string>} */
-export const serialize = sort => {
-        /** @type {(kv: readonly[string, Unknown]) => List<string>} */
-        const propertySerialize = ([k, v]) => flat([
-            stringSerialize(k),
-            colon,
-            f(v)
-        ])
-        const mapPropertySerialize = map(propertySerialize)
-        /** @type {(object: Object) => List<string>} */
-        const objectSerialize = fn(df)
-            .map(sort)
-            .map(mapPropertySerialize)
-            .map(objectWrap)
-            .result
-        /** @type {(value: Unknown) => List<string>} */
-        const f = value => {
-            switch (typeof value) {
-                case 'boolean': { return boolSerialize(value) }
-                case 'number': { return numberSerialize(value) }
-                case 'string': { return stringSerialize(value) }
-                default: {
-                    if (value === null) { return nullSerialize }
-                    if (value instanceof Array) { return arraySerialize(value) }
-                    return objectSerialize(value)
-                }
-            }
-        }
-        const arraySerialize = compose(map(f))(arrayWrap)
-        return f
-    }
+export const serialize = treeSerialize(primitiveSerialize)
 
 /**
  * The standard `JSON.stringify` rules determined by
@@ -89,6 +77,20 @@ export const serialize = sort => {
  */
 export const stringify = sort => compose(serialize(sort))(concat)
 
+/**
+ * The standard codec's numeric policy: every JSON number token becomes a
+ * JavaScript `number`, read from the token's own lexeme.
+ *
+ * It is total — no valid JSON number is rejected — so a magnitude outside the
+ * finite `number` range materializes the way JavaScript itself reads that
+ * text (`1e400` is `Infinity`, `1e-400` is `0`). The bigint-free domain has
+ * nothing more exact to offer; the extended codec keeps such distinctions,
+ * from the same token, without this one having to.
+ *
+ * @type {NumberPolicy<number>}
+ */
+const numberPolicy = token => ok(parseFloat(token.value))
+
 /**
  * Parses `text` as JSON with this module's own pure tokenizer and parser,
  * reporting failure as a `Result` rather than throwing: malformed input is
@@ -101,4 +103,4 @@ export const stringify = sort => compose(serialize(sort))(concat)
  *
  * @type {(text: string) => Result<Unknown, string>}
  */
-export const parse = text => parseTokens(tokenize(stringToList(text)))
+export const parse = text => parseTokens(numberPolicy)(tokenize(stringToList(text)))

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

@@ -0,0 +1,59 @@
+/**
+ * Bounded lexical analysis of a JSON number token.
+ *
+ * `NumberToken.value` is the canonical lossless numeric source, and these
+ * helpers read it **without narrowing it first**: every operation here costs
+ * at most the length of the token, so a valid JSON number is classified
+ * correctly whatever its magnitude. In particular no helper builds a
+ * coefficient bigint, converts an arbitrary exponent to `number`, or evaluates
+ * a power such as `10 ** exponent`.
+ *
+ * That matters for schema-directed consumers, which have to decide questions
+ * such as "is this token an integer?" *before* a materializer rounds the value
+ * into `number`: `1.00000000000000001` and `1` are the same `number` but
+ * different tokens.
+ *
+ * @module
+ *
+ * @import { Sign } from '../../../types/function/compare/types.ts'
+ * @import { NumberLexeme } from './types.ts'
+ */
+import type { NumberLexeme } from './types.ts';
+/**
+ * Splits a JSON number token into its lexical parts.
+ *
+ * The token is grammar-validated by the tokenizer —
+ * `-?(0|[1-9][0-9]*)(\.[0-9]+)?([eE][+-]?[0-9]+)?` — so this is a split, not a
+ * validation.
+ *
+ * @type {(value: string) => NumberLexeme}
+ */
+export declare const numberLexeme: (value: string) => NumberLexeme;
+/**
+ * Whether the lexeme is bare integer syntax: no `.` and no `e` / `E`.
+ *
+ * The distinction is lexical, not mathematical — `1e3` is not bare integer
+ * syntax even though its value is the integer `1000`.
+ *
+ * @type {(lexeme: NumberLexeme) => boolean}
+ */
+export declare const isBareInteger: (lexeme: NumberLexeme) => boolean;
+/**
+ * Whether the lexeme spells a mathematical integer.
+ *
+ * This is the exact question, not the lexical one: `1e3` and `1.00` are
+ * integral while `1.5` is not. It stays bounded by the token's length.
+ *
+ * The value is `coefficient × 10 ** (exponent - fractionDigits)`, so it is an
+ * integer exactly when the exponent shifts the decimal point no further right
+ * than the coefficient's own trailing zeros allow. Both sides of that
+ * comparison — the fraction-digit count and the trailing-zero count — are
+ * bounded by the token, so the exponent only ever has to be compared against a
+ * small number.
+ *
+ * A zero coefficient is the simple case: zero is integral for any exponent, so
+ * the exponent is not examined at all.
+ *
+ * @type {(lexeme: NumberLexeme) => boolean}
+ */
+export declare const isIntegral: (lexeme: NumberLexeme) => boolean;

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

@@ -0,0 +1,136 @@
+/**
+ * Bounded lexical analysis of a JSON number token.
+ *
+ * `NumberToken.value` is the canonical lossless numeric source, and these
+ * helpers read it **without narrowing it first**: every operation here costs
+ * at most the length of the token, so a valid JSON number is classified
+ * correctly whatever its magnitude. In particular no helper builds a
+ * coefficient bigint, converts an arbitrary exponent to `number`, or evaluates
+ * a power such as `10 ** exponent`.
+ *
+ * That matters for schema-directed consumers, which have to decide questions
+ * such as "is this token an integer?" *before* a materializer rounds the value
+ * into `number`: `1.00000000000000001` and `1` are the same `number` but
+ * different tokens.
+ *
+ * @module
+ *
+ * @import { Sign } from '../../../types/function/compare/types.ts'
+ * @import { NumberLexeme } from './types.ts'
+ */
+
+import { cmp } from '../../../types/function/compare/module.f.mjs'
+
+/**
+ * Splits a JSON number token into its lexical parts.
+ *
+ * The token is grammar-validated by the tokenizer —
+ * `-?(0|[1-9][0-9]*)(\.[0-9]+)?([eE][+-]?[0-9]+)?` — so this is a split, not a
+ * validation.
+ *
+ * @type {(value: string) => NumberLexeme}
+ */
+export const numberLexeme = value => {
+    const sign = value.startsWith('-') ? '-' : ''
+    const unsigned = value.slice(sign.length)
+    // at most one of 'e'/'E' can occur, so whichever `indexOf` finds is it
+    const lowerE = unsigned.indexOf('e')
+    const eIndex = lowerE < 0 ? unsigned.indexOf('E') : lowerE
+    const coefficient = eIndex < 0 ? unsigned : unsigned.slice(0, eIndex)
+    const expText = eIndex < 0 ? '' : unsigned.slice(eIndex + 1)
+    const dotIndex = coefficient.indexOf('.')
+    const int = dotIndex < 0 ? coefficient : coefficient.slice(0, dotIndex)
+    const frac = dotIndex < 0 ? '' : coefficient.slice(dotIndex + 1)
+    const expSign = expText.startsWith('-')
+        ? '-'
+        : expText.startsWith('+') ? '+' : ''
+    return { sign, int, frac, expSign, exp: expText.slice(expSign.length) }
+}
+
+/**
+ * Whether the lexeme is bare integer syntax: no `.` and no `e` / `E`.
+ *
+ * The distinction is lexical, not mathematical — `1e3` is not bare integer
+ * syntax even though its value is the integer `1000`.
+ *
+ * @type {(lexeme: NumberLexeme) => boolean}
+ */
+export const isBareInteger = ({ frac, exp }) => frac === '' && exp === ''
+
+/** @type {(digits: string) => string} */
+const stripLeadingZeros = digits => {
+    let i = 0
+    while (i < digits.length && digits[i] === '0') { i += 1 }
+    return digits.slice(i)
+}
+
+/** @type {(digits: string) => number} */
+const trailingZeroCount = digits => {
+    let n = 0
+    while (n < digits.length && digits[digits.length - 1 - n] === '0') { n += 1 }
+    return n
+}
+
+/**
+ * Compares arbitrarily long non-negative digit text against an ordinary
+ * non-negative integer, in the length of that text.
+ *
+ * Leading zeros are dropped, so equal-length digit strings compare
+ * numerically as strings and unequal lengths are decided by length alone.
+ * `bound` therefore never has to be turned into digit text long enough to
+ * match `digits`, and `digits` never has to become a number.
+ *
+ * @type {(digits: string) => (bound: number) => Sign}
+ */
+const compareDigits = digits => bound => {
+    const a = stripLeadingZeros(digits)
+    const b = stripLeadingZeros(`${bound}`)
+    const byLength = cmp(a.length)(b.length)
+    return byLength === 0 ? cmp(a)(b) : byLength
+}
+
+/**
+ * Whether the lexeme's exponent is at least `bound`, an ordinary integer
+ * small enough to have come from the token's own length.
+ *
+ * The exponent itself is never converted: its sign decides which side of the
+ * comparison can already be answered, and only its digit text is compared —
+ * so `1e-99999999999999999999` is settled by looking at the sign and a length,
+ * not by representing that exponent.
+ *
+ * @type {(lexeme: NumberLexeme) => (bound: number) => boolean}
+ */
+const exponentAtLeast = ({ expSign, exp }) => bound =>
+    expSign === '-'
+        // a negative exponent reaches `bound` only if `bound` is not positive
+        // and the exponent's magnitude stays within `-bound`
+        ? bound <= 0 && compareDigits(exp)(-bound) <= 0
+        // a non-negative exponent (`''` — an absent exponent — included, since
+        // its digit text is then empty and compares as zero) always reaches a
+        // non-positive `bound`
+        : bound <= 0 || compareDigits(exp)(bound) >= 0
+
+/**
+ * Whether the lexeme spells a mathematical integer.
+ *
+ * This is the exact question, not the lexical one: `1e3` and `1.00` are
+ * integral while `1.5` is not. It stays bounded by the token's length.
+ *
+ * The value is `coefficient × 10 ** (exponent - fractionDigits)`, so it is an
+ * integer exactly when the exponent shifts the decimal point no further right
+ * than the coefficient's own trailing zeros allow. Both sides of that
+ * comparison — the fraction-digit count and the trailing-zero count — are
+ * bounded by the token, so the exponent only ever has to be compared against a
+ * small number.
+ *
+ * A zero coefficient is the simple case: zero is integral for any exponent, so
+ * the exponent is not examined at all.
+ *
+ * @type {(lexeme: NumberLexeme) => boolean}
+ */
+export const isIntegral = lexeme => {
+    const { int, frac } = lexeme
+    const coefficient = `${int}${frac}`
+    const zeros = trailingZeroCount(coefficient)
+    return zeros === coefficient.length || exponentAtLeast(lexeme)(frac.length - zeros)
+}

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

@@ -0,0 +1,24 @@
+export declare const proof: {
+    numberLexeme: {
+        int: () => void;
+        negative: () => void;
+        fraction: () => void;
+        exponent: () => void;
+        capitalExponent: () => void;
+        plusExponent: () => void;
+        minusExponent: () => void;
+        unbounded: () => void;
+    };
+    isBareInteger: {
+        int: () => void;
+        zero: () => void;
+        fraction: () => void;
+        exponent: () => void;
+    };
+    isIntegral: {
+        zero: (() => void)[];
+        plain: (() => void)[];
+        exponent: (() => void)[];
+        unbounded: (() => void)[];
+    };
+};

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

@@ -0,0 +1,86 @@
+import { isBareInteger, isIntegral, numberLexeme } from './module.f.mjs'
+import { assert, assertStructurallySame } from '../../../asserts/module.f.mjs'
+
+/** @type {(value: string) => boolean} */
+const integral = value => isIntegral(numberLexeme(value))
+
+/** @type {(value: string) => boolean} */
+const bareInteger = value => isBareInteger(numberLexeme(value))
+
+// An exponent long enough that representing it as a `number` loses digits and
+// `10 ** exponent` is not a computation anyone can afford. Every check below
+// that uses it must be decided by the token's shape alone.
+const hugeExp = '99999999999999999999'
+
+export const proof = {
+    numberLexeme: {
+        int: () => assertStructurallySame(
+            numberLexeme('123'),
+            { sign: '', int: '123', frac: '', expSign: '', exp: '' }),
+        negative: () => assertStructurallySame(
+            numberLexeme('-123'),
+            { sign: '-', int: '123', frac: '', expSign: '', exp: '' }),
+        fraction: () => assertStructurallySame(
+            numberLexeme('-0.125'),
+            { sign: '-', int: '0', frac: '125', expSign: '', exp: '' }),
+        exponent: () => assertStructurallySame(
+            numberLexeme('1e10'),
+            { sign: '', int: '1', frac: '', expSign: '', exp: '10' }),
+        capitalExponent: () => assertStructurallySame(
+            numberLexeme('1.5E10'),
+            { sign: '', int: '1', frac: '5', expSign: '', exp: '10' }),
+        plusExponent: () => assertStructurallySame(
+            numberLexeme('1e+10'),
+            { sign: '', int: '1', frac: '', expSign: '+', exp: '10' }),
+        minusExponent: () => assertStructurallySame(
+            numberLexeme('1e-10'),
+            { sign: '', int: '1', frac: '', expSign: '-', exp: '10' }),
+        // nothing is narrowed, so an unrepresentable exponent is just text
+        unbounded: () => assertStructurallySame(
+            numberLexeme(`-1.5e-${hugeExp}`),
+            { sign: '-', int: '1', frac: '5', expSign: '-', exp: hugeExp }),
+    },
+    // bare integer syntax: no `.` and no `e`/`E`, whatever the value is
+    isBareInteger: {
+        int: () => assert(bareInteger('-1230')),
+        zero: () => assert(bareInteger('-0')),
+        fraction: () => assert(!bareInteger('1.0')),
+        exponent: () => assert(!bareInteger('1e3')),
+    },
+    isIntegral: {
+        // a zero coefficient is integral at any exponent, and is decided
+        // without looking at the exponent at all
+        zero: [
+            () => assert(integral('0')),
+            () => assert(integral('-0.000')),
+            () => assert(integral(`0.0e-${hugeExp}`)),
+        ],
+        plain: [
+            () => assert(integral('123')),
+            () => assert(integral('1.00')),
+            () => assert(!integral('1.5')),
+            () => assert(!integral('1.50')),
+        ],
+        // the exponent moves the point; only the coefficient's own trailing
+        // zeros can absorb a move to the right
+        exponent: [
+            () => assert(integral('1e3')),
+            () => assert(integral('1.5e1')),
+            () => assert(integral('1.5e2')),
+            () => assert(integral('150e-1')),
+            () => assert(!integral('1.5e-1')),
+            () => assert(!integral('15e-2')),
+            () => assert(!integral('1.55e1')),
+            () => assert(!integral('1.0000000000001e5')),
+            // leading zeros in the exponent are not extra magnitude
+            () => assert(integral('1.5e001')),
+        ],
+        // decided from lengths and a sign, never by representing the exponent
+        unbounded: [
+            () => assert(integral(`1e${hugeExp}`)),
+            () => assert(integral(`1.5e${hugeExp}`)),
+            () => assert(!integral(`1e-${hugeExp}`)),
+            () => assert(!integral(`1.5e-${hugeExp}`)),
+        ],
+    },
+}

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

@@ -0,0 +1,28 @@
+/**
+ * Types for the lexical view of a JSON number token.
+ *
+ * @module
+ */
+/**
+ * The parts of a JSON number lexeme, each kept as text.
+ *
+ * Nothing here is narrowed to a runtime numeric type, so a lexeme describes
+ * every syntactically valid JSON number — including coefficients larger than
+ * the runtime can build as a `bigint` and exponents beyond `number` precision.
+ *
+ * The empty string means "absent" for both optional parts, which is
+ * unambiguous: JSON requires at least one digit after `.` and at least one
+ * exponent digit, so a present part is never empty.
+ */
+export type NumberLexeme = {
+    /** `'-'` for a negative number, `''` otherwise. */
+    readonly sign: '' | '-';
+    /** The integer digits; always at least one digit. */
+    readonly int: string;
+    /** The fraction digits, or `''` when the lexeme has no `.`. */
+    readonly frac: string;
+    /** The exponent sign as written, or `''` when it is omitted. */
+    readonly expSign: '' | '+' | '-';
+    /** The exponent digits, or `''` when the lexeme has no `e` / `E`. */
+    readonly exp: string;
+};