@sincpro/client-framework 0.3.0 → 0.5.0

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,53 @@
+/**
+ * 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. A
+ * string is JSON text: to read values that were written but never sent, go through `pack`
+ * (`readValues(pack(value))`), as the in-memory transport does.
+ */
+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;

package/dist/common/serialization.js

@@ -0,0 +1,168 @@
+/**
+ * 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`.
+ */
+/** The tag bytes travel under. */
+export const BYTES = "$bytes";
+const ALPHABET = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/";
+/** Base64 by hand: `btoa` is not on every platform this runs on. */
+function base64Of(bytes) {
+    let text = "";
+    for (let at = 0; at < bytes.length; at += 3) {
+        const [a = 0, b = 0, c = 0] = [bytes[at], bytes[at + 1], bytes[at + 2]];
+        const triple = (a << 16) | (b << 8) | c;
+        const letter = (shift) => ALPHABET.charAt((triple >> shift) & 63);
+        text += letter(18) + letter(12);
+        text += at + 1 < bytes.length ? letter(6) : "=";
+        text += at + 2 < bytes.length ? letter(0) : "=";
+    }
+    return text;
+}
+function bytesOf(text) {
+    const clean = text.replace(/[^A-Za-z0-9+/]/g, "");
+    const bytes = new Uint8Array(Math.floor((clean.length * 3) / 4));
+    let filled = 0;
+    for (let at = 0; at < clean.length; at += 4) {
+        const [a = 0, b = 0, c = 0, d = 0] = [0, 1, 2, 3].map((one) => ALPHABET.indexOf(clean[at + one] ?? "A"));
+        const triple = (a << 18) | (b << 12) | (c << 6) | d;
+        for (const shift of [16, 8, 0])
+            if (filled < bytes.length)
+                bytes[filled++] = (triple >> shift) & 255;
+    }
+    return bytes;
+}
+function isBytes(value) {
+    return value instanceof ArrayBuffer || ArrayBuffer.isView(value);
+}
+/** Any binary — a `Uint8Array`, another typed array, a `DataView`, a buffer — as its bytes. */
+function asBytes(value) {
+    if (value instanceof Uint8Array)
+        return value;
+    if (value instanceof ArrayBuffer)
+        return new Uint8Array(value);
+    return new Uint8Array(value.buffer, value.byteOffset, value.byteLength);
+}
+function written(value, where, seen) {
+    if (value === null || typeof value === "string" || typeof value === "boolean")
+        return value;
+    if (value === undefined)
+        return undefined;
+    if (typeof value === "number") {
+        if (!Number.isFinite(value))
+            throw new TypeError(`${where}: ${value} cannot travel as JSON`);
+        return value;
+    }
+    if (typeof value === "bigint")
+        return value.toString();
+    if (typeof value === "function" || typeof value === "symbol")
+        throw new TypeError(`${where}: a ${typeof value} cannot travel as JSON`);
+    if (isBytes(value))
+        return { [BYTES]: base64Of(asBytes(value)) };
+    const object = value;
+    if (seen.has(object))
+        throw new TypeError(`${where}: a cycle cannot travel as JSON`);
+    seen.add(object);
+    try {
+        const own = object.toJSON;
+        if (typeof own === "function") {
+            const said = own.call(object);
+            // A `toJSON` that answers the object itself says nothing new: it is written as an object.
+            // Still in `seen` while what it said is written: `{ self: this }` is a cycle, not a loop.
+            if (said !== object)
+                return written(said, where, seen);
+        }
+        if (object instanceof Map)
+            return Object.fromEntries([...object].flatMap(([key, one]) => {
+                const done = written(one, `${where}.${String(key)}`, seen);
+                return done === undefined ? [] : [[String(key), done]];
+            }));
+        if (object instanceof Set || Array.isArray(object))
+            return [...object].map((one, at) => written(one, `${where}[${at}]`, seen) ?? null);
+        const entries = [];
+        for (const [key, one] of Object.entries(object)) {
+            // Its own way to travel is not a value of it.
+            if (key === "toJSON" && typeof one === "function")
+                continue;
+            const done = written(one, `${where}.${key}`, seen);
+            if (done !== undefined)
+                entries.push([key, done]);
+        }
+        return Object.fromEntries(entries);
+    }
+    finally {
+        seen.delete(object);
+    }
+}
+/**
+ * `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 function valuesOf(value) {
+    return written(value, "value", new Set()) ?? null;
+}
+/** One JSON object back as what it stood for: a lone `$bytes` tag is its bytes. */
+function restored(object) {
+    const keys = Object.keys(object);
+    if (keys.length === 1 && keys[0] === BYTES && typeof object[BYTES] === "string")
+        return bytesOf(object[BYTES]);
+    return object;
+}
+function walked(value) {
+    if (Array.isArray(value))
+        return value.map(walked);
+    if (value !== null && typeof value === "object")
+        return restored(Object.fromEntries(Object.entries(value).map(([key, one]) => [key, walked(one)])));
+    return value;
+}
+/**
+ * What `valuesOf` wrote, from JSON text or already parsed — each tagged bytes back as bytes. A
+ * string is JSON text: to read values that were written but never sent, go through `pack`
+ * (`readValues(pack(value))`), as the in-memory transport does.
+ */
+export function readValues(text) {
+    if (typeof text === "string")
+        return JSON.parse(text, (_key, value) => value !== null && typeof value === "object" && !Array.isArray(value)
+            ? restored(value)
+            : value);
+    return walked(text);
+}
+/** `values` read as `of` — `Money`, a DTO's own reader — or as they are without one. */
+export function rebuilt(values, of) {
+    if (of === undefined)
+        return values;
+    // A class is a function too: one that says how to read itself is read that way.
+    const reader = of.fromJSON;
+    if (typeof reader === "function")
+        return reader.call(of, values);
+    return of(values);
+}
+/** `value` as JSON text — see `valuesOf`. */
+export function pack(value) {
+    return JSON.stringify(valuesOf(value));
+}
+/** What `pack` wrote, read as `of` — see `rebuilt`. */
+export function unpack(text, of) {
+    return rebuilt(readValues(text), of);
+}

