@sincpro/client-framework 0.5.0 → 1.0.0

package/dist/services/feature.d.ts

@@ -1,85 +0,0 @@
-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:
- *
- *     // 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);
- *       }
- *     }
- *
- *     // 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: 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.
- */
-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>>;
-    /** 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>>;
-/**
- * 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" | "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> = {
-    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 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 {};

package/dist/services/feature.js

@@ -1,86 +0,0 @@
-/**
- * `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:
- *
- *     // 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);
- *       }
- *     }
- *
- *     // 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: 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.
- */
-class FeatureCore {
-}
-class ApplicationServiceCore extends FeatureCore {
-}
-/** The base of a bounded context's Features: `class Feature extends BaseFeature<Deps> {}`. */
-export const Feature = FeatureCore;
-/**
- * The base of a bounded context's ApplicationServices:
- * `class ApplicationService extends BaseApplicationService<Deps, typeof features> {}`.
- */
-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));
-}
-export function isApplicationServiceClass(service) {
-    return service.prototype instanceof ApplicationServiceCore;
-}
-/** 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();
-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 !== 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" &&
-                !name.startsWith("_") &&
-                typeof descriptor?.value === "function")
-                names.add(name);
-        }
-    METHODS.set(prototype, names);
-    return names;
-}

package/dist/services/process.d.ts

@@ -1,60 +0,0 @@
-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

@@ -1,57 +0,0 @@
-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/services/screens.d.ts

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

package/dist/services/screens.js

@@ -1,67 +0,0 @@
-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;
-}