@sincpro/client-framework 0.0.0-stage → 0.2.0

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));
+                },
+            }),
+    };
+}

package/dist/client/rest.d.ts

@@ -0,0 +1,49 @@
+import { type Transport } from "./transport.js";
+import { type Criteria } from "@sincpro/criteria";
+/**
+ * The REST wire of sincpro_framework (`FastApiGateway`).
+ *
+ * Context: a list is criteria's `restSource` (0.3.1 sends the criteria as plain JSON and joins
+ * a route that carries its own query, `/projects?tenant_id=acme` — the two things forge's
+ * console found wrong in 0.3.0, fixed there). What this adds is what criteria does not know:
+ * one record (`one()`), a write (`send()`, with its `Idempotency-Key`), and its refusals as a
+ * `TransportError`, the one error every screen explains.
+ *
+ * The definition of each model — what a list, a form and a select are built from — is read
+ * from the bounded context's discovery document (`document`, `/openapi.json` by default), once,
+ * and read again only when an answer says another version of its model (`model_version`); the
+ * document is revalidated with its `ETag`, so an unchanged one costs a `304`.
+ *
+ *     const transport = restTransport({
+ *       base: "/v1",
+ *       headers: () => ({ Authorization: `Bearer ${session.secret}` }),
+ *     });
+ */
+export type RestOptions = {
+    /** Prepended to every route: `"/v1"`, `"https://forge.sincpro.com.bo/v1"`. */
+    base?: string;
+    /** Sent with every request. A function is called fresh each time — a token that rotates. */
+    headers?: Record<string, string> | (() => Record<string, string>);
+    /** Defaults to the global `fetch`. Inject one for tests. */
+    fetch?: typeof fetch;
+    /** 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;
+    /**
+     * The version of each model the application was written against — the snapshot it was
+     * generated from (`versionsOf(contract)`). With it, an answer of another version is told to
+     * `onVersionDrift`: the server moved, the generated code did not.
+     */
+    snapshot?: Readonly<Record<string, string>>;
+    /** Called once per model and version the server answers that the snapshot does not hold —
+     *  never an error: the screen keeps working on the live definition. */
+    onVersionDrift?: (drift: VersionDrift) => void;
+};
+/** A model the server answers at another version than the snapshot the code came from. */
+export type VersionDrift = {
+    model: string;
+    snapshot: string;
+    live: string;
+};
+export declare function urlOf<T>(base: string, route: string, criteria?: Criteria<T>): string;
+export declare function restTransport(options?: RestOptions): Transport;

package/dist/client/rest.js

