@sincpro/client-framework 0.3.0 → 0.5.0

package/dist/index.js

@@ -6,8 +6,10 @@
  * (`sideEffects: false`), so an application pays only for what it uses, and a use case, the
  * client it calls and the entity it reads come from the same place.
  *
+ *   common/   the values of the wire, as the backend writes them: ids, a day and an instant,
+ *             `Decimal`, `Money`, and how any value is written and read (`valuesOf`, `rebuilt`)
  *   client/   the seam with a server: the transport and its REST and in-memory implementations,
- *             entities with typed commands, the service's client contract, client-side ids
+ *             entities with typed commands, the service's client contract
  *   model/    model definitions: written by hand, read from a JSON Schema, kept once known
  *   services/ the bounded context (`UseBoundedContext`), its `Feature` and `ApplicationService`,
  *             the process they run in (`configureProcess`), what each run carries
@@ -19,11 +21,16 @@
  */
 export { entityKeyOf, kindOf, metasOf, versionsOf, } from "./client/contract.js";
 export { bodyFor, entity, listRoute, NEW_PARAM, pathFor, PICK_PARAM, QUERY_PARAM, SCOPE_PARAM, scopeOfRef, startingValuesOf, TRAIL_PARAM, WITH_PARAM, writeRoute, } from "./client/entity.js";
-export { isEntityId, newEntityId } from "./client/ids.js";
 export { memoryTransport, } from "./client/memory.js";
 export { restTransport, urlOf, } from "./client/rest.js";
 export { retryKeys, unanswered, } from "./client/retry.js";
 export { readRoute, TransportError, } from "./client/transport.js";
+export { Decimal } from "./common/decimal.js";
+export { isEntityId, momentOf, newEntityId } from "./common/ids.js";
+export { Money } from "./common/money.js";
+export { BYTES, pack, readValues, rebuilt, unpack, valuesOf, } from "./common/serialization.js";
+export { dayOf, installTimeZone, instantOf, isDay, timeZoneNow, wallTimeOf, } from "./common/time.js";
+export { CONTEXT_HEADER, plainCodec, travelling, travels, } from "./context/codec.js";
 export {} from "./context/context.js";
 export { memoryContexts, } from "./context/store.js";
 export { defineMeta, field, } from "./model/meta.js";
@@ -34,3 +41,5 @@ export { UseBoundedContext, } from "./services/bounded-context.js";
 export { BIND, bindable, bindDependency, bindTransport, headersOf, } from "./services/execution.js";
 export { ApplicationService, Feature, } from "./services/feature.js";
 export { configureProcess, outcomeOf, processContext, } from "./services/process.js";
+export { reportError } from "./services/report.js";
+export { screensTransport } from "./services/screens.js";

package/dist/observability/ports.d.ts

