@sincpro/client-framework 0.5.0 → 0.6.0

package/README.md

@@ -297,15 +297,18 @@ case runs the same — nothing traces, nothing reports. In a test, `memoryTracer
 The backend writes every message with one set of rules, and every client reads and writes them
 the same — so they live here, not in each platform:
 
-| Value       | Travels as                                 | Here                                             |
-| ----------- | ------------------------------------------ | ------------------------------------------------ |
-| a decimal   | text, every digit: `"10.50"`               | `Decimal` — exact, on `BigInt`; rounds half up   |
-| a money     | `{ "amount": "10.50", "currency": "BOB" }` | `Money` — never adds two currencies              |
-| a day       | `"2026-10-02"`, never converted            | `isDay`, `dayOf(instant, zone)` for «today»      |
-| an instant  | ISO text: `"2026-10-02T14:30:00Z"`         | `wallTimeOf` / `instantOf` on the company's zone |
-| an id       | a UUID v7 as 32 hex                        | `newEntityId`, `isEntityId`, `momentOf`          |
-| bytes       | `{ "$bytes": "<base64>" }`                 | `valuesOf` / `readValues`                        |
-| the context | only what travels: text, numbers, lists    | `plainCodec`, `travelling`                       |
+| Value        | Travels as                                 | Here                                               |
+| ------------ | ------------------------------------------ | -------------------------------------------------- |
+| a decimal    | text, every digit: `"10.50"`               | `Decimal` — exact, on `BigInt`; rounds half up     |
+| a money      | `{ "amount": "10.50", "currency": "BOB" }` | `Money` — never adds two currencies                |
+| a day        | `"2026-10-02"`, never converted            | `isDay`, `dayOf(instant, zone)` for «today»        |
+| an instant   | ISO text: `"2026-10-02T14:30:00Z"`         | `wallTimeOf` / `instantOf` on the company's zone   |
+| an id        | a UUID v7 as 32 hex                        | `newEntityId`, `isEntityId`, `momentOf`            |
+| bytes        | `{ "$bytes": "<base64>" }`                 | `valuesOf` / `readValues`                          |
+| the context  | only what travels: text, numbers, lists    | `plainCodec`, `travelling`                         |
+| a to-many    | `{ "items": […], "count": {…}, "cursor" }` | `EntityCollection<T>`, `collectionOf`, `isPartial` |
+| an export    | Parquet, Arrow or JSON Lines, streamed     | `downloadRoute`, `exportRoute`, `Download`         |
+| a large page | Parquet, when the search says so           | `restTransport({ decoders: [parquetDecoder] })`    |
 
 ```ts
 import { Money, pack, unpack, valuesOf } from "@sincpro/client-framework";
@@ -322,6 +325,25 @@ Not restrictive, like the backend: reading keeps every key it finds, a typed rea
 once, naming where. Showing a value to a person — `Intl.NumberFormat`, a date picker — is each
 platform's, never this package's.
 
