@sincpro/client-framework 0.0.0-stage → 0.2.0

package/dist/model/schema.d.ts

@@ -0,0 +1,39 @@
+import type { Meta } from "@sincpro/criteria";
+/**
+ * A model definition read from a JSON Schema — what an OpenAPI document holds.
+ *
+ * Context: a model a READ answers is published by sincpro_framework as its contract — JSON
+ * Schema with `x-sincpro` — and read by the transport (`metaFromContract`, `core/discovery`).
+ * What has no `x-sincpro` is a plain JSON Schema: a COMMAND's body, a value object it carries.
+ *
+ * So this reads such a component schema into a `Meta` — the form of a Command, a value object —
+ * and `completeMeta` fills, from it, what a definition left `unknown`.
+ *
+ *     const spec = metaFromSchema("ProjectSpecification", doc.components.schemas);
+ *     const fixed = completeMeta(project.fields.specification.definition, spec);
+ */
+export type JsonSchema = {
+    type?: string | string[];
+    format?: string;
+    enum?: readonly unknown[];
+    items?: JsonSchema;
+    $ref?: string;
+    anyOf?: readonly JsonSchema[];
+    oneOf?: readonly JsonSchema[];
+    properties?: Readonly<Record<string, JsonSchema>>;
+    required?: readonly string[];
+    title?: string;
+    description?: string;
+    default?: unknown;
+};
+export type SchemaComponents = Readonly<Record<string, JsonSchema>>;
+/** The definition a component schema describes. `identity` empty: a value object has none. */
+export declare function metaFromSchema(name: string, components: SchemaComponents, options?: {
+    identity?: string;
+}): Meta;
+/**
+ * The server's definition, with what it left `unknown` taken from the schema — recursively
+ * into value objects. What the server DID say always wins: its labels, its operators, its
+ * hints. A field the schema does not know is left as the server sent it.
+ */
+export declare function completeMeta(meta: Meta, schema: Meta): Meta;

package/dist/model/schema.js

