@sincpro/client-framework 0.4.0 → 0.6.0

package/README.md

@@ -179,6 +179,23 @@ await project.Issues.close(input); // span project/Issues.close
 await project.CloseAndNotify.execute(input); // project/CloseAndNotify → its Features under it
 ```
 
+The generator writes this skeleton for you, once, from the service's contract — and never touches
+a file that is already there, because from then on it is yours:
+
+```bash
+sincpro-client generate project.contract.json --out src/domains/project/generated --domain project
+sincpro-client scaffold project.contract.json --out src/domains/project   # dependencies, bases, services, index
+```
+
+And the layers stay layers: `sincpro-client check` resolves every import of the application with
+its own TypeScript and `tsconfig` (aliases included) and fails when a bounded context reaches into
+another's insides, a service imports React or web-ui, `common` imports a bounded context, or the
+entrypoints skip a bounded context's `index.ts` — put it in `make doctor`:
+
+```bash
+sincpro-client check --root src
+```
+
 Every public method is a use case: a span named as the backend names its own
 (`project/Issues.close`, identity `project.Issues.close`), and a report when it fails in a way
 nobody expected. One gesture is one trace, from the click to the database:
@@ -224,6 +241,10 @@ processContext.set({ tenant_id: "acme" }); // every use case runs with it and se
 project.context.set({ warehouse_id: 4 }); // only what «project» runs
 ```
 
+What a screen reads and writes is a use case too when it goes through `screensTransport(transport)`:
+each request is `screens/EntityReads.list`, `…/EntityWrites.send` — traced, with the context on
+it, and reported when it failed.
+
 A service reads it as `this.context` — the process's values, under them its bounded context's,
 under them a scope's, read once where the gesture started — and every request it sends carries
 it in `sincpro-context`. A screen hears it change with `processContext.watch(…)`.
@@ -263,6 +284,10 @@ const tracer = openTelemetryTracer(provider.getTracer("my-app")); // the app's p
 const reporter = sentryReporter(client); // the app's Sentry-compatible client (GlitchTip too)
 ```
 
+What fails outside a use case — a screen that broke while drawing, a subscriber, a worker — goes to
+the same reporter with `reportError(error, where)`: once (an error a use case already reported is
+not sent again), with the process's context.
+
 Nothing is installed or shipped unless it is imported, and without a tracer or a reporter every use
 case runs the same — nothing traces, nothing reports. In a test, `memoryTracer()` and
 `memoryReporter()` (`@sincpro/client-framework/testing`).
@@ -272,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";
@@ -297,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
@@ -344,6 +391,9 @@ three ports, in its `main`:
 | `ContextStore`  | memory, `sessionStorage`, or the screens' store | MMKV, or memory hydrated from AsyncStorage | `memoryContexts`  |
 | `Transport`     | `restTransport` over `fetch`                    | `restTransport`, or SQLite offline         | `memoryTransport` |
 
+How @sincpro/mobile adopts all of this — what maps to what, the MMKV store, the order to move
+in — is [`docs/MOBILE.md`](docs/MOBILE.md).
+
 A store's reads are synchronous — a use case reads its context where a gesture starts and never
 waits for it — so an asynchronous storage is held in memory and written through.
 

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

@@ -1,13 +1,15 @@
 import { TransportError, } from "./transport.js";
-import { readValues, valuesOf } from "../common/serialization.js";
+import { pack, readValues } from "../common/serialization.js";
 import { answer, answerGroups } from "@sincpro/criteria/engine";
 /**
- * A deep copy written and read by the wire's rules (`valuesOf`, `readValues`): what a real server
+ * A deep copy written and read by the wire's rules (`pack`, `readValues`): what a real server
  * would have received and answered — a `Money` as `{ amount, currency }`, a `Decimal` as its text,
  * a `Date` as an instant, bytes as bytes — the same on every platform. `structuredClone` kept a
  * `Date` a `Date` in a browser and a JSON round trip made it text on a phone; neither is a wire.
  */
-const copyOf = (value) => value === undefined ? value : readValues(valuesOf(value));
+const copyOf = (value) => 
+// Through text, as a wire is: an answer that is a string («"2.50"», an instant) stays one.
+value === undefined ? value : readValues(pack(value));
 function wait(ms, signal) {
     if (ms <= 0)
         return Promise.resolve();
@@ -58,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/check.d.ts

@@ -0,0 +1,64 @@
+/**
+ * The import rules of a Sincpro application, checked — what `sincpro-client check` runs in an
+ * application's `make doctor`, on the web and on a phone alike.
+ *
+ *     src/domains/<bounded context>/{generated,domain,adapters,services,infrastructure,components,entrypoints}
+ *     src/domains/common/            what bounded contexts share
+ *     src/entrypoints/               where the outside comes in
+ *
+ * | Layer             | Never                                                                  |
+ * | ----------------- | ---------------------------------------------------------------------- |
+ * | generated, domain | React, the DOM's libraries (web-ui, composer), its own adapters        |
+ * | adapters          | React, web-ui, composer                                                |
+ * | services          | React, web-ui, composer                                                |
+ * | infrastructure    | its own components                                                     |
+ * | components        | composer, a router                                                     |
+ * | common            | any bounded context                                                    |
+ * | any layer         | another bounded context — but its `index.ts`, from `infrastructure/`   |
+ * | entrypoints/ root | a bounded context's insides — only its `index.ts` (and `common`)       |
+ *
+ * Context: the architecture says these rules are enforced, not recommended; a rule only read in a
+ * page is the first to go under a deadline. Each import is resolved the way the application's
+ * compiler resolves it — its own `tsconfig.json`, its path aliases (`@/domains/…`) — with the
+ * application's TypeScript, so a relative path and an alias are the same import. Nothing here is
+ * a platform's: a React Native app has the same layers (`react-native` counts as React).
+ */
+export type Violation = {
+    /** The importing file, from the root. */
+    file: string;
+    /** What it imports, as written. */
+    imports: string;
+    why: string;
+};
+/** Where a file is in the application's tree. */
+export type Place = {
+    kind: "context";
+    context: string;
+    layer: string | null;
+    index: boolean;
+} | {
+    kind: "entrypoint";
+} | {
+    kind: "other";
+};
+/**
+ * `domains/sales/services/close.ts` → the bounded context `sales`, the layer `services` — wherever
+ * the `domains/` folder is (`src/domains/…`, a workspace's `domains/sales/src/services/…`).
+ */
+export declare function placeOf(path: string): Place;
+/**
+ * Why `from` may not import `specifier`, which resolves to `to` (`null`: a package), or nothing
+ * when it may.
+ */
+export declare function violationOf(from: Place, specifier: string, to: Place | null): string | undefined;
+/** What stops the check before it starts: no root, no config, a config that does not parse. */
+export declare class CheckError extends Error {
+}
+/**
+ * Every import under `root` that breaks a rule, resolved by the application's own TypeScript and
+ * `tsconfig` (its path aliases and its references included). An alias that does not resolve is a
+ * break too — read as a package it would switch every rule off.
+ */
+export declare function checkImports(root: string, options?: {
+    tsconfig?: string;
+}): Promise<Violation[]>;