@sincpro/client-framework 0.2.0 → 0.4.0

package/dist/adapters/sentry.js

@@ -4,11 +4,11 @@
  *
  *     // @sincpro/web-framework/errors builds the browser's client with GlitchTip's DSN
  *     const reporter = sentryReporter(client);
- *     const runtime = createRuntime({ reporter });
+ *     configureProcess({ reporter });
  *
  * Context: it imports nothing — it takes the client the platform made (with its DSN, release
  * and data rules), so it costs no dependency and works on every platform. What is reported is
- * already decided by the runtime (`outcomeOf`: only `failed`); this only says where it happened.
+ * already decided by the process (`outcomeOf`: only `failed`); this only says where it happened.
  * The context goes as a context, not as tags: a tag is indexed and searched, and an execution's
  * values are not the place for that.
  */

package/dist/client/memory.js

@@ -1,5 +1,13 @@
 import { TransportError, } from "./transport.js";
+import { readValues, valuesOf } from "../common/serialization.js";
 import { answer, answerGroups } from "@sincpro/criteria/engine";
+/**
+ * A deep copy written and read by the wire's rules (`valuesOf`, `readValues`): what a real server
+ * would have received and answered — a `Money` as `{ amount, currency }`, a `Decimal` as its text,
+ * a `Date` as an instant, bytes as bytes — the same on every platform. `structuredClone` kept a
+ * `Date` a `Date` in a browser and a JSON round trip made it text on a phone; neither is a wire.
+ */
+const copyOf = (value) => value === undefined ? value : readValues(valuesOf(value));
 function wait(ms, signal) {
     if (ms <= 0)
         return Promise.resolve();
@@ -46,7 +54,7 @@ export function memoryTransport(tables, options = {}) {
                 ? answerGroups(table.rows, criteria, table.meta)
                 : answer(table.rows, criteria, table.meta);
             // A copy, as over a wire: a screen holding a row must not see the server change it.
-            return { ...page, rows: structuredClone(page.rows) };
+            return { ...page, rows: copyOf(page.rows) };
         },
         async one(route, signal) {
             await check(route, signal);
@@ -66,7 +74,7 @@ export function memoryTransport(tables, options = {}) {
                     detail: `${table.meta.aggregate} ${id} does not exist.`,
                 });
             return {
-                record: structuredClone(record),
+                record: copyOf(record),
                 meta: table.meta,
                 dropped: [],
                 draft: options.draft?.(route) ?? null,
@@ -78,7 +86,7 @@ export function memoryTransport(tables, options = {}) {
             // sincpro_framework's `@idempotency` does with a repeated `Idempotency-Key`.
             const key = sending?.idempotencyKey;
             if (key !== undefined && answered.has(key))
-                return structuredClone(answered.get(key));
+                return copyOf(answered.get(key));
             if (options.handle === undefined)
                 throw new TransportError(route, 404, {
                     kind: "not_found",
@@ -90,9 +98,9 @@ export function memoryTransport(tables, options = {}) {
                     detail: `Nothing answers ${method} ${route}.`,
                 });
             // A deep copy: what the caller sent is not what the server keeps.
-            const answer = await options.handle(method, route, structuredClone(body));
+            const answer = await options.handle(method, route, copyOf(body));
             if (key !== undefined)
-                answered.set(key, structuredClone(answer));
+                answered.set(key, copyOf(answer));
             return answer;
         },
         ...(options.read === undefined
@@ -101,7 +109,7 @@ export function memoryTransport(tables, options = {}) {
                 async read(route, signal) {
                     await check(route, signal);
                     // A copy, as every answer: over a wire nobody holds the server's object.
-                    return structuredClone(await options.read(route));
+                    return copyOf(await options.read(route));
                 },
             }),
     };

package/dist/common/decimal.d.ts

@@ -0,0 +1,49 @@
+/**
+ * An exact decimal — what sincpro_framework's `Decimal` is on the wire: text, every digit kept.
+ *
+ *     new Decimal("10.50").plus("0.25")             →  10.75
+ *     new Decimal("2.500").times("19.90")           →  49.75000
+ *     new Decimal("10").dividedBy("3", 2)           →  3.33        half up, as the backend rounds
+ *     JSON.stringify({ qty: new Decimal("2.500") })  →  {"qty":"2.500"}
+ *
+ * Context: the backend sends a decimal as text (`"10.50"`) so no client reads it as a float —
+ * `0.1 + 0.2` is `0.30000000000000004` in every JavaScript engine, and an invoice cannot be. A
+ * client that adds, multiplies or rounds an amount (a cart, a line, a discount) does it here,
+ * on `BigInt`, which browsers, Node and Hermes have; it depends on nothing. It never rounds by
+ * accident: `plus`, `minus` and `times` are exact, and only `rounded` and `dividedBy` round —
+ * half up, away from zero, the backend's `ROUND_HALF_UP`. Formatting it for a person is the
+ * platform's (`Intl.NumberFormat`), never this.
+ */
+export type DecimalLike = Decimal | string | number | bigint;
+export declare class Decimal {
+    /** The digits, as an integer: `10.50` is `1050n` at scale 2. */
+    readonly units: bigint;
+    /** How many of the digits are after the point. */
+    readonly scale: number;
+    /**
+     * A decimal from its text (`"10.50"`, `"-0.5"`, `"1e3"`), a number — taken by its digits,
+     * `0.1` is `"0.1"` — or a whole `bigint`. Anything else is refused, naming it.
+     */
+    constructor(value: DecimalLike);
+    static of(value: DecimalLike): Decimal;
+    private static at;
+    /** Both at the larger scale, so their units compare and add. */
+    private static aligned;
+    plus(other: DecimalLike): Decimal;
+    minus(other: DecimalLike): Decimal;
+    times(factor: DecimalLike): Decimal;
+    /** This over `divisor`, with `decimals` digits after the point, rounded half up. */
+    dividedBy(divisor: DecimalLike, decimals: number): Decimal;
+    /** With `decimals` digits after the point: rounded half up when it had more, padded when fewer. */
+    rounded(decimals: number): Decimal;
+    negated(): Decimal;
+    /** `-1`, `0` or `1`: `10.5` and `10.50` are the same amount. */
+    compare(other: DecimalLike): -1 | 0 | 1;
+    equals(other: DecimalLike): boolean;
+    get isZero(): boolean;
+    get isNegative(): boolean;
+    get isPositive(): boolean;
+    /** The text the wire carries: every digit, the scale kept (`"10.50"`, never `"10.5"`). */
+    toString(): string;
+    toJSON(): string;
+}

package/dist/common/decimal.js

@@ -0,0 +1,146 @@
+/**
+ * An exact decimal — what sincpro_framework's `Decimal` is on the wire: text, every digit kept.
+ *
+ *     new Decimal("10.50").plus("0.25")             →  10.75
+ *     new Decimal("2.500").times("19.90")           →  49.75000
+ *     new Decimal("10").dividedBy("3", 2)           →  3.33        half up, as the backend rounds
+ *     JSON.stringify({ qty: new Decimal("2.500") })  →  {"qty":"2.500"}
+ *
+ * Context: the backend sends a decimal as text (`"10.50"`) so no client reads it as a float —
+ * `0.1 + 0.2` is `0.30000000000000004` in every JavaScript engine, and an invoice cannot be. A
+ * client that adds, multiplies or rounds an amount (a cart, a line, a discount) does it here,
+ * on `BigInt`, which browsers, Node and Hermes have; it depends on nothing. It never rounds by
+ * accident: `plus`, `minus` and `times` are exact, and only `rounded` and `dividedBy` round —
+ * half up, away from zero, the backend's `ROUND_HALF_UP`. Formatting it for a person is the
+ * platform's (`Intl.NumberFormat`), never this.
+ */
+const NUMBER = /^([+-]?)(\d*)(?:\.(\d*))?(?:[eE]([+-]?\d{1,4}))?$/;
+const TEN = 10n;
+function pow10(exponent) {
+    return TEN ** BigInt(exponent);
+}
+/** `units / divisor` rounded half up, away from zero. */
+function halfUp(units, divisor) {
+    const quotient = units / divisor;
+    const rest = units % divisor;
+    const twice = (rest < 0n ? -rest : rest) * 2n;
+    const whole = divisor < 0n ? -divisor : divisor;
+    if (twice < whole)
+        return quotient;
+    return units < 0n !== divisor < 0n ? quotient - 1n : quotient + 1n;
+}
+export class Decimal {
+    /** The digits, as an integer: `10.50` is `1050n` at scale 2. */
+    units;
+    /** How many of the digits are after the point. */
+    scale;
+    /**
+     * A decimal from its text (`"10.50"`, `"-0.5"`, `"1e3"`), a number — taken by its digits,
+     * `0.1` is `"0.1"` — or a whole `bigint`. Anything else is refused, naming it.
+     */
+    constructor(value) {
+        if (value instanceof Decimal) {
+            this.units = value.units;
+            this.scale = value.scale;
+            return;
+        }
+        if (typeof value === "bigint") {
+            this.units = value;
+            this.scale = 0;
+            return;
+        }
+        if (typeof value === "number" && !Number.isFinite(value))
+            throw new TypeError(`${value} is not a decimal`);
+        const text = typeof value === "number" ? String(value) : String(value).trim();
+        const match = NUMBER.exec(text);
+        const [, sign = "", whole = "", fraction = "", exponent = "0"] = match ?? [];
+        if (match === null || whole + fraction === "")
+            throw new TypeError(`"${text}" is not a decimal`);
+        let digits = whole + fraction;
+        let scale = fraction.length - Number(exponent);
+        if (scale < 0) {
+            digits += "0".repeat(-scale);
+            scale = 0;
+        }
+        this.units = BigInt(digits) * (sign === "-" ? -1n : 1n);
+        this.scale = scale;
+    }
+    static of(value) {
+        return value instanceof Decimal ? value : new Decimal(value);
+    }
+    static at(units, scale) {
+        const made = Object.create(Decimal.prototype);
+        made.units = units;
+        made.scale = scale;
+        return made;
+    }
+    /** Both at the larger scale, so their units compare and add. */
+    static aligned(one, other) {
+        const scale = Math.max(one.scale, other.scale);
+        return [
+            one.units * pow10(scale - one.scale),
+            other.units * pow10(scale - other.scale),
+            scale,
+        ];
+    }
+    plus(other) {
+        const [one, two, scale] = Decimal.aligned(this, Decimal.of(other));
+        return Decimal.at(one + two, scale);
+    }
+    minus(other) {
+        const [one, two, scale] = Decimal.aligned(this, Decimal.of(other));
+        return Decimal.at(one - two, scale);
+    }
+    times(factor) {
+        const by = Decimal.of(factor);
+        return Decimal.at(this.units * by.units, this.scale + by.scale);
+    }
+    /** This over `divisor`, with `decimals` digits after the point, rounded half up. */
+    dividedBy(divisor, decimals) {
+        const by = Decimal.of(divisor);
+        if (by.units === 0n)
+            throw new RangeError("a decimal divided by zero");
+        const numerator = this.units * pow10(by.scale + decimals);
+        const denominator = by.units * pow10(this.scale);
+        return Decimal.at(halfUp(numerator, denominator), decimals);
+    }
+    /** With `decimals` digits after the point: rounded half up when it had more, padded when fewer. */
+    rounded(decimals) {
+        if (decimals >= this.scale)
+            return Decimal.at(this.units * pow10(decimals - this.scale), decimals);
+        return Decimal.at(halfUp(this.units, pow10(this.scale - decimals)), decimals);
+    }
+    negated() {
+        return Decimal.at(-this.units, this.scale);
+    }
+    /** `-1`, `0` or `1`: `10.5` and `10.50` are the same amount. */
+    compare(other) {
+        const [one, two] = Decimal.aligned(this, Decimal.of(other));
+        return one < two ? -1 : one > two ? 1 : 0;
+    }
+    equals(other) {
+        return this.compare(other) === 0;
+    }
+    get isZero() {
+        return this.units === 0n;
+    }
+    get isNegative() {
+        return this.units < 0n;
+    }
+    get isPositive() {
+        return this.units > 0n;
+    }
+    /** The text the wire carries: every digit, the scale kept (`"10.50"`, never `"10.5"`). */
+    toString() {
+        const negative = this.units < 0n;
+        const digits = (negative ? -this.units : this.units)
+            .toString()
+            .padStart(this.scale + 1, "0");
+        const whole = digits.slice(0, digits.length - this.scale);
+        const fraction = digits.slice(digits.length - this.scale);
+        return `${negative ? "-" : ""}${whole}${this.scale > 0 ? `.${fraction}` : ""}`;
+    }
+    toJSON() {
+        return this.toString();
+    }
+}

package/dist/{client → common}/ids.d.ts

@@ -15,3 +15,10 @@
 export declare function newEntityId(now?: number): string;
 /** A key that is a UUID v7 as sincpro_framework writes it: 32 hex, version 7, variant `10`. */
 export declare function isEntityId(text: string): boolean;
+/**
+ * When a UUID v7 was minted, read off its leading 48 bits — sincpro_framework's `moment_of`;
+ * `null` for a key that is not one (a project's own format, a UUID v4).
+ *
+ *     momentOf(newEntityId())   →  "2026-11-06T22:41:07.512Z", the moment it was minted
+ */
+export declare function momentOf(identity: string): string | null;

package/dist/{client → common}/ids.js

@@ -50,3 +50,15 @@ export function newEntityId(now = Date.now()) {
 export function isEntityId(text) {
     return /^[0-9a-f]{12}7[0-9a-f]{3}[89ab][0-9a-f]{15}$/.test(text);
 }
+/**
+ * When a UUID v7 was minted, read off its leading 48 bits — sincpro_framework's `moment_of`;
+ * `null` for a key that is not one (a project's own format, a UUID v4).
+ *
+ *     momentOf(newEntityId())   →  "2026-11-06T22:41:07.512Z", the moment it was minted
+ */
+export function momentOf(identity) {
+    const hex = identity.replaceAll("-", "").toLowerCase();
+    if (!isEntityId(hex))
+        return null;
+    return new Date(Number.parseInt(hex.slice(0, 12), 16)).toISOString();
+}

package/dist/common/money.d.ts

@@ -0,0 +1,74 @@
+import { Decimal, type DecimalLike } from "./decimal.js";
+/**
+ * An amount and its currency, as sincpro_framework's `Money` travels: `{"amount": "10.50",
+ * "currency": "BOB"}`.
+ *
+ *     const line = new Money("19.90", "BOB").times("3");            →  59.70 BOB
+ *     const total = Money.total([line, delivery], "BOB");
+ *     total.rounded().toJSON()                                       →  { amount: "69.70", currency: "BOB" }
+ *     Money.fromJSON(answer.total)                                   ←  what the server sent
+ *
+ * Context: an amount never travels without its currency, never as a float and never rounds by
+ * accident — the backend's three rules, kept here so a cart, a POS line or a portal's quote adds
+ * the way the invoice will. Adding two currencies is refused; `total` sums one, `totals` each.
+ * The arithmetic is `Decimal`'s, exact; `rounded()` rounds to the currency's decimals (ISO 4217:
+ * `BOB` 2, `JPY` 0, `KWD` 3), and `isZero` / `isNegative` read it at those decimals, as an
+ * accountant does.
+ *
+ * Not restrictive: any code is read (a crypto, a loyalty point), and its decimals are 2 unless
+ * `Money.decimals` says otherwise — an application adds its own (`Money.decimals["USDT"] = 6`).
+ * Showing it to a person is the platform's (`Intl.NumberFormat` with `style: "currency"`).
+ */
+export declare class Money {
+    /** Decimals by currency where they are not 2: ISO 4217's, and what an application adds. */
+    static readonly decimals: Record<string, number>;
+    /** The amount as the wire carries it: every digit, the scale kept (`"10.50"`). */
+    readonly amount: string;
+    /** The currency's code, upper case (`"BOB"`). */
+    readonly currency: string;
+    constructor(amount: DecimalLike, currency: string);
+    /**
+     * What the server sent — `{ amount, currency }`, the amount as text or as a JSON number taken
+     * by its digits. Anything else is refused, naming what is wrong.
+     */
+    static fromJSON(value: unknown): Money;
+    /** Whether `value` has the shape of a money on the wire: `{ amount, currency }`. */
+    static isMoney(value: unknown): value is {
+        amount: string | number;
+        currency: string;
+    };
+    /** The decimals `currency` is counted in: 2 unless `Money.decimals` says otherwise. */
+    static decimalsOf(currency: string): number;
+    /** The sum of `items`, all in `currency` — zero when there are none. Another currency is refused. */
+    static total(items: Iterable<Money>, currency: string): Money;
+    /** The sums by currency, each currency's own. */
+    static totals(items: Iterable<Money>): Readonly<Record<string, Money>>;
+    /** The amount as an exact decimal. */
+    get value(): Decimal;
+    /** The decimals this currency is counted in. */
+    get decimals(): number;
+    private same;
+    plus(other: Money): Money;
+    minus(other: Money): Money;
+    /** Times a quantity, a rate or a percentage as a fraction: exact, never rounded. */
+    times(factor: DecimalLike): Money;
+    /** Over `divisor`, rounded half up to the currency's decimals (or `decimals`). */
+    dividedBy(divisor: DecimalLike, decimals?: number): Money;
+    /** Rounded half up to the currency's decimals (or `decimals`): what an invoice shows. */
+    rounded(decimals?: number): Money;
+    negated(): Money;
+    /** `-1`, `0` or `1`, in the same currency. */
+    compare(other: Money): -1 | 0 | 1;
+    /** The same currency and the same amount: `10.5 BOB` equals `10.50 BOB`. */
+    equals(other: Money): boolean;
+    /** Zero at the currency's decimals: `0.004 BOB` is. */
+    get isZero(): boolean;
+    get isNegative(): boolean;
+    get isPositive(): boolean;
+    toJSON(): {
+        amount: string;
+        currency: string;
+    };
+    /** `"10.50 BOB"` — for a log or a test; a person reads it through `Intl.NumberFormat`. */
+    toString(): string;
+}

package/dist/common/money.js

@@ -0,0 +1,168 @@
+import { Decimal } from "./decimal.js";
+/**
+ * An amount and its currency, as sincpro_framework's `Money` travels: `{"amount": "10.50",
+ * "currency": "BOB"}`.
+ *
+ *     const line = new Money("19.90", "BOB").times("3");            →  59.70 BOB
+ *     const total = Money.total([line, delivery], "BOB");
+ *     total.rounded().toJSON()                                       →  { amount: "69.70", currency: "BOB" }
+ *     Money.fromJSON(answer.total)                                   ←  what the server sent
+ *
+ * Context: an amount never travels without its currency, never as a float and never rounds by
+ * accident — the backend's three rules, kept here so a cart, a POS line or a portal's quote adds
+ * the way the invoice will. Adding two currencies is refused; `total` sums one, `totals` each.
+ * The arithmetic is `Decimal`'s, exact; `rounded()` rounds to the currency's decimals (ISO 4217:
+ * `BOB` 2, `JPY` 0, `KWD` 3), and `isZero` / `isNegative` read it at those decimals, as an
+ * accountant does.
+ *
+ * Not restrictive: any code is read (a crypto, a loyalty point), and its decimals are 2 unless
+ * `Money.decimals` says otherwise — an application adds its own (`Money.decimals["USDT"] = 6`).
+ * Showing it to a person is the platform's (`Intl.NumberFormat` with `style: "currency"`).
+ */
+export class Money {
+    /** Decimals by currency where they are not 2: ISO 4217's, and what an application adds. */
+    static decimals = {
+        BHD: 3,
+        BIF: 0,
+        BTC: 8,
+        CLF: 4,
+        CLP: 0,
+        DJF: 0,
+        GNF: 0,
+        IQD: 3,
+        ISK: 0,
+        JOD: 3,
+        JPY: 0,
+        KMF: 0,
+        KRW: 0,
+        KWD: 3,
+        LYD: 3,
+        OMR: 3,
+        PYG: 0,
+        RWF: 0,
+        TND: 3,
+        UGX: 0,
+        UYI: 0,
+        VND: 0,
+        VUV: 0,
+        XAF: 0,
+        XOF: 0,
+        XPF: 0,
+    };
+    /** The amount as the wire carries it: every digit, the scale kept (`"10.50"`). */
+    amount;
+    /** The currency's code, upper case (`"BOB"`). */
+    currency;
+    constructor(amount, currency) {
+        const code = currency.trim().toUpperCase();
+        if (!/^[A-Z][A-Z0-9]{1,9}$/.test(code))
+            throw new TypeError(`"${currency}" is not a currency code`);
+        this.amount = Decimal.of(amount).toString();
+        this.currency = code;
+    }
+    /**
+     * What the server sent — `{ amount, currency }`, the amount as text or as a JSON number taken
+     * by its digits. Anything else is refused, naming what is wrong.
+     */
+    static fromJSON(value) {
+        if (value instanceof Money)
+            return value;
+        if (value === null || typeof value !== "object")
+            throw new TypeError(`${JSON.stringify(value)} is not a money: { amount, currency }`);
+        const { amount, currency } = value;
+        if (typeof currency !== "string")
+            throw new TypeError(`a money without its currency: ${JSON.stringify(value)}`);
+        if (typeof amount !== "string" && typeof amount !== "number")
+            throw new TypeError(`a money without its amount: ${JSON.stringify(value)}`);
+        return new Money(amount, currency);
+    }
+    /** Whether `value` has the shape of a money on the wire: `{ amount, currency }`. */
+    static isMoney(value) {
+        if (value instanceof Money)
+            return true;
+        if (value === null || typeof value !== "object")
+            return false;
+        const { amount, currency } = value;
+        return (typeof currency === "string" &&
+            (typeof amount === "string" || typeof amount === "number"));
+    }
+    /** The decimals `currency` is counted in: 2 unless `Money.decimals` says otherwise. */
+    static decimalsOf(currency) {
+        return Money.decimals[currency.toUpperCase()] ?? 2;
+    }
+    /** The sum of `items`, all in `currency` — zero when there are none. Another currency is refused. */
+    static total(items, currency) {
+        let sum = new Money("0", currency);
+        for (const item of items)
+            sum = sum.plus(item);
+        return sum;
+    }
+    /** The sums by currency, each currency's own. */
+    static totals(items) {
+        const sums = {};
+        for (const item of items) {
+            const held = sums[item.currency];
+            sums[item.currency] = held === undefined ? item : held.plus(item);
+        }
+        return sums;
+    }
+    /** The amount as an exact decimal. */
+    get value() {
+        return new Decimal(this.amount);
+    }
+    /** The decimals this currency is counted in. */
+    get decimals() {
+        return Money.decimalsOf(this.currency);
+    }
+    same(other) {
+        if (other.currency !== this.currency)
+            throw new TypeError(`${other.currency} cannot be added to ${this.currency} — sum each currency apart (Money.totals)`);
+        return other;
+    }
+    plus(other) {
+        return new Money(this.value.plus(this.same(other).amount), this.currency);
+    }
+    minus(other) {
+        return new Money(this.value.minus(this.same(other).amount), this.currency);
+    }
+    /** Times a quantity, a rate or a percentage as a fraction: exact, never rounded. */
+    times(factor) {
+        return new Money(this.value.times(factor), this.currency);
+    }
+    /** Over `divisor`, rounded half up to the currency's decimals (or `decimals`). */
+    dividedBy(divisor, decimals = this.decimals) {
+        return new Money(this.value.dividedBy(divisor, decimals), this.currency);
+    }
+    /** Rounded half up to the currency's decimals (or `decimals`): what an invoice shows. */
+    rounded(decimals = this.decimals) {
+        return new Money(this.value.rounded(decimals), this.currency);
+    }
+    negated() {
+        return new Money(this.value.negated(), this.currency);
+    }
+    /** `-1`, `0` or `1`, in the same currency. */
+    compare(other) {
+        return this.value.compare(this.same(other).amount);
+    }
+    /** The same currency and the same amount: `10.5 BOB` equals `10.50 BOB`. */
+    equals(other) {
+        return other.currency === this.currency && this.value.equals(other.amount);
+    }
+    /** Zero at the currency's decimals: `0.004 BOB` is. */
+    get isZero() {
+        return this.rounded().value.isZero;
+    }
+    get isNegative() {
+        return this.rounded().value.isNegative;
+    }
+    get isPositive() {
+        return this.rounded().value.isPositive;
+    }
+    toJSON() {
+        return { amount: this.amount, currency: this.currency };
+    }
+    /** `"10.50 BOB"` — for a log or a test; a person reads it through `Intl.NumberFormat`. */
+    toString() {
+        return `${this.amount} ${this.currency}`;
+    }
+}

package/dist/common/serialization.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Any value as JSON values and back — what every message a client sends is written with, as
+ * sincpro_framework's `common/serialization` (`values_of`, `read_values`, `rebuilt`, `pack`,
+ * `unpack`).
+ *
+ *     valuesOf({ total: new Money("12.50", "BOB"), qty: new Decimal("2.500") })
+ *       →  { total: { amount: "12.50", currency: "BOB" }, qty: "2.500" }
+ *     valuesOf(new Uint8Array([104, 105]))          →  { $bytes: "aGk=" }
+ *     readValues('{"photo":{"$bytes":"aGk="}}')      →  { photo: Uint8Array [104, 105] }
+ *     unpack(text, Money)                           →  a Money, or a TypeError naming what is wrong
+ *
+ * Context: the wire has one set of rules, the backend's, and every platform writes and reads it
+ * the same — that is why it lives here and not in each client:
+ *
+ * - a decimal is text (`"10.50"`): a `Decimal`, a `Money`'s amount, a `bigint` — never a float;
+ * - a day is text (`"2026-10-02"`) and stays text: a `Date` is always an instant, written as one;
+ * - an instant is ISO text (`Date` → `toISOString()`);
+ * - bytes are `{"$bytes": "<base64>"}`, so binary is never mistaken for text;
+ * - a value that says how it travels (`toJSON`) is written that way: `Money`, `Decimal`, `Date`;
+ * - a map is an object with text keys; a set or a list, a list.
+ *
+ * Not restrictive, like the backend: reading keeps every key it finds — what a reader does not
+ * know it ignores, never refuses — and a typed read is asked for, never imposed (`rebuilt(values,
+ * Money)`). What JSON cannot write (a function, `NaN`, a cycle) is refused at once, naming where,
+ * rather than sent as `null`.
+ */
+/** A value JSON writes as it is. */
+export type JsonValue = null | boolean | number | string | JsonValue[] | {
+    [key: string]: JsonValue;
+};
+/** The tag bytes travel under. */
+export declare const BYTES = "$bytes";
+/** What `rebuilt` reads values as: a class with `fromJSON` (`Money`), or a function. */
+export type Rebuild<T> = {
+    fromJSON(values: unknown): T;
+} | ((values: unknown) => T);
+/**
+ * `value` as JSON values, by the wire's rules. `undefined` is left out of an object and written
+ * `null` in a list, as JSON does.
+ */
+export declare function valuesOf(value: unknown): JsonValue;
+/** What `valuesOf` wrote, from JSON text or already parsed — each tagged bytes back as bytes. */
+export declare function readValues(text: string | unknown): unknown;
+/** `values` read as `of` — `Money`, a DTO's own reader — or as they are without one. */
+export declare function rebuilt<T = unknown>(values: unknown, of?: Rebuild<T>): T;
+/** `value` as JSON text — see `valuesOf`. */
+export declare function pack(value: unknown): string;
+/** What `pack` wrote, read as `of` — see `rebuilt`. */
+export declare function unpack<T = unknown>(text: string, of?: Rebuild<T>): T;