@raoh/core 0.9.0-dev.15.20261004151401.ge5893e0cc07d

package/dist/decimal.js

@@ -0,0 +1,148 @@
+// A decimal number that keeps the scale it was written with.
+import { tagOf } from "./copy.js";
+const NUMBER = /^([+-]?)([0-9]+)(?:\.([0-9]*))?(?:[eE]([+-]?[0-9]+))?$|^([+-]?)\.([0-9]+)(?:[eE]([+-]?[0-9]+))?$/;
+const INT32_MIN = -(2 ** 31);
+const INT32_MAX = 2 ** 31 - 1;
+/**
+ * A coefficient and a scale: the number coefficient × 10^-scale.
+ *
+ * Two decimals are the same value only when both are equal, so 1.5 and 1.50 are different values;
+ * {@link Decimal.compare} orders them by the number they denote, in which they are equal. The
+ * scale is an int32, as the value model's is.
+ */
+export class Decimal {
+    coefficient;
+    scale;
+    constructor(coefficient, scale) {
+        if (!Number.isInteger(scale) || scale < INT32_MIN || scale > INT32_MAX) {
+            throw new RangeError(`a decimal's scale is an int32, not ${scale}`);
+        }
+        this.coefficient = coefficient;
+        this.scale = scale;
+    }
+    /**
+     * The decimal a number written as `[+-]?(digits[.digits]|.digits)([eE][+-]?digits)?` denotes,
+     * at the scale it is written with: the digits after the point, less the exponent. `undefined`
+     * where the text is not such a number, or its scale is not an int32.
+     */
+    static parse(text) {
+        const read = NUMBER.exec(text);
+        if (read === null) {
+            return undefined;
+        }
+        const [, sign1, whole1, fraction1, exponent1, sign2, fraction2, exponent2] = read;
+        const sign = sign1 ?? sign2 ?? "";
+        const whole = whole1 ?? "";
+        const fraction = fraction1 ?? fraction2 ?? "";
+        const exponent = exponent1 ?? exponent2;
+        const exponentValue = exponent === undefined ? 0 : Number(exponent);
+        const scale = fraction.length - exponentValue;
+        if (!Number.isSafeInteger(exponentValue) || scale < INT32_MIN || scale > INT32_MAX) {
+            return undefined;
+        }
+        const magnitude = BigInt(whole + fraction);
+        return new Decimal(sign === "-" ? -magnitude : magnitude, scale);
+    }
+    get [Symbol.toStringTag]() {
+        return tagOf("Decimal");
+    }
+    /** The decimal of an integer, at scale 0. */
+    static of(value) {
+        return new Decimal(BigInt(value), 0);
+    }
+    /** -1, 0 or 1 as this denotes a number less than, equal to or greater than `other`'s. */
+    compare(other) {
+        if (this.signum !== other.signum) {
+            return this.signum < other.signum ? -1 : 1;
+        }
+        if (this.signum === 0) {
+            return 0;
+        }
+        // Of two numbers of one sign whose first digits stand at different powers of ten, the one
+        // whose first digit stands higher is the larger in magnitude. Settling that first keeps
+        // 1E+999999999 and 1E-999999999 from being brought to one scale.
+        const above = adjustedExponent(this) - adjustedExponent(other);
+        if (above !== 0) {
+            return above > 0 === this.signum > 0 ? 1 : -1;
+        }
+        const [a, b] = aligned(this, other);
+        return a < b ? -1 : a > b ? 1 : 0;
+    }
+    /** Whether the two are the same value: the same coefficient and the same scale. */
+    equals(other) {
+        return this.coefficient === other.coefficient && this.scale === other.scale;
+    }
+    /** -1, 0 or 1 as the number is negative, zero or positive. */
+    get signum() {
+        return this.coefficient < 0n ? -1 : this.coefficient > 0n ? 1 : 0;
+    }
+    /** Whether this is an integer multiple of `divisor`, which is not zero. */
+    isMultipleOf(divisor) {
+        if (this.coefficient === 0n) {
+            return true;
+        }
+        // An integer times the divisor has no more digits after the point than the divisor has, once
+        // neither carries trailing zeros.
+        const value = stripped(this);
+        const by = stripped(divisor);
+        if (value.scale > by.scale) {
+            return false;
+        }
+        // value / divisor = value's coefficient × 10^n / divisor's, for n the difference of the
+        // scales. Past the divisor's own count of 2s and 5s, which its bit length bounds, a further
+        // factor of 10 decides nothing, so n is taken no larger than that: 7E-2147483647 does not
+        // make a power of ten with two billion digits.
+        const divisorDigits = by.coefficient < 0n ? -by.coefficient : by.coefficient;
+        const n = Math.min(by.scale - value.scale, divisorDigits.toString(2).length);
+        return (value.coefficient * 10n ** BigInt(n)) % by.coefficient === 0n;
+    }
+    /**
+     * The decimal as Java's `BigDecimal.toString` writes it, which is the message form the Raoh
+     * Specification gives: plain where the scale is not negative and the first digit's exponent is
+     * at least -6, and otherwise one digit before the point and an exponent (`1E+3`, `1.5E-7`).
+     */
+    toString() {
+        const digits = (this.coefficient < 0n ? -this.coefficient : this.coefficient).toString();
+        const sign = this.coefficient < 0n ? "-" : "";
+        const adjusted = digits.length - 1 - this.scale;
+        if (this.scale >= 0 && adjusted >= -6) {
+            if (this.scale === 0) {
+                return sign + digits;
+            }
+            if (digits.length > this.scale) {
+                const point = digits.length - this.scale;
+                return `${sign}${digits.slice(0, point)}.${digits.slice(point)}`;
+            }
+            return `${sign}0.${"0".repeat(this.scale - digits.length)}${digits}`;
+        }
+        const mantissa = digits.length > 1 ? `${digits[0]}.${digits.slice(1)}` : digits;
+        return `${sign}${mantissa}E${adjusted >= 0 ? "+" : "-"}${Math.abs(adjusted)}`;
+    }
+    toJSON() {
+        return this.toString();
+    }
+}
+/** The exponent of the first digit: 2 for 123, -1 for 0.5, 2 for 1.5E+2. */
+function adjustedExponent(decimal) {
+    const digits = decimal.coefficient < 0n ? -decimal.coefficient : decimal.coefficient;
+    return digits.toString().length - 1 - decimal.scale;
+}
+/** The same number with no trailing zeros in its coefficient. */
+function stripped(decimal) {
+    let { coefficient, scale } = decimal;
+    while (coefficient !== 0n && coefficient % 10n === 0n) {
+        coefficient /= 10n;
+        scale -= 1;
+    }
+    return { coefficient, scale };
+}
+/** The two coefficients brought to the larger scale, so that they compare as the numbers do. */
+function aligned(a, b) {
+    if (a.scale === b.scale) {
+        return [a.coefficient, b.coefficient];
+    }
+    if (a.scale > b.scale) {
+        return [a.coefficient, b.coefficient * 10n ** BigInt(a.scale - b.scale)];
+    }
+    return [a.coefficient * 10n ** BigInt(b.scale - a.scale), b.coefficient];
+}