package/dist/common/time.d.ts

@@ -0,0 +1,41 @@
+/**
+ * A day and an instant, as the server sends them — and the two conversions every client needs:
+ * the server's instant to the wall clock of a zone, and back.
+ *
+ *     installTimeZone("America/La_Paz");                       once, for the company in use
+ *     wallTimeOf("2026-03-12T14:30:00Z", timeZoneNow())   →  "2026-03-12T10:30"
+ *     instantOf("2026-03-12T10:30", timeZoneNow())        →  "2026-03-12T14:30:00.000Z"
+ *
+ * Context: sincpro_framework sends a `datetime` as an instant (`2026-03-12T14:30:00Z`) and a
+ * `date` as a day of the calendar (`2026-03-12`). A person reads and types the wall clock of
+ * where the business is (10:30 in La Paz), on a browser or on a phone alike, so the conversion
+ * is this package's and every platform draws with it. Which zone belongs to whoever is above the
+ * screens — the application, the company the user works in — so it is installed once and every
+ * instant follows it; without it, the platform's own. A day is never converted: turned into an
+ * instant it lands on the day before west of Greenwich.
+ *
+ * Only `Intl.DateTimeFormat` with time zones is asked of the platform: browsers, Node and
+ * Hermes (React Native) have it.
+ */
+/** Install the time zone dates and times are read and written in (IANA: `"America/La_Paz"`);
+ *  `undefined` goes back to the platform's. */
+export declare function installTimeZone(timeZone: string | undefined): void;
+/** The time zone in use. */
+export declare function timeZoneNow(): string;
+/** `"2026-03-12T14:30:00Z"` → `"2026-03-12T10:30"` in `America/La_Paz`: the wall clock there,
+ *  as a date-and-time control reads it. `null` when it is not an instant. */
+export declare function wallTimeOf(instant: string, timeZone: string): string | null;
+/**
+ * `"2026-03-12T10:30"` on the wall clock of `timeZone` → the instant, `"2026-03-12T14:30:00.000Z"`.
+ * `null` when it is not a wall time.
+ *
+ * Context: the offset depends on the instant (daylight saving), so it is asked twice: at the
+ * first guess, and again at the answer when the guess fell on the other side of a change.
+ */
+export declare function instantOf(wall: string, timeZone: string): string | null;
+/** A day of the calendar as the server writes it: `"2026-03-12"` — never an instant, never a day
+ *  the calendar does not have (`"2026-02-30"`, which `Date` would roll into March). */
+export declare function isDay(text: string): boolean;
+/** The day it is at `instant` on the wall clock of `timeZone`: what «today» means for a company.
+ *  `null` when it is not an instant. */
+export declare function dayOf(instant: string, timeZone: string): string | null;

