@raoh/core 0.9.0-dev.15.20261004151401.ge5893e0cc07d

package/dist/float.js

@@ -0,0 +1,257 @@
+// IEEE 754 binary32 and binary64 values as the Raoh Specification reads and writes them.
+import { JsonNumber } from "./input.js";
+import { tagOf } from "./copy.js";
+const EXACT_INTEGER = 2n ** 53n;
+/** 10^0 to 10^22, each an exact binary64, written as literals rather than computed with `**`. */
+const POWERS_OF_TEN = [
+    1e0, 1e1, 1e2, 1e3, 1e4, 1e5, 1e6, 1e7, 1e8, 1e9, 1e10, 1e11, 1e12, 1e13, 1e14, 1e15, 1e16, 1e17, 1e18, 1e19, 1e20,
+    1e21, 1e22,
+];
+const FORMATS = {
+    32: { precision: 24, minExponent: -126, maxExponent: 127 },
+    64: { precision: 53, minExponent: -1022, maxExponent: 1023 },
+};
+/**
+ * A float, kept with its width, as an issue's metadata holds one: the width decides how it is
+ * written in a message, so that a float32 bound of 0.1 reads `0.1` and not the binary64 digits of
+ * the same value.
+ */
+export class Float {
+    value;
+    width;
+    constructor(value, width) {
+        this.value = width === 32 ? Math.fround(value) : value;
+        this.width = width;
+    }
+    get [Symbol.toStringTag]() {
+        return tagOf("Float");
+    }
+    valueOf() {
+        return this.value;
+    }
+    /** The message form: the canonical decimal, written as Java writes a float. */
+    toString() {
+        return floatMessageForm(this.value, this.width);
+    }
+    /** The observation of the float: its canonical decimal, or a tag where JSON cannot carry it. */
+    toJSON() {
+        return floatJson(this.value, this.width);
+    }
+}
+/**
+ * A float as the Raoh Specification observes it: its canonical decimal as a JSON number, or a
+ * tag, `{"float": "-0"}`, `{"float": "NaN"}`, `{"float": "+Infinity"}` or
+ * `{"float": "-Infinity"}`, where JSON cannot carry it.
+ */
+export function floatJson(value, width) {
+    if (Number.isNaN(value))
+        return { float: "NaN" };
+    if (value === Infinity)
+        return { float: "+Infinity" };
+    if (value === -Infinity)
+        return { float: "-Infinity" };
+    if (Object.is(value, -0))
+        return { float: "-0" };
+    return new JsonNumber(value === 0 ? "0" : floatMessageForm(value, width));
+}
+/**
+ * The float of the given width nearest to ±coefficient × 10^exponent, rounding to nearest with
+ * ties to even, once: `Infinity` (with the sign) where it rounds beyond the largest finite value.
+ * The number is read exactly, so a float32 is not rounded through a binary64 first.
+ */
+export function nearestFloat(negative, coefficient, exponent, width) {
+    const sign = negative ? -1 : 1;
+    if (coefficient === 0n) {
+        return negative ? -0 : 0;
+    }
+    // Clinger's fast path: an integer below 2^53 and a power of ten up to 10^22 are both exact
+    // binary64 values, so one multiplication or division rounds the number once.
+    if (width === 64 && coefficient < EXACT_INTEGER && exponent >= -22 && exponent <= 22) {
+        const digits = Number(coefficient);
+        const power = POWERS_OF_TEN[Math.abs(exponent)];
+        return sign * (exponent >= 0 ? digits * power : digits / power);
+    }
+    // Far enough beyond either end of binary64 that the answer is known without the arithmetic.
+    const magnitude = coefficient.toString().length - 1 + exponent;
+    if (magnitude > 400) {
+        return sign * Infinity;
+    }
+    if (magnitude < -400) {
+        return negative ? -0 : 0;
+    }
+    let numerator = coefficient;
+    let denominator = 1n;
+    if (exponent >= 0) {
+        numerator *= 10n ** BigInt(exponent);
+    }
+    else {
+        denominator = 10n ** BigInt(-exponent);
+    }
+    const { precision, minExponent, maxExponent } = FORMATS[width];
+    // The binary exponent of the leading bit: 2^e <= numerator / denominator < 2^(e+1).
+    let e = bitLength(numerator) - bitLength(denominator);
+    if (compareWithPowerOfTwo(numerator, denominator, e) < 0) {
+        e -= 1;
+    }
+    let shift = Math.max(e, minExponent) - (precision - 1);
+    let n = numerator;
+    let d = denominator;
+    if (shift >= 0) {
+        d <<= BigInt(shift);
+    }
+    else {
+        n <<= BigInt(-shift);
+    }
+    let mantissa = n / d;
+    const twice = 2n * (n - mantissa * d);
+    if (twice > d || (twice === d && (mantissa & 1n) === 1n)) {
+        mantissa += 1n;
+    }
+    if (mantissa === 1n << BigInt(precision)) {
+        mantissa >>= 1n;
+        shift += 1;
+    }
+    if (bitLength(mantissa) - 1 + shift > maxExponent) {
+        return sign * Infinity;
+    }
+    return sign * Number(mantissa) * 2 ** shift;
+}
+/**
+ * The canonical decimal of a finite, non-zero float as `digits × 10^exponent`, with no trailing
+ * zero in `digits`: the decimal of the least length that rounds to the float, the one closest to
+ * it, ties going to the even coefficient; where one digit is enough, the closest decimal of one or
+ * two digits, so that the least float64 is `4.9E-324` rather than `5E-324`.
+ */
+export function canonicalDecimal(value, width) {
+    const magnitude = Math.abs(value);
+    const [numerator, denominator] = exactly(magnitude);
+    let leading = Math.floor(Math.log10(magnitude));
+    // log10 is near enough to be off by one at most; settle it exactly.
+    while (compareWithPowerOfTen(numerator, denominator, leading) < 0) {
+        leading -= 1;
+    }
+    while (compareWithPowerOfTen(numerator, denominator, leading + 1) >= 0) {
+        leading += 1;
+    }
+    for (let length = 1; length <= 17; length += 1) {
+        const grid = leading - length + 1;
+        const coefficient = nearestOnGrid(numerator, denominator, grid);
+        if (nearestFloat(false, coefficient, grid, width) !== magnitude) {
+            continue;
+        }
+        if (length > 1) {
+            return stripped(coefficient, grid);
+        }
+        // One digit reaches the float, so two may come closer, and the closest of those is
+        // as close as any decimal of one or two digits.
+        return stripped(nearestOnGrid(numerator, denominator, grid - 1), grid - 1);
+    }
+    throw new Error(`no decimal of up to 17 digits rounds to ${value}`);
+}
+/**
+ * The message form of a float: its canonical decimal, plain with at least one digit after the
+ * point where the first digit's exponent is from -3 to 6, and otherwise one digit, a point, the
+ * others (at least one), `E` and the exponent; `0.0`, `-0.0`, `NaN`, `Infinity`, `-Infinity`.
+ */
+export function floatMessageForm(value, width) {
+    if (Number.isNaN(value)) {
+        return "NaN";
+    }
+    if (value === Infinity) {
+        return "Infinity";
+    }
+    if (value === -Infinity) {
+        return "-Infinity";
+    }
+    if (value === 0) {
+        return Object.is(value, -0) ? "-0.0" : "0.0";
+    }
+    const sign = value < 0 ? "-" : "";
+    const { digits, exponent } = canonicalDecimal(value, width);
+    const first = exponent + digits.length - 1;
+    if (first < -3 || first > 6) {
+        return `${sign}${digits[0]}.${digits.slice(1) || "0"}E${first}`;
+    }
+    if (exponent >= 0) {
+        return `${sign}${digits}${"0".repeat(exponent)}.0`;
+    }
+    const point = digits.length + exponent;
+    if (point > 0) {
+        return `${sign}${digits.slice(0, point)}.${digits.slice(point)}`;
+    }
+    return `${sign}0.${"0".repeat(-point)}${digits}`;
+}
+/**
+ * -1, 0 or 1 as `a` comes before, with or after `b` in the float order of the value model: -∞,
+ * the negative values, -0, +0, the positive values, +∞, and last NaN.
+ */
+export function compareFloats(a, b) {
+    const aNaN = Number.isNaN(a);
+    const bNaN = Number.isNaN(b);
+    if (aNaN || bNaN) {
+        return aNaN === bNaN ? 0 : aNaN ? 1 : -1;
+    }
+    if (a !== b) {
+        return a < b ? -1 : 1;
+    }
+    if (a === 0) {
+        const aNegative = Object.is(a, -0);
+        return aNegative === Object.is(b, -0) ? 0 : aNegative ? -1 : 1;
+    }
+    return 0;
+}
+/** Whether the two are the same float: +0 and -0 differ, and NaN is NaN. */
+export function sameFloat(a, b) {
+    return Object.is(a, b);
+}
+function bitLength(n) {
+    return n === 0n ? 0 : n.toString(2).length;
+}
+/** The sign of numerator / denominator - 2^e. */
+function compareWithPowerOfTwo(numerator, denominator, e) {
+    const left = e >= 0 ? numerator : numerator << BigInt(-e);
+    const right = e >= 0 ? denominator << BigInt(e) : denominator;
+    return left < right ? -1 : left > right ? 1 : 0;
+}
+/** The sign of numerator / denominator - 10^e. */
+function compareWithPowerOfTen(numerator, denominator, e) {
+    const left = e >= 0 ? numerator : numerator * 10n ** BigInt(-e);
+    const right = e >= 0 ? denominator * 10n ** BigInt(e) : denominator;
+    return left < right ? -1 : left > right ? 1 : 0;
+}
+/** A finite, positive binary64 as an exact fraction. */
+function exactly(magnitude) {
+    const view = new DataView(new ArrayBuffer(8));
+    view.setFloat64(0, magnitude);
+    const bits = view.getBigUint64(0);
+    const biased = Number((bits >> 52n) & 0x7ffn);
+    const fraction = bits & ((1n << 52n) - 1n);
+    const mantissa = biased === 0 ? fraction : fraction | (1n << 52n);
+    const exponent = (biased === 0 ? 1 : biased) - 1075;
+    return exponent >= 0 ? [mantissa << BigInt(exponent), 1n] : [mantissa, 1n << BigInt(-exponent)];
+}
+/** The integer nearest numerator / (denominator × 10^grid), ties to even. */
+function nearestOnGrid(numerator, denominator, grid) {
+    let n = numerator;
+    let d = denominator;
+    if (grid >= 0) {
+        d *= 10n ** BigInt(grid);
+    }
+    else {
+        n *= 10n ** BigInt(-grid);
+    }
+    let q = n / d;
+    const twice = 2n * (n - q * d);
+    if (twice > d || (twice === d && (q & 1n) === 1n)) {
+        q += 1n;
+    }
+    return q;
+}
+function stripped(coefficient, exponent) {
+    let digits = coefficient.toString();
+    while (digits.length > 1 && digits.endsWith("0")) {
+        digits = digits.slice(0, -1);
+        exponent += 1;
+    }
+    return { digits, exponent };
+}