@@ -47,7 +47,8 @@ export interface Tracer {
 }
 /** What a report says about where the error happened. */
 export type ErrorAbout = {
-    /** `<bounded context>.<Service>[.<method>]`: the use case's identity, as the backend's. */
+    /** `<bounded context>.<Service>[.<method>]`: the use case's identity, as the backend's — or,
+     *  for what failed outside one (`reportError`), where it happened (`view project:issue/acme-3`). */
     useCase: string;
     /** The trace the error belongs to — the same id the server logged, when it got that far. */
     traceId: string;

package/dist/services/bounded-context.js

@@ -1,12 +1,13 @@
-import { newEntityId } from "../client/ids.js";
+import { newEntityId } from "../common/ids.js";
 import { contextAt } from "../context/context.js";
 import { bindDependency } from "./execution.js";
 import { composes, isApplicationServiceClass, isFeatureClass, methodsOf, } from "./feature.js";
 import { processContext, processNow, processStore, } from "./process.js";
+import { firstReport } from "./report.js";
 /** Names `project` answers itself: no service is registered under them. */
 const RESERVED = new Set(["name", "context", "with", "scoped"]);
 /** Names a run answers on `this` itself: no dependency is added under them. */
-const ANSWERED = new Set(["context", "feature"]);
+const ANSWERED = new Set(["context", "feature", "span"]);
 export class UseBoundedContext {
     name;
     /** This bounded context's level of the context, saved in the process's store. */
@@ -142,6 +143,8 @@ function viewOf(target, binding, execution) {
         get(held, property, receiver) {
             if (property === "context")
                 return execution.context;
+            if (property === "span")
+                return execution.span;
             if (property === "feature" && isComposer)
                 return (features ??= featuresOf(binding, execution));
             if (typeof property === "string") {
@@ -191,20 +194,6 @@ function contextOf(binding) {
         ...binding.scope,
     };
 }
-/**
- * Whether this is the first run to report this error. A Feature that fails inside an
- * ApplicationService throws through it: the error is reported once, by the run where it
- * happened — its span is the one that says where — and every run around it still ends `failed`.
- */
-const REPORTED = new WeakSet();
-function firstReport(error) {
-    if (error === null || (typeof error !== "object" && typeof error !== "function"))
-        return true;
-    if (REPORTED.has(error))
-        return false;
-    REPORTED.add(error);
-    return true;
-}
 /** What watches a use case never changes what it answers: a tracer or reporter that throws is ignored. */
 function quietly(work, otherwise) {
     try {

package/dist/services/execution.d.ts

@@ -33,8 +33,8 @@ export type Bindable<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.
+ * (`sincpro-context`, the header sincpro_framework's entrances read, written with `plainCodec`).
+ * Nothing when there is no trace and no context that travels.
  */
 export declare function headersOf(execution: Execution): Record<string, string>;
 /**

package/dist/services/execution.js

@@ -1,3 +1,4 @@
+import { CONTEXT_HEADER, plainCodec, travels } from "../context/codec.js";
 /**
  * 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;
@@ -19,8 +20,8 @@ function isTransport(value) {
 }
 /**
  * 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.
+ * (`sincpro-context`, the header sincpro_framework's entrances read, written with `plainCodec`).
+ * Nothing when there is no trace and no context that travels.
  */
 export function headersOf(execution) {
     const headers = {};
@@ -31,8 +32,9 @@ export function headersOf(execution) {
         if (span.state)
             headers["tracestate"] = span.state;
     }
-    if (Object.keys(context).length > 0)
-        headers["sincpro-context"] = JSON.stringify(context);
+    // Only what travels: an object or a function held in the context stays in this process.
+    if (Object.values(context).some(travels))
+        headers[CONTEXT_HEADER] = plainCodec.dumps(context);
     return headers;
 }
 /**

package/dist/services/feature.d.ts

@@ -1,4 +1,5 @@
 import type { ContextValues } from "../context/store.js";
+import type { Span } from "../observability/ports.js";
 /**
  * `Feature` and `ApplicationService`: the two kinds of service a bounded context holds, as in
  * sincpro_framework. Each bounded context gives them its dependencies once, in its own base:
@@ -47,6 +48,8 @@ type Within<D extends object, C extends object> = Readonly<D> & {
      * read once where the gesture started and the same for every Feature it runs.
      */
     readonly context: Readonly<Partial<C>>;
+    /** This run's span: a use case says more about what it ran on (`this.span.set({ … })`). */
+    readonly span: Span;
 };
 /** Service classes by the name a bounded context gives them: `{ Issues, Notices }`. */
 export type ServiceClasses = Readonly<Record<string, new () => object>>;
@@ -55,7 +58,7 @@ export type ServiceClasses = Readonly<Record<string, new () => object>>;
  * methods, without its dependencies, its context or its `_` helpers.
  */
 export type ServiceMethods<I, D> = {
-    readonly [M in keyof I as M extends keyof D | "context" | "feature" | `_${string}` ? never : I[M] extends (...args: never[]) => unknown ? M : never]: I[M];
+    readonly [M in keyof I as M extends keyof D | "context" | "feature" | "span" | `_${string}` ? never : I[M] extends (...args: never[]) => unknown ? M : never]: I[M];
 };
 /** The services of a set of classes, by their names. */
 export type Services<S extends ServiceClasses, D> = {

package/dist/services/report.d.ts

@@ -0,0 +1,15 @@
+export declare function firstReport(error: unknown): boolean;
+/**
+ * Reports what nobody expected that is not a use case — a screen that broke while drawing, a
+ * subscriber, a worker — through the process's reporter, with the process's context.
+ *
+ *     <Composer onViewError={(error, { resource }) => reportError(error, `view ${formatRef(resource)}`)} />
+ *     ErrorUtils.setGlobalHandler((error) => reportError(error, "react-native global"));
+ *
+ * Context: a use case reports its own failures (the bounded context does it for it); what fails
+ * outside one would only reach a console. `where` takes the place of the use case's name in the
+ * report. Only what failed is reported (`outcomeOf`: a refusal the server explained or an abort is
+ * not); an error a use case already reported is not reported again; and a reporter that throws is
+ * ignored: telling about a failure never becomes a second one.
+ */
+export declare function reportError(error: unknown, where: string): void;

package/dist/services/report.js

@@ -0,0 +1,53 @@
+import { newEntityId } from "../common/ids.js";
+import { processContext, processNow } from "./process.js";
+/**
+ * Whether this is the first time this error is reported. A Feature that fails inside an
+ * ApplicationService throws through it, and a screen that draws the failure may break on it:
+ * the error is reported once, by the first that saw it — its span is the one that says where.
+ */
+const REPORTED = new WeakSet();
+export function firstReport(error) {
+    if (error === null || (typeof error !== "object" && typeof error !== "function"))
+        return true;
+    if (REPORTED.has(error))
+        return false;
+    REPORTED.add(error);
+    return true;
+}
+/**
+ * Reports what nobody expected that is not a use case — a screen that broke while drawing, a
+ * subscriber, a worker — through the process's reporter, with the process's context.
+ *
+ *     <Composer onViewError={(error, { resource }) => reportError(error, `view ${formatRef(resource)}`)} />
+ *     ErrorUtils.setGlobalHandler((error) => reportError(error, "react-native global"));
+ *
+ * Context: a use case reports its own failures (the bounded context does it for it); what fails
+ * outside one would only reach a console. `where` takes the place of the use case's name in the
+ * report. Only what failed is reported (`outcomeOf`: a refusal the server explained or an abort is
+ * not); an error a use case already reported is not reported again; and a reporter that throws is
+ * ignored: telling about a failure never becomes a second one.
+ */
+export function reportError(error, where) {
+    const settings = processNow();
+    try {
+        // What the server explained, or what the caller stopped waiting for, is not a fault here either.
+        if (settings.outcomeOf(error) !== "failed")
+            return;
+    }
+    catch {
+        // An outcome that cannot be told is a failure.
+    }
+    if (!firstReport(error))
+        return;
+    try {
+        settings.reporter?.report(error, {
+            useCase: where,
+            traceId: "",
+            executionId: newEntityId(),
+            context: processContext.values,
+        });
+    }
+    catch {
+        // Ignored, as a reporter that fails inside a use case is.
+    }
+}

package/dist/services/screens.d.ts

@@ -0,0 +1,2 @@
+import type { Transport } from "../client/transport.js";
+export declare function screensTransport(transport: Transport, name?: string): Transport;

package/dist/services/screens.js

@@ -0,0 +1,67 @@
+import { UseBoundedContext } from "./bounded-context.js";
+import { Feature } from "./feature.js";
+/**
+ * What a screen reads of an entity — a page, a record, a read of its own: sincpro_framework's
+ * built-in `EntityReads`, on the client.
+ */
+class EntityReads extends Feature {
+    list(route, criteria, signal, options) {
+        this.span.set({ "http.route": route });
+        return this.transport.list(route, criteria, signal, options);
+    }
+    one(route, signal, options) {
+        this.span.set({ "http.route": route });
+        return this.transport.one(route, signal, options);
+    }
+    read(route, signal, options) {
+        this.span.set({ "http.route": route });
+        const read = this.transport.read;
+        if (read === undefined)
+            return Promise.reject(new Error(`this transport cannot read ${route}: it has no read()`));
+        return read.call(this.transport, route, signal, options);
+    }
+}
+/** What a screen writes — a save, a draft, a preview, a Command: each request a use case. */
+class EntityWrites extends Feature {
+    send(method, route, body, signal, options) {
+        this.span.set({ "http.method": method, "http.route": route });
+        return this.transport.send(method, route, body, signal, options);
+    }
+}
+/**
+ * The transport, every call a use case of a bounded context of its own — `screens` unless named:
+ * what a platform hands the screens it draws.
+ *
+ *     const screens = screensTransport(restTransport({ base: "/v1" }));
+ *     await screens.list("/facturas", criteria);   // span screens/EntityReads.list
+ *
+ * Context: a use case is traced, carries its context and reports what nobody expected; a list a
+ * screen reads through the transport was none of that — no span, no `traceparent` (the backend's
+ * trace started there, with no client in it), no company, and a 500 reported to nobody. Here
+ * each read and write runs as a use case of `screens` — `EntityReads.list`, `.one`, `.read`,
+ * `EntityWrites.send` —, so it gets all three the way any other does: the span (its route said
+ * on it), the trace and the process's context on the request, and a report only when it failed
+ * (a 4xx the server explained is the screen's to show). A bounded context's own dependencies are
+ * never given this: there its use case is the one that runs.
+ */
+/** The transports this made: given one again, it is answered as it is — wrapped twice, each
+ *  request would be two unrelated use cases, and the server would see only the outer's trace. */
+const MADE = new WeakSet();
+export function screensTransport(transport, name = "screens") {
+    if (MADE.has(transport))
+        return transport;
+    const screens = new UseBoundedContext(name)
+        .addDependency("transport", transport)
+        .register({ features: { EntityReads, EntityWrites } });
+    const reads = screens.EntityReads;
+    const writes = screens.EntityWrites;
+    const through = {
+        list: (route, criteria, signal, options) => reads.list(route, criteria, signal, options),
+        one: (route, signal, options) => reads.one(route, signal, options),
+        send: (method, route, body, signal, options) => writes.send(method, route, body, signal, options),
+    };
+    if (transport.read !== undefined)
+        through.read = (route, signal, options) => reads.read(route, signal, options);
+    MADE.add(through);
+    return through;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sincpro/client-framework",
-  "version": "0.3.0",
+  "version": "0.5.0",
   "description": "The client side of sincpro_framework, for every platform: Feature and ApplicationService traced and reported by default, applications made of domains, and the typed client generated from a service's contract. No React, no DOM.",
   "type": "module",
   "main": "./dist/index.js",
@@ -68,11 +68,15 @@
   },
   "peerDependencies": {
     "@opentelemetry/api": "^1.9.0",
-    "@sincpro/criteria": "^2.0.0"
+    "@sincpro/criteria": "^2.0.0",
+    "typescript": ">=5.5 <7"
   },
   "peerDependenciesMeta": {
     "@opentelemetry/api": {
       "optional": true
+    },
+    "typescript": {
+      "optional": true
     }
   },
   "devDependencies": {