package/dist/decoder.d.ts

@@ -0,0 +1,83 @@
+import { Issue, Issues, type Result } from "./issue.ts";
+import { Path } from "./path.ts";
+/** How a decoder reads an input at a path. */
+export type Run<T> = (input: unknown, path: Path) => Result<T>;
+/**
+ * Reads a value of the input model into a `T`, or says everything that kept it from being one.
+ *
+ * What a decoder gives depends on the input alone, so a decoder can be kept and shared. An absent
+ * value is `undefined`: a missing member of an object is handed to its decoder as `undefined`,
+ * and decoders tell it from `null` where they say so.
+ */
+export declare abstract class Decoder<T> {
+    /** Reads `input`, which is at `path` in what is being decoded; every issue is at a path below it. */
+    abstract decodeAt(input: unknown, path: Path): Result<T>;
+    /**
+     * A value this decoder gives, as an issue's metadata holds it. A float decoder's value is held
+     * with its width, so that the message writes it as a float of that width; every other value is
+     * held as it is.
+     */
+    metaValue(value: T): unknown;
+    /** Reads `input` as the whole of what is being decoded. */
+    decode(input: unknown): Result<T>;
+    /**
+     * Reads a JSON text: its numbers as written, its members in order. Text that is not JSON gives
+     * `invalid_format` under the message key `invalid_format.json`, at the root.
+     */
+    decodeJson(text: string): Result<T>;
+    /** A decoder giving what `f` makes of this one's value. */
+    map<U>(f: (value: T) => U): Decoder<U>;
+    /**
+     * A decoder giving what `f` makes of this one's value, which may be a failure: a rule that
+     * relates the parts of a value, checked once they exist. The paths of the issues `f` gives are
+     * read as relative to where this decoder is.
+     */
+    flatMap<U>(f: (value: T) => Result<U>): Decoder<U>;
+    /**
+     * This decoder, failing with `issue` where `predicate` does not hold of its value. The issue is
+     * given at this decoder's path, or below it where it has a path of its own.
+     */
+    refine(predicate: (value: T) => boolean, issue: Issue | ((value: T) => Issue)): Decoder<T>;
+    /** A decoder giving `null` for a JSON null, and reading anything else, absence included, with this one. */
+    nullable(): Decoder<T | null>;
+    /** A decoder giving `fallback` for a JSON null or an absent value, and reading anything else with this one. */
+    withDefault(fallback: T): Decoder<T>;
+    /** This decoder, giving `fallback` instead of any failure. */
+    recover(fallback: T): Decoder<T>;
+    /** This decoder, giving what `f` makes of the issues instead of any failure. */
+    recoverWith(f: (issues: Issues) => T): Decoder<T>;
+}
+/** A decoder that reads as `run` does. */
+export declare function decoder<T>(run: Run<T>): Decoder<T>;
+/**
+ * A decoder made of how it reads, to which checks are added one after another: each runs only
+ * where everything before it succeeded, and the decoder it makes is of the same class, so that
+ * the checks of that class can follow it.
+ */
+export declare class Chain<T> extends Decoder<T> {
+    #private;
+    constructor(run: Run<T>);
+    decodeAt(input: unknown, path: Path): Result<T>;
+    /** A decoder of this class that reads as `run` does. */
+    protected derive(run: Run<T>): this;
+    /**
+     * This decoder, then `test` of its value: the issue it gives, at this decoder's path, with
+     * `message` as its sentence where one is given.
+     */
+    protected check(test: (value: T) => Issue | undefined, message?: string): this;
+    /** How this decoder reads, then `test` of its value. */
+    protected then(test: (value: T) => Issue | undefined, message?: string): Run<T>;
+    /**
+     * How this decoder reads, then what `f` makes of its value: the issues it gives at this
+     * decoder's path, each with `message` as its sentence where one is given.
+     */
+    protected convert<U>(f: (value: T) => Result<U>, message?: string): Run<U>;
+}
+/** A decoder giving `null` for a JSON null, and reading anything else, absence included, with `inner`. */
+export declare function nullable<T>(inner: Decoder<T>): Decoder<T | null>;
+/** A decoder giving `fallback` for a JSON null or an absent value, and reading anything else with `inner`. */
+export declare function withDefault<T>(inner: Decoder<T>, fallback: T): Decoder<T>;
+/** `inner`, giving `fallback` instead of any failure. */
+export declare function recover<T>(inner: Decoder<T>, fallback: T): Decoder<T>;
+/** `inner`, giving what `f` makes of the issues instead of any failure. */
+export declare function recoverWith<T>(inner: Decoder<T>, f: (issues: Issues) => T): Decoder<T>;

