@raoh/core 0.9.0-dev.15.20261004151401.ge5893e0cc07d

package/dist/input.js

@@ -0,0 +1,465 @@
+// The values a decoder reads.
+//
+// The input model is what a JSON text denotes, with every number kept as it is written. A decoder
+// reads it from plain JavaScript values: `null`, a boolean, a string, an array, an object (a
+// plain object or a `Map` of string keys), and a number as a `JsonNumber`, which `parse` gives and
+// which keeps the lexeme. A JavaScript `number` or `bigint` is read as the number it is, which is
+// what an adapter that has already converted the text gives: `1.50` read by `JSON.parse` is 1.5,
+// and a decimal decoder sees the scale 1. `undefined` is an absent value, at the top as much
+// as an object's member.
+import { Decimal } from "./decimal.js";
+import { ofThisCopy, tagOf } from "./copy.js";
+/** A number of the input model: the text it is written with. */
+export class JsonNumber {
+    lexeme;
+    constructor(lexeme) {
+        if (!LEXEME.test(lexeme)) {
+            throw new SyntaxError(`${JSON.stringify(lexeme)} is not a JSON number`);
+        }
+        this.lexeme = lexeme;
+    }
+    get [Symbol.toStringTag]() {
+        return tagOf("JsonNumber");
+    }
+    toString() {
+        return this.lexeme;
+    }
+    /**
+     * 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() {
+        const raw = JSON.rawJSON;
+        if (raw !== undefined) {
+            return raw(this.lexeme);
+        }
+        const number = Number(this.lexeme);
+        if (!Number.isFinite(number) || Object.is(number, -0) || !sameNumber(String(number), this.lexeme)) {
+            throw new RangeError(`${this.lexeme} cannot be written as a JavaScript number, and this engine has no JSON.rawJSON`);
+        }
+        return number;
+    }
+}
+/** Whether the two JSON number texts denote the same number. */
+function sameNumber(a, b) {
+    const x = Decimal.parse(a);
+    const y = Decimal.parse(b);
+    return x !== undefined && y !== undefined && x.compare(y) === 0;
+}
+const LEXEME = /^-?(?:0|[1-9][0-9]*)(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$/;
+/**
+ * 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 function kindOf(value) {
+    if (value === undefined) {
+        return "missing";
+    }
+    if (value === null) {
+        return "null";
+    }
+    switch (typeof value) {
+        case "boolean":
+            return "boolean";
+        case "number":
+        case "bigint":
+            return "number";
+        case "string":
+            wellFormed(value);
+            return "string";
+        case "object":
+            if (ofThisCopy(value, JsonNumber, "JsonNumber") || ofThisCopy(value, Decimal, "Decimal")
+                || rawNumber(value) !== undefined) {
+                return "number";
+            }
+            if (Array.isArray(value)) {
+                return "array";
+            }
+            if (value instanceof Map || Object.prototype.toString.call(value) === "[object Object]") {
+                return "object";
+            }
+            throw new TypeError(`${Object.prototype.toString.call(value)} is no value of the input model`);
+        default:
+            throw new TypeError(`a ${typeof value} is no value of the input model`);
+    }
+}
+/** `text`, refused where it is not a sequence of Unicode scalar values, which no JSON text holds. */
+function wellFormed(text) {
+    if (!text.isWellFormed()) {
+        throw new TypeError(`${JSON.stringify(text)} holds an unpaired surrogate, and is no string of the input model`);
+    }
+    return text;
+}
+/**
+ * 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 function elementsOf(value) {
+    const out = [];
+    for (let i = 0; i < value.length; i += 1) {
+        if (!(i in value)) {
+            throw new TypeError(`an array with no element at ${i} is no value of the input model`);
+        }
+        out.push(value[i]);
+    }
+    return out;
+}
+const isRawJSON = JSON.isRawJSON;
+/**
+ * The text of a number `JSON.rawJSON` made, which is how JavaScript itself carries a number as it
+ * is written; `undefined` for any other value.
+ *
+ * @throws {TypeError} for raw JSON that is not a number, which is no value of the input model
+ */
+function rawNumber(value) {
+    if (isRawJSON === undefined || !isRawJSON(value)) {
+        return undefined;
+    }
+    const text = value.rawJSON;
+    if (!LEXEME.test(text)) {
+        throw new TypeError(`raw JSON ${text} is not a number, and only a number is read from raw JSON`);
+    }
+    return text;
+}
+/** Whether `value` is an object of the input model. */
+export function isObject(value) {
+    return kindOf(value) === "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 function lexemeOf(value) {
+    if (ofThisCopy(value, JsonNumber, "JsonNumber")) {
+        return value.lexeme;
+    }
+    if (ofThisCopy(value, Decimal, "Decimal")) {
+        return value.toString();
+    }
+    const raw = rawNumber(value);
+    if (raw !== undefined) {
+        return raw;
+    }
+    if (typeof value === "bigint") {
+        return value.toString();
+    }
+    if (typeof value === "number") {
+        if (!Number.isFinite(value)) {
+            return undefined;
+        }
+        if (Object.is(value, -0)) {
+            return "-0";
+        }
+        return Number.isInteger(value) ? BigInt(value).toString() : String(value);
+    }
+    return 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 function membersOf(value) {
+    const entries = value instanceof Map ? [...value.entries()] : Object.entries(value);
+    const out = [];
+    for (const [name, member] of entries) {
+        if (typeof name !== "string") {
+            throw new TypeError(`a Map with the key ${String(name)}, which is not a string, is no object of the input model`);
+        }
+        if (member !== undefined) {
+            out.push([wellFormed(name), member]);
+        }
+    }
+    return out;
+}
+/** The member of an object of the input model, or `undefined` where it is absent. */
+export function memberOf(value, name) {
+    if (value instanceof Map) {
+        return value.get(name);
+    }
+    return Object.prototype.hasOwnProperty.call(value, name) ? value[name] : undefined;
+}
+/**
+ * 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 function parse(text) {
+    const reader = new Reader(text);
+    reader.space();
+    const value = reader.value(0);
+    reader.space();
+    if (reader.at < text.length) {
+        reader.fail("text after the value");
+    }
+    return value;
+}
+/**
+ * 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 function stringify(value) {
+    const out = [];
+    write(value, out, 0);
+    return out.join("");
+}
+function write(value, out, depth) {
+    if (depth > DEPTH) {
+        throw new TypeError(`nesting deeper than ${DEPTH}`);
+    }
+    switch (kindOf(value)) {
+        case "missing":
+            throw new TypeError("an absent value has no JSON text");
+        case "null":
+            out.push("null");
+            return;
+        case "boolean":
+            out.push(value ? "true" : "false");
+            return;
+        case "string":
+            out.push(JSON.stringify(value));
+            return;
+        case "number": {
+            const lexeme = lexemeOf(value);
+            if (lexeme === undefined) {
+                throw new TypeError(`${String(value)} is in no JSON text`);
+            }
+            out.push(lexeme);
+            return;
+        }
+        case "array": {
+            out.push("[");
+            elementsOf(value).forEach((item, i) => {
+                if (i > 0) {
+                    out.push(",");
+                }
+                write(item, out, depth + 1);
+            });
+            out.push("]");
+            return;
+        }
+        case "object": {
+            out.push("{");
+            membersOf(value).forEach(([name, member], i) => {
+                if (i > 0) {
+                    out.push(",");
+                }
+                out.push(JSON.stringify(name), ":");
+                write(member, out, depth + 1);
+            });
+            out.push("}");
+        }
+    }
+}
+/** How deep arrays and objects may nest before the text is refused rather than the stack overflowing. */
+const DEPTH = 1000;
+class Reader {
+    text;
+    at = 0;
+    constructor(text) {
+        this.text = text;
+    }
+    fail(what) {
+        throw new SyntaxError(`not JSON: ${what} at ${this.at}`);
+    }
+    space() {
+        while (this.at < this.text.length) {
+            const c = this.text.charCodeAt(this.at);
+            if (c !== 0x20 && c !== 0x09 && c !== 0x0a && c !== 0x0d) {
+                return;
+            }
+            this.at += 1;
+        }
+    }
+    value(depth) {
+        if (depth > DEPTH) {
+            this.fail(`nesting deeper than ${DEPTH}`);
+        }
+        const c = this.text[this.at];
+        switch (c) {
+            case "{":
+                return this.object(depth);
+            case "[":
+                return this.array(depth);
+            case '"':
+                return this.string();
+            case "t":
+                return this.word("true", true);
+            case "f":
+                return this.word("false", false);
+            case "n":
+                return this.word("null", null);
+            default:
+                if (c === "-" || (c !== undefined && c >= "0" && c <= "9")) {
+                    return this.number();
+                }
+                return this.fail(c === undefined ? "the end of the text" : `${JSON.stringify(c)}`);
+        }
+    }
+    word(word, value) {
+        if (!this.text.startsWith(word, this.at)) {
+            this.fail("an unknown word");
+        }
+        this.at += word.length;
+        return value;
+    }
+    number() {
+        NUMBER_AT.lastIndex = this.at;
+        const read = NUMBER_AT.exec(this.text);
+        if (read === null) {
+            this.fail("a malformed number");
+        }
+        this.at += read[0].length;
+        return new JsonNumber(read[0]);
+    }
+    string() {
+        this.at += 1;
+        let out = "";
+        let from = this.at;
+        for (;;) {
+            const c = this.text.charCodeAt(this.at);
+            if (Number.isNaN(c)) {
+                this.fail("an unterminated string");
+            }
+            if (c === 0x22) {
+                out += this.text.slice(from, this.at);
+                this.at += 1;
+                break;
+            }
+            if (c < 0x20) {
+                this.fail("a control character in a string");
+            }
+            if (c === 0x5c) {
+                out += this.text.slice(from, this.at);
+                out += this.escape();
+                from = this.at;
+                continue;
+            }
+            this.at += 1;
+        }
+        if (!out.isWellFormed()) {
+            this.fail("a string holding an unpaired surrogate");
+        }
+        return out;
+    }
+    escape() {
+        const c = this.text[this.at + 1];
+        this.at += 2;
+        switch (c) {
+            case '"':
+                return '"';
+            case "\\":
+                return "\\";
+            case "/":
+                return "/";
+            case "b":
+                return "\b";
+            case "f":
+                return "\f";
+            case "n":
+                return "\n";
+            case "r":
+                return "\r";
+            case "t":
+                return "\t";
+            case "u": {
+                const hex = this.text.slice(this.at, this.at + 4);
+                if (!/^[0-9a-fA-F]{4}$/.test(hex)) {
+                    this.fail("a malformed \\u escape");
+                }
+                this.at += 4;
+                return String.fromCharCode(Number.parseInt(hex, 16));
+            }
+            default:
+                return this.fail("an unknown escape");
+        }
+    }
+    array(depth) {
+        this.at += 1;
+        const out = [];
+        this.space();
+        if (this.text[this.at] === "]") {
+            this.at += 1;
+            return out;
+        }
+        for (;;) {
+            this.space();
+            out.push(this.value(depth + 1));
+            this.space();
+            const c = this.text[this.at];
+            this.at += 1;
+            if (c === "]") {
+                return out;
+            }
+            if (c !== ",") {
+                this.at -= 1;
+                this.fail("an array not closed");
+            }
+        }
+    }
+    object(depth) {
+        this.at += 1;
+        const out = new Map();
+        this.space();
+        if (this.text[this.at] === "}") {
+            this.at += 1;
+            return out;
+        }
+        for (;;) {
+            this.space();
+            if (this.text[this.at] !== '"') {
+                this.fail("a member without a name");
+            }
+            const name = this.string();
+            if (out.has(name)) {
+                this.fail(`the member ${JSON.stringify(name)} twice`);
+            }
+            this.space();
+            if (this.text[this.at] !== ":") {
+                this.fail("a member name without a colon");
+            }
+            this.at += 1;
+            this.space();
+            out.set(name, this.value(depth + 1));
+            this.space();
+            const c = this.text[this.at];
+            this.at += 1;
+            if (c === "}") {
+                return out;
+            }
+            if (c !== ",") {
+                this.at -= 1;
+                this.fail("an object not closed");
+            }
+        }
+    }
+}
+const NUMBER_AT = /-?(?:0|[1-9][0-9]*)(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?/y;

package/dist/issue.d.ts

@@ -0,0 +1,85 @@
+import { type MessageResolver } from "./messages.ts";
+import { Path } from "./path.ts";
+import { type IssueWire } from "./wire.ts";
+/** What an issue is made with, besides its code. */
+export interface IssueInit {
+    /** The kind of problem within the code's class; the code itself when not given. */
+    readonly messageKey?: string;
+    /** Named values that describe the problem. */
+    readonly meta?: Readonly<Record<string, unknown>>;
+    /** A sentence of the issue's own, which every catalogue leaves as it is. */
+    readonly message?: string;
+    /** Where the problem is, relative to where the issue is given. */
+    readonly path?: Path | readonly (string | number)[];
+}
+/**
+ * One thing the input did wrong: where it is, its code, the message key that says which kind of
+ * problem within the code it is, and the metadata that describes it.
+ *
+ * An issue carries no sentence unless whoever made it gave one. {@link message} writes one from a
+ * catalogue, the English one unless another is given, so the same issue reads in each person's
+ * language.
+ */
+export declare class Issue {
+    #private;
+    readonly path: Path;
+    readonly code: string;
+    readonly messageKey: string;
+    readonly meta: Readonly<Record<string, unknown>>;
+    /** The sentence the issue was given, if it was given one. */
+    readonly givenMessage: string | undefined;
+    constructor(code: string, init?: IssueInit);
+    get [Symbol.toStringTag](): string;
+    /** The sentence for the issue: the one it was given, or the one `resolver` writes. */
+    message(resolver?: MessageResolver): string;
+    /** The same issue with `message` as its sentence. */
+    withMessage(message: string): Issue;
+    /** The same issue, its path read as starting at `base`. */
+    under(base: Path): Issue;
+    /**
+     * The issue as JSON, with its English sentence; {@link issueWire} writes it with another
+     * catalogue's. It takes no argument: `JSON.stringify` hands `toJSON` the member name.
+     */
+    toJSON(): IssueWire;
+}
+/** The issues a failed decode gives, in the order they were found; never empty. */
+export declare class Issues implements Iterable<Issue> {
+    #private;
+    constructor(issues: readonly Issue[]);
+    get [Symbol.toStringTag](): string;
+    get length(): number;
+    /** The issues, in order. */
+    get list(): readonly Issue[];
+    [Symbol.iterator](): Iterator<Issue>;
+    /** The same issues, their paths read as starting at `base`. */
+    under(base: Path): Issues;
+    /**
+     * The issues at `path`, in order, and none where nothing was found there: what a form shows beside
+     * the field the path names. The path is a `Path` or its segments, a number naming an element by
+     * its index, so `at(["lines", 0, "sku"])` is the issues of the first line's `sku`. An issue at a
+     * path below or above it is not at it.
+     */
+    at(path: Path | readonly (string | number)[]): readonly Issue[];
+    /** The sentences for the issues, grouped by the JSON Pointer of their path. */
+    flatten(resolver?: MessageResolver): Record<string, string[]>;
+    /** The issues as JSON, in order, their sentences written by `resolver`. */
+    toWire(resolver?: MessageResolver): IssueWire[];
+    /** The issues as JSON, in order, with their English sentences. */
+    toJSON(): IssueWire[];
+}
+/** What decoding came to when it succeeded. */
+export interface Ok<T> {
+    readonly value: T;
+    readonly issues?: undefined;
+}
+/** What decoding came to when it failed. */
+export interface Failed {
+    readonly issues: Issues;
+    readonly value?: undefined;
+}
+/** What decoding comes to: the value, or the issues that kept it from being one. */
+export type Result<T> = Ok<T> | Failed;
+/** A success holding `value`. */
+export declare function ok<T>(value: T): Ok<T>;
+/** A failure with the issues given. */
+export declare function failed(issues: Issues | Issue | readonly Issue[]): Failed;

package/dist/issue.js

@@ -0,0 +1,130 @@
+// What a decoder that fails gives, and what decoding comes to.
+var _a;
+import { Messages } from "./messages.js";
+import { Path } from "./path.js";
+import { issueWire } from "./wire.js";
+import { ofThisCopy, tagOf } from "./copy.js";
+/**
+ * One thing the input did wrong: where it is, its code, the message key that says which kind of
+ * problem within the code it is, and the metadata that describes it.
+ *
+ * An issue carries no sentence unless whoever made it gave one. {@link message} writes one from a
+ * catalogue, the English one unless another is given, so the same issue reads in each person's
+ * language.
+ */
+export class Issue {
+    path;
+    code;
+    messageKey;
+    meta;
+    /** The sentence the issue was given, if it was given one. */
+    givenMessage;
+    constructor(code, init = {}) {
+        this.code = code;
+        this.messageKey = init.messageKey ?? code;
+        this.meta = Object.freeze({ ...init.meta });
+        this.givenMessage = init.message;
+        this.path = init.path === undefined
+            ? Path.ROOT
+            : ofThisCopy(init.path, Path, "Path")
+                ? init.path
+                : Path.of(...init.path);
+    }
+    get [Symbol.toStringTag]() {
+        return tagOf("Issue");
+    }
+    /** The sentence for the issue: the one it was given, or the one `resolver` writes. */
+    message(resolver = Messages.english) {
+        return this.givenMessage ?? resolver.resolve(this);
+    }
+    /** The same issue with `message` as its sentence. */
+    withMessage(message) {
+        return this.#with({ message });
+    }
+    /** The same issue, its path read as starting at `base`. */
+    under(base) {
+        return base.isRoot ? this : this.#with({ path: base.concat(this.path) });
+    }
+    #with(changes) {
+        return new _a(this.code, {
+            messageKey: this.messageKey,
+            meta: this.meta,
+            message: this.givenMessage,
+            path: this.path,
+            ...changes,
+        });
+    }
+    /**
+     * The issue as JSON, with its English sentence; {@link issueWire} writes it with another
+     * catalogue's. It takes no argument: `JSON.stringify` hands `toJSON` the member name.
+     */
+    toJSON() {
+        return issueWire(this);
+    }
+}
+_a = Issue;
+/** The issues a failed decode gives, in the order they were found; never empty. */
+export class Issues {
+    #list;
+    constructor(issues) {
+        if (issues.length === 0) {
+            throw new RangeError("a failure has at least one issue");
+        }
+        this.#list = Object.freeze([...issues]);
+    }
+    get [Symbol.toStringTag]() {
+        return tagOf("Issues");
+    }
+    get length() {
+        return this.#list.length;
+    }
+    /** The issues, in order. */
+    get list() {
+        return this.#list;
+    }
+    [Symbol.iterator]() {
+        return this.#list[Symbol.iterator]();
+    }
+    /** The same issues, their paths read as starting at `base`. */
+    under(base) {
+        return base.isRoot ? this : new Issues(this.#list.map((issue) => issue.under(base)));
+    }
+    /**
+     * The issues at `path`, in order, and none where nothing was found there: what a form shows beside
+     * the field the path names. The path is a `Path` or its segments, a number naming an element by
+     * its index, so `at(["lines", 0, "sku"])` is the issues of the first line's `sku`. An issue at a
+     * path below or above it is not at it.
+     */
+    at(path) {
+        const wanted = ofThisCopy(path, Path, "Path") ? path : Path.of(...path);
+        return this.#list.filter((issue) => issue.path.equals(wanted));
+    }
+    /** The sentences for the issues, grouped by the JSON Pointer of their path. */
+    flatten(resolver = Messages.english) {
+        const out = {};
+        for (const issue of this.#list) {
+            const path = issue.path.toString();
+            (out[path] ??= []).push(issue.message(resolver));
+        }
+        return out;
+    }
+    /** The issues as JSON, in order, their sentences written by `resolver`. */
+    toWire(resolver = Messages.english) {
+        return this.#list.map((issue) => issueWire(issue, resolver));
+    }
+    /** The issues as JSON, in order, with their English sentences. */
+    toJSON() {
+        return this.toWire();
+    }
+}
+/** A success holding `value`. */
+export function ok(value) {
+    return { value };
+}
+/** A failure with the issues given. */
+export function failed(issues) {
+    if (ofThisCopy(issues, Issues, "Issues")) {
+        return { issues };
+    }
+    return { issues: new Issues(ofThisCopy(issues, Issue, "Issue") ? [issues] : issues) };
+}