@@ -0,0 +1,128 @@
+import { field } from "./meta.js";
+const UNKNOWN = {
+    type: "unknown",
+    kind: "scalar",
+    nullable: true,
+    sortable: false,
+    ops: [],
+};
+function nameOfRef(ref) {
+    return ref.slice(ref.lastIndexOf("/") + 1);
+}
+/** `anyOf: [X, {type: "null"}]` is `X`, nullable — how pydantic writes `X | None`. */
+function unwrap(schema) {
+    const options = schema.anyOf ?? schema.oneOf;
+    if (options === undefined)
+        return { schema, nullable: false };
+    const real = options.filter((one) => one.type !== "null");
+    const [only] = real;
+    return real.length === 1 && only !== undefined
+        ? { schema: { ...only, ...pick(schema) }, nullable: real.length < options.length }
+        : { schema, nullable: real.length < options.length };
+}
+/** The words of the outer schema win over the ones of what it wraps. */
+function pick(schema) {
+    return {
+        ...(schema.title === undefined ? {} : { title: schema.title }),
+        ...(schema.description === undefined ? {} : { description: schema.description }),
+        ...(schema.default === undefined ? {} : { default: schema.default }),
+    };
+}
+function fieldFrom(raw, required, components, seen) {
+    const { schema: unwrapped, nullable } = unwrap(raw);
+    const target = unwrapped.$ref !== undefined
+        ? { ...components[nameOfRef(unwrapped.$ref)], ...pick(unwrapped) }
+        : unwrapped;
+    const options = {
+        ...(target.title === undefined ? {} : { label: target.title }),
+        ...(target.description === undefined ? {} : { help: target.description }),
+        ...(target.default === undefined ? {} : { default: target.default }),
+        ...(nullable ? { nullable } : {}),
+        required: required && target.default === undefined && !nullable,
+    };
+    if (unwrapped.$ref !== undefined) {
+        const name = nameOfRef(unwrapped.$ref);
+        if (components[name] === undefined || seen.has(name))
+            return UNKNOWN;
+        if (target.properties === undefined)
+            return target.enum ? field.choice(target.enum.map(String), options) : UNKNOWN;
+        return field.embedded(metaOf(name, target, components, new Set([...seen, name])), options);
+    }
+    if (target.enum)
+        return field.choice(target.enum.map(String), options);
+    const type = Array.isArray(target.type)
+        ? target.type.find((t) => t !== "null")
+        : target.type;
+    switch (type) {
+        case "string":
+            if (target.format === "date")
+                return field.date(options);
+            if (target.format === "date-time")
+                return field.datetime(options);
+            return field.text(options);
+        case "integer":
+            return field.integer(options);
+        case "number":
+            return field.number(options);
+        case "boolean":
+            return field.boolean(options);
+        case "array": {
+            const item = target.items === undefined ? undefined : unwrap(target.items).schema;
+            if (item?.$ref !== undefined) {
+                const inner = fieldFrom(item, false, components, seen);
+                return inner.kind === "embedded" && inner.definition
+                    ? field.embedded(inner.definition, { ...options, many: true })
+                    : field.tags(options);
+            }
+            return item?.type === "string" || item?.enum ? field.tags(options) : UNKNOWN;
+        }
+        default:
+            return UNKNOWN;
+    }
+}
+function metaOf(name, schema, components, seen) {
+    const required = new Set(schema.required ?? []);
+    const fields = Object.fromEntries(Object.entries(schema.properties ?? {}).map(([key, property]) => [
+        key,
+        fieldFrom(property, required.has(key), components, seen),
+    ]));
+    return {
+        aggregate: name,
+        identity: "",
+        default_order: "",
+        fields,
+        ...(schema.title === undefined ? {} : { name: { default: schema.title } }),
+    };
+}
+/** The definition a component schema describes. `identity` empty: a value object has none. */
+export function metaFromSchema(name, components, options = {}) {
+    const schema = components[name];
+    if (schema === undefined)
+        throw new Error(`no schema named ${name}`);
+    const meta = metaOf(name, schema, components, new Set([name]));
+    return options.identity
+        ? { ...meta, identity: options.identity, get_id: options.identity }
+        : meta;
+}
+/**
+ * The server's definition, with what it left `unknown` taken from the schema — recursively
+ * into value objects. What the server DID say always wins: its labels, its operators, its
+ * hints. A field the schema does not know is left as the server sent it.
+ */
+export function completeMeta(meta, schema) {
+    const fields = Object.fromEntries(Object.entries(meta.fields).map(([name, own]) => {
+        const known = schema.fields[name];
+        if (known === undefined)
+            return [name, own];
+        if (own.type === "unknown")
+            return [name, { ...known, ...labelsOf(own) }];
+        if (own.kind === "embedded" && own.definition && known.definition)
+            return [name, { ...own, definition: completeMeta(own.definition, known.definition) }];
+        return [name, own];
+    }));
+    return { ...meta, fields };
+}
+/** A label the server declared is kept over the schema's generated title. */
+function labelsOf(own) {
+    return own.label && Object.keys(own.label).length > 0 ? { label: own.label } : {};
+}

package/dist/observability/ports.d.ts