package/dist/decoder.js

@@ -0,0 +1,178 @@
+// A value that describes how to read an input, and the ways decoders compose.
+import { parse } from "./input.js";
+import { Issue, Issues, failed, ok } from "./issue.js";
+import { INVALID_FORMAT_JSON } from "./messages.js";
+import { Path } from "./path.js";
+/**
+ * Reads a value of the input model into a `T`, or says everything that kept it from being one.
+ *
+ * What a decoder gives depends on the input alone, so a decoder can be kept and shared. An absent
+ * value is `undefined`: a missing member of an object is handed to its decoder as `undefined`,
+ * and decoders tell it from `null` where they say so.
+ */
+export class Decoder {
+    /**
+     * A value this decoder gives, as an issue's metadata holds it. A float decoder's value is held
+     * with its width, so that the message writes it as a float of that width; every other value is
+     * held as it is.
+     */
+    metaValue(value) {
+        return value;
+    }
+    /** Reads `input` as the whole of what is being decoded. */
+    decode(input) {
+        return this.decodeAt(input, Path.ROOT);
+    }
+    /**
+     * Reads a JSON text: its numbers as written, its members in order. Text that is not JSON gives
+     * `invalid_format` under the message key `invalid_format.json`, at the root.
+     */
+    decodeJson(text) {
+        let input;
+        try {
+            input = parse(text);
+        }
+        catch (e) {
+            if (e instanceof SyntaxError) {
+                return failed(new Issue("invalid_format", { messageKey: INVALID_FORMAT_JSON }));
+            }
+            throw e;
+        }
+        return this.decode(input);
+    }
+    /** A decoder giving what `f` makes of this one's value. */
+    map(f) {
+        return decoder((input, path) => {
+            const read = this.decodeAt(input, path);
+            return read.issues === undefined ? ok(f(read.value)) : read;
+        });
+    }
+    /**
+     * A decoder giving what `f` makes of this one's value, which may be a failure: a rule that
+     * relates the parts of a value, checked once they exist. The paths of the issues `f` gives are
+     * read as relative to where this decoder is.
+     */
+    flatMap(f) {
+        return decoder((input, path) => {
+            const read = this.decodeAt(input, path);
+            if (read.issues !== undefined) {
+                return read;
+            }
+            const made = f(read.value);
+            return made.issues === undefined ? made : failed(made.issues.under(path));
+        });
+    }
+    /**
+     * This decoder, failing with `issue` where `predicate` does not hold of its value. The issue is
+     * given at this decoder's path, or below it where it has a path of its own.
+     */
+    refine(predicate, issue) {
+        return this.flatMap((value) => (predicate(value) ? ok(value) : failed(typeof issue === "function" ? issue(value) : issue)));
+    }
+    /** A decoder giving `null` for a JSON null, and reading anything else, absence included, with this one. */
+    nullable() {
+        return nullable(this);
+    }
+    /** A decoder giving `fallback` for a JSON null or an absent value, and reading anything else with this one. */
+    withDefault(fallback) {
+        return withDefault(this, fallback);
+    }
+    /** This decoder, giving `fallback` instead of any failure. */
+    recover(fallback) {
+        return recover(this, fallback);
+    }
+    /** This decoder, giving what `f` makes of the issues instead of any failure. */
+    recoverWith(f) {
+        return recoverWith(this, f);
+    }
+}
+/** A decoder that reads as `run` does. */
+export function decoder(run) {
+    return new Chain(run);
+}
+/**
+ * A decoder made of how it reads, to which checks are added one after another: each runs only
+ * where everything before it succeeded, and the decoder it makes is of the same class, so that
+ * the checks of that class can follow it.
+ */
+export class Chain extends Decoder {
+    #run;
+    constructor(run) {
+        super();
+        this.#run = run;
+    }
+    decodeAt(input, path) {
+        return this.#run(input, path);
+    }
+    /** A decoder of this class that reads as `run` does. */
+    derive(run) {
+        return new this.constructor(run);
+    }
+    /**
+     * This decoder, then `test` of its value: the issue it gives, at this decoder's path, with
+     * `message` as its sentence where one is given.
+     */
+    check(test, message) {
+        return this.derive(this.then(test, message));
+    }
+    /** How this decoder reads, then `test` of its value. */
+    then(test, message) {
+        return this.convert((value) => {
+            const issue = test(value);
+            return issue === undefined ? ok(value) : failed(issue);
+        }, message);
+    }
+    /**
+     * How this decoder reads, then what `f` makes of its value: the issues it gives at this
+     * decoder's path, each with `message` as its sentence where one is given.
+     */
+    convert(f, message) {
+        return (input, path) => {
+            const read = this.decodeAt(input, path);
+            if (read.issues !== undefined) {
+                return read;
+            }
+            const made = f(read.value);
+            if (made.issues === undefined) {
+                return made;
+            }
+            const issues = message === undefined ? made.issues.list : made.issues.list.map((issue) => issue.withMessage(message));
+            return failed(new Issues(issues).under(path));
+        };
+    }
+}
+/** A decoder that reads as `run` does and gives values of `inner`'s kind, which it holds as metadata as `inner` does. */
+class Around extends Decoder {
+    #run;
+    #inner;
+    constructor(inner, run) {
+        super();
+        this.#inner = inner;
+        this.#run = run;
+    }
+    decodeAt(input, path) {
+        return this.#run(input, path);
+    }
+    metaValue(value) {
+        return value === null || value === undefined ? value : this.#inner.metaValue(value);
+    }
+}
+/** A decoder giving `null` for a JSON null, and reading anything else, absence included, with `inner`. */
+export function nullable(inner) {
+    return new Around(inner, (input, path) => (input === null ? ok(null) : inner.decodeAt(input, path)));
+}
+/** A decoder giving `fallback` for a JSON null or an absent value, and reading anything else with `inner`. */
+export function withDefault(inner, fallback) {
+    return new Around(inner, (input, path) => input === null || input === undefined ? ok(fallback) : inner.decodeAt(input, path));
+}
+/** `inner`, giving `fallback` instead of any failure. */
+export function recover(inner, fallback) {
+    return recoverWith(inner, () => fallback);
+}
+/** `inner`, giving what `f` makes of the issues instead of any failure. */
+export function recoverWith(inner, f) {
+    return new Around(inner, (input, path) => {
+        const read = inner.decodeAt(input, path);
+        return read.issues === undefined ? read : ok(f(read.issues));
+    });
+}