package/dist/index.d.ts

@@ -0,0 +1,13 @@
+export { Decimal } from "./decimal.ts";
+export { Chain, Decoder, type Run, decoder, nullable, recover, recoverWith, withDefault } from "./decoder.ts";
+export * as encode from "./encode.ts";
+export { Float, type Width } from "./float.ts";
+export { JsonNumber, type Kind, kindOf, parse, stringify } from "./input.ts";
+export { Issue, type IssueInit, Issues, type Failed, type Ok, type Result, failed, ok } from "./issue.ts";
+export { INVALID_FORMAT_JSON, type MessageResolver, Messages } from "./messages.ts";
+export { messageForm, same } from "./meta.ts";
+export { Path, type Segment } from "./path.ts";
+export { BoolDecoder, BoundedDecoder, DecimalDecoder, DoubleDecoder, FloatDecoder, IntDecoder, LongDecoder, StringDecoder, bool, decimal, double, float, int, long, string, } from "./scalars.ts";
+export { ValueSet } from "./set.ts";
+export { type IssueWire, issueWire, type Wire } from "./wire.ts";
+export { ABSENT, DictDecoder, Field, ListDecoder, NULL, ObjectDecoder, type Presence, type ReadWith, dict, discriminate, discriminateBy, enumOf, field, flat, list, literal, object, oneOf, optionalField, optionalNullableField, presentWith, strict, } from "./structure.ts";

