@sincpro/client-framework 0.2.0 → 0.4.0

package/dist/services/feature.js

@@ -1,95 +1,79 @@
-import { newEntityId } from "../client/ids.js";
-import { bindDependency } from "./execution.js";
-import { DETACHED } 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.
+ * `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:
  *
- *     export class SendIssue extends Feature<{ project: ProjectClient }> {
- *       execute(input: dto.CommandSendIssue) {
- *         return this.deps.project.sendIssue(input);
+ *     // domains/project/infrastructure/bounded_context.ts
+ *     export class Feature extends BaseFeature<ProjectDependencies> {}
+ *     export class ApplicationService extends BaseApplicationService<ProjectDependencies, ProjectFeatures> {}
+ *
+ *     // domains/project/services/issues.ts
+ *     export class Issues extends Feature {
+ *       close(input: dto.CommandCloseIssue) {
+ *         this.session.require();                 // each dependency is a property — typed
+ *         return this.client.closeIssue(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 class Feature {
-    deps;
-    /** What this run executes with (`RuntimeOptions.context`): empty outside a run. */
-    context = NO_CONTEXT;
-    constructor(deps) {
-        this.deps = deps ?? {};
-        // A class constructor that answers another object hands THAT to `new` and to every subclass
-        // constructor after it: their fields land on the instance through the proxy.
-        return intercepted(this, { runtime: DETACHED, domain: undefined, name: undefined });
-    }
-}
-/**
- * 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" });
+ *     // domains/project/services/close_and_notify.ts
+ *     export class CloseAndNotify extends ApplicationService {
+ *       async execute(input: dto.CommandCloseIssue) {
+ *         await this.feature.Issues.close(input);   // a child of this run, on the same trace
+ *         return this.feature.Notices.tell(input);
  *       }
  *     }
  *
- * Context: it never executes another ApplicationService — sincpro_framework's rule, refused here
- * when it is constructed rather than found in a trace later.
+ * Context: a Feature is a facade — the operations of one part of the domain, each a public
+ * method; an ApplicationService composes the Features of its own bounded context and never
+ * another ApplicationService (sincpro_framework's rule). Neither writes a span nor catches an
+ * error to report it: the bounded context runs every public method inside its own execution
+ * (`UseBoundedContext`).
+ *
+ * The dependencies are typed, not declared: `BaseFeature<ProjectDependencies>` types
+ * `this.client` and `this.session` from the bounded context's dependency type — sincpro_framework's
+ * `DependencyContextType` — and the bounded context hands them in on each run. So a service
+ * constructs with nothing, keeps no dependency on `this`, and declares no `#private` field: a run
+ * sees the instance through a view of its own (its dependencies bound to its trace), and
+ * `#private` refuses views. TypeScript's `private` is the same promise without that.
  */