package/dist/encode.d.ts

@@ -0,0 +1,28 @@
+/** A value JSON can carry. */
+export type Json = null | boolean | number | string | readonly Json[] | {
+    readonly [member: string]: Json;
+};
+/** Writes a `T` as JSON. */
+export interface Encoder<T> {
+    encode(value: T): Json;
+}
+/** An encoder writing a string as a JSON string. */
+export declare function string(): Encoder<string>;
+/** One member of an object encoder: its name, and what it writes for a value. */
+export interface Property<T> {
+    readonly name: string;
+    write(value: T): Json;
+}
+/** A member `name` holding what `encoder` writes of what `getter` reads of the value. */
+export declare function property<T, P>(name: string, getter: (value: T) => P, encoder: Encoder<P>): Property<T>;
+/**
+ * A member `name` holding what `encoder` writes of what `getter` reads of the value, or of
+ * `fallback` where it reads null or undefined.
+ */
+export declare function propertyWithDefault<T, P>(name: string, getter: (value: T) => P | null | undefined, encoder: Encoder<P>, fallback: P): Property<T>;
+/**
+ * An encoder writing a JSON object with one member per property, in the order declared.
+ *
+ * @throws {RangeError} where two properties write the same member
+ */
+export declare function object<T>(...properties: readonly Property<T>[]): Encoder<T>;

