@sincpro/client-framework 0.4.0 → 0.6.0

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/metamodel.d.ts

@@ -26,7 +26,11 @@ export type Schema = {
         type?: string;
         relation?: string | null;
         identity?: string;
+        /** A to-many whose records are other aggregates: listed and searched, never edited as lines. */
+        reference?: boolean;
     };
+    /** An answer that is bytes as they are produced (an export): the media types it may be. */
+    "x-sincpro-streamed"?: readonly string[];
 };
 export type Operation = {
     /** What it is for its entity: `search`, `get`, `edit`, `command`… */

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/collection.d.ts

@@ -0,0 +1,110 @@
+import type { AnyRecord, Count, Criteria } from "@sincpro/criteria";
+/**
+ * A to-many as a reading answers it — sincpro_framework's `EntityCollection`: the records, how
+ * many there are, and the cursor to go on inside this parent. Never a bare list, which would
+ * say the page is all there is.
+ *
+ *     customer.invoices   ->  { items: [i1, …, i40], count: { value: 1000, exact: false }, cursor: "eyJ…" }
+ *
+ * Context: a customer may have a million invoices, and the read brings forty of them with
+ * «at least a thousand» — the backend counts up to a cap (`RELATION_COUNT_CAP`) because an exact
+ * total reads every child. A screen that counted `items` showed forty and called it the total;
+ * one that iterated an array never knew there was more. The same type on every platform, so the
+ * web, the phone and a script read a relation the same way.
+ *
+ * `count` is `null` when the read asked for none (`CountMode.NONE`): the cursor alone says there
+ * is more. A collection is written back only whole — the backend refuses a page of it, because
+ * written back it would remove what it did not bring.
+ */
+export type EntityCollection<T> = {
+    readonly items: readonly T[];
+    readonly count?: Count | null;
+    readonly cursor?: string | null;
+};
+/**
+ * A collection with every part said — what `collectionOf` answers —, edited the way a string or
+ * a date is: `append`, `extend`, `remove` and `replace` answer a new collection and never change
+ * this one, as sincpro_framework's `EntityCollection` does.
+ *
+ *     const lines = collectionOf(invoice.lines);
+ *     const next = lines.append(newLine).remove(oldLine.id);   // lines is as it was
+ *
+ * An edit keeps what the collection says: a page stays a page (its cursor; a floor stays a
+ * floor), an exact count moves with what was added or removed. `remove` and `replace` of a record
+ * it does not hold throw, as Python's `list.remove` does. Written as JSON it is the wire's shape:
+ * `{ items, count, cursor }`.
+ */
+export declare class HeldCollection<T> implements EntityCollection<T> {
+    #private;
+    readonly items: readonly T[];
+    readonly count: Count | null;
+    readonly cursor: string | null;
+    constructor(items: readonly T[], count?: Count | null, cursor?: string | null, identity?: string);
+    /** How many records are held — this page, never the total (`count` is that). */
+    get length(): number;
+    /** Whether it holds less than there is (`isPartial`). */
+    get partial(): boolean;
+    [Symbol.iterator](): Iterator<T>;
+    /** A new collection with `records` at the end. */
+    append(...records: T[]): HeldCollection<T>;
+    /** A new collection with every one of `records` at the end, in order. */
+    extend(records: Iterable<T>): HeldCollection<T>;
+    /** A new collection without these records — each named by itself or by its identity. */
+    remove(...records: unknown[]): HeldCollection<T>;
+    /** A new collection where each of `records` takes the place of the held one with its identity. */
+    replace(...records: T[]): HeldCollection<T>;
+    toJSON(): EntityCollection<T>;
+}
+/** Whether `value` is a collection as a reading answers one (`{items, …}`). */
+export declare function isCollection(value: unknown): value is EntityCollection<unknown>;
+/**
+ * Whatever a relation arrived as, as a collection with every part said.
+ *
+ *     collectionOf({ items: [a, b], count: { value: 30, exact: true }, cursor: "x" })
+ *       -> the same, `cursor` and `count` said
+ *     collectionOf([a, b])        -> { items: [a, b], count: { value: 2, exact: true }, cursor: null }
+ *     collectionOf(undefined)     -> { items: [], count: { value: 0, exact: true }, cursor: null }
+ *
+ * An array — a domain written by hand, a record built in memory — holds all there is. `identity`
+ * is the field `remove` and `replace` match records by (the model's `identity`, `"id"`).
+ */
+export declare function collectionOf<T>(value: EntityCollection<T> | readonly T[] | null | undefined, identity?: string): HeldCollection<T>;
+/**
+ * Whether the collection holds less than there is — sincpro_framework's `is_partial`, the same
+ * rule: a cursor says there is more; no count claims nothing; a floor, or a count above what it
+ * holds, says there is more.
+ *
+ *     isPartial({ items: [a], cursor: "x" })                          -> true
+ *     isPartial({ items: [a], count: { value: 1000, exact: false } }) -> true
+ *     isPartial({ items: [a, b], count: { value: 2, exact: true } })  -> false
+ *     isPartial({ items: [a] })                                       -> false
+ */
+export declare function isPartial(collection: EntityCollection<unknown>): boolean;
+/**
+ * How many there are, as well as the collection knows: its count, or — when the read asked for
+ * none — what it holds, exact only when nothing says there is more.
+ *
+ *     totalOf({ items: [a, b], count: { value: 1000, exact: false } })  -> { value: 1000, exact: false }
+ *     totalOf({ items: [a, b], cursor: "x" })                           -> { value: 2, exact: false }
+ */
+export declare function totalOf(collection: EntityCollection<unknown>): Count;
+/** How a relation ties two records, as a model's definition says it (`FieldMeta`). */
+export type RelationKeys = {
+    identified_by?: string | null;
+    parent_field?: string | null;
+    related_field?: string | null;
+};
+/**
+ * The question «the related records of this one», over the related entity — sincpro_framework's
+ * `References.criteria()`: what pages a relation past what its record brought, searches it and
+ * orders it, a list like any other. `criteria` narrows it; it never widens it.
+ *
+ *     relatedCriteria(meta.fields.invoices, customer, "id")
+ *       -> { selection: { field: "customer_id", operator: "=", value: customer.id } }
+ *     relatedCriteria(field, customer, "id", { order: [{ field: "issued_on", descending: true }] })
+ *
+ * The two fields the definition names (`parent_field`, `related_field`) are read when it names
+ * them — a relation by a business key —; `identified_by` against the record's own key otherwise.
+ * A relation whose definition says neither cannot be asked, and says so.
+ */
+export declare function relatedCriteria<T extends AnyRecord>(keys: RelationKeys, record: AnyRecord, identity?: string, criteria?: Criteria<T>): Criteria<T>;

package/dist/common/collection.js

@@ -0,0 +1,169 @@
+/**
+ * A collection with every part said — what `collectionOf` answers —, edited the way a string or
+ * a date is: `append`, `extend`, `remove` and `replace` answer a new collection and never change
+ * this one, as sincpro_framework's `EntityCollection` does.
+ *
+ *     const lines = collectionOf(invoice.lines);
+ *     const next = lines.append(newLine).remove(oldLine.id);   // lines is as it was
+ *
+ * An edit keeps what the collection says: a page stays a page (its cursor; a floor stays a
+ * floor), an exact count moves with what was added or removed. `remove` and `replace` of a record
+ * it does not hold throw, as Python's `list.remove` does. Written as JSON it is the wire's shape:
+ * `{ items, count, cursor }`.
+ */
+export class HeldCollection {
+    items;
+    count;
+    cursor;
+    /** The field each record's identity is in — what `remove` and `replace` match by. */
+    #identity;
+    constructor(items, count = null, cursor = null, identity = "id") {
+        this.items = Object.freeze([...items]);
+        this.count = count;
+        this.cursor = cursor;
+        this.#identity = identity;
+        Object.freeze(this);
+    }
+    /** How many records are held — this page, never the total (`count` is that). */
+    get length() {
+        return this.items.length;
+    }
+    /** Whether it holds less than there is (`isPartial`). */
+    get partial() {
+        return isPartial(this);
+    }
+    [Symbol.iterator]() {
+        return this.items[Symbol.iterator]();
+    }
+    /** A new collection with `records` at the end. */
+    append(...records) {
+        return this.#edited([...this.items, ...records], records.length);
+    }
+    /** A new collection with every one of `records` at the end, in order. */
+    extend(records) {
+        return this.append(...records);
+    }
+    /** A new collection without these records — each named by itself or by its identity. */
+    remove(...records) {
+        const unwanted = new Set(records.map((one) => this.#keyOf(one)));
+        const held = new Set(this.items.map((one) => this.#keyOf(one)));
+        const missing = [...unwanted].filter((key) => !held.has(key));
+        if (missing.length > 0)
+            throw new Error(`not in the collection: ${missing.join(", ")}`);
+        return this.#edited(this.items.filter((one) => !unwanted.has(this.#keyOf(one))), -unwanted.size);
+    }
+    /** A new collection where each of `records` takes the place of the held one with its identity. */
+    replace(...records) {
+        const byKey = new Map(records.map((one) => [this.#keyOf(one), one]));
+        const held = new Set(this.items.map((one) => this.#keyOf(one)));
+        const missing = [...byKey.keys()].filter((key) => !held.has(key));
+        if (missing.length > 0)
+            throw new Error(`not in the collection: ${missing.join(", ")} — append adds a record`);
+        return this.#edited(this.items.map((one) => byKey.get(this.#keyOf(one)) ?? one), 0);
+    }
+    toJSON() {
+        return { items: this.items, count: this.count, cursor: this.cursor };
+    }
+    #keyOf(record) {
+        if (typeof record !== "object" || record === null)
+            return record;
+        const key = record[this.#identity];
+        // A record not stored yet has no identity: it is itself, never every other new one too.
+        return key === undefined || key === null || key === "" ? record : key;
+    }
+    #edited(items, moved) {
+        const count = this.count !== null && this.count.exact
+            ? { value: Math.max(this.count.value + moved, 0), exact: true }
+            : this.count;
+        return new HeldCollection(items, count, this.cursor, this.#identity);
+    }
+}
+/** Whether `value` is a collection as a reading answers one (`{items, …}`). */
+export function isCollection(value) {
+    if (typeof value !== "object" || value === null || Array.isArray(value))
+        return false;
+    if (!("items" in value))
+        return false;
+    const items = value.items;
+    // A page whose records did not come (`items: null`) is still a page: its count says so.
+    return Array.isArray(items) || items === null || items === undefined;
+}
+/**
+ * Whatever a relation arrived as, as a collection with every part said.
+ *
+ *     collectionOf({ items: [a, b], count: { value: 30, exact: true }, cursor: "x" })
+ *       -> the same, `cursor` and `count` said
+ *     collectionOf([a, b])        -> { items: [a, b], count: { value: 2, exact: true }, cursor: null }
+ *     collectionOf(undefined)     -> { items: [], count: { value: 0, exact: true }, cursor: null }
+ *
+ * An array — a domain written by hand, a record built in memory — holds all there is. `identity`
+ * is the field `remove` and `replace` match records by (the model's `identity`, `"id"`).
+ */
+export function collectionOf(value, identity = "id") {
+    if (value instanceof HeldCollection && identity === "id")
+        return value;
+    if (Array.isArray(value))
+        return new HeldCollection(value, { value: value.length, exact: true }, null, identity);
+    if (isCollection(value)) {
+        const page = value;
+        return new HeldCollection(page.items ?? [], page.count ?? null, page.cursor ?? null, identity);
+    }
+    return new HeldCollection([], { value: 0, exact: true }, null, identity);
+}
+/**
+ * Whether the collection holds less than there is — sincpro_framework's `is_partial`, the same
+ * rule: a cursor says there is more; no count claims nothing; a floor, or a count above what it
+ * holds, says there is more.
+ *
+ *     isPartial({ items: [a], cursor: "x" })                          -> true
+ *     isPartial({ items: [a], count: { value: 1000, exact: false } }) -> true
+ *     isPartial({ items: [a, b], count: { value: 2, exact: true } })  -> false
+ *     isPartial({ items: [a] })                                       -> false
+ */
+export function isPartial(collection) {
+    if (collection.cursor != null)
+        return true;
+    const count = collection.count;
+    if (count == null)
+        return false;
+    return !count.exact || count.value > (collection.items ?? []).length;
+}
+/**
+ * How many there are, as well as the collection knows: its count, or — when the read asked for
+ * none — what it holds, exact only when nothing says there is more.
+ *
+ *     totalOf({ items: [a, b], count: { value: 1000, exact: false } })  -> { value: 1000, exact: false }
+ *     totalOf({ items: [a, b], cursor: "x" })                           -> { value: 2, exact: false }
+ */
+export function totalOf(collection) {
+    return (collection.count ?? {
+        value: (collection.items ?? []).length,
+        exact: collection.cursor == null,
+    });
+}
+/**
+ * The question «the related records of this one», over the related entity — sincpro_framework's
+ * `References.criteria()`: what pages a relation past what its record brought, searches it and
+ * orders it, a list like any other. `criteria` narrows it; it never widens it.
+ *
+ *     relatedCriteria(meta.fields.invoices, customer, "id")
+ *       -> { selection: { field: "customer_id", operator: "=", value: customer.id } }
+ *     relatedCriteria(field, customer, "id", { order: [{ field: "issued_on", descending: true }] })
+ *
+ * The two fields the definition names (`parent_field`, `related_field`) are read when it names
+ * them — a relation by a business key —; `identified_by` against the record's own key otherwise.
+ * A relation whose definition says neither cannot be asked, and says so.
+ */
+export function relatedCriteria(keys, record, identity = "id", criteria = {}) {
+    const there = keys.related_field ?? keys.identified_by;
+    const here = keys.related_field != null ? (keys.parent_field ?? identity) : identity;
+    if (there == null || there === "")
+        throw new Error("this relation's definition names no key to ask it by (identified_by, related_field)");
+    const mine = { field: there, operator: "=", value: record[here] };
+    return {
+        ...criteria,
+        selection: (criteria.selection === undefined
+            ? mine
+            : { all: [criteria.selection, mine] }),
+    };
+}

package/dist/common/decimal.js

@@ -19,6 +19,12 @@ 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;
@@ -97,6 +103,7 @@ export class Decimal {
     }
     /** 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");
@@ -106,6 +113,7 @@ export class Decimal {
     }
     /** 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);

package/dist/common/serialization.d.ts

@@ -39,7 +39,11 @@ export type Rebuild<T> = {
  * `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. */
+/**
+ * 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;

package/dist/common/serialization.js

@@ -54,8 +54,9 @@ function bytesOf(text) {
     return bytes;
 }
 function isBytes(value) {
-    return (value instanceof Uint8Array || value instanceof ArrayBuffer || value instanceof DataView);
+    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;
@@ -85,8 +86,13 @@ function written(value, where, seen) {
     seen.add(object);
     try {
         const own = object.toJSON;
-        if (typeof own === "function")
-            return written(own.call(object), where, seen);
+        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);
@@ -96,6 +102,9 @@ function written(value, where, seen) {
             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]);
@@ -127,7 +136,11 @@ function walked(value) {
         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. */
+/**
+ * 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)

package/dist/common/time.d.ts

@@ -33,7 +33,8 @@ export declare function wallTimeOf(instant: string, timeZone: string): string |
  * 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. */
+/** 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. */