@@ -0,0 +1,64 @@
+/**
+ * What a platform plugs so every use case is traced and every unexpected error reported.
+ *
+ * Context: sincpro_framework opens one span per use case and reports what nobody expected; a
+ * client has to do the same, and continue the backend's trace. The vendor — OpenTelemetry in a
+ * browser, a queue on a phone, GlitchTip, memory in a test — is the platform's, so this package
+ * defines the contract and calls it, and bundles none. Two implementations at least (a
+ * platform's and a test's) are why these are ports.
+ *
+ * Nothing here may break a use case: a tracer or a reporter that throws is ignored, and the use
+ * case answers as it would have.
+ */
+/** What is said about a span: plain values only, the way OpenTelemetry takes them. */
+export type Attributes = Readonly<Record<string, string | number | boolean>>;
+/**
+ * How a use case ended.
+ *
+ * - `ok`: it answered.
+ * - `refused`: the server said no and explained why — a validation, a conflict, a permission.
+ *   Expected; never reported.
+ * - `aborted`: whoever asked stopped waiting (a screen that closed). Never reported.
+ * - `failed`: anything else — a bug, a server that broke, a server nobody could reach. Reported.
+ */
+export type Outcome = "ok" | "refused" | "aborted" | "failed";
+/** One span: a use case, open while it runs. */
+export interface Span {
+    /** 32 hex — the id the server continues and a person quotes as a support code. Empty when
+     *  nothing traces. */
+    readonly traceId: string;
+    /** 16 hex. Empty when nothing traces. */
+    readonly spanId: string;
+    /** Whether this trace is kept: the server follows the same decision. */
+    readonly sampled: boolean;
+    /** Vendor state that travels beside the trace (`tracestate`), when there is any. */
+    readonly state?: string;
+    /** Says more about the use case while it runs. */
+    set(attributes: Attributes): void;
+    /** Closes it, once. `error` is what it failed or was refused with. */
+    end(outcome: Outcome, error?: unknown): void;
+}
+/** Opens spans. One per platform; `NO_TRACER` when nothing traces. */
+export interface Tracer {
+    start(name: string, options: {
+        parent?: Span;
+        attributes?: Attributes;
+    }): Span;
+}
+/** What a report says about where the error happened. */
+export type ErrorAbout = {
+    /** `<domain>/<Feature>`, the span's name. */
+    useCase: string;
+    /** The trace the error belongs to — the same id the server logged, when it got that far. */
+    traceId: string;
+    /** The execution's own id. */
+    executionId: string;
+    /** What the use case ran with (`Runtime` `context`). */
+    context: Readonly<Record<string, unknown>>;
+};
+/** Reports what nobody expected. One per platform; none when nothing reports. */
+export interface ErrorReporter {
+    report(error: unknown, about: ErrorAbout): void;
+}
+/** Traces nothing: what a use case runs with until a platform plugs a tracer. */
+export declare const NO_TRACER: Tracer;

package/dist/observability/ports.js

@@ -0,0 +1,21 @@
+/**
+ * What a platform plugs so every use case is traced and every unexpected error reported.
+ *
+ * Context: sincpro_framework opens one span per use case and reports what nobody expected; a
+ * client has to do the same, and continue the backend's trace. The vendor — OpenTelemetry in a
+ * browser, a queue on a phone, GlitchTip, memory in a test — is the platform's, so this package
+ * defines the contract and calls it, and bundles none. Two implementations at least (a
+ * platform's and a test's) are why these are ports.
+ *
+ * Nothing here may break a use case: a tracer or a reporter that throws is ignored, and the use
+ * case answers as it would have.
+ */
+const EMPTY_SPAN = {
+    traceId: "",
+    spanId: "",
+    sampled: false,
+    set: () => undefined,
+    end: () => undefined,
+};
+/** Traces nothing: what a use case runs with until a platform plugs a tracer. */
+export const NO_TRACER = { start: () => EMPTY_SPAN };

package/dist/services/execution.d.ts