-export class ApplicationService extends Feature {
-    features;
-    constructor(features, deps) {
-        super(deps);
-        for (const [name, feature] of Object.entries(features))
-            if (targetOf(feature) instanceof ApplicationService)
-                throw new Error(`${this.constructor.name}: "${name}" is an ApplicationService — an ApplicationService executes Features, never another ApplicationService`);
-        this.features = features;
-    }
+class FeatureCore {
+}
+class ApplicationServiceCore extends FeatureCore {
 }
+/** The base of a bounded context's Features: `class Feature extends BaseFeature<Deps> {}`. */
+export const Feature = FeatureCore;
 /**
- * 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.
+ * The base of a bounded context's ApplicationServices:
+ * `class ApplicationService extends BaseApplicationService<Deps, typeof features> {}`.
  */
-export function bindServices(runtime, domain, services) {
-    return Object.fromEntries(Object.entries(services).map(([name, service]) => [
-        name,
-        intercepted(targetOf(service), { runtime, domain, name }),
-    ]));
+export const ApplicationService = ApplicationServiceCore;
+/** Whether a class is a Feature — and not an ApplicationService. */
+export function isFeatureClass(service) {
+    return (service.prototype instanceof FeatureCore &&
+        !(service.prototype instanceof ApplicationServiceCore));
 }
-const NO_CONTEXT = Object.freeze({});
-const TARGETS = new WeakMap();
-function targetOf(feature) {
-    return TARGETS.get(feature) ?? feature;
+export function isApplicationServiceClass(service) {
+    return service.prototype instanceof ApplicationServiceCore;
 }
-/** The methods a class adds over Feature — what is traced — read once per class. */
+/** Whether a service composes Features — an ApplicationService. */
+export function composes(service) {
+    return service instanceof ApplicationServiceCore;
+}
+/**
+ * The methods a class adds over its base — what is traced — read once per class: every public
+ * method of the class and its parents up to `Feature`, but `constructor` and a name that starts
+ * with `_`.
+ */
 const METHODS = new WeakMap();
-function methodsOf(target) {
-    const prototype = Object.getPrototypeOf(target);
+export function methodsOf(service) {
+    const prototype = Object.getPrototypeOf(service);
     const known = METHODS.get(prototype);
     if (known !== undefined)
         return known;
     const names = new Set();
-    for (let level = prototype; level !== null && level !== Feature.prototype && level !== Object.prototype; level = Object.getPrototypeOf(level))
+    for (let level = prototype; level !== null &&
+        level !== ApplicationServiceCore.prototype &&
+        level !== FeatureCore.prototype &&
+        level !== Object.prototype; level = Object.getPrototypeOf(level))
         for (const name of Object.getOwnPropertyNames(level)) {
             const descriptor = Object.getOwnPropertyDescriptor(level, name);
             if (name !== "constructor" &&
@@ -100,121 +84,3 @@ function methodsOf(target) {
     METHODS.set(prototype, names);
     return names;
 }
-function intercepted(target, binding) {
-    const proxy = new Proxy(target, {
-        get(held, property) {
-            const value = Reflect.get(held, property, held);
-            if (typeof property !== "string" || typeof value !== "function")
-                return value;
-            if (!methodsOf(held).has(property))
-                return value;
-            return (...args) => run(held, property, value, args, binding);
-        },
-    });
-    TARGETS.set(proxy, target);
-    return proxy;
-}
-/**
- * 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;
-}
-function quietly(work, otherwise) {
-    try {
-        return work();
-    }
-    catch {
-        return otherwise;
-    }
-}
-const NO_SPAN = {
-    traceId: "",
-    spanId: "",
-    sampled: false,
-    set: () => undefined,
-    end: () => undefined,
-};
-function run(target, method, body, args, binding) {
-    const { runtime, domain, parent } = binding;
-    const name = binding.name ?? target.constructor.name;
-    const useCase = `${domain === undefined ? "" : `${domain}/`}${name}${method === "execute" ? "" : `.${method}`}`;
-    const context = parent?.context ?? quietly(() => runtime.context(), NO_CONTEXT);
-    const composes = target instanceof ApplicationService;
-    const id = newEntityId();
-    const attributes = {
-        "sincpro.use_case": useCase,
-        "sincpro.layer": composes ? "application_service" : "feature",
-        "sincpro.execution_id": id,
-        ...(domain === undefined ? {} : { "sincpro.domain": domain }),
-    };
-    const span = quietly(() => runtime.tracer.start(useCase, {
-        ...(parent === undefined ? {} : { parent: parent.span }),
-        attributes,
-    }), NO_SPAN);
-    const execution = { id, useCase, domain, parent, span, context };
-    // The run's own view of the instance: its dependencies bound to this execution, its context,
-    // and — for an ApplicationService — its Features as children of this run.
-    const own = target;
-    const view = Object.create(target, {
-        deps: {
-            value: Object.fromEntries(Object.entries(own.deps ?? {}).map(([key, dependency]) => [
-                key,
-                bindDependency(dependency, execution),
-            ])),
-        },
-        context: { value: context },
-        ...(composes
-            ? {
-                features: {
-                    value: Object.fromEntries(Object.entries(own.features ?? {}).map(([key, feature]) => [
-                        key,
-                        intercepted(targetOf(feature), {
-                            runtime,
-                            domain,
-                            name: key,
-                            parent: execution,
-                        }),
-                    ])),
-                },
-            }
-            : {}),
-    });
-    const finish = (failed, error) => {
-        const outcome = failed ? quietly(() => runtime.outcomeOf(error), "failed") : "ok";
-        quietly(() => span.end(outcome, error), undefined);
-        if (outcome === "failed" && firstReport(error))
-            quietly(() => runtime.reporter?.report(error, {
-                useCase,
-                traceId: span.traceId,
-                executionId: id,
-                context,
-            }), undefined);
-    };
-    let answer;
-    try {
-        answer = body.apply(view, args);
-    }
-    catch (error) {
-        finish(true, error);
-        throw error;
-    }
-    if (answer instanceof Promise)
-        return answer.then((value) => {
-            finish(false);
-            return value;
-        }, (error) => {
-            finish(true, error);
-            throw error;
-        });
-    finish(false);
-    return answer;
-}

package/dist/services/process.d.ts

@@ -0,0 +1,60 @@
+import { type Context, type StoreSource } from "../context/context.js";
+import { type ContextStore } from "../context/store.js";
+import { type ErrorReporter, type Outcome, type Tracer } from "../observability/ports.js";
+/**
+ * What every bounded context of this process runs with — set once, in `main`, the way
+ * sincpro_framework's process is: who traces, who reports, where the context lives.
+ *
+ *     // entrypoints/main.tsx — the platform's pieces, built from the application's settings
+ *     configureProcess({
+ *       tracer: browserTracer({ endpoint: settings.otlp, service: "forge-web" }),
+ *       reporter: glitchtipReporter({ dsn: settings.glitchtip }),
+ *       context: memoryContexts(),
+ *     });
+ *
+ * Context: everything is optional, and nothing breaks without it. A process that never configures
+ * runs every use case untraced, unreported, with its context in memory — so a bounded context is
+ * usable the moment it is imported, and `main` adds what it watches with. The bounded contexts
+ * read the process on every call, never at import: `project` may be defined before `main` runs.
+ *
+ * It replaces everything at once: what is not given goes back to its default — a test calls it
+ * with its own tracer and starts from a clean context.
+ */
+export type ProcessOptions = {
+    /** The platform's (OpenTelemetry in a browser, a queue on a phone, memory in a test). */
+    tracer?: Tracer;
+    /** The platform's (GlitchTip, Sentry, memory in a test). Only what nobody expected reaches it. */
+    reporter?: ErrorReporter;
+    /** Where the context lives (`memoryContexts()` by default). */
+    context?: ContextStore;
+    /** How an error ended a use case (`outcomeOf` by default). Only `failed` is reported. */
+    outcomeOf?: (error: unknown) => Outcome;
+};
+/** The process as a use case reads it. Not public: `configureProcess` is the way in. */
+export type Process = {
+    readonly tracer: Tracer;
+    readonly reporter: ErrorReporter | undefined;
+    readonly store: ContextStore;
+    readonly outcomeOf: (error: unknown) => Outcome;
+};
+export declare function configureProcess(options?: ProcessOptions): void;
+/** The process's store as every level of the context reads it — the process's and each bounded context's. */
+export declare const processStore: StoreSource;
+/** What the process runs with now. */
+export declare function processNow(): Process;
+/**
+ * The process's level of the context: what every use case of every bounded context runs with —
+ * the tenant, the company, the language.
+ *
+ *     processContext.set({ tenant_id: "acme" });
+ */
+export declare const processContext: Context;
+/**
+ * How an error ended a use case, by default.
+ *
+ * Context: the backend reports what nobody expected and only that — a refusal it explained is
+ * the business answering, not a fault. Here the same: a `TransportError` the server answered
+ * with a 4xx is `refused`; a request the caller stopped waiting for is `aborted`; everything
+ * else — a bug, a 5xx, a server nobody could reach — is `failed`, and reported.
+ */
+export declare function outcomeOf(error: unknown): Outcome;

package/dist/services/process.js

@@ -0,0 +1,57 @@
+import { TransportError } from "../client/transport.js";
+import { contextAt, } from "../context/context.js";
+import { memoryContexts } from "../context/store.js";
+import { NO_TRACER, } from "../observability/ports.js";
+function settled(options) {
+    return {
+        tracer: options.tracer ?? NO_TRACER,
+        reporter: options.reporter,
+        store: options.context ?? memoryContexts(),
+        outcomeOf: options.outcomeOf ?? outcomeOf,
+    };
+}
+let current = settled({});
+const replacing = new Set();
+export function configureProcess(options = {}) {
+    const before = current.store;
+    current = settled(options);
+    if (current.store !== before)
+        for (const listener of [...replacing])
+            listener();
+}
+/** The process's store as every level of the context reads it — the process's and each bounded context's. */
+export const processStore = {
+    current: () => current.store,
+    replaced(listener) {
+        replacing.add(listener);
+        return () => void replacing.delete(listener);
+    },
+};
+/** What the process runs with now. */
+export function processNow() {
+    return current;
+}
+/**
+ * The process's level of the context: what every use case of every bounded context runs with —
+ * the tenant, the company, the language.
+ *
+ *     processContext.set({ tenant_id: "acme" });
+ */
+export const processContext = contextAt("process", processStore);
+/**
+ * How an error ended a use case, by default.
+ *
+ * Context: the backend reports what nobody expected and only that — a refusal it explained is
+ * the business answering, not a fault. Here the same: a `TransportError` the server answered
+ * with a 4xx is `refused`; a request the caller stopped waiting for is `aborted`; everything
+ * else — a bug, a 5xx, a server nobody could reach — is `failed`, and reported.
+ */
+export function outcomeOf(error) {
+    if (error instanceof TransportError && error.status !== null)
+        return error.status >= 400 && error.status < 500 ? "refused" : "failed";
+    if (error !== null &&
+        typeof error === "object" &&
+        error.name === "AbortError")
+        return "aborted";
+    return "failed";
+}

package/dist/testing/index.d.ts

@@ -3,9 +3,9 @@ import type { ErrorAbout, ErrorReporter, Outcome, Tracer } from "../observabilit
  * A tracer and a reporter that keep what they were told, so a test reads it back.
  *
  *     const tracer = memoryTracer();
- *     const project = bindServices(createRuntime({ tracer }), "project", { closeIssue });
- *     await project.closeIssue.execute(input);
- *     tracer.spans.map((one) => one.name);   // ["project/closeIssue", "project/send", …]
+ *     configureProcess({ tracer });
+ *     await project.CloseIssue.execute(input);
+ *     tracer.spans.map((one) => one.name);   // ["project/CloseIssue", "project/Issues.close", …]
  *
  * Context: a use case is proven in Node with nothing of a platform; these are the platform's
  * part, held in memory. Not test doubles of this package — real implementations of its ports.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sincpro/client-framework",
-  "version": "0.2.0",
+  "version": "0.4.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",
@@ -67,7 +67,7 @@
     "printWidth": 94
   },
   "peerDependencies": {
-    "@opentelemetry/api": "^1.10.0",
+    "@opentelemetry/api": "^1.9.0",
     "@sincpro/criteria": "^2.0.0"
   },
   "peerDependenciesMeta": {

package/dist/services/runtime.d.ts

@@ -1,48 +0,0 @@
-import { type ErrorReporter, type Outcome, type Tracer } from "../observability/ports.js";
-/**
- * What every use case of an application runs with: who traces, who reports, and the context
- * each one carries to the server.
- *
- *     const runtime = createRuntime({
- *       tracer,                                  // the platform's (OpenTelemetry, …)
- *       reporter,                                // the platform's (GlitchTip, …)
- *       context: () => ({ tenant_id: session.tenant }),
- *     });
- *     const project = bindServices(runtime, "project", { sendIssue, closeIssue });
- *     await project.closeIssue.execute({ issue_id: "acme-3" });
- *
- * Context: sincpro_framework's bus is what gives every use case its span, its error report and
- * its context; here the same comes from the interceptors of `Feature`, and this is what they
- * read. A use case that was never bound runs too — with nothing tracing and nothing reporting —
- * so a Feature is tested by constructing it.
- */
-export type RuntimeOptions = {
-    tracer?: Tracer;
-    reporter?: ErrorReporter;
-    /**
-     * What a use case runs with, read once where a gesture starts and inherited by every use case
-     * it executes. It is what services read (`this.context`) and what travels to the server in
-     * `sincpro-context` — never a secret: the token goes in the transport's headers.
-     */
-    context?: () => Readonly<Record<string, unknown>>;
-    /** How an error ended a use case (`outcomeOf` by default). Only `failed` is reported. */
-    outcomeOf?: (error: unknown) => Outcome;
-};
-export type Runtime = {
-    readonly tracer: Tracer;
-    readonly reporter: ErrorReporter | undefined;
-    readonly context: () => Readonly<Record<string, unknown>>;
-    readonly outcomeOf: (error: unknown) => Outcome;
-};
-export declare function createRuntime(options?: RuntimeOptions): Runtime;
-/** Where a use case that was never bound runs: nothing traces, nothing reports. */
-export declare const DETACHED: Runtime;
-/**
- * How an error ended a use case, by default.
- *
- * Context: the backend reports what nobody expected and only that — a refusal it explained is
- * the business answering, not a fault. Here the same: a `TransportError` the server answered
- * with a 4xx is `refused`; a request the caller stopped waiting for is `aborted`; everything
- * else — a bug, a 5xx, a server nobody could reach — is `failed`, and reported.
- */
-export declare function outcomeOf(error: unknown): Outcome;

package/dist/services/runtime.js

@@ -1,30 +0,0 @@
-import { TransportError } from "../client/transport.js";
-import { NO_TRACER, } from "../observability/ports.js";
-const NO_CONTEXT = Object.freeze({});
-export function createRuntime(options = {}) {
-    return {
-        tracer: options.tracer ?? NO_TRACER,
-        reporter: options.reporter,
-        context: options.context ?? (() => NO_CONTEXT),
-        outcomeOf: options.outcomeOf ?? outcomeOf,
-    };
-}
-/** Where a use case that was never bound runs: nothing traces, nothing reports. */
-export const DETACHED = createRuntime();
-/**
- * How an error ended a use case, by default.
- *
- * Context: the backend reports what nobody expected and only that — a refusal it explained is
- * the business answering, not a fault. Here the same: a `TransportError` the server answered
- * with a 4xx is `refused`; a request the caller stopped waiting for is `aborted`; everything
- * else — a bug, a 5xx, a server nobody could reach — is `failed`, and reported.
- */
-export function outcomeOf(error) {
-    if (error instanceof TransportError && error.status !== null)
-        return error.status >= 400 && error.status < 500 ? "refused" : "failed";
-    if (error !== null &&
-        typeof error === "object" &&
-        error.name === "AbortError")
-        return "aborted";
-    return "failed";
-}