+A relation that holds several records — the invoices of a customer — comes as a page of them,
+never an array: forty records, «at least 1000», and the cursor to go on. Read it with
+`collectionOf` (an array from a hand-written domain reads the same) — a `HeldCollection`, edited
+the way a string is: `append`, `extend`, `remove`, `replace` answer a new one. Say «1000+» when
+`count.exact` is false, and ask for the rest as a list of the related entity
+(`relatedCriteria(meta.fields.invoices, customer)`). A part of the record — the lines of an
+invoice — is written back only whole: the backend refuses a page of it.
+
+A search asked for millions of records answers Parquet instead of JSON to a client that reads it.
+Give the transport the decoder — an optional entry over `hyparquet` — and nothing above it
+changes: the same page, each value as the JSON wire writes it.
+
+```ts
+import { restTransport } from "@sincpro/client-framework";
+import { parquetDecoder } from "@sincpro/client-framework/parquet";
+
+const transport = restTransport({ base: "/v1", decoders: [parquetDecoder] });
+```
+
 ## Where it sits
 
 ```mermaid

package/dist/adapters/parquet.d.ts

@@ -0,0 +1,50 @@
+import type { Decoder } from "../client/transport.js";
+import type { AnyRecord, Count, Dropped, Envelope } from "@sincpro/criteria";
+/**
+ * A page sincpro_framework answered as Parquet, read into what JSON would have sent — the
+ * `[optional]` entry `@sincpro/client-framework/parquet`, over `hyparquet` (an optional peer).
+ *
+ *     restTransport({ base: "/v1", decoders: [parquetDecoder] })
+ *     // a search of two million records: Accept says Parquet is read, the server answers it,
+ *     // and the screen gets the same page — records, cursor, count — it gets from JSON
+ *
+ * Context: a JSON page of millions is the slowest, largest way to send them; a search answers
+ * Parquet past its `parquet_above`, only to a caller that says it reads it. This is that
+ * reading. Every value comes back as the JSON wire writes it, so nothing above the transport
+ * changes: a decimal as its exact text, a day as `"2026-11-01"`, an instant as ISO text, an
+ * integer as a number, what the server wrote as JSON text (`json` in the footer) parsed back.
+ * The cursor, the count and the model's version travel in the file's footer.
+ *
+ * One limit, said: hyparquet reads a decimal as a JavaScript number, written back here as text
+ * at the column's scale — exact while the unscaled value stays below 2^53 (with two decimals,
+ * amounts up to ninety thousand billion).
+ */
+export declare const PARQUET = "application/vnd.apache.parquet";
+/** What the footer of a sincpro_framework Parquet answer says beside the records. */
+export type ParquetFooter = {
+    /** The response's field holding the records: `entries`. */
+    records: string;
+    cursor: string | null;
+    count: Count | null;
+    model_version: string;
+    dropped: Dropped[];
+    /** The columns written as JSON text: a value object, a translated text. */
+    json?: string[];
+};
+/**
+ * The records of a sincpro_framework Parquet file — an answer's body, an export downloaded —
+ * each as the JSON wire writes it, and what its footer says.
+ *
+ *     const { records, footer } = await parquetRecords(await download.blob().then((b) => b.arrayBuffer()));
+ */
+export declare function parquetRecords(bytes: ArrayBuffer): Promise<{
+    records: AnyRecord[];
+    footer: ParquetFooter | null;
+}>;
+/**
+ * A Parquet answer read into the envelope a page is built from — what JSON would have sent:
+ * the records under the response's own field, the cursor, the count, the model's version.
+ */
+export declare function readParquetAnswer(response: Response): Promise<Envelope & AnyRecord>;
+/** What `restTransport({ decoders })` takes: the media type it reads, and how. */
+export declare const parquetDecoder: Decoder;

package/dist/adapters/parquet.js

@@ -0,0 +1,151 @@
+import { parquetMetadata, parquetReadObjects, } from "hyparquet";
+/**
+ * A page sincpro_framework answered as Parquet, read into what JSON would have sent — the
+ * `[optional]` entry `@sincpro/client-framework/parquet`, over `hyparquet` (an optional peer).
+ *
+ *     restTransport({ base: "/v1", decoders: [parquetDecoder] })
+ *     // a search of two million records: Accept says Parquet is read, the server answers it,
+ *     // and the screen gets the same page — records, cursor, count — it gets from JSON
+ *
+ * Context: a JSON page of millions is the slowest, largest way to send them; a search answers
+ * Parquet past its `parquet_above`, only to a caller that says it reads it. This is that
+ * reading. Every value comes back as the JSON wire writes it, so nothing above the transport
+ * changes: a decimal as its exact text, a day as `"2026-11-01"`, an instant as ISO text, an
+ * integer as a number, what the server wrote as JSON text (`json` in the footer) parsed back.
+ * The cursor, the count and the model's version travel in the file's footer.
+ *
+ * One limit, said: hyparquet reads a decimal as a JavaScript number, written back here as text
+ * at the column's scale — exact while the unscaled value stays below 2^53 (with two decimals,
+ * amounts up to ninety thousand billion).
+ */
+export const PARQUET = "application/vnd.apache.parquet";
+const ENVELOPE = "sincpro";
+const pad = (value, size = 2) => String(value).padStart(size, "0");
+/** A day as the wire writes it: days since 1970-01-01 → `"2026-11-01"`. */
+function dayOf(days) {
+    const at = new Date(days * 86_400_000);
+    return `${at.getUTCFullYear()}-${pad(at.getUTCMonth() + 1)}-${pad(at.getUTCDate())}`;
+}
+/** An instant as the wire writes it, to the microsecond: `"2026-11-06T14:30:00.123456Z"`. */
+function instantOf(micros) {
+    // Floored to the second, so an instant before 1970 keeps its fraction on the right side.
+    const fraction = ((micros % 1000000n) + 1000000n) % 1000000n;
+    const seconds = (micros - fraction) / 1000000n;
+    const at = new Date(Number(seconds) * 1000);
+    return `${at.toISOString().slice(0, 19)}.${pad(Number(fraction), 6)}Z`;
+}
+/** The decimal columns at the top of the file's schema. */
+function decimalScales(metadata) {
+    const scales = new Map();
+    const [root, ...elements] = metadata.schema;
+    let index = 0;
+    const top = root?.num_children ?? 0;
+    for (let column = 0; column < top && index < elements.length; column += 1) {
+        const element = elements[index];
+        const converted = element.converted_type === "DECIMAL";
+        if (converted || element.logical_type?.type === "DECIMAL") {
+            const logical = element.logical_type;
+            scales.set(element.name, {
+                scale: element.scale ?? logical?.scale ?? 0,
+                scaled: converted,
+            });
+        }
+        index += 1 + descendants(elements, index);
+    }
+    return scales;
+}
+/** How many schema elements a nested column holds below the one at `at`. */
+function descendants(elements, at) {
+    let count = 0;
+    let pending = elements[at]?.num_children ?? 0;
+    let next = at + 1;
+    while (pending > 0 && next < elements.length) {
+        count += 1;
+        pending -= 1;
+        pending += elements[next]?.num_children ?? 0;
+        next += 1;
+    }
+    return count;
+}
+/** One value as the JSON wire writes it. */
+/** An unscaled decimal (an integer, a bigint) as its exact text at `scale`. */
+function scaledText(unscaled, scale) {
+    const digits = BigInt(unscaled);
+    const negative = digits < 0n;
+    const text = (negative ? -digits : digits).toString().padStart(scale + 1, "0");
+    const whole = scale === 0 ? text : `${text.slice(0, -scale)}.${text.slice(-scale)}`;
+    return negative ? `-${whole}` : whole;
+}
+/** What the server wrote as JSON text, read back — left as it is when it is no JSON. */
+function parsedJson(value) {
+    try {
+        return JSON.parse(value);
+    }
+    catch {
+        return value;
+    }
+}
+function wireValue(value, decimal, json) {
+    if (value === null || value === undefined)
+        return null;
+    if (decimal !== undefined) {
+        if (!decimal.scaled && (typeof value === "number" || typeof value === "bigint"))
+            return scaledText(value, decimal.scale);
+        if (typeof value === "number")
+            return value.toFixed(decimal.scale);
+    }
+    if (typeof value === "bigint")
+        return value <= BigInt(Number.MAX_SAFE_INTEGER) &&
+            value >= BigInt(Number.MIN_SAFE_INTEGER)
+            ? Number(value)
+            : value.toString();
+    if (json && typeof value === "string")
+        return parsedJson(value);
+    return value;
+}
+/**
+ * The records of a sincpro_framework Parquet file — an answer's body, an export downloaded —
+ * each as the JSON wire writes it, and what its footer says.
+ *
+ *     const { records, footer } = await parquetRecords(await download.blob().then((b) => b.arrayBuffer()));
+ */
+export async function parquetRecords(bytes) {
+    const metadata = parquetMetadata(bytes);
+    const said = metadata.key_value_metadata?.find((one) => one.key === ENVELOPE)?.value;
+    const footer = said ? JSON.parse(said) : null;
+    const scales = decimalScales(metadata);
+    const json = new Set(footer?.json ?? []);
+    const rows = await parquetReadObjects({
+        file: bytes,
+        metadata,
+        parsers: {
+            dateFromDays: dayOf,
+            timestampFromMicroseconds: instantOf,
+            timestampFromMilliseconds: (millis) => instantOf(millis * 1000n),
+            timestampFromNanoseconds: (nanos) => instantOf(nanos / 1000n),
+        },
+    });
+    const records = rows.map((row) => {
+        const record = {};
+        for (const [name, value] of Object.entries(row))
+            record[name] = wireValue(value, scales.get(name), json.has(name));
+        return record;
+    });
+    return { records, footer };
+}
+/**
+ * A Parquet answer read into the envelope a page is built from — what JSON would have sent:
+ * the records under the response's own field, the cursor, the count, the model's version.
+ */
+export async function readParquetAnswer(response) {
+    const { records, footer } = await parquetRecords(await response.arrayBuffer());
+    return {
+        [footer?.records ?? "records"]: records,
+        cursor: footer?.cursor ?? null,
+        count: footer?.count ?? null,
+        model_version: footer?.model_version ?? "",
+        dropped: footer?.dropped ?? [],
+    };
+}
+/** What `restTransport({ decoders })` takes: the media type it reads, and how. */
+export const parquetDecoder = { mediaType: PARQUET, decode: readParquetAnswer };

package/dist/client/entity.d.ts

@@ -1,5 +1,5 @@
 import type { Method } from "./transport.js";
-import { type AnyRecord, type Expression } from "@sincpro/criteria";
+import { type AnyRecord, type Criteria, type Expression } from "@sincpro/criteria";
 /**
  * The parts any record may have beside its name: what a link, a card or a record's header says
  * about it, whatever the entity.
@@ -97,6 +97,8 @@ export type Entity<T extends AnyRecord = AnyRecord, C extends CommandBodies = Co
         route: string;
         type: string;
     };
+    /** Every record of a criteria as a file: the route `exportRoute` fills, `downloadRoute` asks. */
+    export?: string;
     /** Which fields are its description, state, picture… when they are not the conventional
      *  ones (`summaryOf`). Empty: the convention decides. */
     summary: SummaryFields;
@@ -193,6 +195,9 @@ export type EntityRoutes<C extends CommandBodies = CommandBodies> = CommandRoute
         route: string;
         type: string;
     };
+    /** `"/invoices/export"`: every record of a criteria as a file (`Export[Invoice, Streamed]`),
+     *  asked through `exportRoute` and `downloadRoute`. */
+    export?: string;
     /** `{ image: "logo", state: "estado_pago", person: true }` — not a route, but declared once
      *  with the rest of what a screen should not have to know. */
     summary?: SummaryFields;
@@ -238,5 +243,15 @@ export declare function bodyFor(route: WriteRoute, id: string | undefined, body:
  * key the path needs and the parameters lack is the screen's bug, said before anything is sent.
  */
 export declare function listRoute(list: string, params?: Readonly<Record<string, string>>): string;
+/** What an export is written as: Parquet, an Arrow IPC stream, or JSON Lines. */
+export type ExportFormat = "parquet" | "arrow" | "jsonl";
+/**
+ * The route of an export: its path, its keys filled from `params`, the criteria and the format as
+ * its query — what `downloadRoute` asks.
+ *
+ *     exportRoute("/invoices/export", { selection: { field: "paid", operator: "=", value: false } }, "jsonl")
+ *       -> "/invoices/export?criteria=%7B…%7D&format=jsonl"
+ */
+export declare function exportRoute<T>(path: string, criteria?: Criteria<T>, format?: ExportFormat, params?: Readonly<Record<string, string>>): string;
 export declare function entity<T extends AnyRecord = AnyRecord, C extends CommandBodies = CommandBodies, A extends CommandAnswers = CommandAnswers>(key: string, routes: EntityRoutes<C>): Entity<T, C, A>;
 export {};

package/dist/client/entity.js

@@ -1,4 +1,4 @@
-import { readExpression } from "@sincpro/criteria";
+import { readExpression, } from "@sincpro/criteria";
 /**
  * The params that say what a reference without an id is for: `new` is the form of a record
  * that does not exist yet, `pick` is the list opened to choose one. Params, because they are
@@ -136,6 +136,20 @@ export function listRoute(list, params) {
         return path;
     return `${path}${path.includes("?") ? "&" : "?"}${query}`;
 }
+/**
+ * The route of an export: its path, its keys filled from `params`, the criteria and the format as
+ * its query — what `downloadRoute` asks.
+ *
+ *     exportRoute("/invoices/export", { selection: { field: "paid", operator: "=", value: false } }, "jsonl")
+ *       -> "/invoices/export?criteria=%7B…%7D&format=jsonl"
+ */
+export function exportRoute(path, criteria, format, params) {
+    return listRoute(path, {
+        ...params,
+        ...(criteria === undefined ? {} : { criteria: JSON.stringify(criteria) }),
+        ...(format === undefined ? {} : { format }),
+    });
+}
 export function entity(key, routes) {
     if (!/^[^:\s]+:[^:\s]+$/.test(key))
         throw new Error(`entity key "${key}" is not domain:kind`);
@@ -181,6 +195,7 @@ export function entity(key, routes) {
         ...(routes.draft === undefined ? {} : { draft: writeRoute(routes.draft) }),
         ...(routes.edit === undefined ? {} : { edit: writeRoute(routes.edit) }),
         ...(routes.history === undefined ? {} : { history: routes.history }),
+        ...(routes.export === undefined ? {} : { export: routes.export }),
         summary: routes.summary ?? {},
         ...(routes.aggregate === undefined ? {} : { aggregate: routes.aggregate }),
     };

package/dist/client/memory.js

@@ -60,9 +60,11 @@ export function memoryTransport(tables, options = {}) {
         },
         async one(route, signal) {
             await check(route, signal);
-            const slash = route.lastIndexOf("/");
-            const table = tableAt(route.slice(0, slash));
-            const id = decodeURIComponent(route.slice(slash + 1));
+            // A record's route may carry a question (`?draft=true`): the id is the path's last part.
+            const path = route.split("?")[0] ?? route;
+            const slash = path.lastIndexOf("/");
+            const table = tableAt(path.slice(0, slash));
+            const id = decodeURIComponent(path.slice(slash + 1));
             const key = table.meta.get_id || table.meta.identity;
             const record = table.rows.find((row) => String(row[key]) === id);
             if (record === undefined)

package/dist/client/rest.d.ts

@@ -1,4 +1,4 @@
-import { type Transport } from "./transport.js";
+import { type Decoder, type Transport } from "./transport.js";
 import { type Criteria } from "@sincpro/criteria";
 /**
  * The REST wire of sincpro_framework (`FastApiGateway`).
@@ -26,6 +26,12 @@ export type RestOptions = {
     headers?: Record<string, string> | (() => Record<string, string>);
     /** Defaults to the global `fetch`. Inject one for tests. */
     fetch?: typeof fetch;
+    /**
+     * The formats besides JSON this transport reads a page in — `[parquetDecoder]` from
+     * `@sincpro/client-framework/parquet`. Each is said in `Accept`, so a search that answers its
+     * large pages as Parquet does so only to a client that reads it.
+     */
+    decoders?: readonly Decoder[];
     /** Where the bounded context's discovery document is: `"/openapi.json"` by default, at the
      *  origin of `base`. `null`: none is read, and the definitions come only from `metas`. */
     document?: string | null;

package/dist/client/rest.js

@@ -4,6 +4,25 @@ import { readProblem } from "@sincpro/criteria";
 import { RestError, restSource } from "@sincpro/criteria/rest";
 /** The keys of an answer that are not the record: what is left is the record's own field. */
 const ENVELOPE = new Set(["cursor", "count", "model_version", "dropped", "draft", "missing"]);
+/**
+ * The name a `Content-Disposition` says to save a file as; `""` when it says none. The encoded
+ * form (`filename*=UTF-8'es'informe%20final.parquet`, RFC 5987) wins, its charset and language
+ * dropped and its bytes decoded; the plain one (`filename="report 100%.csv"`) is taken as it is.
+ */
+function filenameOf(disposition) {
+    const said = disposition ?? "";
+    const encoded = /filename\*\s*=\s*([^']*)'[^']*'([^;]+)/i.exec(said);
+    if (encoded?.[2] !== undefined) {
+        try {
+            return decodeURIComponent(encoded[2].trim().replace(/^"|"$/g, ""));
+        }
+        catch {
+            return encoded[2].trim();
+        }
+    }
+    const plain = /filename\s*=\s*("([^"]*)"|[^;]+)/i.exec(said);
+    return (plain?.[2] ?? plain?.[1] ?? "").trim();
+}
 export function urlOf(base, route, criteria) {
     const url = `${base}${route}`;
     if (criteria === undefined)
@@ -25,7 +44,17 @@ function documentUrl(base, document) {
 export function restTransport(options = {}) {
     const base = options.base ?? "";
     const doFetch = options.fetch ?? ((input, init) => fetch(input, init));
+    const decoders = options.decoders ?? [];
+    const accept = decoders.length === 0
+        ? {}
+        : { Accept: ["application/json", ...decoders.map((one) => one.mediaType)].join(", ") };
     const own = () => typeof options.headers === "function" ? options.headers() : (options.headers ?? {});
+    /** A body in a format a decoder reads, read by it; anything else left to JSON. */
+    const decode = async (response) => {
+        const type = (response.headers.get("content-type") ?? "").split(";")[0]?.trim();
+        const decoder = decoders.find((one) => one.mediaType === type);
+        return decoder === undefined ? undefined : decoder.decode(response);
+    };
     // The discovery document, read once; asked again — with its ETag — when an answer says a
     // version of its model the document did not.
     const located = options.document === null ? null : (options.document ?? "/openapi.json");
@@ -104,8 +133,10 @@ export function restTransport(options = {}) {
     return {
         async list(route, criteria, signal, call) {
             const source = restSource(`${base}${route}`, {
-                headers: () => ({ ...own(), ...call?.headers }),
+                // Only a page may come in another format: the decoders are said here, and nowhere else.
+                headers: () => ({ ...accept, ...own(), ...call?.headers }),
                 fetch: doFetch,
+                ...(decoders.length === 0 ? {} : { decode }),
             });
             try {
                 const page = await source.read(criteria, signal);
@@ -123,6 +154,20 @@ export function restTransport(options = {}) {
         async read(route, signal, call) {
             return (await get(route, urlOf(base, route), signal, undefined, call));
         },
+        async download(route, signal, call) {
+            const response = await doFetch(urlOf(base, route), {
+                headers: { ...own(), ...call?.headers },
+                ...(signal ? { signal } : {}),
+            });
+            if (!response.ok)
+                throw new TransportError(route, response.status, readProblem(await response.text()), undefined);
+            return {
+                mediaType: (response.headers.get("content-type") ?? "").split(";")[0]?.trim() ?? "",
+                filename: filenameOf(response.headers.get("content-disposition")),
+                body: response.body,
+                blob: () => response.blob(),
+            };
+        },
         async one(route, signal, call) {
             const answer = (await get(route, urlOf(base, route), signal, undefined, call));
             const own = Object.keys(answer).filter((key) => !ENVELOPE.has(key));

package/dist/client/transport.d.ts

@@ -1,4 +1,4 @@
-import type { Criteria, Dropped, Meta, Page, Problem } from "@sincpro/criteria";
+import type { AnyRecord, Criteria, Dropped, Envelope, Meta, Page, Problem } from "@sincpro/criteria";
 /**
  * The one seam between this package and a server.
  *
@@ -24,7 +24,43 @@ export interface Transport {
      * so a transport written before it keeps compiling; call it through `readRoute`.
      */
     read?<T>(route: string, signal?: AbortSignal, options?: CallOptions): Promise<T>;
+    /**
+     * A file the server streams — an export (`Export[Entity, Streamed]`): the route with its
+     * parameters already in it, the bytes as they arrive. Optional, as `read`; call it through
+     * `downloadRoute`.
+     */
+    download?(route: string, signal?: AbortSignal, options?: CallOptions): Promise<Download>;
 }
+/**
+ * What a server streams instead of answering JSON — every record of a criteria as Parquet, an
+ * Arrow stream or JSON Lines: what it is, the name to save it under, and its bytes.
+ *
+ * Context: an export is millions of rows, written by the server a page at a time; parsing it as
+ * JSON, or holding it whole before the first byte is used, is what it exists to avoid. `body`
+ * hands the bytes on as they come — to Arrow JS, to a file — where the platform's fetch streams
+ * (a browser); `blob()` reads them all, which is what a phone's fetch can do.
+ */
+export type Download = {
+    /** `"application/vnd.apache.parquet"`, `"application/vnd.apache.arrow.stream"`, `"application/jsonl"`. */
+    mediaType: string;
+    /** What the server says to save it as (`Content-Disposition`); `""` when it says nothing. */
+    filename: string;
+    /** The bytes as they arrive; `null` where the platform's fetch has no streams. */
+    body: ReadableStream<Uint8Array> | null;
+    /** Every byte, at once. */
+    blob(): Promise<Blob>;
+};
+/**
+ * How a transport reads a page that came in another format than JSON — Parquet, from
+ * `@sincpro/client-framework/parquet` —: the media type, said to the server in `Accept`, and how
+ * a body of it becomes the envelope JSON would have sent.
+ */
+export type Decoder = {
+    mediaType: string;
+    decode(response: Response): Promise<Envelope & AnyRecord>;
+};
+/** A download through `transport.download`, or the reason it cannot be, by name. */
+export declare function downloadRoute(transport: Transport, route: string, signal?: AbortSignal, options?: CallOptions): Promise<Download>;
 /**
  * A read through `transport.read`, or the reason it cannot be: a transport that has no `read`
  * is said so by name, never a `TypeError` from somewhere inside a screen.

package/dist/client/transport.js

@@ -1,3 +1,9 @@
+/** A download through `transport.download`, or the reason it cannot be, by name. */
+export function downloadRoute(transport, route, signal, options) {
+    if (transport.download === undefined)
+        return Promise.reject(new Error(`this transport has no download(): it cannot ask GET ${route} — give it one`));
+    return transport.download(route, signal, options);
+}
 /**
  * A read through `transport.read`, or the reason it cannot be: a transport that has no `read`
  * is said so by name, never a `TypeError` from somewhere inside a screen.

package/dist/codegen/client.js

@@ -7,17 +7,20 @@ import { ownerOf, restOf, WRITES, } from "./rest.js";
  *
  * Context: a method only writes down the route the contract published and hands the call to the
  * transport, which keeps the rules — the `Idempotency-Key`, the `Problem`, the model's version.
- * A GET is a page (`list`), one record (`one`), or — a Query of the context's own, `GET /me` —
- * a read of its answer as it came (`readRoute`, over a transport that has `read`). A GET's
+ * A GET is a page (`list`), one record (`one`), a file (`export`: `downloadRoute`, its bytes as
+ * they arrive), or — a Query of the context's own, `GET /me` — a read of its answer as it came
+ * (`readRoute`, over a transport that has `read`). A GET's
  * keys in its path are required parameters; every other field is an optional one.
  */
 /** A search's fields a page asks with, not the screen: the criteria, and its cursor inside it. */
 const PAGED = new Set(["criteria", "cursor"]);
+/** An export's fields its method takes apart: the criteria and the format. */
+const EXPORTED = new Set(["criteria", "cursor", "format"]);
 /** A GET's parameters: the path's keys, and the rest of its input but what a page asks with. */
-function askedOf(operation, rest, paged) {
+function askedOf(operation, rest, paged, apart = PAGED) {
     const path = [...rest.fields].sort();
     const query = Object.keys(operation.input.properties ?? {})
-        .filter((one) => !path.includes(one) && !(paged && PAGED.has(one)))
+        .filter((one) => !path.includes(one) && !(paged && apart.has(one)))
         .sort();
     return { path, query };
 }
@@ -29,6 +32,9 @@ function callOf(metamodel, operation, rest) {
     const owner = ownerOf(metamodel, operation);
     if (operation.role === "search" && owner !== undefined && owner in metamodel.models)
         return { kind: "list", entity: owner, ...askedOf(operation, rest, true) };
+    // An export answers bytes, never JSON: it is downloaded.
+    if (operation.role === "export" && owner !== undefined && owner in metamodel.models)
+        return { kind: "download", entity: owner, ...askedOf(operation, rest, true, EXPORTED) };
     const field = owner === undefined ? undefined : operation.targets[owner];
     const record = rest.fields.length === 1 && rest.fields[0] === field;
     if (operation.role === "get" && owner !== undefined && field !== undefined && record)
@@ -78,6 +84,15 @@ function methodSourceOf(local, answer, method, call, rest, doc) {
         const signature = params.signature === "" ? "" : `, ${params.signature}`;
         return `${doc}    ${method}: (criteria: Criteria<${entity}>${signature}) =>\n      transport.list<${entity}>(${params.route(rest.path)}, criteria),`;
     }
+    if (call.kind === "download") {
+        const entity = `dto.${identifierOf(call.entity)}`;
+        const params = paramsOf(call);
+        // The path's keys are required, so they come first: a required parameter never follows an
+        // optional one.
+        const keys = params.signature === "" ? "" : `${params.signature.replace("params?:", "params:")}, `;
+        const given = params.signature === "" ? "" : ", params";
+        return `${doc}    ${method}: (${keys}criteria?: Criteria<${entity}>, format?: ExportFormat) =>\n      downloadRoute(transport, exportRoute(${JSON.stringify(rest.path)}, criteria, format${given})),`;
+    }
     if (call.kind === "read") {
         const params = paramsOf(call);
         return `${doc}    ${method}: (${params.signature}) =>\n      readRoute<dto.${answer}>(transport, ${params.route(rest.path)}),`;
@@ -122,6 +137,7 @@ export function clientFileOf(metamodel, options = {}) {
     let paged = false;
     let reads = false;
     let sends = false;
+    let downloads = false;
     for (const [identity, operation] of operations) {
         const local = localOf(metamodel, identity);
         const rest = restOf(metamodel, identity, options);
@@ -135,6 +151,10 @@ export function clientFileOf(metamodel, options = {}) {
         claim(method, `operation ${identity}`);
         const doc = docOf([operation.description, deprecationOf(metamodel, operation)], "    ");
         methods.push(methodSourceOf(local, answerOf(metamodel, identity), method, call, rest, doc));
+        if (call.kind === "download") {
+            downloads = true;
+            paged = true;
+        }
         if (call.kind === "list" || call.kind === "read") {
             paged ||= call.kind === "list";
             reads ||= call.kind === "read";
@@ -147,6 +167,7 @@ export function clientFileOf(metamodel, options = {}) {
     }
     const core = [
         "bindable",
+        ...(downloads ? ["downloadRoute", "type ExportFormat", "exportRoute"] : []),
         ...(lists ? ["listRoute"] : []),
         ...(sends ? ["pathFor"] : []),
         ...(reads ? ["readRoute"] : []),

package/dist/codegen/domain.js

@@ -20,7 +20,11 @@ const DEFINITIONS = "#/$defs/";
 /** A shared definition a package of the stack already types: imported, never written again. */
 const IMPORTED = {
     Criteria: { name: "Criteria", from: "@sincpro/criteria" },
+    Download: { name: "Download", from: "@sincpro/client-framework" },
+    EntityCollection: { name: "EntityCollection", from: "@sincpro/client-framework" },
 };
+/** A relation that holds several records: a reading answers it as a page of them. */
+const TO_MANY = new Set(["one2many", "many2many"]);
 /** The field types whose value is the record itself, not a key that names it. */
 const RELATIONAL = new Set(["many2one", "one2many", "many2many", "embedded"]);
 /** A related record: in an answer only when the read expands it. */
@@ -82,6 +86,29 @@ function optional(name, property, schema, record) {
         return EXPANDED.has(property["x-sincpro"]?.type ?? "");
     return !(schema.required ?? []).includes(name);
 }
+/**
+ * The records a to-many holds, when `property` is one — however the contract writes it: the
+ * collection a reading answers (`{items, count, cursor}`, sincpro_framework 3.33 on) or, before
+ * that, a bare array, which said less than the wire sent.
+ */
+function heldRecords(property) {
+    if (!TO_MANY.has(property["x-sincpro"]?.type ?? ""))
+        return undefined;
+    const held = property.properties?.["items"] ?? property;
+    return held.type === "array" ? held.items : undefined;
+}
+/**
+ * A property's TypeScript. A to-many inside a record is an `EntityCollection` of its records —
+ * a page with its count and cursor, as the read answers it — never an array, which would say the
+ * page is all there is.
+ */
+function propertyTypeOf(property, scope, depth, record) {
+    const records = record ? heldRecords(property) : undefined;
+    if (records === undefined)
+        return typeOf(property, scope, depth, record);
+    scope.imports.add("EntityCollection");
+    return `EntityCollection<${typeOf(records, scope, depth, record)}>`;
+}
 function objectOf(schema, scope, depth, record) {
     const properties = sorted(schema.properties ?? {});
     if (properties.length === 0) {
@@ -95,7 +122,7 @@ function objectOf(schema, scope, depth, record) {
     const lines = properties.map(([name, property]) => {
         const doc = docOf([property.description, keyNote(property)], pad);
         const mark = optional(name, property, schema, record) ? "?" : "";
-        return `${doc}${pad}${keyOf(name)}${mark}: ${typeOf(property, scope, depth + 1, record)};`;
+        return `${doc}${pad}${keyOf(name)}${mark}: ${propertyTypeOf(property, scope, depth + 1, record)};`;
     });
     return `{\n${lines.join("\n")}\n${"  ".repeat(depth)}}`;
 }
@@ -133,6 +160,13 @@ function typeOf(schema, scope, depth, record) {
                 : objectOf(schema, scope, depth, record);
     }
 }
+/** What a streamed answer is on the client — an export's bytes (`Download`) —, else nothing. */
+function streamed(output, scope) {
+    if (output["x-sincpro-streamed"] === undefined)
+        return undefined;
+    scope.imports.add("Download");
+    return "Download";
+}
 /** What the server says of an operation: its words, then what it is, for whom, on which field. */
 function operationDoc(metamodel, local, operation) {
     const runsOn = sorted(operation.targets).map(([entity, field]) => `\`${entity}\` in \`${field}\``);