package/dist/common/time.js

@@ -0,0 +1,100 @@
+/**
+ * A day and an instant, as the server sends them — and the two conversions every client needs:
+ * the server's instant to the wall clock of a zone, and back.
+ *
+ *     installTimeZone("America/La_Paz");                       once, for the company in use
+ *     wallTimeOf("2026-03-12T14:30:00Z", timeZoneNow())   →  "2026-03-12T10:30"
+ *     instantOf("2026-03-12T10:30", timeZoneNow())        →  "2026-03-12T14:30:00.000Z"
+ *
+ * Context: sincpro_framework sends a `datetime` as an instant (`2026-03-12T14:30:00Z`) and a
+ * `date` as a day of the calendar (`2026-03-12`). A person reads and types the wall clock of
+ * where the business is (10:30 in La Paz), on a browser or on a phone alike, so the conversion
+ * is this package's and every platform draws with it. Which zone belongs to whoever is above the
+ * screens — the application, the company the user works in — so it is installed once and every
+ * instant follows it; without it, the platform's own. A day is never converted: turned into an
+ * instant it lands on the day before west of Greenwich.
+ *
+ * Only `Intl.DateTimeFormat` with time zones is asked of the platform: browsers, Node and
+ * Hermes (React Native) have it.
+ */
+let installed;
+/** Install the time zone dates and times are read and written in (IANA: `"America/La_Paz"`);
+ *  `undefined` goes back to the platform's. */
+export function installTimeZone(timeZone) {
+    installed = timeZone;
+}
+/** The time zone in use. */
+export function timeZoneNow() {
+    return installed ?? Intl.DateTimeFormat().resolvedOptions().timeZone;
+}
+const clocks = new Map();
+/** One formatter per zone, kept: building one costs far more than using it. */
+function clockOf(timeZone) {
+    let clock = clocks.get(timeZone);
+    if (clock === undefined) {
+        clock = new Intl.DateTimeFormat("en-US", {
+            timeZone,
+            hourCycle: "h23",
+            year: "numeric",
+            month: "2-digit",
+            day: "2-digit",
+            hour: "2-digit",
+            minute: "2-digit",
+            second: "2-digit",
+        });
+        clocks.set(timeZone, clock);
+    }
+    return clock;
+}
+/** The wall clock of `timeZone` at `at` (ms), as the fields of a UTC date: what to compare. */
+function wallAt(at, timeZone) {
+    const parts = Object.fromEntries(clockOf(timeZone)
+        .formatToParts(new Date(at))
+        .map((part) => [part.type, part.value]));
+    return Date.UTC(Number(parts["year"]), Number(parts["month"]) - 1, Number(parts["day"]), Number(parts["hour"]), Number(parts["minute"]), Number(parts["second"]));
+}
+const pad = (n) => String(n).padStart(2, "0");
+/** `"2026-03-12T14:30:00Z"` → `"2026-03-12T10:30"` in `America/La_Paz`: the wall clock there,
+ *  as a date-and-time control reads it. `null` when it is not an instant. */
+export function wallTimeOf(instant, timeZone) {
+    // A day alone is not an instant: `Date` would read it as midnight in UTC, the day before here.
+    if (!/T\d{2}:\d{2}/.test(instant))
+        return null;
+    const at = Date.parse(instant);
+    if (Number.isNaN(at))
+        return null;
+    const wall = new Date(wallAt(at, timeZone));
+    return (`${wall.getUTCFullYear()}-${pad(wall.getUTCMonth() + 1)}-${pad(wall.getUTCDate())}` +
+        `T${pad(wall.getUTCHours())}:${pad(wall.getUTCMinutes())}`);
+}
+/**
+ * `"2026-03-12T10:30"` on the wall clock of `timeZone` → the instant, `"2026-03-12T14:30:00.000Z"`.
+ * `null` when it is not a wall time.
+ *
+ * Context: the offset depends on the instant (daylight saving), so it is asked twice: at the
+ * first guess, and again at the answer when the guess fell on the other side of a change.
+ */
+export function instantOf(wall, timeZone) {
+    const match = /^(\d{4})-(\d{2})-(\d{2})T(\d{2}):(\d{2})/.exec(wall);
+    if (match === null)
+        return null;
+    const [, year, month, day, hour, minute] = match.map(Number);
+    const guess = Date.UTC(year, month - 1, day, hour, minute);
+    const first = guess - (wallAt(guess, timeZone) - guess);
+    const second = guess - (wallAt(first, timeZone) - first);
+    return new Date(second).toISOString();
+}
+const DAY = /^\d{4}-\d{2}-\d{2}$/;
+/** A day of the calendar as the server writes it: `"2026-03-12"` — never an instant, never a day
+ *  the calendar does not have (`"2026-02-30"`, which `Date` would roll into March). */
+export function isDay(text) {
+    if (!DAY.test(text))
+        return false;
+    const at = Date.parse(`${text}T00:00:00Z`);
+    return !Number.isNaN(at) && new Date(at).toISOString().slice(0, 10) === text;
+}
+/** The day it is at `instant` on the wall clock of `timeZone`: what «today» means for a company.
+ *  `null` when it is not an instant. */
+export function dayOf(instant, timeZone) {
+    return wallTimeOf(instant, timeZone)?.slice(0, 10) ?? null;
+}

