@sincpro/client-framework 0.1.0 → 0.3.0

package/dist/services/bounded-context.js

@@ -0,0 +1,272 @@
+import { newEntityId } from "../client/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";
+/** 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"]);
+export class UseBoundedContext {
+    name;
+    /** This bounded context's level of the context, saved in the process's store. */
+    context;
+    #dependencies = {};
+    constructor(name) {
+        if (name === "" || name.includes("/"))
+            throw new Error(`"${name}" is not a bounded context's name — it names its spans: "${name}/Issues.close"`);
+        this.name = name;
+        this.context = contextAt(`bounded_context:${name}`, processStore);
+    }
+    /** `value` is what every service of this bounded context finds at `this.<name>`. */
+    addDependency(name, value) {
+        if (ANSWERED.has(name))
+            throw new Error(`${this.name}: a dependency cannot be called "${name}" — every service answers this.${name} itself`);
+        this.#dependencies[name] = value;
+        return this;
+    }
+    /**
+     * The object the bounded context is used through: each service under its name. A dependency
+     * added after this is seen too — the services read them on every call.
+     */
+    register(services) {
+        const classes = new Map();
+        const add = (key, service) => {
+            if (RESERVED.has(key))
+                throw new Error(`${this.name}: no service can be called "${key}" — it is the bounded context's own`);
+            if (classes.has(key))
+                throw new Error(`${this.name}: two services are called "${key}"`);
+            classes.set(key, service);
+        };
+        for (const [key, service] of Object.entries(services.features)) {
+            if (typeof service !== "function" || !isFeatureClass(service))
+                throw new Error(`${this.name}: "${key}" is not a Feature — an ApplicationService goes in applicationServices`);
+            add(key, service);
+        }
+        for (const [key, service] of Object.entries(services.applicationServices ?? {})) {
+            if (typeof service !== "function" || !isApplicationServiceClass(service))
+                throw new Error(`${this.name}: "${key}" is not an ApplicationService — a Feature goes in features`);
+            add(key, service);
+        }
+        const registry = {
+            name: this.name,
+            dependencies: this.#dependencies,
+            classes,
+            features: new Set(Object.keys(services.features)),
+            instances: new Map(),
+            context: this.context,
+        };
+        return assemble({ registry, overrides: {}, scope: {} });
+    }
+}
+function assemble(binding) {
+    const { registry } = binding;
+    const held = {};
+    Object.defineProperties(held, {
+        name: { value: registry.name, enumerable: true },
+        context: { value: registry.context, enumerable: true },
+        with: {
+            value: (dependencies) => assemble({ ...binding, overrides: { ...binding.overrides, ...dependencies } }),
+        },
+        scoped: {
+            value: (values) => assemble({ ...binding, scope: { ...binding.scope, ...values } }),
+        },
+    });
+    // Each service is made and wrapped the first time it is asked for, then kept on this object.
+    for (const key of registry.classes.keys())
+        Object.defineProperty(held, key, {
+            configurable: true,
+            enumerable: true,
+            get() {
+                const service = intercepted(key, binding, undefined);
+                Object.defineProperty(held, key, { value: service, enumerable: true });
+                return service;
+            },
+        });
+    return held;
+}
+function instanceOf(registry, key) {
+    const known = registry.instances.get(key);
+    if (known !== undefined)
+        return known;
+    const Service = registry.classes.get(key);
+    if (Service === undefined)
+        throw new Error(`${registry.name}: no service is called "${key}"`);
+    const made = new Service();
+    registry.instances.set(key, made);
+    return made;
+}
+/**
+ * A service as its holder sees it: each public method runs in an execution of its own — a child
+ * of `parent` when an ApplicationService runs it. A method is the same function every time it is
+ * read, so a screen can keep it (`useService(project.Issues.close)`).
+ */
+function intercepted(key, binding, parent) {
+    const target = instanceOf(binding.registry, key);
+    const traced = methodsOf(target);
+    const methods = new Map();
+    return new Proxy(target, {
+        get(held, property) {
+            const value = Reflect.get(held, property, held);
+            if (typeof property !== "string" ||
+                typeof value !== "function" ||
+                !traced.has(property))
+                return value;
+            let method = methods.get(property);
+            if (method === undefined) {
+                const body = value;
+                method = (...args) => run(held, key, property, body, args, binding, parent);
+                methods.set(property, method);
+            }
+            return method;
+        },
+    });
+}
+function dependencyOf(binding, name) {
+    if (Object.hasOwn(binding.overrides, name))
+        return { found: true, value: binding.overrides[name] };
+    if (Object.hasOwn(binding.registry.dependencies, name))
+        return { found: true, value: binding.registry.dependencies[name] };
+    return { found: false, value: undefined };
+}
+/**
+ * The run's own view of the instance: its context, its dependencies bound to this execution
+ * (each bound the first time it is read), and — for an ApplicationService — its Features as
+ * children of this run. Anything else is the instance's.
+ */
+function viewOf(target, binding, execution) {
+    const bound = new Map();
+    let features;
+    const isComposer = composes(target);
+    return new Proxy(target, {
+        get(held, property, receiver) {
+            if (property === "context")
+                return execution.context;
+            if (property === "feature" && isComposer)
+                return (features ??= featuresOf(binding, execution));
+            if (typeof property === "string") {
+                if (bound.has(property))
+                    return bound.get(property);
+                const dependency = dependencyOf(binding, property);
+                if (dependency.found) {
+                    const value = bindDependency(dependency.value, execution);
+                    bound.set(property, value);
+                    return value;
+                }
+            }
+            return Reflect.get(held, property, receiver);
+        },
+        set(held, property, value) {
+            if (ANSWERED.has(String(property)))
+                return false;
+            if (typeof property === "string" && dependencyOf(binding, property).found)
+                return false;
+            // What a method writes on `this` lands on the instance — it is the bounded context's.
+            return Reflect.set(held, property, value);
+        },
+    });
+}
+/** An ApplicationService's `this.feature`: each Feature, asked by name, a child of the run. */
+function featuresOf(binding, execution) {
+    const children = new Map();
+    return new Proxy({}, {
+        get(_, property) {
+            if (typeof property !== "string" || !binding.registry.features.has(property))
+                return undefined;
+            let child = children.get(property);
+            if (child === undefined) {
+                child = intercepted(property, binding, execution);
+                children.set(property, child);
+            }
+            return child;
+        },
+    });
+}
+const NOTHING = {};
+/** What a gesture runs with: the process's context, under it the bounded context's, its scope's. */
+function contextOf(binding) {
+    return {
+        ...processContext.values,
+        ...binding.registry.context.values,
+        ...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 {
+        return work();
+    }
+    catch {
+        return otherwise;
+    }
+}
+const NO_SPAN = {
+    traceId: "",
+    spanId: "",
+    sampled: false,
+    set: () => undefined,
+    end: () => undefined,
+};
+function run(target, key, method, body, args, binding, parent) {
+    const settings = processNow();
+    const boundedContext = binding.registry.name;
+    // As sincpro_framework names a use case: the span `context/Name`, the identity `context.Name`.
+    const identity = method === "execute" ? key : `${key}.${method}`;
+    const useCase = `${boundedContext}.${identity}`;
+    const context = parent?.context ?? quietly(() => contextOf(binding), NOTHING);
+    const id = newEntityId();
+    const attributes = {
+        "sincpro.use_case": useCase,
+        "sincpro.layer": composes(target) ? "application_service" : "feature",
+        "sincpro.context": boundedContext,
+        "sincpro.execution_id": id,
+    };
+    const span = quietly(() => settings.tracer.start(`${boundedContext}/${identity}`, {
+        ...(parent === undefined ? {} : { parent: parent.span }),
+        attributes,
+    }), NO_SPAN);
+    const execution = { id, useCase, boundedContext, parent, span, context };
+    const finish = (failed, error) => {
+        const outcome = failed ? quietly(() => settings.outcomeOf(error), "failed") : "ok";
+        quietly(() => span.end(outcome, error), undefined);
+        if (outcome === "failed" && firstReport(error))
+            quietly(() => settings.reporter?.report(error, {
+                useCase,
+                traceId: span.traceId,
+                executionId: id,
+                context,
+            }), undefined);
+    };
+    let answer;
+    try {
+        answer = body.apply(viewOf(target, binding, execution), 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/execution.d.ts

@@ -7,15 +7,15 @@ import type { Span } from "../observability/ports.js";
  * 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`).
+ * the use case calls: its Features (`this.feature`) 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. */
+    /** `<bounded context>.<Service>[.<method>]` — the use case's identity, 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 bounded context the use case belongs to. */
+    readonly boundedContext: string;
     /** The run that executed this one: an ApplicationService, for its Features. */
     readonly parent: Execution | undefined;
     readonly span: Span;
@@ -25,7 +25,7 @@ export type Execution = {
 /**
  * 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.
+ * any other dependency of a bounded context is handed as it is.
  */
 export declare const BIND: unique symbol;
 export type Bindable<T> = {
@@ -49,7 +49,7 @@ export declare function bindTransport(transport: Transport, execution: Execution
 /**
  * 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.
+ * `this.client.sendIssue(…)` sends that request with its own trace.
  *
  *     export function clientOf(transport: Transport) {
  *       return bindable(transport, (transport) => ({ sendIssue: (body) => transport.send(…) }));

package/dist/services/execution.js

@@ -1,7 +1,7 @@
 /**
  * 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.
+ * any other dependency of a bounded context is handed as it is.
  */
 export const BIND = Symbol.for("sincpro.client-framework.bind");
 function isBindable(value) {
@@ -61,7 +61,7 @@ export function bindTransport(transport, execution) {
 /**
  * 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.
+ * `this.client.sendIssue(…)` sends that request with its own trace.
  *
  *     export function clientOf(transport: Transport) {
  *       return bindable(transport, (transport) => ({ sendIssue: (body) => transport.send(…) }));

package/dist/services/feature.d.ts

@@ -1,60 +1,82 @@
-import { type Runtime } from "./runtime.js";
+import type { ContextValues } from "../context/store.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 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" });
+ *     // 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 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);
+declare class FeatureCore {
+}
+declare class ApplicationServiceCore extends FeatureCore {
 }
+/** What every service sees on `this` inside a method. */
+type Within<D extends object, C extends object> = Readonly<D> & {
+    /**
+     * What this run executes with: the process's context, its bounded context's, its scope's —
+     * read once where the gesture started and the same for every Feature it runs.
+     */
+    readonly context: Readonly<Partial<C>>;
+};
+/** Service classes by the name a bounded context gives them: `{ Issues, Notices }`. */
+export type ServiceClasses = Readonly<Record<string, new () => object>>;
 /**
- * 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.
+ * What a service offers to whoever holds it — `project.Issues`, `this.feature.Issues`: its public
+ * 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];
+};
+/** The services of a set of classes, by their names. */
+export type Services<S extends ServiceClasses, D> = {
+    readonly [K in keyof S]: ServiceMethods<InstanceType<S[K]>, D>;
+};
+type FeatureClass = abstract new <D extends object = Record<never, never>, C extends object = ContextValues>() => FeatureCore & Within<D, C>;
+type ApplicationServiceClass = abstract new <D extends object = Record<never, never>, F extends ServiceClasses = Record<never, never>, C extends object = ContextValues>() => ApplicationServiceCore & Within<D, C> & {
+    /** The Features of this bounded context, each run a child of this one. */
+    readonly feature: Services<F, D>;
+};
+/** The base of a bounded context's Features: `class Feature extends BaseFeature<Deps> {}`. */
+export declare const Feature: FeatureClass;
+/**
+ * The base of a bounded context's ApplicationServices:
+ * `class ApplicationService extends BaseApplicationService<Deps, typeof features> {}`.
  */
-export declare function bindServices<Services extends Readonly<Record<string, Feature<object>>>>(runtime: Runtime, domain: string, services: Services): Services;
+export declare const ApplicationService: ApplicationServiceClass;
+/** Whether a class is a Feature — and not an ApplicationService. */
+export declare function isFeatureClass(service: new () => object): boolean;
+export declare function isApplicationServiceClass(service: new () => object): boolean;
+/** Whether a service composes Features — an ApplicationService. */
+export declare function composes(service: object): boolean;
+export declare function methodsOf(service: object): ReadonlySet<string>;
+export {};