@@ -172,7 +206,9 @@ export function domainFileOf(metamodel) {
         const local = localOf(metamodel, identity);
         const named = answerOf(metamodel, identity);
         claim(local, `operation ${identity}`);
-        const answer = operation.output === null ? "unknown" : typeOf(operation.output, scope, 0, false);
+        const answer = operation.output === null
+            ? "unknown"
+            : (streamed(operation.output, scope) ?? typeOf(operation.output, scope, 0, false));
         const written = [
             `${operationDoc(metamodel, local, operation)}export type ${local} = ${typeOf(operation.input, scope, 0, false)};`,
         ];
@@ -199,9 +235,14 @@ export function domainFileOf(metamodel) {
         claim(identifierOf(name), `definition ${name}`);
         return written.get(name);
     });
-    const imports = [...scope.imports].sort().map((name) => {
+    // One line per package, its names sorted.
+    const byPackage = new Map();
+    for (const name of [...scope.imports].sort()) {
         const imported = IMPORTED[name];
-        return `import type { ${imported.name} } from "${imported.from}";`;
-    });
+        byPackage.set(imported.from, [...(byPackage.get(imported.from) ?? []), imported.name]);
+    }
+    const imports = [...byPackage.keys()]
+        .sort()
+        .map((from) => `import type { ${byPackage.get(from).join(", ")} } from "${from}";`);
     return `${[headerOf("The DTOs", metamodel), ...(imports.length === 0 ? [] : [imports.join("\n")]), ...models, ...shared, ...operations].join("\n\n")}\n`;
 }