package/dist/index.js

@@ -0,0 +1,14 @@
+// Raoh for TypeScript: decoders that turn untyped boundary input into typed domain values.
+export { Decimal } from "./decimal.js";
+export { Chain, Decoder, decoder, nullable, recover, recoverWith, withDefault } from "./decoder.js";
+export * as encode from "./encode.js";
+export { Float } from "./float.js";
+export { JsonNumber, kindOf, parse, stringify } from "./input.js";
+export { Issue, Issues, failed, ok } from "./issue.js";
+export { INVALID_FORMAT_JSON, Messages } from "./messages.js";
+export { messageForm, same } from "./meta.js";
+export { Path } from "./path.js";
+export { BoolDecoder, BoundedDecoder, DecimalDecoder, DoubleDecoder, FloatDecoder, IntDecoder, LongDecoder, StringDecoder, bool, decimal, double, float, int, long, string, } from "./scalars.js";
+export { ValueSet } from "./set.js";
+export { issueWire } from "./wire.js";
+export { ABSENT, DictDecoder, Field, ListDecoder, NULL, ObjectDecoder, dict, discriminate, discriminateBy, enumOf, field, flat, list, literal, object, oneOf, optionalField, optionalNullableField, presentWith, strict, } from "./structure.js";

package/dist/input.d.ts