package/dist/context/codec.d.ts

@@ -0,0 +1,26 @@
+import type { ContextValues } from "./store.js";
+/**
+ * How a context is written to text and read back: what a `ContextStore` that persists uses
+ * (`sessionStorage`, MMKV), and what travels to the server in `sincpro-context`.
+ *
+ *     plainCodec.dumps({ tenant_id: "acme", company_id: 2, session: socket })
+ *       →  '{"tenant_id":"acme","company_id":2}'
+ *     plainCodec.loads('{"tenant_id":"acme"}')   →  { tenant_id: "acme" }
+ *
+ * Context: sincpro_framework's `ContextCodec`, and its `PlainCodec` — the one for anything outside
+ * the codebase: another language, a browser, a phone. Only the travelling values go — text,
+ * numbers, booleans, `null`, and lists of them; an object, a function or a connection held in the
+ * context stays where it is. Reading never fails a context whole: text that is not a JSON object
+ * reads as an empty one. A project with a schema of its own writes its own codec over this port.
+ */
+/** The header the context travels in: the one sincpro_framework's entrances read. */
+export declare const CONTEXT_HEADER = "sincpro-context";
+export interface ContextCodec {
+    dumps(values: ContextValues): string;
+    loads(text: string): ContextValues;
+}
+/** Whether a value travels: a plain value, or a list of them. */
+export declare function travels(value: unknown): boolean;
+/** The values of `context` that travel; the rest stays in this process. */
+export declare function travelling(context: ContextValues): ContextValues;
+export declare const plainCodec: ContextCodec;

package/dist/context/codec.js

@@ -0,0 +1,44 @@
+/**
+ * How a context is written to text and read back: what a `ContextStore` that persists uses
+ * (`sessionStorage`, MMKV), and what travels to the server in `sincpro-context`.
+ *
+ *     plainCodec.dumps({ tenant_id: "acme", company_id: 2, session: socket })
+ *       →  '{"tenant_id":"acme","company_id":2}'
+ *     plainCodec.loads('{"tenant_id":"acme"}')   →  { tenant_id: "acme" }
+ *
+ * Context: sincpro_framework's `ContextCodec`, and its `PlainCodec` — the one for anything outside
+ * the codebase: another language, a browser, a phone. Only the travelling values go — text,
+ * numbers, booleans, `null`, and lists of them; an object, a function or a connection held in the
+ * context stays where it is. Reading never fails a context whole: text that is not a JSON object
+ * reads as an empty one. A project with a schema of its own writes its own codec over this port.
+ */
+/** The header the context travels in: the one sincpro_framework's entrances read. */
+export const CONTEXT_HEADER = "sincpro-context";
+function isPlain(value) {
+    return (value === null ||
+        typeof value === "string" ||
+        typeof value === "boolean" ||
+        (typeof value === "number" && Number.isFinite(value)));
+}
+/** Whether a value travels: a plain value, or a list of them. */
+export function travels(value) {
+    return isPlain(value) || (Array.isArray(value) && value.every(isPlain));
+}
+/** The values of `context` that travel; the rest stays in this process. */
+export function travelling(context) {
+    return Object.fromEntries(Object.entries(context).filter(([, value]) => travels(value)));
+}
+export const plainCodec = {
+    dumps: (values) => JSON.stringify(travelling(values)),
+    loads(text) {
+        try {
+            const found = JSON.parse(text);
+            return found !== null && typeof found === "object" && !Array.isArray(found)
+                ? found
+                : {};
+        }
+        catch {
+            return {};
+        }
+    },
+};