package/dist/codegen/entities.d.ts

@@ -5,7 +5,8 @@ import { type GenerateOptions } from "./rest.js";
  *
  * 1. Per model, by name: the one `search` a transport reads for it (`own` when there are
  *    several) — none, and the model gets no entity, said in the file's own doc.
- * 2. Its `get`, `edit` and `preview` the same way, the record's field written `{id}`.
+ * 2. Its `get`, `edit` and `preview` the same way, the record's field written `{id}`, and its
+ *    `export` — every record of a criteria as a file — by its path.
  * 3. Every write of role `command` that concerns it: with `target` when its body names the
  *    record, as it is when it creates one; its body typed without that field.
  * Final: an `entity<T, C>()` per model listed, keyed `<domain>:<kind>`, and `entities`, all of

package/dist/codegen/entities.js

@@ -61,10 +61,18 @@ function entitySourceOf(metamodel, model, domain, options, claim) {
     const missing = [];
     const routes = [`  list: ${JSON.stringify(list.found.rest.path)},`];
     const one = oneOf(reads("get", isGet), "get");
+    const edit = oneOf(reads("edit", isWrite), "edit");
     if (one !== undefined && "found" in one) {
         const field = one.found.operation.targets[model];
+        // sincpro_framework's `Get` answers the caller's own draft only when asked (`draft`), and an
+        // entity edited through `Edit` keeps its drafts there: its record is read with them, or a
+        // draft kept on one visit never comes back on the next.
+        const drafts = edit !== undefined &&
+            "found" in edit &&
+            one.found.operation.input.properties?.["draft"]?.type === "boolean";
+        const path = `${recordPath(one.found.rest, field)}${drafts ? "?draft=true" : ""}`;
         if (field !== undefined && one.found.rest.fields.length === 1)
-            routes.push(`  one: ${JSON.stringify(recordPath(one.found.rest, field))},`);
+            routes.push(`  one: ${JSON.stringify(path)},`);
         else
             missing.push(`one: \`${one.found.local}\` is at ${one.found.rest.path}`);
     }
@@ -82,6 +90,13 @@ function entitySourceOf(metamodel, model, domain, options, claim) {
         const route = `${write.found.rest.method} ${recordPath(write.found.rest, field)}`;
         routes.push(`  ${role}: ${JSON.stringify(route)},`);
     }
+    const exported = oneOf(reads("export", isGet), "export");
+    if (exported !== undefined) {
+        if ("missing" in exported)
+            missing.push(`export: ${exported.missing}`);
+        else
+            routes.push(`  export: ${JSON.stringify(exported.found.rest.path)},`);
+    }
     const commands = reached.filter((one) => one.operation.role === "command" &&
         isWrite(one.rest.method) &&
         one.operation.entities.includes(model));
@@ -127,7 +142,8 @@ function entitySourceOf(metamodel, model, domain, options, claim) {
  *
  * 1. Per model, by name: the one `search` a transport reads for it (`own` when there are
  *    several) — none, and the model gets no entity, said in the file's own doc.
- * 2. Its `get`, `edit` and `preview` the same way, the record's field written `{id}`.
+ * 2. Its `get`, `edit` and `preview` the same way, the record's field written `{id}`, and its
+ *    `export` — every record of a criteria as a file — by its path.
  * 3. Every write of role `command` that concerns it: with `target` when its body names the
  *    record, as it is when it creates one; its body typed without that field.
  * Final: an `entity<T, C>()` per model listed, keyed `<domain>:<kind>`, and `entities`, all of

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

@@ -7,7 +7,8 @@
  * 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`)
+ *             `Decimal`, `Money`, a to-many as a page of its records (`EntityCollection`), 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
  *   model/    model definitions: written by hand, read from a JSON Schema, kept once known
@@ -20,11 +21,12 @@
  * `@sincpro/client-framework/testing`: neither is part of what an application runs.
  */
 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 { bodyFor, type CommandAnswers, type CommandBodies, type CommandRoute, type Entity, entity, type EntityRef, type EntityRoutes, type ExportFormat, exportRoute, 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 { 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 { type CallOptions, type Decoder, type Download, downloadRoute, type Draft, type Method, type One, readRoute, type SendOptions, type Transport, TransportError, } from "./client/transport.js";
+export { collectionOf, type EntityCollection, type HeldCollection, isCollection, isPartial, relatedCriteria, type RelationKeys, totalOf, } from "./common/collection.js";
 export { Decimal, type DecimalLike } from "./common/decimal.js";
 export { isEntityId, momentOf, newEntityId } from "./common/ids.js";
 export { Money } from "./common/money.js";

package/dist/index.js

@@ -7,7 +7,8 @@
  * 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`)
+ *             `Decimal`, `Money`, a to-many as a page of its records (`EntityCollection`), 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
  *   model/    model definitions: written by hand, read from a JSON Schema, kept once known
@@ -20,11 +21,12 @@
  * `@sincpro/client-framework/testing`: neither is part of what an application runs.
  */
 export { entityKeyOf, kindOf, metasOf, versionsOf, } from "./client/contract.js";
-export { bodyFor, entity, listRoute, NEW_PARAM, pathFor, PICK_PARAM, QUERY_PARAM, SCOPE_PARAM, scopeOfRef, startingValuesOf, TRAIL_PARAM, WITH_PARAM, writeRoute, } from "./client/entity.js";
+export { bodyFor, entity, exportRoute, listRoute, NEW_PARAM, pathFor, PICK_PARAM, QUERY_PARAM, SCOPE_PARAM, scopeOfRef, startingValuesOf, TRAIL_PARAM, WITH_PARAM, writeRoute, } from "./client/entity.js";
 export { memoryTransport, } from "./client/memory.js";
 export { restTransport, urlOf, } from "./client/rest.js";
 export { retryKeys, unanswered, } from "./client/retry.js";
-export { readRoute, TransportError, } from "./client/transport.js";
+export { downloadRoute, readRoute, TransportError, } from "./client/transport.js";
+export { collectionOf, isCollection, isPartial, relatedCriteria, totalOf, } from "./common/collection.js";
 export { Decimal } from "./common/decimal.js";
 export { isEntityId, momentOf, newEntityId } from "./common/ids.js";
 export { Money } from "./common/money.js";

package/dist/model/meta.d.ts

@@ -69,6 +69,7 @@ export declare const field: {
         holds?: Expression | null;
         computes?: import("@sincpro/criteria").Formula | null;
         navigable?: boolean;
+        reference?: boolean;
         total?: string | null;
         many?: boolean;
         relation?: string | null;

package/dist/services/execution.js

@@ -58,6 +58,9 @@ export function bindTransport(transport, execution) {
     const read = transport.read;
     if (read !== undefined)
         bound.read = (route, signal, options) => read.call(transport, route, signal, call(options));
+    const download = transport.download;
+    if (download !== undefined)
+        bound.download = (route, signal, options) => download.call(transport, route, signal, call(options));
     return bound;
 }
 /**

package/dist/services/screens.js

@@ -20,6 +20,13 @@ class EntityReads extends Feature {
             return Promise.reject(new Error(`this transport cannot read ${route}: it has no read()`));
         return read.call(this.transport, route, signal, options);
     }
+    download(route, signal, options) {
+        this.span.set({ "http.route": route });
+        const download = this.transport.download;
+        if (download === undefined)
+            return Promise.reject(new Error(`this transport cannot download ${route}: it has no download()`));
+        return download.call(this.transport, route, signal, options);
+    }
 }
 /** What a screen writes — a save, a draft, a preview, a Command: each request a use case. */
 class EntityWrites extends Feature {
@@ -39,7 +46,7 @@ class EntityWrites extends Feature {
  * screen reads through the transport was none of that — no span, no `traceparent` (the backend's
  * trace started there, with no client in it), no company, and a 500 reported to nobody. Here
  * each read and write runs as a use case of `screens` — `EntityReads.list`, `.one`, `.read`,
- * `EntityWrites.send` —, so it gets all three the way any other does: the span (its route said
+ * `.download`, `EntityWrites.send` —, so it gets all three the way any other does: the span (its route said
  * on it), the trace and the process's context on the request, and a report only when it failed
  * (a 4xx the server explained is the screen's to show). A bounded context's own dependencies are
  * never given this: there its use case is the one that runs.
@@ -62,6 +69,8 @@ export function screensTransport(transport, name = "screens") {
     };
     if (transport.read !== undefined)
         through.read = (route, signal, options) => reads.read(route, signal, options);
+    if (transport.download !== undefined)
+        through.download = (route, signal, options) => reads.download(route, signal, options);
     MADE.add(through);
     return through;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sincpro/client-framework",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "description": "The client side of sincpro_framework, for every platform: Feature and ApplicationService traced and reported by default, applications made of domains, and the typed client generated from a service's contract. No React, no DOM.",
   "type": "module",
   "main": "./dist/index.js",
@@ -25,6 +25,10 @@
     "./sentry": {
       "types": "./dist/adapters/sentry.d.ts",
       "default": "./dist/adapters/sentry.js"
+    },
+    "./parquet": {
+      "types": "./dist/adapters/parquet.d.ts",
+      "default": "./dist/adapters/parquet.js"
     }
   },
   "bin": {
@@ -68,13 +72,17 @@
   },
   "peerDependencies": {
     "@opentelemetry/api": "^1.9.0",
-    "@sincpro/criteria": "^2.0.0",
+    "@sincpro/criteria": "^2.1.0",
+    "hyparquet": "^1.32.0",
     "typescript": ">=5.5 <7"
   },
   "peerDependenciesMeta": {
     "@opentelemetry/api": {
       "optional": true
     },
+    "hyparquet": {
+      "optional": true
+    },
     "typescript": {
       "optional": true
     }
@@ -83,11 +91,12 @@
     "@eslint/js": "^10.0.1",
     "@opentelemetry/api": "1.10.0",
     "@opentelemetry/sdk-trace": "3.1.0",
-    "@sincpro/criteria": "^2.0.0",
+    "@sincpro/criteria": "^2.1.0",
     "@types/node": "^26.6.6",
     "eslint": "^10.14.0",
     "eslint-config-prettier": "^10.1.8",
     "eslint-plugin-simple-import-sort": "^14.0.0",
+    "hyparquet": "^1.32.0",
     "prettier": "^3.9.10",
     "tsc-alias": "^1.9.9",
     "typescript": "~6.0.3",