@raoh/core 0.9.0-dev.15.20261004151401.ge5893e0cc07d

package/dist/messages.d.ts

@@ -0,0 +1,59 @@
+import type { Issue } from "./issue.ts";
+/** Writes the sentence for an issue that carries no message of its own. */
+export interface MessageResolver {
+    resolve(issue: Issue): string;
+}
+/** The message key of an issue for text that is not JSON, which the specification leaves outside its input model. */
+export declare const INVALID_FORMAT_JSON = "invalid_format.json";
+/**
+ * A catalogue of message templates keyed by message key or code, over the catalogue it falls
+ * back to.
+ *
+ * A catalogue is a stack of layers, most specific first, as Raoh for Java reads a locale's
+ * `.properties` file before its parent's. An issue is looked up one layer at a time, by its
+ * message key and then by its code, and only when neither has a template does the next layer down
+ * get asked. So a layer that translates just `invalid_format` wins over a refined key such as
+ * `invalid_format.email` beneath it. A template's `{name}` placeholders are filled with the
+ * message forms of the issue's metadata; a placeholder naming an entry the metadata lacks stays as
+ * it is written. Where no layer has a template, the sentence is what the catalogue's fallback
+ * writes, `validation failed: <code>` unless one is given with {@link withFallback}.
+ */
+export declare class Messages implements MessageResolver {
+    #private;
+    private constructor();
+    /** The English catalogue of the Raoh Specification. Every issue's default message comes from it. */
+    static readonly english: Messages;
+    /** The Japanese catalogue of the Raoh Specification, over the English one. */
+    static readonly japanese: Messages;
+    /** A catalogue with no templates, in which every issue reads `validation failed: <code>`. */
+    static empty(): Messages;
+    /**
+     * The catalogue a `.properties` text holds, read as Java's `Properties.load` reads one, such as
+     * the `messages*.properties` of Raoh for Java: one `raoh.<key>=<template>` per entry, `\uXXXX`
+     * escapes and continued lines included. The `raoh.` prefix is optional. The catalogue falls
+     * back to nothing; give it one with {@link fallingBackTo}.
+     *
+     * @throws {SyntaxError} where a `\u` escape is malformed
+     */
+    static fromProperties(text: string): Messages;
+    /**
+     * The catalogue for a language tag, `ja` or `ja-JP` among them: Japanese for Japanese, and
+     * English for any other language.
+     */
+    static forLocale(locale: string): Messages;
+    /** This catalogue with `parent` beneath its last layer, as a locale's file sits over its parent's. */
+    fallingBackTo(parent: Messages): Messages;
+    /**
+     * This catalogue, writing what `fallback` writes for an issue no layer has a template for. It is
+     * how a host language gives the issues of its own, which no catalogue of Raoh's knows, the
+     * sentence it has for them, and still lets a catalogue that does have a template for one win.
+     */
+    withFallback(fallback: (issue: Issue) => string): Messages;
+    /** A layer of `overrides`, keyed by message key or code, over this catalogue. */
+    withOverrides(overrides: Readonly<Record<string, string>>): Messages;
+    /** The template the most specific layer holding `key` has, if one does. */
+    template(key: string): string | undefined;
+    /** Every key, and the template the most specific layer holding it has. */
+    templates(): Map<string, string>;
+    resolve(issue: Issue): string;
+}

package/dist/messages.js