@@ -0,0 +1,143 @@
+import { definitionOf, modelAt, } from "./discovery.js";
+import { TransportError, } from "./transport.js";
+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"]);
+export function urlOf(base, route, criteria) {
+    const url = `${base}${route}`;
+    if (criteria === undefined)
+        return url;
+    const joiner = url.includes("?") ? "&" : "?";
+    return `${url}${joiner}criteria=${encodeURIComponent(JSON.stringify(criteria))}`;
+}
+/** The path a route is asked at, without its query: what a document path is matched with. */
+function pathOf(url) {
+    const path = url.split("?")[0] ?? url;
+    return /^https?:\/\//.test(path) ? new URL(path).pathname : path;
+}
+/** Where the document is: `document` as given when absolute, else at the origin of `base`. */
+function documentUrl(base, document) {
+    if (/^https?:\/\//.test(document) || !/^https?:\/\//.test(base))
+        return document;
+    return new URL(document, base).toString();
+}
+export function restTransport(options = {}) {
+    const base = options.base ?? "";
+    const doFetch = options.fetch ?? ((input, init) => fetch(input, init));
+    const own = () => typeof options.headers === "function" ? options.headers() : (options.headers ?? {});
+    // 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");
+    let held;
+    let tag = null;
+    function documentRead(fresh) {
+        if (located === null)
+            return Promise.resolve(null);
+        if (held !== undefined && !fresh)
+            return held;
+        const before = held;
+        held = (async () => {
+            try {
+                const response = await doFetch(documentUrl(base, located), {
+                    headers: { ...own(), ...(tag === null ? {} : { "If-None-Match": tag }) },
+                });
+                if (response.status === 304 && before !== undefined)
+                    return await before;
+                if (!response.ok)
+                    return null;
+                tag = response.headers.get("etag");
+                return (await response.json());
+            }
+            catch {
+                return null;
+            }
+        })();
+        return held;
+    }
+    /** The definition of the model `url` answers; read again when `version` is not the one held. */
+    // Each drift is told once: a list read every few seconds would say it on every page.
+    const told = new Set();
+    function noticeDrift(model, live) {
+        const snapshot = options.snapshot?.[model];
+        if (snapshot === undefined || !live || live === snapshot)
+            return;
+        const key = `${model}\u0000${live}`;
+        if (told.has(key))
+            return;
+        told.add(key);
+        options.onVersionDrift?.({ model, snapshot, live });
+    }
+    async function definitionAt(url, method, version) {
+        const published = await documentRead(false);
+        if (published === null)
+            return null;
+        const name = modelAt(published, pathOf(url), method);
+        if (name === undefined)
+            return null;
+        noticeDrift(name, version);
+        const known = definitionOf(published, name);
+        if (known === undefined || !version || known.version === version)
+            return known?.meta ?? null;
+        const again = await documentRead(true);
+        return (again === null ? undefined : definitionOf(again, name))?.meta ?? known.meta;
+    }
+    async function get(route, url, signal, write, call) {
+        const headers = write
+            ? {
+                ...own(),
+                ...call?.headers,
+                "Content-Type": "application/json",
+                ...(write.key === undefined ? {} : { "Idempotency-Key": write.key }),
+            }
+            : { ...own(), ...call?.headers };
+        const response = await doFetch(url, {
+            headers,
+            ...(write ? { method: write.method, body: JSON.stringify(write.body) } : {}),
+            ...(signal ? { signal } : {}),
+        });
+        const text = await response.text();
+        if (!response.ok)
+            throw new TransportError(route, response.status, readProblem(text), undefined);
+        return text ? JSON.parse(text) : null;
+    }
+    return {
+        async list(route, criteria, signal, call) {
+            const source = restSource(`${base}${route}`, {
+                headers: () => ({ ...own(), ...call?.headers }),
+                fetch: doFetch,
+            });
+            try {
+                const page = await source.read(criteria, signal);
+                return {
+                    ...page,
+                    meta: page.meta ?? (await definitionAt(`${base}${route}`, "get", page.version)),
+                };
+            }
+            catch (error) {
+                if (error instanceof RestError)
+                    throw new TransportError(route, error.status, error.problem, undefined);
+                throw error;
+            }
+        },
+        async read(route, signal, call) {
+            return (await get(route, urlOf(base, route), signal, undefined, call));
+        },
+        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));
+            const [key] = own;
+            if (own.length !== 1 || key === undefined)
+                throw new TransportError(route, 200, null, `${route} answered ${own.length} fields of its own (${own.join(", ")}); a record answers one`);
+            return {
+                record: answer[key],
+                meta: await definitionAt(urlOf(base, route), "get", answer["model_version"]),
+                dropped: answer["dropped"] ?? [],
+                draft: answer["draft"] ?? null,
+            };
+        },
+        async send(method, route, body, signal, sending) {
+            return (await get(route, urlOf(base, route), signal, { method, body, key: sending?.idempotencyKey }, sending));
+        },
+    };
+}

package/dist/client/retry.d.ts

