@sincpro/client-framework 0.0.0-stage → 0.1.0

package/dist/client/entity.d.ts

@@ -0,0 +1,242 @@
+import type { Method } from "./transport.js";
+import { type AnyRecord, 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.
+ */
+export type SummaryPart = "description" | "state" | "type" | "image" | "createdAt" | "createdBy" | "updatedAt" | "updatedBy";
+/**
+ * Which field of the entity plays each part, when it is not the conventional one. `person`: its
+ * records are people or companies.
+ *
+ * Context: declared once with the rest of the entity (`entity(…, { summary })`) because it is
+ * what the entity IS, not how one screen draws it; how a platform reads a record's summary from
+ * it is the platform's.
+ */
+export type SummaryFields = Partial<Record<SummaryPart, string>> & {
+    person?: boolean;
+};
+/**
+ * What each Command of an entity is sent with, by its name: `{ send: { message: string } }`.
+ *
+ * Context: the default is any name and any body — every entity declared before Commands had
+ * types keeps compiling. A typed entity is still one of these (`Entity<T, C>` is assignable to
+ * `Entity<T>`), so every piece that takes an entity takes it.
+ */
+export type CommandBodies = Readonly<Record<string, AnyRecord>>;
+/**
+ * What each Command of an entity answers, by its name: `{ send: { run_id: string } }` — what a
+ * generated entity reads off each operation's `output`.
+ *
+ * Context: `useCommand(issues, "send").run(…)` returns it with no type argument written; a
+ * Command it does not name answers `unknown`, as every Command did before.
+ */
+export type CommandAnswers = Readonly<Record<string, unknown>>;
+/**
+ * Everything a screen needs to know about where an entity lives on the server, declared once.
+ *
+ * Context: a screen should not know a URL. It names the entity, and the entity says where its
+ * list is, where one record is, which Commands it takes, how it is saved and previewed, where a
+ * draft is kept and where its history is. `key` is how the workspace refers to it
+ * (`domain:kind`, the shape of a composer `ResourceRef`).
+ *
+ * The routes are declared, not guessed: sincpro_framework publishes a route per use case and
+ * its model definition does not list them (yet). A route is `"METHOD /path/{id}"` for a write.
+ *
+ *     export const invoices = entity<Invoice>("billing:invoice", {
+ *       list: "/invoices",
+ *       create: "POST /invoices",
+ *       save: "PUT /invoices/{id}",
+ *       preview: "POST /invoices/preview",
+ *       commands: { confirm: "POST /invoices/{id}/confirm", cancel: "POST /invoices/{id}/cancel" },
+ *       history: { route: "/billing-events", type: "Invoice" },
+ *     });
+ *
+ * Its Commands may be typed too — what each one is sent with, by name (`CommandBodies`), and
+ * what each one answers (`CommandAnswers`) — and then `useCommand` and `CommandButton` take
+ * only those names and those bodies, and give back that answer:
+ *
+ *     entity<Issue, { send: { message: string } }, { send: { run_id: string } }>(…)
+ */
+export type Entity<T extends AnyRecord = AnyRecord, C extends CommandBodies = CommandBodies, A extends CommandAnswers = CommandAnswers> = {
+    /** `domain:kind`, e.g. `"billing:invoice"`. */
+    key: string;
+    domain: string;
+    kind: string;
+    /** Where the workspace finds it: the list without an id, one record with it — the shape of a
+     *  composer `ResourceRef`, built here so no screen writes `{ domain, kind, id }` by hand. */
+    ref: (id?: string) => EntityRef;
+    /** A record that does not exist yet — the form that creates one. Its view is the record's.
+     *  With `values`, the form starts with them over the model's defaults: an invoice created
+     *  from its customer starts with that customer (`startingValuesOf`). */
+    newRef: (values?: AnyRecord) => EntityRef;
+    /** Its list opened to CHOOSE one: a row answers whoever asked (composer's `api.pick`). With
+     *  `query`, the list opens on that literal search — what was typed in the picker; with
+     *  `scope`, it offers only what the picker may choose (`scopeOfRef`). */
+    chooserRef: (query?: string, scope?: Expression) => EntityRef;
+    /** The route of its list. */
+    list: string;
+    /** The route of one record. */
+    one: (id: string) => string;
+    /** Its Commands, by name. */
+    commands: Readonly<Record<keyof C & string, WriteRoute>>;
+    /** How a new record is created: the list's own route, usually. */
+    create?: WriteRoute;
+    /** How an edit is saved: the record's own route with `{id}`. */
+    save?: WriteRoute;
+    /** «What does this record become?» before saving — sincpro_framework's `Preview`. */
+    preview?: WriteRoute;
+    /** Where this caller keeps an edit between requests — sincpro_framework's `Drafts`. */
+    draft?: WriteRoute;
+    /** sincpro_framework's `Edit`: ONE route that keeps the draft, saves and discards, by its
+     *  `action`. Declared, a save sends the record whole as the form holds it — not the fields
+     *  that changed under `save` — and it is also where the draft is kept. */
+    edit?: WriteRoute;
+    /** Its business events: the context's events route, and the `entity_type` they carry. */
+    history?: {
+        route: string;
+        type: string;
+    };
+    /** Which fields are its description, state, picture… when they are not the conventional
+     *  ones (`summaryOf`). Empty: the convention decides. */
+    summary: SummaryFields;
+    /** The aggregate it is, as a relation of another model names it (`relation: "Cliente"`).
+     *  Without it, the `aggregate` of its model definition, once known. */
+    aggregate?: string;
+    /** Only carries the record type; never read. */
+    readonly _record?: T;
+    /** Only carries what each Command is sent with; never read. */
+    readonly _commands?: C;
+    /** Only carries what each Command answers; never read. */
+    readonly _answers?: A;
+};
+/** A composer `ResourceRef`, structurally: `core/` does not import the composer. */
+export type EntityRef = {
+    domain: string;
+    kind: string;
+    id?: string;
+    params?: Readonly<Record<string, string>>;
+};
+/**
+ * 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
+ * what a composer reference carries and survives a reload with.
+ */
+export declare const NEW_PARAM = "new";
+export declare const PICK_PARAM = "pick";
+/** What was typed where the chooser was asked for: its list opens on that search. */
+export declare const QUERY_PARAM = "q";
+/** The list a record was opened from (its `Trail`): «3 / 64» and the arrows to its neighbours. */
+export declare const TRAIL_PARAM = "from";
+/** What a new record starts with, as JSON: one param keeps each value's type (a number stays
+ *  a number), where a param per field would turn all of them into text. */
+export declare const WITH_PARAM = "with";
+/** What a chooser may offer at all, as JSON: the picker's cut — its criteria, the keys it
+ *  excludes, its named list's scope — that the list it opens ANDs under everything. */
+export declare const SCOPE_PARAM = "scope";
+/**
+ * What a new record's reference says it starts with (`newRef(values)`), or nothing.
+ *
+ * Context: a reference survives a reload and a link, so its params can be anything a person
+ * typed in the address bar — a value that is not a JSON object is not a start, never an error.
+ */
+export declare function startingValuesOf(ref: Pick<EntityRef, "params">): AnyRecord;
+/**
+ * The cut a chooser's reference carries (`chooserRef(query, scope)`), or nothing.
+ *
+ * Context: a picker that may offer only some records — the contacts of the chosen customer, the
+ * tenants a project is not shared with yet — opened the workspace's chooser on the WHOLE
+ * entity, and offered the rest. The cut travels in the reference, so it survives a reload; read
+ * from an address bar it is untyped, so it is read the way criteria reads a filter from outside
+ * (`readExpression`), and one that does not read is no cut, never an error. It narrows what is
+ * OFFERED; the server still decides what may be stored.
+ */
+export declare function scopeOfRef(ref: Pick<EntityRef, "params">): Expression | undefined;
+/**
+ * A write: its method and its path, `{id}` where the record's key goes. A Command may also say
+ * which field of its body names the record it runs on (`target`: `issue_id`), and then the
+ * record's id is written there when it is sent (`bodyFor`).
+ */
+export type WriteRoute = {
+    method: Method;
+    path: string;
+    target?: string;
+};
+/**
+ * A Command's route: `"POST /invoices/{id}/confirm"`, or, when its body names the record —
+ * sincpro_framework's `targets`, what a generated entity declares —, the route and that field:
+ * `{ route: "POST /issues", target: "project_id" }`.
+ */
+export type CommandRoute = string | {
+    route: string;
+    target: string;
+};
+/** Each Command's route, by name. Typed Commands MUST each have their route — a name a screen
+ *  may run with nowhere to send it is caught here, not on the click. */
+type CommandRoutes<C extends CommandBodies> = string extends keyof C ? {
+    commands?: Readonly<Record<string, CommandRoute>>;
+} : {
+    commands: Readonly<Record<keyof C & string, CommandRoute>>;
+};
+export type EntityRoutes<C extends CommandBodies = CommandBodies> = CommandRoutes<C> & {
+    list: string;
+    /** With `{id}` where the key goes. Without it, `<list>/<id>` — sincpro_framework's convention. */
+    one?: string;
+    /** `"POST /invoices"`: where a new record goes. */
+    create?: string;
+    save?: string;
+    preview?: string;
+    draft?: string;
+    /** `"PUT /invoices/{id}/edit"`: the use case that answers sincpro_framework's `Edit`. */
+    edit?: string;
+    history?: {
+        route: string;
+        type: 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;
+    /** `"Cliente"`: what a many2one of another model calls it, so a form resolves it alone. */
+    aggregate?: string;
+};
+/** `"POST /invoices/{id}/confirm"` → its method and path. A write without a method is a bug. */
+export declare function writeRoute(text: string): WriteRoute;
+/**
+ * The path with the record's key in place of `{id}`, and every other `{name}` taken from the
+ * body's field of that name: `POST /projects/{id}/shares/{tenant_id}/revoke` with
+ * `{ tenant_id: "acme" }`.
+ *
+ * Context: sincpro_framework reads a path parameter as a field of the use case's DTO (its
+ * wire merges `{...body, ...path_params}`), so the body already names every key a route
+ * needs — a second argument for them would say the same thing twice. A key the body lacks is
+ * the screen's bug, said before anything is sent. Without an `id`, `{id}` stays: a create or a
+ * preview of a new record has none.
+ */
+export declare function pathFor(route: WriteRoute, id?: string, body?: AnyRecord): string;
+/**
+ * What a Command of a record is sent with: the body as given, and — when its route says which
+ * field names the record (`target`) — the record's id in that field.
+ *
+ *     bodyFor({ method: "POST", path: "/issues", target: "project_id" }, "p1", { title: "x" })
+ *       ->  { title: "x", project_id: "p1" }
+ *
+ * Context: sincpro_framework says, per operation, which input field holds the key of each
+ * entity it runs on (`targets`). A path that carries it (`/issues/{issue_id}/messages`) and a
+ * body that carries it (`POST /issues` with `project_id`) are the same thing to the server — a
+ * path parameter is read as a field of the DTO — so it goes in the body, and `pathFor` takes it
+ * from there. Without an id (a Command that creates) the body is sent as it is.
+ */
+export declare function bodyFor(route: WriteRoute, id: string | undefined, body: AnyRecord): AnyRecord;
+/**
+ * A list's route with its own parameters: `{ tenant_id: "acme" }` → `/projects?tenant_id=acme`.
+ * An empty value is no parameter — a filter left blank. A list under a record names its key in
+ * the path (`/tenants/{tenant_id}/members`): that parameter fills it, and only the rest goes in
+ * the query.
+ *
+ * Context: sincpro_framework reads a path parameter as a field of the search's DTO, the same
+ * field a query parameter would fill, so the screen gives them all as one set of parameters. A
+ * 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;
+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

@@ -0,0 +1,187 @@
+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
+ * what a composer reference carries and survives a reload with.
+ */
+export const NEW_PARAM = "new";
+export const PICK_PARAM = "pick";
+/** What was typed where the chooser was asked for: its list opens on that search. */
+export const QUERY_PARAM = "q";
+/** The list a record was opened from (its `Trail`): «3 / 64» and the arrows to its neighbours. */
+export const TRAIL_PARAM = "from";
+/** What a new record starts with, as JSON: one param keeps each value's type (a number stays
+ *  a number), where a param per field would turn all of them into text. */
+export const WITH_PARAM = "with";
+/** What a chooser may offer at all, as JSON: the picker's cut — its criteria, the keys it
+ *  excludes, its named list's scope — that the list it opens ANDs under everything. */
+export const SCOPE_PARAM = "scope";
+/**
+ * What a new record's reference says it starts with (`newRef(values)`), or nothing.
+ *
+ * Context: a reference survives a reload and a link, so its params can be anything a person
+ * typed in the address bar — a value that is not a JSON object is not a start, never an error.
+ */
+export function startingValuesOf(ref) {
+    const written = ref.params?.[WITH_PARAM];
+    if (written === undefined)
+        return {};
+    try {
+        const read = JSON.parse(written);
+        return read !== null && typeof read === "object" && !Array.isArray(read)
+            ? read
+            : {};
+    }
+    catch {
+        return {};
+    }
+}
+/**
+ * The cut a chooser's reference carries (`chooserRef(query, scope)`), or nothing.
+ *
+ * Context: a picker that may offer only some records — the contacts of the chosen customer, the
+ * tenants a project is not shared with yet — opened the workspace's chooser on the WHOLE
+ * entity, and offered the rest. The cut travels in the reference, so it survives a reload; read
+ * from an address bar it is untyped, so it is read the way criteria reads a filter from outside
+ * (`readExpression`), and one that does not read is no cut, never an error. It narrows what is
+ * OFFERED; the server still decides what may be stored.
+ */
+export function scopeOfRef(ref) {
+    const written = ref.params?.[SCOPE_PARAM];
+    if (written === undefined)
+        return undefined;
+    try {
+        return readExpression(JSON.parse(written));
+    }
+    catch {
+        return undefined;
+    }
+}
+const METHODS = new Set(["POST", "PUT", "PATCH", "DELETE"]);
+/** `"POST /invoices/{id}/confirm"` → its method and path. A write without a method is a bug. */
+export function writeRoute(text) {
+    const [method, path] = text.trim().split(/\s+/, 2);
+    if (!METHODS.has(method) || path === undefined)
+        throw new Error(`"${text}" is not "METHOD /path": a write says how it is sent`);
+    return { method: method, path };
+}
+const PATH_KEY = /\{([A-Za-z_][A-Za-z0-9_]*)\}/g;
+/**
+ * The path with the record's key in place of `{id}`, and every other `{name}` taken from the
+ * body's field of that name: `POST /projects/{id}/shares/{tenant_id}/revoke` with
+ * `{ tenant_id: "acme" }`.
+ *
+ * Context: sincpro_framework reads a path parameter as a field of the use case's DTO (its
+ * wire merges `{...body, ...path_params}`), so the body already names every key a route
+ * needs — a second argument for them would say the same thing twice. A key the body lacks is
+ * the screen's bug, said before anything is sent. Without an `id`, `{id}` stays: a create or a
+ * preview of a new record has none.
+ */
+export function pathFor(route, id, body) {
+    return route.path.replace(PATH_KEY, (whole, name) => {
+        if (name === "id")
+            return id === undefined ? whole : encodeURIComponent(id);
+        const value = body?.[name];
+        if (value === undefined || value === null || value === "")
+            throw new Error(`"${route.method} ${route.path}" needs "${name}" in the body`);
+        return encodeURIComponent(String(value));
+    });
+}
+/**
+ * What a Command of a record is sent with: the body as given, and — when its route says which
+ * field names the record (`target`) — the record's id in that field.
+ *
+ *     bodyFor({ method: "POST", path: "/issues", target: "project_id" }, "p1", { title: "x" })
+ *       ->  { title: "x", project_id: "p1" }
+ *
+ * Context: sincpro_framework says, per operation, which input field holds the key of each
+ * entity it runs on (`targets`). A path that carries it (`/issues/{issue_id}/messages`) and a
+ * body that carries it (`POST /issues` with `project_id`) are the same thing to the server — a
+ * path parameter is read as a field of the DTO — so it goes in the body, and `pathFor` takes it
+ * from there. Without an id (a Command that creates) the body is sent as it is.
+ */
+export function bodyFor(route, id, body) {
+    if (route.target === undefined || id === undefined || id === "")
+        return body;
+    return { ...body, [route.target]: id };
+}
+/** A Command's route as declared: a `"METHOD /path"`, or that and the field naming its record. */
+function commandRoute(declared) {
+    if (typeof declared === "string")
+        return writeRoute(declared);
+    return { ...writeRoute(declared.route), target: declared.target };
+}
+/**
+ * A list's route with its own parameters: `{ tenant_id: "acme" }` → `/projects?tenant_id=acme`.
+ * An empty value is no parameter — a filter left blank. A list under a record names its key in
+ * the path (`/tenants/{tenant_id}/members`): that parameter fills it, and only the rest goes in
+ * the query.
+ *
+ * Context: sincpro_framework reads a path parameter as a field of the search's DTO, the same
+ * field a query parameter would fill, so the screen gives them all as one set of parameters. A
+ * key the path needs and the parameters lack is the screen's bug, said before anything is sent.
+ */
+export function listRoute(list, params) {
+    const given = params ?? {};
+    const placed = new Set();
+    const path = list.replace(PATH_KEY, (_whole, name) => {
+        const value = given[name];
+        if (value === undefined || value === "")
+            throw new Error(`the list "${list}" needs "${name}" in its parameters`);
+        placed.add(name);
+        return encodeURIComponent(value);
+    });
+    const query = new URLSearchParams(Object.entries(given).filter(([name, value]) => value !== "" && !placed.has(name))).toString();
+    if (query === "")
+        return path;
+    return `${path}${path.includes("?") ? "&" : "?"}${query}`;
+}
+export function entity(key, routes) {
+    if (!/^[^:\s]+:[^:\s]+$/.test(key))
+        throw new Error(`entity key "${key}" is not domain:kind`);
+    const list = routes.list.split("?")[0] ?? routes.list;
+    const template = routes.one ?? `${list}/{id}`;
+    const [domain = "", kind = ""] = key.split(":");
+    return {
+        key,
+        domain,
+        kind,
+        ref: (id) => ({ domain, kind, ...(id === undefined || id === "" ? {} : { id }) }),
+        newRef: (values) => ({
+            domain,
+            kind,
+            params: {
+                [NEW_PARAM]: "1",
+                ...(values === undefined || Object.keys(values).length === 0
+                    ? {}
+                    : { [WITH_PARAM]: JSON.stringify(values) }),
+            },
+        }),
+        chooserRef: (query, scope) => ({
+            domain,
+            kind,
+            params: {
+                [PICK_PARAM]: "1",
+                ...(query === undefined || query.trim() === ""
+                    ? {}
+                    : { [QUERY_PARAM]: query.trim() }),
+                ...(scope === undefined ? {} : { [SCOPE_PARAM]: JSON.stringify(scope) }),
+            },
+        }),
+        list: routes.list,
+        one: (id) => template.replace("{id}", encodeURIComponent(id)),
+        // Built from exactly the names `routes.commands` was typed with.
+        commands: Object.fromEntries(Object.entries(routes.commands ?? {}).map(([name, declared]) => [
+            name,
+            commandRoute(declared),
+        ])),
+        ...(routes.create === undefined ? {} : { create: writeRoute(routes.create) }),
+        ...(routes.save === undefined ? {} : { save: writeRoute(routes.save) }),
+        ...(routes.preview === undefined ? {} : { preview: writeRoute(routes.preview) }),
+        ...(routes.draft === undefined ? {} : { draft: writeRoute(routes.draft) }),
+        ...(routes.edit === undefined ? {} : { edit: writeRoute(routes.edit) }),
+        ...(routes.history === undefined ? {} : { history: routes.history }),
+        summary: routes.summary ?? {},
+        ...(routes.aggregate === undefined ? {} : { aggregate: routes.aggregate }),
+    };
+}

package/dist/client/ids.d.ts

@@ -0,0 +1,17 @@
+/**
+ * A new record's key, minted where the record is born: a UUID v7 as 32 hex characters —
+ * sincpro_framework's `new_entity_id`.
+ *
+ * Context: sincpro_framework's `Edit` creates a new record under the id the CLIENT names («a
+ * UUID v7 it mints»), and the draft and the stored record share it from the first draft save.
+ * A form that waited for the server to name it could neither keep a draft of a new record nor
+ * reach the edit route at all (`PUT /invoices/{id}/edit` needs the id in its path). The layout
+ * is the backend's (RFC 9562): 48 bits of unix milliseconds, the version, a 12-bit counter
+ * within the millisecond, the variant and 62 random bits — so ids minted here sort by when
+ * they were minted, like the server's, and ordering by `id` is still ordering by creation.
+ *
+ *     newEntityId()   // "019a4c2e7f1074a8b13fa739ccbdcd53"
+ */
+export declare function newEntityId(now?: number): string;
+/** A key that is a UUID v7 as sincpro_framework writes it: 32 hex, version 7, variant `10`. */
+export declare function isEntityId(text: string): boolean;

package/dist/client/ids.js

@@ -0,0 +1,52 @@
+/**
+ * A new record's key, minted where the record is born: a UUID v7 as 32 hex characters —
+ * sincpro_framework's `new_entity_id`.
+ *
+ * Context: sincpro_framework's `Edit` creates a new record under the id the CLIENT names («a
+ * UUID v7 it mints»), and the draft and the stored record share it from the first draft save.
+ * A form that waited for the server to name it could neither keep a draft of a new record nor
+ * reach the edit route at all (`PUT /invoices/{id}/edit` needs the id in its path). The layout
+ * is the backend's (RFC 9562): 48 bits of unix milliseconds, the version, a 12-bit counter
+ * within the millisecond, the variant and 62 random bits — so ids minted here sort by when
+ * they were minted, like the server's, and ordering by `id` is still ordering by creation.
+ *
+ *     newEntityId()   // "019a4c2e7f1074a8b13fa739ccbdcd53"
+ */
+const COUNTER_MAX = 0xfff;
+let lastMillis = -1;
+let counter = 0;
+function randomBytes(count) {
+    return globalThis.crypto.getRandomValues(new Uint8Array(count));
+}
+function hex(value, digits) {
+    return value.toString(16).padStart(digits, "0");
+}
+export function newEntityId(now = Date.now()) {
+    // The clock never runs backwards for these ids: the same millisecond (or an earlier one, a
+    // clock moved back) counts up; a full counter borrows the next millisecond.
+    let millis = now;
+    if (millis <= lastMillis) {
+        millis = lastMillis;
+        counter += 1;
+        if (counter > COUNTER_MAX) {
+            millis += 1;
+            counter = 0;
+        }
+    }
+    else {
+        // A fresh millisecond starts the counter at a random point of its lower half: room to count.
+        const [high = 0, low = 0] = randomBytes(2);
+        counter = ((high << 8) | low) & 0x7ff;
+    }
+    lastMillis = millis;
+    const tail = randomBytes(8);
+    tail[0] = ((tail[0] ?? 0) & 0x3f) | 0x80; // the variant, `10`
+    return (hex(millis, 12) +
+        "7" + // the version
+        hex(counter, 3) +
+        Array.from(tail, (byte) => hex(byte, 2)).join(""));
+}
+/** A key that is a UUID v7 as sincpro_framework writes it: 32 hex, version 7, variant `10`. */
+export function isEntityId(text) {
+    return /^[0-9a-f]{12}7[0-9a-f]{3}[89ab][0-9a-f]{15}$/.test(text);
+}

package/dist/client/memory.d.ts

@@ -0,0 +1,46 @@
+import { type Draft, type Method, type Transport } from "./transport.js";
+import type { AnyRecord, Criteria, Meta, Problem } from "@sincpro/criteria";
+/**
+ * A server held in memory: tables of rows with their definition, answered with the same
+ * engine sincpro_framework's criteria runs on.
+ *
+ * Context: not a test double. It is what a screen runs against before its server exists,
+ * what Storybook and the tests run against, and what a domain with no server at all uses —
+ * rows a screen already holds. It filters, orders, pages and counts
+ * exactly as the server would (`answer` from `@sincpro/criteria/engine`), drops what the
+ * model cannot answer and reports it, and refuses what the server would refuse. So the day a
+ * real server answers, only the transport changes.
+ *
+ * A record is found at `<list route>/<id>`, by the field the model fetches by (`get_id`, else
+ * the identity) — the convention sincpro_framework's REST routes follow.
+ *
+ *     const transport = memoryTransport({
+ *       "/invoices": { meta: invoiceMeta, rows: invoices },
+ *     }, { latency: 300 });
+ */
+export type MemoryTable = {
+    meta: Meta;
+    rows: readonly AnyRecord[];
+};
+export type MemoryOptions = {
+    /** Milliseconds every answer waits, so a screen's «loading» can be seen and tested. */
+    latency?: number;
+    /**
+     * Answer a Command — a write, an action, a preview — the way the service would. It may
+     * change the tables' rows (they are read on every request) and throw a `TransportError` to
+     * refuse. Without it, every Command is a 404.
+     */
+    handle?: (method: Method, route: string, body: unknown) => unknown;
+    /** Answer a read that is neither a page nor a record (`GET /me`), its route with its query.
+     *  Without it, the transport has no `read`. */
+    read?: (route: string) => unknown;
+    /** The draft this caller kept of a record, answered with it — sincpro_framework's `Drafts`. */
+    draft?: (route: string) => Draft | null;
+    /** Every list request, as it arrived: what a story or a test checks was really asked. */
+    observe?: (route: string, criteria: Criteria) => void;
+    /** Refuse a route the way a server would: return the problem it answers with. */
+    refuse?: (route: string) => (Problem & {
+        status?: number;
+    }) | undefined;
+};
+export declare function memoryTransport(tables: Readonly<Record<string, MemoryTable>>, options?: MemoryOptions): Transport;

package/dist/client/memory.js

@@ -0,0 +1,108 @@
+import { TransportError, } from "./transport.js";
+import { answer, answerGroups } from "@sincpro/criteria/engine";
+function wait(ms, signal) {
+    if (ms <= 0)
+        return Promise.resolve();
+    return new Promise((done, failed) => {
+        const timer = setTimeout(done, ms);
+        signal?.addEventListener("abort", () => {
+            clearTimeout(timer);
+            failed(signal.reason);
+        });
+    });
+}
+export function memoryTransport(tables, options = {}) {
+    const answered = new Map();
+    async function check(route, signal) {
+        await wait(options.latency ?? 0, signal);
+        const refused = options.refuse?.(route);
+        if (refused !== undefined)
+            throw new TransportError(route, refused.status ?? 400, refused);
+    }
+    function tableAt(route) {
+        const path = route.split("?")[0] ?? route;
+        const table = tables[path];
+        if (table === undefined)
+            throw new TransportError(route, 404, {
+                kind: "not_found",
+                reason: "ROUTE_NOT_FOUND",
+                next_step: "fix_request",
+                retryable: false,
+                errors: [],
+                extensions: {},
+                detail: `No table answers ${path}.`,
+            });
+        return table;
+    }
+    return {
+        async list(route, criteria, signal) {
+            options.observe?.(route, criteria);
+            await check(route, signal);
+            const table = tableAt(route);
+            // A grouped question is answered with the groups — counted over EVERY row that matches,
+            // each with the criteria that opens it — the way the server's aggregation answers it.
+            const grouped = (criteria.grouping?.group_by?.length ?? 0) > 0;
+            const page = grouped
+                ? answerGroups(table.rows, criteria, table.meta)
+                : answer(table.rows, criteria, table.meta);
+            // A copy, as over a wire: a screen holding a row must not see the server change it.
+            return { ...page, rows: structuredClone(page.rows) };
+        },
+        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));
+            const key = table.meta.get_id || table.meta.identity;
+            const record = table.rows.find((row) => String(row[key]) === id);
+            if (record === undefined)
+                throw new TransportError(route, 404, {
+                    kind: "not_found",
+                    reason: "AGGREGATE_NOT_FOUND",
+                    next_step: "do_not_retry",
+                    retryable: false,
+                    errors: [],
+                    extensions: {},
+                    detail: `${table.meta.aggregate} ${id} does not exist.`,
+                });
+            return {
+                record: structuredClone(record),
+                meta: table.meta,
+                dropped: [],
+                draft: options.draft?.(route) ?? null,
+            };
+        },
+        async send(method, route, body, signal, sending) {
+            await check(route, signal);
+            // A key already answered is answered again, without running the Command twice — what
+            // sincpro_framework's `@idempotency` does with a repeated `Idempotency-Key`.
+            const key = sending?.idempotencyKey;
+            if (key !== undefined && answered.has(key))
+                return structuredClone(answered.get(key));
+            if (options.handle === undefined)
+                throw new TransportError(route, 404, {
+                    kind: "not_found",
+                    reason: "ROUTE_NOT_FOUND",
+                    next_step: "fix_request",
+                    retryable: false,
+                    errors: [],
+                    extensions: {},
+                    detail: `Nothing answers ${method} ${route}.`,
+                });
+            // A deep copy: what the caller sent is not what the server keeps.
+            const answer = await options.handle(method, route, structuredClone(body));
+            if (key !== undefined)
+                answered.set(key, structuredClone(answer));
+            return answer;
+        },
+        ...(options.read === undefined
+            ? {}
+            : {
+                async read(route, signal) {
+                    await check(route, signal);
+                    // A copy, as every answer: over a wire nobody holds the server's object.
+                    return structuredClone(await options.read(route));
+                },
+            }),
+    };
+}