@@ -0,0 +1,78 @@
+/** A number of the input model: the text it is written with. */
+export declare class JsonNumber {
+    readonly lexeme: string;
+    constructor(lexeme: string);
+    get [Symbol.toStringTag](): string;
+    toString(): string;
+    /**
+     * The number for `JSON.stringify` to write as this text. Where the engine has no
+     * `JSON.rawJSON`, a JavaScript number is given in its place only where the text it is written
+     * as denotes the same number; for one it would change, such as an integer beyond 2^53, this
+     * throws rather than write another number.
+     */
+    toJSON(): unknown;
+}
+/** The kinds of value of the input model, and `missing` for no value at all. */
+export type Kind = "null" | "boolean" | "number" | "string" | "array" | "object" | "missing";
+/**
+ * The kind of `value`, as an issue's `actual` names it.
+ *
+ * This is where a JavaScript value is read as a value of the input model, for a decoder and for
+ * {@link stringify} alike. A string is one only where it is a sequence of Unicode scalar values;
+ * an object is a `Map` of string keys, or an object whose data are its own properties, plain or an
+ * instance of a class of the program's. A value that holds its data elsewhere — a `Date`, a `Set`,
+ * a `String` or `Number` object, a typed array, a function — is no value of the input model, and
+ * reading it as an object of no members, or of its characters, would read something it is not.
+ *
+ * @throws {TypeError} for a value that is no value of the input model
+ */
+export declare function kindOf(value: unknown): Kind;
+/**
+ * The elements of an array of the input model, in order.
+ *
+ * @throws {TypeError} for an array with a hole, a place no value is at, which no JSON text writes
+ */
+export declare function elementsOf(value: readonly unknown[]): unknown[];
+/** Whether `value` is an object of the input model. */
+export declare function isObject(value: unknown): value is object;
+/**
+ * The lexeme of a number of the input model; `undefined` for a JavaScript number that no JSON
+ * text writes (NaN or an infinity). An integer is written in full, as `BigInt` writes it, so that
+ * 1e21 read by `JSON.parse` is still an integer to an integer decoder. A `Decimal` is written at its
+ * scale, so that `decimal()` reads back the decimal it is, trailing zeros and all.
+ */
+export declare function lexemeOf(value: unknown): string | undefined;
+/**
+ * The members of an object of the input model, in order; a member whose value is `undefined` is
+ * absent.
+ *
+ * @throws {TypeError} for a `Map` with a key that is not a string, and for a name that is not a
+ *   sequence of Unicode scalar values: no JSON text names a member so
+ */
+export declare function membersOf(value: object): [string, unknown][];
+/** The member of an object of the input model, or `undefined` where it is absent. */
+export declare function memberOf(value: object, name: string): unknown;
+/**
+ * Reads a JSON text (RFC 8259) into the input model: every number a {@link JsonNumber} holding its
+ * lexeme, and every object a `Map` holding its members in the order written.
+ *
+ * @throws {SyntaxError} where the text is not JSON, an object repeats a member name, or a string
+ *   holds an unpaired surrogate, none of which is in the input model
+ */
+export declare function parse(text: string): unknown;
+/**
+ * Writes a value of the input model as JSON text, as {@link parse} reads it back: every number as
+ * its lexeme, and every object's members in their order, a `Map`'s as it holds them. This is how
+ * a value is handed on to what reads JSON text and not JavaScript values, such as a module across
+ * a boundary, without a number rounded or a member moved: `JSON.stringify` writes a `Map` as `{}`
+ * and an object's integer-like member names before its others.
+ *
+ * What it writes, `parse` reads, as the value it was: a value is read as {@link kindOf} reads one,
+ * the same way a decoder reads it, so what the input model has no place for is refused here rather
+ * than written as text `parse` refuses or as some other value.
+ *
+ * @throws {TypeError} for `undefined` where a value has to be, a hole in an array, a number that is
+ *   NaN or an infinity, a string or member name holding an unpaired surrogate, and any value that
+ *   is no value of the input model
+ */
+export declare function stringify(value: unknown): string;