@@ -0,0 +1,225 @@
+// Writing an issue's message in a person's language.
+import { CATALOG } from "./catalog.js";
+import { messageForm } from "./meta.js";
+/** The message key of an issue for text that is not JSON, which the specification leaves outside its input model. */
+export const INVALID_FORMAT_JSON = "invalid_format.json";
+/**
+ * A catalogue of message templates keyed by message key or code, over the catalogue it falls
+ * back to.
+ *
+ * A catalogue is a stack of layers, most specific first, as Raoh for Java reads a locale's
+ * `.properties` file before its parent's. An issue is looked up one layer at a time, by its
+ * message key and then by its code, and only when neither has a template does the next layer down
+ * get asked. So a layer that translates just `invalid_format` wins over a refined key such as
+ * `invalid_format.email` beneath it. A template's `{name}` placeholders are filled with the
+ * message forms of the issue's metadata; a placeholder naming an entry the metadata lacks stays as
+ * it is written. Where no layer has a template, the sentence is what the catalogue's fallback
+ * writes, `validation failed: <code>` unless one is given with {@link withFallback}.
+ */
+export class Messages {
+    #templates;
+    #parent;
+    #fallback;
+    constructor(templates, parent, fallback = undefined) {
+        this.#templates = templates;
+        this.#parent = parent;
+        this.#fallback = fallback;
+    }
+    /** The English catalogue of the Raoh Specification. Every issue's default message comes from it. */
+    static english = Messages.fromProperties(CATALOG.en).withOverrides({
+        [INVALID_FORMAT_JSON]: "not valid JSON",
+    });
+    /** The Japanese catalogue of the Raoh Specification, over the English one. */
+    static japanese = Messages.fromProperties(CATALOG.ja)
+        .withOverrides({ [INVALID_FORMAT_JSON]: "JSONとして読めません" })
+        .fallingBackTo(Messages.english);
+    /** A catalogue with no templates, in which every issue reads `validation failed: <code>`. */
+    static empty() {
+        return new Messages(new Map(), undefined);
+    }
+    /**
+     * The catalogue a `.properties` text holds, read as Java's `Properties.load` reads one, such as
+     * the `messages*.properties` of Raoh for Java: one `raoh.<key>=<template>` per entry, `\uXXXX`
+     * escapes and continued lines included. The `raoh.` prefix is optional. The catalogue falls
+     * back to nothing; give it one with {@link fallingBackTo}.
+     *
+     * @throws {SyntaxError} where a `\u` escape is malformed
+     */
+    static fromProperties(text) {
+        const templates = new Map();
+        for (const [key, template] of loadProperties(text)) {
+            templates.set(key.startsWith("raoh.") ? key.slice("raoh.".length) : key, template);
+        }
+        return new Messages(templates, undefined);
+    }
+    /**
+     * The catalogue for a language tag, `ja` or `ja-JP` among them: Japanese for Japanese, and
+     * English for any other language.
+     */
+    static forLocale(locale) {
+        const language = locale.split(/[-_]/)[0]?.toLowerCase();
+        return language === "ja" ? Messages.japanese : Messages.english;
+    }
+    /** This catalogue with `parent` beneath its last layer, as a locale's file sits over its parent's. */
+    fallingBackTo(parent) {
+        return new Messages(this.#templates, this.#parent === undefined ? parent : this.#parent.fallingBackTo(parent), this.#fallback);
+    }
+    /**
+     * This catalogue, writing what `fallback` writes for an issue no layer has a template for. It is
+     * how a host language gives the issues of its own, which no catalogue of Raoh's knows, the
+     * sentence it has for them, and still lets a catalogue that does have a template for one win.
+     */
+    withFallback(fallback) {
+        return new Messages(this.#templates, this.#parent, fallback);
+    }
+    /** A layer of `overrides`, keyed by message key or code, over this catalogue. */
+    withOverrides(overrides) {
+        return new Messages(new Map(Object.entries(overrides)), this);
+    }
+    /** The template the most specific layer holding `key` has, if one does. */
+    template(key) {
+        for (let layer = this; layer !== undefined; layer = layer.#parent) {
+            const template = layer.#templates.get(key);
+            if (template !== undefined) {
+                return template;
+            }
+        }
+        return undefined;
+    }
+    /** Every key, and the template the most specific layer holding it has. */
+    templates() {
+        const out = new Map();
+        for (let layer = this; layer !== undefined; layer = layer.#parent) {
+            for (const [key, template] of layer.#templates) {
+                if (!out.has(key)) {
+                    out.set(key, template);
+                }
+            }
+        }
+        return out;
+    }
+    resolve(issue) {
+        let fallback;
+        for (let layer = this; layer !== undefined; layer = layer.#parent) {
+            const template = layer.#templates.get(issue.messageKey) ?? layer.#templates.get(issue.code);
+            if (template !== undefined) {
+                return fill(template, issue.meta);
+            }
+            fallback ??= layer.#fallback;
+        }
+        return fallback === undefined ? `validation failed: ${issue.code}` : fallback(issue);
+    }
+}
+const PLACEHOLDER = /\{([A-Za-z_][A-Za-z0-9_.-]*)\}/g;
+/** `template` with each `{name}` replaced by the message form of the entry `name`, or left as written where there is none. */
+function fill(template, meta) {
+    return template.replace(PLACEHOLDER, (written, name) => Object.prototype.hasOwnProperty.call(meta, name) ? messageForm(meta[name]) : written);
+}
+/**
+ * `Properties.load`: the key and value pairs of a `.properties` text, in order.
+ *
+ * A logical line continues onto the next when it ends in an odd number of backslashes, and the
+ * next line's leading whitespace is skipped. Lines that are blank or whose first character other
+ * than whitespace is `#` or `!` are comments. A key ends at the first `=`, `:` or whitespace not
+ * escaped; whitespace around the separator is skipped. Both key and value undo the escapes `\t`,
+ * `\n`, `\r`, `\f` and `\uXXXX`, and a backslash before any other character stands for that
+ * character.
+ */
+function loadProperties(text) {
+    const lines = text.replaceAll("\r\n", "\n").replaceAll("\r", "\n").split("\n");
+    const pairs = [];
+    let logical = "";
+    let start = 0;
+    let continuing = false;
+    lines.forEach((raw, index) => {
+        let line;
+        if (continuing) {
+            line = raw.replace(/^[ \t\f]+/, "");
+        }
+        else {
+            line = raw.replace(/^[ \t\f]+/, "");
+            if (line === "" || line.startsWith("#") || line.startsWith("!")) {
+                return;
+            }
+            start = index + 1;
+        }
+        const trailing = line.length - line.replace(/\\+$/, "").length;
+        if (trailing % 2 === 1) {
+            logical += line.slice(0, -1);
+            continuing = true;
+        }
+        else {
+            logical += line;
+            continuing = false;
+            pairs.push(entry(logical, start));
+            logical = "";
+        }
+    });
+    if (continuing) {
+        pairs.push(entry(logical, start));
+    }
+    return pairs;
+}
+function entry(line, number) {
+    let keyEnd = line.length;
+    let escaped = false;
+    for (let i = 0; i < line.length; i += 1) {
+        const c = line[i];
+        if (escaped) {
+            escaped = false;
+        }
+        else if (c === "\\") {
+            escaped = true;
+        }
+        else if (c === "=" || c === ":" || c === " " || c === "\t" || c === "\f") {
+            keyEnd = i;
+            break;
+        }
+    }
+    let rest = line.slice(keyEnd).replace(/^[ \t\f]+/, "");
+    if (rest.startsWith("=") || rest.startsWith(":")) {
+        rest = rest.slice(1);
+    }
+    rest = rest.replace(/^[ \t\f]+/, "");
+    return [unescape(line.slice(0, keyEnd), number), unescape(rest, number)];
+}
+function unescape(raw, number) {
+    let out = "";
+    for (let i = 0; i < raw.length; i += 1) {
+        const c = raw[i];
+        if (c !== "\\") {
+            out += c;
+            continue;
+        }
+        i += 1;
+        const next = raw[i];
+        switch (next) {
+            case undefined:
+                break;
+            case "t":
+                out += "\t";
+                break;
+            case "n":
+                out += "\n";
+                break;
+            case "r":
+                out += "\r";
+                break;
+            case "f":
+                out += "\f";
+                break;
+            case "u": {
+                const hex = raw.slice(i + 1, i + 5);
+                if (!/^[0-9a-fA-F]{4}$/.test(hex)) {
+                    throw new SyntaxError(`line ${number}: malformed \\uXXXX encoding`);
+                }
+                out += String.fromCharCode(Number.parseInt(hex, 16));
+                i += 4;
+                break;
+            }
+            default:
+                out += next;
+        }
+    }
+    return out;
+}

package/dist/meta.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Whether the two are the same value of the value model: floats as `Object.is` compares them (+0
+ * and -0 differ, NaN is NaN), a decimal by coefficient and scale, lists element by element, sets
+ * and maps in any order.
+ */
+export declare function same(a: unknown, b: unknown): boolean;
+/**
+ * A key two values share exactly when they are the same value, for the scalars that have one;
+ * `undefined` for a value that has to be compared with {@link same}.
+ */
+export declare function keyOf(value: unknown): string | undefined;
+/** Whether `value` occurs in `values`, compared as the value model compares them. */
+export declare function includesSame(values: readonly unknown[], value: unknown): boolean;
+/** -1, 0 or 1 as `a` comes before, with or after `b`, for the values the bounding operations order. */
+export declare function compareValues(a: unknown, b: unknown): number;
+/** -1, 0 or 1 as `a` comes before, with or after `b` in code point order, which UTF-16 order is not. */
+export declare function compareCodePoints(a: string, b: string): number;
+/**
+ * How a metadata value is written in a message: a boolean, an integer or a string as it is, a
+ * float and a decimal in their message forms, a list as `[a, b]`, and a temporal value as its
+ * `toString` writes it.
+ */
+export declare function messageForm(value: unknown): string;

package/dist/meta.js

@@ -0,0 +1,128 @@
+// Values of the value model: how they are compared, ordered and written in a message.
+import { Decimal } from "./decimal.js";
+import { Float, compareFloats } from "./float.js";
+import { ofThisCopy } from "./copy.js";
+/**
+ * Whether the two are the same value of the value model: floats as `Object.is` compares them (+0
+ * and -0 differ, NaN is NaN), a decimal by coefficient and scale, lists element by element, sets
+ * and maps in any order.
+ */
+export function same(a, b) {
+    if (typeof a !== "object" || a === null || typeof b !== "object" || b === null) {
+        return Object.is(a, b);
+    }
+    if (ofThisCopy(a, Decimal, "Decimal")) {
+        return ofThisCopy(b, Decimal, "Decimal") && a.equals(b);
+    }
+    if (ofThisCopy(a, Float, "Float")) {
+        return ofThisCopy(b, Float, "Float") && a.width === b.width && Object.is(a.value, b.value);
+    }
+    if (Array.isArray(a)) {
+        return Array.isArray(b) && a.length === b.length && a.every((item, i) => same(item, b[i]));
+    }
+    if (a instanceof Set) {
+        return b instanceof Set && a.size === b.size && [...a].every((item) => [...b].some((other) => same(item, other)));
+    }
+    if (a instanceof Map) {
+        return (b instanceof Map &&
+            a.size === b.size &&
+            [...a].every(([key, value]) => b.has(key) && same(value, b.get(key))));
+    }
+    const equals = a.equals;
+    if (typeof equals === "function") {
+        return equals.call(a, b);
+    }
+    if (Object.getPrototypeOf(a) !== Object.getPrototypeOf(b)) {
+        return false;
+    }
+    const keys = Object.keys(a);
+    return (keys.length === Object.keys(b).length &&
+        keys.every((key) => Object.prototype.hasOwnProperty.call(b, key) &&
+            same(a[key], b[key])));
+}
+/**
+ * A key two values share exactly when they are the same value, for the scalars that have one;
+ * `undefined` for a value that has to be compared with {@link same}.
+ */
+export function keyOf(value) {
+    switch (typeof value) {
+        case "string":
+            return `s${value}`;
+        case "boolean":
+            return value ? "t" : "f";
+        case "bigint":
+            return `i${value}`;
+        case "number":
+            return Object.is(value, -0) ? "n-0" : `n${value}`;
+        default:
+            if (value === null) {
+                return "z";
+            }
+            if (ofThisCopy(value, Decimal, "Decimal")) {
+                return `d${value.coefficient}:${value.scale}`;
+            }
+            if (ofThisCopy(value, Float, "Float")) {
+                return `f${value.width}:${Object.is(value.value, -0) ? "-0" : value.value}`;
+            }
+            return undefined;
+    }
+}
+/** Whether `value` occurs in `values`, compared as the value model compares them. */
+export function includesSame(values, value) {
+    return values.some((each) => same(each, value));
+}
+/** -1, 0 or 1 as `a` comes before, with or after `b`, for the values the bounding operations order. */
+export function compareValues(a, b) {
+    if (typeof a === "string" && typeof b === "string") {
+        return compareCodePoints(a, b);
+    }
+    if (typeof a === "bigint" && typeof b === "bigint") {
+        return a < b ? -1 : a > b ? 1 : 0;
+    }
+    if (typeof a === "number" && typeof b === "number") {
+        return compareFloats(a, b);
+    }
+    if (ofThisCopy(a, Float, "Float") && ofThisCopy(b, Float, "Float")) {
+        return compareFloats(a.value, b.value);
+    }
+    if (ofThisCopy(a, Decimal, "Decimal") && ofThisCopy(b, Decimal, "Decimal")) {
+        return a.compare(b);
+    }
+    const compare = a?.compare;
+    if (typeof compare === "function") {
+        return compare.call(a, b);
+    }
+    throw new TypeError(`${String(a)} and ${String(b)} have no order`);
+}
+/** -1, 0 or 1 as `a` comes before, with or after `b` in code point order, which UTF-16 order is not. */
+export function compareCodePoints(a, b) {
+    const length = Math.min(a.length, b.length);
+    for (let i = 0; i < length; i += 1) {
+        const x = a.codePointAt(i);
+        const y = b.codePointAt(i);
+        if (x !== y) {
+            return x < y ? -1 : 1;
+        }
+        if (x > 0xffff) {
+            i += 1;
+        }
+    }
+    return a.length - b.length < 0 ? -1 : a.length > b.length ? 1 : 0;
+}
+/**
+ * How a metadata value is written in a message: a boolean, an integer or a string as it is, a
+ * float and a decimal in their message forms, a list as `[a, b]`, and a temporal value as its
+ * `toString` writes it.
+ */
+export function messageForm(value) {
+    if (Array.isArray(value)) {
+        return `[${value.map(messageForm).join(", ")}]`;
+    }
+    if (typeof value === "object" && value !== null && !hasOwnToString(value)) {
+        return JSON.stringify(value);
+    }
+    return String(value);
+}
+function hasOwnToString(value) {
+    return Object.getPrototypeOf(value) !== Object.prototype && Object.getPrototypeOf(value) !== null;
+}

package/dist/path.d.ts

@@ -0,0 +1,48 @@
+/**
+ * A step into the input: a reference token of a JSON Pointer (RFC 6901). It is the name of an
+ * object's member or the index of an array's element, written in decimal; which one is for the
+ * value it is applied to to say, as RFC 6901 has it, so a path holds the text and nothing more.
+ */
+export type Segment = string;
+/**
+ * A path into the input, kept as its segments and written as a JSON Pointer only when it is
+ * reported, so that a segment is escaped exactly once. A path holds what its pointer writes and
+ * no more, so reading back what it writes gives the same path.
+ *
+ * A path is immutable. Walking down the input makes a child that points at its parent, so a
+ * successful decode copies no segments.
+ */
+export declare class Path {
+    #private;
+    /** The input itself. */
+    static readonly ROOT: Path;
+    private constructor();
+    get [Symbol.toStringTag](): string;
+    /** The path of the given segments, from the root; an index is its decimal text. */
+    static of(...segments: readonly (string | number)[]): Path;
+    /**
+     * The path a JSON Pointer writes, each reference token unescaped and kept as its text.
+     *
+     * @throws {SyntaxError} when the text is not a JSON Pointer
+     */
+    static parse(pointer: string): Path;
+    /**
+     * The path one step below this one. An index is held as its decimal text, the token a
+     * pointer writes for it.
+     *
+     * @throws {RangeError} for a number that is not an index: negative, fractional, or beyond
+     *   the integers a JavaScript number holds exactly
+     */
+    child(segment: string | number): Path;
+    /** `relative`, read as starting where this path ends. */
+    concat(relative: Path): Path;
+    /** Whether this is the input itself. */
+    get isRoot(): boolean;
+    /** The segments from the root. */
+    segments(): Segment[];
+    /** Whether the two paths have the same segments. */
+    equals(other: Path): boolean;
+    /** The path as a JSON Pointer: `""` for the root, `/items/0/name` below it. */
+    toString(): string;
+    toJSON(): string;
+}

package/dist/path.js

@@ -0,0 +1,118 @@
+// Where in the input an issue is.
+import { ofThisCopy, tagOf } from "./copy.js";
+/**
+ * A path into the input, kept as its segments and written as a JSON Pointer only when it is
+ * reported, so that a segment is escaped exactly once. A path holds what its pointer writes and
+ * no more, so reading back what it writes gives the same path.
+ *
+ * A path is immutable. Walking down the input makes a child that points at its parent, so a
+ * successful decode copies no segments.
+ */
+export class Path {
+    /** The input itself. */
+    static ROOT = new Path(undefined, undefined);
+    #parent;
+    #segment;
+    constructor(parent, segment) {
+        this.#parent = parent;
+        this.#segment = segment;
+    }
+    get [Symbol.toStringTag]() {
+        return tagOf("Path");
+    }
+    /** The path of the given segments, from the root; an index is its decimal text. */
+    static of(...segments) {
+        let path = Path.ROOT;
+        for (const segment of segments) {
+            path = path.child(segment);
+        }
+        return path;
+    }
+    /**
+     * The path a JSON Pointer writes, each reference token unescaped and kept as its text.
+     *
+     * @throws {SyntaxError} when the text is not a JSON Pointer
+     */
+    static parse(pointer) {
+        if (pointer === "") {
+            return Path.ROOT;
+        }
+        if (!pointer.startsWith("/")) {
+            throw new SyntaxError(`${JSON.stringify(pointer)} is not a JSON Pointer`);
+        }
+        let path = Path.ROOT;
+        for (const written of pointer.slice(1).split("/")) {
+            if (/~(?![01])/.test(written)) {
+                throw new SyntaxError(`${JSON.stringify(pointer)} has a ~ that is not ~0 or ~1`);
+            }
+            path = path.child(written.replaceAll("~1", "/").replaceAll("~0", "~"));
+        }
+        return path;
+    }
+    /**
+     * The path one step below this one. An index is held as its decimal text, the token a
+     * pointer writes for it.
+     *
+     * @throws {RangeError} for a number that is not an index: negative, fractional, or beyond
+     *   the integers a JavaScript number holds exactly
+     */
+    child(segment) {
+        if (typeof segment === "number" && !(Number.isSafeInteger(segment) && segment >= 0)) {
+            throw new RangeError(`${segment} is not an array index`);
+        }
+        return new Path(this, String(segment));
+    }
+    /** `relative`, read as starting where this path ends. */
+    concat(relative) {
+        thisCopys(relative);
+        let path = this;
+        for (const segment of relative.segments()) {
+            path = path.child(segment);
+        }
+        return path;
+    }
+    /** Whether this is the input itself. */
+    get isRoot() {
+        return this.#parent === undefined;
+    }
+    /** The segments from the root. */
+    segments() {
+        const out = [];
+        for (let at = this; at.#parent !== undefined; at = at.#parent) {
+            out.push(at.#segment);
+        }
+        return out.reverse();
+    }
+    /** Whether the two paths have the same segments. */
+    equals(other) {
+        thisCopys(other);
+        let a = this;
+        let b = other;
+        while (a !== undefined && b !== undefined) {
+            if (a === b) {
+                return true;
+            }
+            if (a.#segment !== b.#segment) {
+                return false;
+            }
+            a = a.#parent;
+            b = b.#parent;
+        }
+        return a === b;
+    }
+    /** The path as a JSON Pointer: `""` for the root, `/items/0/name` below it. */
+    toString() {
+        return this.segments()
+            .map((segment) => `/${segment.replaceAll("~", "~0").replaceAll("/", "~1")}`)
+            .join("");
+    }
+    toJSON() {
+        return this.toString();
+    }
+}
+/** `path`, refused where another copy of the library made it. */
+function thisCopys(path) {
+    if (!ofThisCopy(path, Path, "Path")) {
+        throw new TypeError(`${String(path)} is not a Path`);
+    }
+}