@@ -0,0 +1,63 @@
+import type { Transport } from "../client/transport.js";
+import type { Span } from "../observability/ports.js";
+/**
+ * One run of a use case: its span, what it runs with, and who ran it.
+ *
+ * Context: sincpro_framework keeps the running use case in a context variable; a browser has
+ * nothing like it that survives an `await` (AsyncContext is a proposal, Zone.js patches the
+ * world), and a global stack mixes the parents of two use cases running at once — which a
+ * screen with several windows does all the time. So an execution is a value, handed to what
+ * the use case calls: its Features (`ApplicationService`) and its dependencies (`BIND`).
+ */
+export type Execution = {
+    /** UUID v7, as 32 hex: this run. */
+    readonly id: string;
+    /** `<domain>/<Feature>` — the span's name, as the backend names its own. */
+    readonly useCase: string;
+    /** The bounded context the use case belongs to, when it was bound to one. */
+    readonly domain: string | undefined;
+    /** The run that executed this one: an ApplicationService, for its Features. */
+    readonly parent: Execution | undefined;
+    readonly span: Span;
+    /** What it runs with, read once where the gesture started and inherited by every child. */
+    readonly context: Readonly<Record<string, unknown>>;
+};
+/**
+ * A dependency that has something to say about the execution it is used in: given that
+ * execution, it answers itself bound to it. The transport and every generated client are;
+ * anything else in a Feature's `deps` is handed as it is.
+ */
+export declare const BIND: unique symbol;
+export type Bindable<T> = {
+    [BIND]: (execution: Execution) => T;
+};
+/**
+ * What every request of an execution carries: its trace (`traceparent`, W3C) and its context
+ * (`sincpro-context`, the header sincpro_framework's entrances read). Nothing when there is no
+ * trace and no context.
+ */
+export declare function headersOf(execution: Execution): Record<string, string>;
+/**
+ * The transport, writing the execution's headers on every call — the caller's own headers of a
+ * call still win.
+ *
+ * Context: the transport's own headers (`restTransport({ headers })`) are the session's — the
+ * token, the tenant — the same for every call; these are the use case's, different for two use
+ * cases running at once, so they travel per call (`CallOptions`).
+ */
+export declare function bindTransport(transport: Transport, execution: Execution): Transport;
+/**
+ * A client made over a transport, made again over the transport bound to each execution it is
+ * used in. What a generated `clientOf(transport)` answers, so a Feature that calls
+ * `this.deps.project.sendIssue(…)` sends that request with its own trace.
+ *
+ *     export function clientOf(transport: Transport) {
+ *       return bindable(transport, (transport) => ({ sendIssue: (body) => transport.send(…) }));
+ *     }
+ *
+ * Context: it takes the function that makes the client, not the client — rebuilding through
+ * `clientOf` itself would make TypeScript infer `clientOf` from its own return.
+ */
+export declare function bindable<T extends object>(transport: Transport, make: (transport: Transport) => T): T;
+/** A dependency as the execution should see it: bound when it can be, as it is otherwise. */
+export declare function bindDependency<T>(value: T, execution: Execution): T;

package/dist/services/execution.js

@@ -0,0 +1,88 @@
+/**
+ * A dependency that has something to say about the execution it is used in: given that
+ * execution, it answers itself bound to it. The transport and every generated client are;
+ * anything else in a Feature's `deps` is handed as it is.
+ */
+export const BIND = Symbol.for("sincpro.client-framework.bind");
+function isBindable(value) {
+    return (value !== null &&
+        (typeof value === "object" || typeof value === "function") &&
+        typeof value[BIND] === "function");
+}
+function isTransport(value) {
+    if (value === null || typeof value !== "object")
+        return false;
+    const one = value;
+    return (typeof one.list === "function" &&
+        typeof one.one === "function" &&
+        typeof one.send === "function");
+}
+/**
+ * What every request of an execution carries: its trace (`traceparent`, W3C) and its context
+ * (`sincpro-context`, the header sincpro_framework's entrances read). Nothing when there is no
+ * trace and no context.
+ */
+export function headersOf(execution) {
+    const headers = {};
+    const { span, context } = execution;
+    if (span.traceId !== "" && span.spanId !== "") {
+        headers["traceparent"] =
+            `00-${span.traceId}-${span.spanId}-${span.sampled ? "01" : "00"}`;
+        if (span.state)
+            headers["tracestate"] = span.state;
+    }
+    if (Object.keys(context).length > 0)
+        headers["sincpro-context"] = JSON.stringify(context);
+    return headers;
+}
+/**
+ * The transport, writing the execution's headers on every call — the caller's own headers of a
+ * call still win.
+ *
+ * Context: the transport's own headers (`restTransport({ headers })`) are the session's — the
+ * token, the tenant — the same for every call; these are the use case's, different for two use
+ * cases running at once, so they travel per call (`CallOptions`).
+ */
+export function bindTransport(transport, execution) {
+    const own = headersOf(execution);
+    if (Object.keys(own).length === 0)
+        return transport;
+    const call = (options) => ({ ...options, headers: { ...own, ...options?.headers } });
+    const bound = {
+        list: (route, criteria, signal, options) => transport.list(route, criteria, signal, call(options)),
+        one: (route, signal, options) => transport.one(route, signal, call(options)),
+        send: (method, route, body, signal, options) => transport.send(method, route, body, signal, call(options)),
+    };
+    const read = transport.read;
+    if (read !== undefined)
+        bound.read = (route, signal, options) => read.call(transport, route, signal, call(options));
+    return bound;
+}
+/**
+ * A client made over a transport, made again over the transport bound to each execution it is
+ * used in. What a generated `clientOf(transport)` answers, so a Feature that calls
+ * `this.deps.project.sendIssue(…)` sends that request with its own trace.
+ *
+ *     export function clientOf(transport: Transport) {
+ *       return bindable(transport, (transport) => ({ sendIssue: (body) => transport.send(…) }));
+ *     }
+ *
+ * Context: it takes the function that makes the client, not the client — rebuilding through
+ * `clientOf` itself would make TypeScript infer `clientOf` from its own return.
+ */
+export function bindable(transport, make) {
+    const client = make(transport);
+    Object.defineProperty(client, BIND, {
+        value: (execution) => bindable(bindTransport(transport, execution), make),
+        enumerable: false,
+    });
+    return client;
+}
+/** A dependency as the execution should see it: bound when it can be, as it is otherwise. */
+export function bindDependency(value, execution) {
+    if (isBindable(value))
+        return value[BIND](execution);
+    if (isTransport(value))
+        return bindTransport(value, execution);
+    return value;
+}