@@ -0,0 +1,24 @@
+/**
+ * The `Idempotency-Key` of a gesture: one per thing a person meant to do, the SAME one while
+ * that thing is retried.
+ *
+ * Context: a Command that got no answer — the network dropped, a proxy answered 502 — may have
+ * run. Sending it again with a new key could pay twice; with the same key the server answers
+ * what it already did (sincpro_framework's `@idempotency`). So a key lives until the server
+ * gives a definite answer: done, or refused for a reason a retry does not change. Changing the
+ * body is a different gesture, and gets a new key — the server refuses a key that comes back
+ * with another payload.
+ *
+ *     const keys = retryKeys();
+ *     const key = keys.keyFor(body);          // the same while the previous one went unanswered
+ *     try { await send(…, { idempotencyKey: key }); keys.settle(null); }
+ *     catch (error) { keys.settle(error); }   // kept when nobody knows what happened
+ */
+export type RetryKeys = {
+    keyFor: (body: unknown) => string;
+    /** What the last attempt ended in: `null` when it was answered. */
+    settle: (error: unknown) => void;
+};
+/** Whether a failure leaves it unknown if the Command ran — so a retry must reuse its key. */
+export declare function unanswered(error: unknown): boolean;
+export declare function retryKeys(make?: () => string): RetryKeys;

package/dist/client/retry.js

@@ -0,0 +1,25 @@
+import { TransportError } from "./transport.js";
+/** Whether a failure leaves it unknown if the Command ran — so a retry must reuse its key. */
+export function unanswered(error) {
+    if (!(error instanceof TransportError))
+        return true;
+    if (error.status === null || error.status >= 500)
+        return true;
+    // The same key is still running elsewhere: retry once it completes, with that key.
+    return error.problem?.kind === "in_progress";
+}
+export function retryKeys(make = () => globalThis.crypto.randomUUID()) {
+    let pending = null;
+    return {
+        keyFor: (body) => {
+            const sent = JSON.stringify(body ?? null);
+            if (pending === null || pending.body !== sent)
+                pending = { body: sent, key: make() };
+            return pending.key;
+        },
+        settle: (error) => {
+            if (error === null || !unanswered(error))
+                pending = null;
+        },
+    };
+}

package/dist/client/transport.d.ts