package/dist/encode.js

@@ -0,0 +1,45 @@
+// Encoders: writing a value as JSON.
+/** An encoder writing a string as a JSON string. */
+export function string() {
+    return { encode: (value) => value };
+}
+/** A member `name` holding what `encoder` writes of what `getter` reads of the value. */
+export function property(name, getter, encoder) {
+    return { name, write: (value) => encoder.encode(getter(value)) };
+}
+/**
+ * A member `name` holding what `encoder` writes of what `getter` reads of the value, or of
+ * `fallback` where it reads null or undefined.
+ */
+export function propertyWithDefault(name, getter, encoder, fallback) {
+    return {
+        name,
+        write: (value) => {
+            const read = getter(value);
+            return encoder.encode(read === null || read === undefined ? fallback : read);
+        },
+    };
+}
+/**
+ * An encoder writing a JSON object with one member per property, in the order declared.
+ *
+ * @throws {RangeError} where two properties write the same member
+ */
+export function object(...properties) {
+    const names = new Set();
+    for (const { name } of properties) {
+        if (names.has(name)) {
+            throw new RangeError(`two properties write the member ${JSON.stringify(name)}`);
+        }
+        names.add(name);
+    }
+    return {
+        encode: (value) => {
+            const out = {};
+            for (const p of properties) {
+                Object.defineProperty(out, p.name, { value: p.write(value), enumerable: true, writable: true, configurable: true });
+            }
+            return out;
+        },
+    };
+}

package/dist/float.d.ts

@@ -0,0 +1,58 @@
+import { JsonNumber } from "./input.ts";
+/** The width of a float: binary32 or binary64. */
+export type Width = 32 | 64;
+/**
+ * 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 declare class Float {
+    readonly value: number;
+    readonly width: Width;
+    constructor(value: number, width: Width);
+    get [Symbol.toStringTag](): string;
+    valueOf(): number;
+    /** The message form: the canonical decimal, written as Java writes a float. */
+    toString(): string;
+    /** The observation of the float: its canonical decimal, or a tag where JSON cannot carry it. */
+    toJSON(): JsonNumber | {
+        float: string;
+    };
+}
+/**
+ * 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 declare function floatJson(value: number, width: Width): JsonNumber | {
+    float: string;
+};
+/**
+ * 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 declare function nearestFloat(negative: boolean, coefficient: bigint, exponent: number, width: Width): number;
+/**
+ * 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 declare function canonicalDecimal(value: number, width: Width): {
+    digits: string;
+    exponent: number;
+};
+/**
+ * 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 declare function floatMessageForm(value: number, width: Width): string;
+/**
+ * -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 declare function compareFloats(a: number, b: number): number;
+/** Whether the two are the same float: +0 and -0 differ, and NaN is NaN. */
+export declare function sameFloat(a: number, b: number): boolean;