@sincpro/client-framework 0.3.0 → 0.5.0

package/dist/codegen/domain.js

@@ -1,4 +1,4 @@
-import { claimed, contextOf, deprecationOf, docOf, headerOf, identifierOf, keyOf, localOf, sorted, } from "./names.js";
+import { answerOf, claimed, contextOf, deprecationOf, docOf, headerOf, identifierOf, keyOf, localOf, sorted, } from "./names.js";
 /**
  * The DTOs of a bounded context as TypeScript, out of the contract sincpro_framework exports:
  * a type per model, per shared definition a model or an operation reaches, and per operation's
@@ -150,7 +150,8 @@ function operationDoc(metamodel, local, operation) {
  *
  * 1. The models, by name: an entity's contract, a related model by its own name.
  * 2. Each operation, by its local name (its identity without `<context>.`): its input as
- *    `<Name>` and its answer as `<Name>Answer`.
+ *    `<Name>` and its answer by the backend's own name for it (`answerOf`: `ResponseX`), with
+ *    `<Name>Answer` kept as a deprecated alias — or as `<Name>Answer` when it has no name.
  * 3. The shared definitions those reach — and the ones those reach, until none is new —, but
  *    never one a package of the stack already types (`Criteria`).
  * Final: a header that says where it came from and not to edit it, the imports, then models,
@@ -165,15 +166,26 @@ export function domainFileOf(metamodel) {
         claim(identifierOf(name), `model ${name}`);
         return `${docOf([schema.description], "")}export type ${identifierOf(name)} = ${typeOf(schema, scope, 0, true)};`;
     });
+    // A Response two Commands share is written once, under the first that answers with it.
+    const answered = new Set();
     const operations = sorted(metamodel.operations).flatMap(([identity, operation]) => {
         const local = localOf(metamodel, identity);
+        const named = answerOf(metamodel, identity);
         claim(local, `operation ${identity}`);
-        claim(`${local}Answer`, `the answer of ${identity}`);
         const answer = operation.output === null ? "unknown" : typeOf(operation.output, scope, 0, false);
-        return [
+        const written = [
             `${operationDoc(metamodel, local, operation)}export type ${local} = ${typeOf(operation.input, scope, 0, false)};`,
-            `/** What \`${local}\` answers. */\nexport type ${local}Answer = ${answer};`,
         ];
+        if (!answered.has(named)) {
+            answered.add(named);
+            claim(named, `the answer of ${identity}`);
+            written.push(`/** What \`${local}\` answers. */\nexport type ${named} = ${answer};`);
+        }
+        if (named !== `${local}Answer`) {
+            claim(`${local}Answer`, `the old name of the answer of ${identity}`);
+            written.push(`/** @deprecated The backend calls it \`${named}\`: use that name. */\nexport type ${local}Answer = ${named};`);
+        }
+        return written;
     });
     const written = new Map();
     for (let pending = [...scope.reached]; pending.length > 0;) {

package/dist/codegen/entities.js

@@ -1,5 +1,5 @@
 import { entityKeyOf } from "../client/contract.js";
-import { aliasOf, claimed, DOMAIN_MODULE, FRAMEWORK, headerOf, identifierOf, isEntity, localOf, methodOf, pluralOf, sorted, } from "./names.js";
+import { aliasOf, answerOf, claimed, DOMAIN_MODULE, FRAMEWORK, headerOf, identifierOf, isEntity, localOf, methodOf, pluralOf, sorted, } from "./names.js";
 import { ownerOf, restOf, WRITES, } from "./rest.js";
 /** The one operation of `role` for `entity` a transport can call, by `own` when there are many. */
 function oneOf(candidates, role) {
@@ -37,7 +37,14 @@ function entitySourceOf(metamodel, model, domain, options, claim) {
         const rest = restOf(metamodel, identity, options);
         return rest === undefined
             ? []
-            : [{ local: localOf(metamodel, identity), operation, rest }];
+            : [
+                {
+                    local: localOf(metamodel, identity),
+                    answer: answerOf(metamodel, identity),
+                    operation,
+                    rest,
+                },
+            ];
     });
     const reads = (role, method) => reached.filter((one) => one.operation.role === role &&
         method(one.rest.method) &&
@@ -88,7 +95,7 @@ function entitySourceOf(metamodel, model, domain, options, claim) {
         bodies.push(target === undefined
             ? `    ${method}: dto.${command.local};`
             : `    ${method}: Omit<dto.${command.local}, ${JSON.stringify(target)}>;`);
-        answers.push(`    ${method}: dto.${command.local}Answer;`);
+        answers.push(`    ${method}: dto.${command.answer};`);
         named.push(target === undefined
             ? `    ${method}: ${JSON.stringify(route)},`
             : `    ${method}: { route: ${JSON.stringify(route)}, target: ${JSON.stringify(target)} },`);

package/dist/codegen/index.d.ts

@@ -3,8 +3,10 @@
  * sincpro_framework exports (PRD_01 phase B). A build step that runs in Node — nothing in
  * the runtime imports it (`make doctor`), and the package's root entry does not re-export it. `sincpro-client generate` (`cli.ts`) is the same, from a terminal.
  */
+export { CheckError, checkImports, type Place, placeOf, type Violation, violationOf, } from "./check.js";
 export { clientFileOf } from "./client.js";
 export { domainFileOf } from "./domain.js";
 export { entitiesFileOf } from "./entities.js";
 export type { Bindings, Metamodel, Operation, RestBinding, Schema, } from "./metamodel.js";
 export type { GenerateOptions } from "./rest.js";
+export { scaffoldFilesOf, type ScaffoldOptions, } from "./scaffold.js";

package/dist/codegen/index.js

@@ -3,6 +3,8 @@
  * sincpro_framework exports (PRD_01 phase B). A build step that runs in Node — nothing in
  * the runtime imports it (`make doctor`), and the package's root entry does not re-export it. `sincpro-client generate` (`cli.ts`) is the same, from a terminal.
  */
+export { CheckError, checkImports, placeOf, violationOf, } from "./check.js";
 export { clientFileOf } from "./client.js";
 export { domainFileOf } from "./domain.js";
 export { entitiesFileOf } from "./entities.js";
+export { scaffoldFilesOf, } from "./scaffold.js";

package/dist/codegen/names.d.ts

@@ -21,6 +21,18 @@ export declare function aliasOf(metamodel: Metamodel): string;
 export declare function isEntity(metamodel: Metamodel, model: string): boolean;
 /** An operation's name in its context: its identity without `<bounded_context>.`. */
 export declare function localOf(metamodel: Metamodel, identity: string): string;
+/**
+ * What an operation's answer is called: the backend's own name for it — its output's title,
+ * `ResponseCancelIssue` — when that name is one type (every output with it is the same schema)
+ * and no other type has it; `<Name>Answer` when the output has no name of its own (a model, a
+ * list) or two different shapes share it. A new operation answering with the same Response keeps
+ * the name: regenerating never renames by itself.
+ *
+ * Context: the ubiquitous language. The backend writes `CommandCancelIssue` → `ResponseCancelIssue`,
+ * and a client that calls it `CommandCancelIssueAnswer` makes a person learn two words for one
+ * thing. The `<Name>Answer` it used to write stays as a deprecated alias of the backend's name.
+ */
+export declare function answerOf(metamodel: Metamodel, identity: string): string;
 /** The method an operation is called by: `CommandSendIssue` → `sendIssue`. */
 export declare function methodOf(local: string): string;
 /** `Issue` → `issues`, `ProjectEvent` → `projectEvents`, `Policy` → `policies`. */

package/dist/codegen/names.js

@@ -52,6 +52,64 @@ export function localOf(metamodel, identity) {
     const prefix = `${contextOf(metamodel)}.`;
     return identifierOf(identity.startsWith(prefix) ? identity.slice(prefix.length) : identity);
 }
+const ANSWERS = new WeakMap();
+/** The output's own name, when it has one a TypeScript type can take. */
+function titleOf(output) {
+    if (output === null || output.$ref !== undefined)
+        return undefined;
+    const title = output.title;
+    return typeof title === "string" && /^[A-Za-z_$][\w$]*$/.test(title) ? title : undefined;
+}
+function answersOf(metamodel) {
+    const operations = Object.entries(metamodel.operations);
+    const taken = new Set([
+        ...Object.keys(metamodel.models).map(identifierOf),
+        ...Object.keys(metamodel.$defs ?? {}).map(identifierOf),
+    ]);
+    for (const [identity] of operations) {
+        const local = localOf(metamodel, identity);
+        taken.add(local);
+        taken.add(`${local}Answer`);
+    }
+    // A title is one type when every output that carries it is the same schema — the backend
+    // answering two Commands with one Response class; two different schemas under one title are
+    // two types, and neither takes the name.
+    const shapes = new Map();
+    for (const [, operation] of operations) {
+        const title = titleOf(operation.output);
+        if (title === undefined)
+            continue;
+        const seen = shapes.get(title) ?? new Set();
+        seen.add(JSON.stringify(operation.output));
+        shapes.set(title, seen);
+    }
+    const names = new Map();
+    for (const [identity, operation] of operations) {
+        const title = titleOf(operation.output);
+        if (title !== undefined && shapes.get(title)?.size === 1 && !taken.has(title))
+            names.set(identity, title);
+    }
+    return names;
+}
+/**
+ * What an operation's answer is called: the backend's own name for it — its output's title,
+ * `ResponseCancelIssue` — when that name is one type (every output with it is the same schema)
+ * and no other type has it; `<Name>Answer` when the output has no name of its own (a model, a
+ * list) or two different shapes share it. A new operation answering with the same Response keeps
+ * the name: regenerating never renames by itself.
+ *
+ * Context: the ubiquitous language. The backend writes `CommandCancelIssue` → `ResponseCancelIssue`,
+ * and a client that calls it `CommandCancelIssueAnswer` makes a person learn two words for one
+ * thing. The `<Name>Answer` it used to write stays as a deprecated alias of the backend's name.
+ */
+export function answerOf(metamodel, identity) {
+    let known = ANSWERS.get(metamodel);
+    if (known === undefined) {
+        known = answersOf(metamodel);
+        ANSWERS.set(metamodel, known);
+    }
+    return known.get(identity) ?? `${localOf(metamodel, identity)}Answer`;
+}
 /** The method an operation is called by: `CommandSendIssue` → `sendIssue`. */
 export function methodOf(local) {
     const bare = local.replace(/^(Command|Query)(?=[A-Z])/, "");

package/dist/codegen/scaffold.d.ts

@@ -0,0 +1,24 @@
+import type { Metamodel } from "./metamodel.js";
+/**
+ * A bounded context's skeleton, written ONCE beside what is generated — the files that are the
+ * application's from then on:
+ *
+ *     domains/project/
+ *       generated/                         `sincpro-client generate` — regenerated, never edited
+ *       infrastructure/dependencies.ts     what the services can count on: the generated client
+ *       infrastructure/bounded_context.ts  its Feature and ApplicationService, and how it is made
+ *       services/index.ts                  the services, by the name each is reached by
+ *       index.ts                           `export const project` — ready to use
+ *
+ * Context: the layout sincpro_framework gives a service (`dependencies.py`, `framework.py`,
+ * `services/`, `__init__.py`), so a bounded context starts the way every other does and nobody
+ * copies it by hand from another. It is the application's to change: the CLI writes a file only
+ * when it is not there, and never touches one that is — unlike `generated/`, which is written
+ * whole every time.
+ */
+export type ScaffoldOptions = {
+    /** Where the application's transport is exported (`export const transport`), from the
+     *  bounded context's folder. `../common/infrastructure/transport` by default. */
+    transport?: string;
+};
+export declare function scaffoldFilesOf(metamodel: Metamodel, options?: ScaffoldOptions): Record<string, string>;

package/dist/codegen/scaffold.js

@@ -0,0 +1,123 @@
+import { aliasOf, FRAMEWORK } from "./names.js";
+/** Names the skeleton's `index.ts` cannot give its constant. */
+const TAKEN = new Set([
+    "transport",
+    "features",
+    "applicationServices",
+    ..."break case catch class const continue debugger default delete do else enum export extends false finally for function if import in instanceof new null return super switch this throw true try typeof var void while with yield let static implements interface package private protected public await".split(" "),
+]);
+/** `sales-orders` → `SalesOrders`. */
+function pascalOf(alias) {
+    const joined = alias
+        .split(/[^A-Za-z0-9]+/)
+        .filter((one) => one !== "")
+        .map((one) => `${one.charAt(0).toUpperCase()}${one.slice(1)}`)
+        .join("");
+    return joined === "" ? "Context" : /^[0-9]/.test(joined) ? `_${joined}` : joined;
+}
+/** A module the skeleton imports, built in parts — see `FRAMEWORK` (`codegen/names.ts`). */
+const at = (...parts) => parts.join("/");
+const HEADER = (what) => `// ${what} — written once by \`sincpro-client scaffold\`; the application's to change.`;
+export function scaffoldFilesOf(metamodel, options = {}) {
+    const alias = aliasOf(metamodel);
+    const Name = pascalOf(alias);
+    const bare = `${Name.charAt(0).toLowerCase()}${Name.slice(1)}`;
+    // A word the language keeps (`import`, `default`) or a name `index.ts` already imports cannot
+    // be the constant's: it takes the bounded context's word instead.
+    const name = TAKEN.has(bare) ? `${bare}BoundedContext` : bare;
+    const Dependencies = `${Name}Dependencies`;
+    const client = metamodel.bindings !== undefined;
+    const transport = options.transport ?? at("..", "common", "infrastructure", "transport");
+    const dependencies = [
+        HEADER(`What the services of «${alias}» can count on`),
+        "",
+        `import type { Transport, UseBoundedContext } from "${FRAMEWORK}";`,
+        ...(client ? ["", `import { clientOf } from "${at("..", "generated", "client")}";`] : []),
+        "",
+        `/** What every service of «${alias}» finds on \`this\`${client ? ": `this.client`, the service's operations" : ""}. */`,
+        `export interface ${Dependencies} {`,
+        ...(client
+            ? ["  client: ReturnType<typeof clientOf>;"]
+            : [
+                "  /** What the services need: a repository, an adapter, another bounded context. */",
+            ]),
+        "}",
+        "",
+        "export function registerDependencies(",
+        `  bc: UseBoundedContext<${Dependencies}>,`,
+        `  ${client ? "transport" : "_transport"}: Transport,`,
+        ") {",
+        ...(client ? [`  bc.addDependency("client", clientOf(transport));`] : []),
+        "  return bc;",
+        "}",
+        "",
+    ].join("\n");
+    const boundedContext = [
+        HEADER(`How «${alias}» is made`),
+        "",
+        "import {",
+        "  ApplicationService as BaseApplicationService,",
+        "  Feature as BaseFeature,",
+        "  type Transport,",
+        "  UseBoundedContext,",
+        `} from "${FRAMEWORK}";`,
+        "",
+        `import type { ${Name}Features } from "${at("..", "services")}";`,
+        `import { type ${Dependencies}, registerDependencies } from "${at(".", "dependencies")}";`,
+        "",
+        `/** A Feature of «${alias}»: its dependencies typed on \`this\`, and \`this.context\`. */`,
+        `export class Feature extends BaseFeature<${Dependencies}> {}`,
+        "",
+        `/** An ApplicationService of «${alias}»: the same, and \`this.feature.<Name>\` for each Feature. */`,
+        "export class ApplicationService extends BaseApplicationService<",
+        `  ${Dependencies},`,
+        `  ${Name}Features`,
+        "> {}",
+        "",
+        `export function config${Name}BoundedContext(name: string, transport: Transport) {`,
+        `  return registerDependencies(new UseBoundedContext<${Dependencies}>(name), transport);`,
+        "}",
+        "",
+    ].join("\n");
+    const services = [
+        HEADER(`What «${alias}» offers`),
+        "",
+        "/**",
+        ` * Each service by the name it is reached by — \`${name}.Issues.close(…)\`. A Feature groups the`,
+        " * operations of one part of the domain; an ApplicationService composes the Features:",
+        " *",
+        " *     // services/issues.ts",
+        ` *     export class Issues extends Feature {`,
+        " *       close(input: dto.CommandCloseIssue) {",
+        " *         return this.client.closeIssue(input);",
+        " *       }",
+        " *     }",
+        " */",
+        "export const features = {};",
+        "export const applicationServices = {};",
+        "",
+        `export type ${Name}Features = typeof features;`,
+        "",
+    ].join("\n");
+    const index = [
+        HEADER(`«${alias}», ready to use`),
+        "",
+        `import { transport } from "${transport}";`,
+        "",
+        `import { config${Name}BoundedContext } from "${at(".", "infrastructure", "bounded_context")}";`,
+        `import { applicationServices, features } from "${at(".", "services")}";`,
+        "",
+        `/** «${alias}»: \`${name}.<Service>.<method>(…)\` — from a screen, a test, another bounded context. */`,
+        `export const ${name} = config${Name}BoundedContext(${JSON.stringify(alias)}, transport).register({`,
+        "  features,",
+        "  applicationServices,",
+        "});",
+        "",
+    ].join("\n");
+    return {
+        "infrastructure/dependencies.ts": dependencies,
+        "infrastructure/bounded_context.ts": boundedContext,
+        "services/index.ts": services,
+        "index.ts": index,
+    };
+}

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,154 @@
+/**
+ * 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);
+}
+/** How many digits after the point a result keeps: a whole number from 0 up. */
+function decimalsGiven(decimals) {
+    if (!Number.isInteger(decimals) || decimals < 0)
+        throw new RangeError(`${decimals} decimals: a decimal keeps 0 or more whole digits after the point`);
+    return decimals;
+}
+/** `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) {
+        decimalsGiven(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) {
+        decimalsGiven(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;
+}