@@ -0,0 +1,89 @@
+import type { Criteria, Dropped, Meta, Page, Problem } from "@sincpro/criteria";
+/**
+ * The one seam between this package and a server.
+ *
+ * Context: a list and a record are the same two questions whatever the wire is — «a page of
+ * these, under this criteria» and «this one». REST today; JSON-RPC and gRPC are the other
+ * wires sincpro_framework serves. Each of those is
+ * one adapter implementing this, and nothing above it changes. A route is a string the adapter
+ * understands: a path for REST, a method for RPC.
+ *
+ * Every adapter throws `TransportError` for a refusal, so a screen explains a failure once
+ * whichever wire it came over.
+ */
+export interface Transport {
+    /** A page of records under the criteria. */
+    list<T>(route: string, criteria: Criteria<T>, signal?: AbortSignal, options?: CallOptions): Promise<Page<T>>;
+    /** One record, with the definition of its model. */
+    one<T>(route: string, signal?: AbortSignal, options?: CallOptions): Promise<One<T>>;
+    /** A Command — a write, an action, a preview: `method` and a JSON body, its answer back. */
+    send<T>(method: Method, route: string, body: unknown, signal?: AbortSignal, options?: SendOptions): Promise<T>;
+    /**
+     * A read that is neither a page nor one record — a Query of the context's own, `GET /me` —:
+     * the route with its parameters already in it (`listRoute`), its answer as it came. Optional,
+     * so a transport written before it keeps compiling; call it through `readRoute`.
+     */
+    read?<T>(route: string, signal?: AbortSignal, options?: CallOptions): Promise<T>;
+}
+/**
+ * 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.
+ */
+export declare function readRoute<T>(transport: Transport, route: string, signal?: AbortSignal, options?: CallOptions): Promise<T>;
+export type Method = "POST" | "PUT" | "PATCH" | "DELETE";
+/**
+ * How a Command travels besides its body.
+ *
+ * Context: sincpro_framework runs a Command declared `@idempotency` once per key (REST: the
+ * `Idempotency-Key` header; 400 `IDEMPOTENCY_KEY_MISSING` without it) and answers a repeat with
+ * the first answer. That is what makes «retry» safe after a request that got no answer: the
+ * server may have created the invoice, and the same key cannot create it twice.
+ */
+export type SendOptions = CallOptions & {
+    /** One per gesture, kept while it is retried — `retryKeys()`. */
+    idempotencyKey?: string;
+};
+/**
+ * What one call carries besides its question: headers of that call alone.
+ *
+ * Context: the trace and the context of the use case that asked travel with each request
+ * (`traceparent`, `sincpro-context`) — and two use cases run at once, so they cannot be the
+ * transport's own headers. A transport bound to a use case's execution (`bindTransport`) writes
+ * them here; a transport that has nowhere to send headers ignores them.
+ */
+export type CallOptions = {
+    headers?: Readonly<Record<string, string>>;
+};
+/** One record as sincpro_framework answers it (`ResponseRecord`): the record, its model. */
+export type One<T> = {
+    record: T;
+    meta: Meta | null;
+    dropped: Dropped[];
+    /** What this caller kept of an edit between requests (sincpro_framework `Drafts`). */
+    draft: Draft | null;
+};
+/** A kept edit: the values typed, the version of the draft, the record version it started on. */
+/**
+ * The caller's draft of a record (sincpro_framework's `DraftState`): the version the next edit
+ * names, the stored version it started from, and whether the record moved on since (`stale`).
+ * `values` only when a server answers them apart from the record — sincpro_framework answers the
+ * record FROM the draft instead.
+ */
+export type Draft = {
+    values?: Record<string, unknown>;
+    version: number;
+    origin_version?: number;
+    kept_at?: string;
+    stale?: boolean;
+};
+/**
+ * A refusal, from any wire. `problem` is what the server said about it (RFC 9457 plus the
+ * engine's `kind`, `next_step`, `guidance`) or `null` when it said nothing readable — a proxy's
+ * HTML page. `status` is `null` when the request never got an answer.
+ */
+export declare class TransportError extends Error {
+    readonly route: string;
+    readonly status: number | null;
+    readonly problem: Problem | null;
+    constructor(route: string, status: number | null, problem: Problem | null, message?: string);
+}

package/dist/client/transport.js

@@ -0,0 +1,26 @@
+/**
+ * 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.
+ */
+export function readRoute(transport, route, signal, options) {
+    if (transport.read === undefined)
+        return Promise.reject(new Error(`this transport has no read(): it cannot ask GET ${route} — give it one`));
+    return transport.read(route, signal, options);
+}
+/**
+ * A refusal, from any wire. `problem` is what the server said about it (RFC 9457 plus the
+ * engine's `kind`, `next_step`, `guidance`) or `null` when it said nothing readable — a proxy's
+ * HTML page. `status` is `null` when the request never got an answer.
+ */
+export class TransportError extends Error {
+    route;
+    status;
+    problem;
+    constructor(route, status, problem, message) {
+        super(message ?? problem?.detail ?? problem?.title ?? `${status ?? "no answer"} at ${route}`);
+        this.route = route;
+        this.status = status;
+        this.problem = problem;
+        this.name = "TransportError";
+    }
+}

package/dist/codegen/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/codegen/cli.js