package/dist/services/feature.d.ts

@@ -0,0 +1,60 @@
+import { type Runtime } from "./runtime.js";
+/**
+ * One use case. What it needs from outside — the generated client of its domain, another
+ * adapter — comes in `deps`, typed by the subclass.
+ *
+ *     export class SendIssue extends Feature<{ project: ProjectClient }> {
+ *       execute(input: dto.CommandSendIssue) {
+ *         return this.deps.project.sendIssue(input);
+ *       }
+ *     }
+ *
+ * Context: all of a client's logic lives in Features and ApplicationServices, as in
+ * sincpro_framework and @sincpro/mobile, and none of them writes a span or catches an error to
+ * report it: `new` answers the instance behind interceptors, and every public method runs
+ * inside its own execution — a span named `<domain>/<name>`, the context it runs with, its
+ * report if nobody expected how it failed. `execute` is a use case's entry; another public
+ * method is traced as `<name>.<method>`, and a name that starts with `_` is not traced at all.
+ *
+ * Inside a method, `this.deps` and `this.context` are this run's own: each dependency that can
+ * be (the transport, a generated client) is bound to the execution, so its requests carry this
+ * run's trace. So a Feature keeps nothing of a request on `this`, and declares no `#private`
+ * fields — the run sees the instance through a view of its own, and `#private` refuses views;
+ * TypeScript's `private` is the same promise without that.
+ */
+export declare class Feature<Deps extends object = Record<string, never>> {
+    protected readonly deps: Deps;
+    /** What this run executes with (`RuntimeOptions.context`): empty outside a run. */
+    protected readonly context: Readonly<Record<string, unknown>>;
+    constructor(deps?: Deps);
+}
+/**
+ * A use case that composes the Features of its own domain — the only difference with a
+ * Feature. Each call to one of them is a child of this run: its span under this span, the same
+ * context, the same trace on the wire.
+ *
+ *     export class CloseIssue extends ApplicationService<{ preview: PreviewClose; send: SendIssue }> {
+ *       async execute(input: CloseIssueInput) {
+ *         const preview = await this.features.preview.execute(input);
+ *         if (preview.warnings.length > 0) return { blocked: preview };
+ *         return this.features.send.execute({ ...input, message: "cerrado" });
+ *       }
+ *     }
+ *
+ * Context: it never executes another ApplicationService — sincpro_framework's rule, refused here
+ * when it is constructed rather than found in a trace later.
+ */
+export declare class ApplicationService<Features extends Readonly<Record<string, Feature<object>>>, Deps extends object = Record<string, never>> extends Feature<Deps> {
+    protected readonly features: Features;
+    constructor(features: Features, deps?: Deps);
+}
+/**
+ * The services of a bounded context, each running in this runtime under that domain: traced as
+ * `<domain>/<key>`, reported by its reporter, with its context.
+ *
+ *     const project = bindServices(runtime, "project", { sendIssue, closeIssue });
+ *
+ * Context: a span is named by the key it is bound with, not by the class — a production build
+ * renames classes, never the keys of an object.
+ */
+export declare function bindServices<Services extends Readonly<Record<string, Feature<object>>>>(runtime: Runtime, domain: string, services: Services): Services;