package/dist/index.d.ts

@@ -6,8 +6,10 @@
  * (`sideEffects: false`), so an application pays only for what it uses, and a use case, the
  * client it calls and the entity it reads come from the same place.
  *
+ *   common/   the values of the wire, as the backend writes them: ids, a day and an instant,
+ *             `Decimal`, `Money`, and how any value is written and read (`valuesOf`, `rebuilt`)
  *   client/   the seam with a server: the transport and its REST and in-memory implementations,
- *             entities with typed commands, the service's client contract, client-side ids
+ *             entities with typed commands, the service's client contract
  *   model/    model definitions: written by hand, read from a JSON Schema, kept once known
  *   services/ the bounded context (`UseBoundedContext`), its `Feature` and `ApplicationService`,
  *             the process they run in (`configureProcess`), what each run carries
@@ -19,11 +21,16 @@
  */
 export { type ClientContract, entityKeyOf, kindOf, metasOf, versionsOf, } from "./client/contract.js";
 export { bodyFor, type CommandAnswers, type CommandBodies, type CommandRoute, type Entity, entity, type EntityRef, type EntityRoutes, listRoute, NEW_PARAM, pathFor, PICK_PARAM, QUERY_PARAM, SCOPE_PARAM, scopeOfRef, startingValuesOf, type SummaryFields, type SummaryPart, TRAIL_PARAM, WITH_PARAM, type WriteRoute, writeRoute, } from "./client/entity.js";
-export { isEntityId, newEntityId } from "./client/ids.js";
 export { type MemoryOptions, type MemoryTable, memoryTransport, } from "./client/memory.js";
 export { type RestOptions, restTransport, urlOf, type VersionDrift, } from "./client/rest.js";
 export { type RetryKeys, retryKeys, unanswered, } from "./client/retry.js";
 export { type CallOptions, type Draft, type Method, type One, readRoute, type SendOptions, type Transport, TransportError, } from "./client/transport.js";
+export { Decimal, type DecimalLike } from "./common/decimal.js";
+export { isEntityId, momentOf, newEntityId } from "./common/ids.js";
+export { Money } from "./common/money.js";
+export { BYTES, type JsonValue, pack, readValues, type Rebuild, rebuilt, unpack, valuesOf, } from "./common/serialization.js";
+export { dayOf, installTimeZone, instantOf, isDay, timeZoneNow, wallTimeOf, } from "./common/time.js";
+export { CONTEXT_HEADER, type ContextCodec, plainCodec, travelling, travels, } from "./context/codec.js";
 export { type Context } from "./context/context.js";
 export { type ContextStore, type ContextValues, memoryContexts, } from "./context/store.js";
 export { defineMeta, field, type FieldOptions, type MetaSpec, type Words, } from "./model/meta.js";
@@ -34,3 +41,5 @@ export { type BoundedContext, UseBoundedContext, } from "./services/bounded-cont
 export { BIND, type Bindable, bindable, bindDependency, bindTransport, type Execution, headersOf, } from "./services/execution.js";
 export { ApplicationService, Feature, type ServiceClasses, type ServiceMethods, type Services, } from "./services/feature.js";
 export { configureProcess, outcomeOf, processContext, type ProcessOptions, } from "./services/process.js";
+export { reportError } from "./services/report.js";
+export { screensTransport } from "./services/screens.js";