@@ -0,0 +1,82 @@
+#!/usr/bin/env node
+import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { clientFileOf } from "./client.js";
+import { domainFileOf } from "./domain.js";
+import { entitiesFileOf } from "./entities.js";
+import { aliasOf } from "./names.js";
+/**
+ * `sincpro-client generate <contract.json> --out <dir> [--domain <name>] [--base <path>]` — what an
+ * application's `make client` runs, once per bounded context, over the client contract
+ * sincpro_framework exported (`export-client-contract`):
+ *
+ * - `domain.ts`: the DTOs, only types;
+ * - `client.ts`: every operation as data, and `clientOf(transport)`;
+ * - `entities.ts`: an `entity<T, C>()` per model a screen can list;
+ * - `contract.json`: the snapshot they were written from, for `metasOf`.
+ *
+ * A bare metamodel (`export_metamodel`, no bindings) writes `domain.ts` and `contract.json` only.
+ *
+ * Context: it writes only into `--out`, and the same bytes for the same contract, so `make
+ * verify-client` regenerates and fails on any difference. The folder is the generator's: keep
+ * it out of the application's prettier and eslint, or a formatter rewrites what was generated.
+ */
+const USAGE = "usage: sincpro-client generate <contract.json> --out <dir> [--domain <name>] [--base <path>]";
+/** JSON with every key sorted: the snapshot reads the same however the server ordered it. */
+function canonical(value) {
+    if (Array.isArray(value))
+        return value.map(canonical);
+    if (value === null || typeof value !== "object")
+        return value;
+    return Object.fromEntries(Object.keys(value)
+        .sort()
+        .map((key) => [key, canonical(value[key])]));
+}
+/** The command, its source and its flags — or `undefined` when they do not read as usage says. */
+function parsed(args) {
+    const [command, source, ...rest] = args;
+    if (command !== "generate" || source === undefined)
+        return undefined;
+    const flags = new Map();
+    for (let at = 0; at < rest.length; at += 2) {
+        const flag = rest[at];
+        const value = rest[at + 1];
+        if (flag === undefined || value === undefined || !flag.startsWith("--"))
+            return undefined;
+        flags.set(flag, value);
+    }
+    const out = flags.get("--out");
+    const known = new Set(["--out", "--domain", "--base"]);
+    if (out === undefined || [...flags.keys()].some((one) => !known.has(one)))
+        return undefined;
+    const domain = flags.get("--domain");
+    const base = flags.get("--base");
+    return {
+        source,
+        out,
+        options: {
+            ...(domain === undefined ? {} : { domain }),
+            ...(base === undefined ? {} : { base }),
+        },
+    };
+}
+function main(args) {
+    const asked = parsed(args);
+    if (asked === undefined) {
+        console.error(USAGE);
+        return 2;
+    }
+    const metamodel = JSON.parse(readFileSync(asked.source, "utf8"));
+    const files = { "domain.ts": domainFileOf(metamodel) };
+    if (metamodel.bindings !== undefined) {
+        files["client.ts"] = clientFileOf(metamodel, asked.options);
+        files["entities.ts"] = entitiesFileOf(metamodel, asked.options);
+    }
+    files["contract.json"] = `${JSON.stringify(canonical(metamodel), null, 2)}\n`;
+    mkdirSync(asked.out, { recursive: true });
+    for (const [name, source] of Object.entries(files))
+        writeFileSync(join(asked.out, name), source);
+    console.log(`✓ ${aliasOf(metamodel)} → ${asked.out} (${Object.keys(files).join(", ")})`);
+    return 0;
+}
+process.exitCode = main(process.argv.slice(2));

package/dist/codegen/client.d.ts

@@ -0,0 +1,14 @@
+import type { Metamodel } from "./metamodel.js";
+import { type GenerateOptions } from "./rest.js";
+/**
+ * The TypeScript of the client of `metamodel`, as the text of one file next to its `domain.ts`.
+ *
+ * 1. Every operation, by its local name, as data: identity, role, `query`, entities, targets
+ *    and the binding of each wire that publishes it.
+ * 2. Per operation REST reaches, how a transport calls it (`callOf`): a page, a record, a write
+ *    — or none, said in the client's own doc.
+ * 3. The routes of the writes, read once (`writeRoute`).
+ * Final: `clientOf(transport)`, a method per operation reached, named by `methodOf`; two with
+ *    one name are refused, naming both.
+ */
+export declare function clientFileOf(metamodel: Metamodel, options?: GenerateOptions): string;