@cullet/erp-core 1.0.11 → 1.1.0

package/src/core/application/use-case.ts

@@ -1,8 +1,31 @@
 import { type ContractVersion, version } from "../versioning/version.js";
 import type { Result } from "../result/result.js";
 
+import type { LoggerPort } from "./ports/logger.port.js";
+import type { MetricsPort } from "./ports/metrics.port.js";
+import type { TracerPort } from "./ports/tracer.port.js";
+
 type MaybePromise<T> = T | Promise<T>;
 
+/**
+ * Observability adapters a use case may opt into.
+ *
+ * All fields are optional: a use case that provides none keeps the plain
+ * `input → Result` behavior with zero overhead. When provided, {@link UseCase.run}
+ * instruments every execution around `execute()` — opening a span, recording
+ * duration, counting outcomes, and logging business/unexpected failures.
+ */
+interface UseCaseObservability {
+    readonly logger?: LoggerPort;
+    readonly metrics?: MetricsPort;
+    readonly tracer?: TracerPort;
+}
+
+const EXECUTION_COUNTER = "use_case.executions";
+const DURATION_HISTOGRAM = "use_case.duration_ms";
+
+type ExecutionOutcome = "ok" | "error" | "exception";
+
 @version("1.0")
 abstract class UseCase<
     Input = void,
@@ -14,11 +37,119 @@ abstract class UseCase<
         return UseCase.CONTRACT_VERSION;
     }
 
+    /**
+     * Runs the use case.
+     *
+     * `run()` is the single seam every use case crosses, so it is where
+     * cross-cutting instrumentation lives. When {@link observability} exposes
+     * any adapter, the call to `execute()` is wrapped with tracing, metrics and
+     * failure logging; otherwise it delegates directly with no overhead.
+     *
+     * Observability is strictly side-effecting: a misbehaving adapter never
+     * changes the business result nor masks a thrown error — its own failures
+     * are swallowed.
+     */
     public async run(input: Input): Promise<Output> {
-        return await this.execute(input);
+        const observability = this.observability();
+        if (
+            !observability.logger &&
+            !observability.metrics &&
+            !observability.tracer
+        ) {
+            return await this.execute(input);
+        }
+
+        return await this.runInstrumented(input, observability);
+    }
+
+    /**
+     * Adapters used to instrument {@link run}. Override to opt a use case into
+     * tracing/metrics/logging. Returns an empty object by default, which keeps
+     * the plain delegating behavior.
+     */
+    protected observability(): UseCaseObservability {
+        return {};
+    }
+
+    /**
+     * Stable identity used for span names and metric labels. Defaults to the
+     * runtime class name; override when bundling/minification would otherwise
+     * erase a meaningful name.
+     */
+    protected get useCaseName(): string {
+        return this.constructor.name;
     }
 
     protected abstract execute(input: Input): MaybePromise<Output>;
+
+    private async runInstrumented(
+        input: Input,
+        observability: UseCaseObservability,
+    ): Promise<Output> {
+        const { logger, metrics, tracer } = observability;
+        const name = this.useCaseName;
+        const span = safely(() =>
+            tracer?.startSpan(name, { "use_case.name": name }),
+        );
+        const startedAt = Date.now();
+
+        try {
+            const output = await this.execute(input);
+            const outcome: ExecutionOutcome = output.isOk() ? "ok" : "error";
+
+            if (outcome === "error") {
+                safely(() =>
+                    logger?.warn(`${name} returned a business error`, {
+                        useCase: name,
+                    }),
+                );
+            }
+            safely(() => span?.setAttribute("use_case.outcome", outcome));
+            safely(() =>
+                metrics?.counter(EXECUTION_COUNTER, 1, {
+                    useCase: name,
+                    outcome,
+                }),
+            );
+
+            return output;
+        } catch (error) {
+            safely(() =>
+                logger?.error(`${name} threw an unexpected error`, {
+                    useCase: name,
+                }),
+            );
+            safely(() => span?.setAttribute("use_case.outcome", "exception"));
+            safely(() => span?.recordException(error));
+            safely(() =>
+                metrics?.counter(EXECUTION_COUNTER, 1, {
+                    useCase: name,
+                    outcome: "exception",
+                }),
+            );
+
+            throw error;
+        } finally {
+            safely(() =>
+                metrics?.histogram(DURATION_HISTOGRAM, Date.now() - startedAt, {
+                    useCase: name,
+                }),
+            );
+            safely(() => span?.end());
+        }
+    }
+}
+
+/**
+ * Invokes an observability side effect, isolating any adapter failure so it
+ * cannot alter the use case outcome.
+ */
+function safely<R>(effect: () => R): R | undefined {
+    try {
+        return effect();
+    } catch {
+        return undefined;
+    }
 }
 
-export { type MaybePromise, UseCase };
+export { type MaybePromise, UseCase, type UseCaseObservability };

package/src/core/index.ts

@@ -1,15 +1,6 @@
 export * from "./errors/index.js";
 export * from "./exceptions/validation-field.js";
-export type {
-    LogPayload,
-    LoggerPort,
-    MetricLabels,
-    MetricsPort,
-    TraceAttributeValue,
-    TraceSpan,
-    TracerPort,
-} from "./application/index.js";
-export { mapPolicyEvaluationError } from "./application/policy-error-mapper.js";
+export * from "./application/index.js";
 export { Entity, type EntityState } from "./domain/entity.js";
 export { ValueObject, type DeepReadonly } from "./domain/value-object.js";
 export * from "./policies/index.js";

package/src/examples/application/cancel-order.example.ts

@@ -0,0 +1,124 @@
+/**
+ * End-to-end reference: a concrete {@link Command} wiring a
+ * {@link ResultRepository} and a {@link PolicyPort} together.
+ *
+ * Flow: load the aggregate → ask a declarative policy whether the action is
+ * allowed → mutate and persist. Every recoverable failure (infra error from
+ * the repository, a policy `DENY`, a missing aggregate, an optimistic-locking
+ * conflict on save) is returned as a typed `Result.err(...)` rather than
+ * thrown — the "errors as values" contract that `Command`/`UseCase` enforce.
+ *
+ * Consumers import these symbols from the package root (`@cullet/erp-core`);
+ * inside the kit we use relative paths so the example stays compilable and
+ * test-covered, guarding the snippet in the README/KIT_CONTEXT against rot.
+ */
+import { Command, type CommandInput } from "../../core/application/index.js";
+import type {
+    PolicyPort,
+    ResultRepository,
+} from "../../core/application/index.js";
+import { AuthorizationError } from "../../core/errors/authorization-error.js";
+import { NotFoundError } from "../../core/errors/not-found-error.js";
+import {
+    asPolicyDecisionId,
+    asSchoolId,
+    asTenantId,
+} from "../../core/policies/index.js";
+import { Result } from "../../core/result/result.js";
+
+// ─── Minimal domain ─────────────────────────────────────────────────────────
+
+type OrderStatus = "OPEN" | "CANCELLED";
+
+interface Order {
+    readonly id: string;
+    readonly status: OrderStatus;
+}
+
+// ─── Command contract ────────────────────────────────────────────────────────
+
+// `CommandInput` forces every mutation to record *who* triggered it.
+interface CancelOrderInput extends CommandInput {
+    readonly orderId: string;
+    readonly tenantId: string;
+    readonly schoolId: string;
+}
+
+type CancelOrderError = NotFoundError | AuthorizationError;
+
+// ─── The use case ─────────────────────────────────────────────────────────────
+
+class CancelOrder extends Command<
+    CancelOrderInput,
+    Result<Order, CancelOrderError>
+> {
+    constructor(
+        private readonly orders: ResultRepository<
+            Order,
+            string,
+            CancelOrderError
+        >,
+        private readonly policies: PolicyPort,
+    ) {
+        super();
+    }
+
+    protected async execute(
+        input: CancelOrderInput,
+    ): Promise<Result<Order, CancelOrderError>> {
+        // 1. Load the aggregate. Infra failures stay in band as Result.err.
+        const found = await this.orders.findById(input.orderId);
+        if (found.isErr()) {
+            return found;
+        }
+
+        const order = found.getOrThrow();
+        if (!order) {
+            return Result.err(
+                new NotFoundError("Order", { id: input.orderId }),
+            );
+        }
+
+        // 2. Decide via a declarative policy (a GATE returns ALLOW/DENY).
+        const evaluated = await this.policies.evaluate({
+            decisionId: asPolicyDecisionId(input.orderId),
+            policyKey: "order.cancel",
+            scopeChain: [],
+            contextVersion: 1,
+            seed: {
+                tenantId: asTenantId(input.tenantId),
+                schoolId: asSchoolId(input.schoolId),
+                fields: { orderStatus: order.status },
+            },
+        });
+        if (evaluated.isErr()) {
+            return evaluated;
+        }
+
+        const result = evaluated.getOrThrow();
+        if (result.kind === "GATE" && result.decision.status === "DENY") {
+            return Result.err(
+                AuthorizationError.policyDenied({
+                    action: "order.cancel",
+                    resource: { type: "Order", id: order.id },
+                    policyId: result.ref.definitionId,
+                    policyVersion: Number(result.ref.policyVersion),
+                    evaluatedAtIso: result.evaluatedAt.toISOString(),
+                }),
+            );
+        }
+
+        // 3. Mutate and persist. A version conflict on save also surfaces as
+        //    Result.err — never an exception crossing the boundary.
+        const cancelled: Order = { ...order, status: "CANCELLED" };
+        const saved = await this.orders.save(cancelled);
+        if (saved.isErr()) {
+            return saved;
+        }
+
+        return Result.ok(cancelled);
+    }
+}
+
+export { CancelOrder };
+export type { CancelOrderError, CancelOrderInput, Order, OrderStatus };

package/src/examples/application/in-memory-account-repository.example.ts

@@ -0,0 +1,73 @@
+/**
+ * Reference implementation of a {@link ResultRepository}: shows how a
+ * repository signals recoverable persistence outcomes as `Result` values
+ * instead of throwing.
+ *
+ * - `save` returns a `ConflictError` on an optimistic-concurrency version
+ *   mismatch, otherwise persists and bumps the version.
+ * - `delete` returns a `NotFoundError` when the row is absent.
+ * - `findById` keeps `null` as the "not present" answer (a valid lookup
+ *   result, not an error), still wrapped in a `Result` so genuine infra
+ *   failures could stay in band.
+ *
+ * Consumers import `ResultRepository` from the package root
+ * (`@cullet/erp-core`); the relative paths here keep the example compilable
+ * and test-covered.
+ */
+import type { ResultRepository } from "../../core/application/index.js";
+import {
+    AlreadyExistsError,
+    type ConflictError,
+    NotFoundError,
+} from "../../core/errors/index.js";
+import { Result } from "../../core/result/result.js";
+
+interface Account {
+    readonly id: string;
+    readonly version: number;
+    readonly balance: number;
+}
+
+type AccountError = NotFoundError | ConflictError;
+
+class InMemoryAccountRepository implements ResultRepository<
+    Account,
+    string,
+    AccountError
+> {
+    private readonly store = new Map<string, Account>();
+
+    seed(account: Account): void {
+        this.store.set(account.id, account);
+    }
+
+    async findById(id: string): Promise<Result<Account | null, AccountError>> {
+        return Result.ok(this.store.get(id) ?? null);
+    }
+
+    async save(entity: Account): Promise<Result<void, AccountError>> {
+        const current = this.store.get(entity.id);
+        if (current && current.version !== entity.version) {
+            return Result.err(
+                AlreadyExistsError.detected({
+                    entity: "Account",
+                    operation: "update",
+                    existingId: entity.id,
+                }),
+            );
+        }
+        this.store.set(entity.id, { ...entity, version: entity.version + 1 });
+        return Result.ok(undefined);
+    }
+
+    async delete(id: string): Promise<Result<void, AccountError>> {
+        if (!this.store.has(id)) {
+            return Result.err(new NotFoundError("Account", { id }));
+        }
+        this.store.delete(id);
+        return Result.ok(undefined);
+    }
+}
+
+export { InMemoryAccountRepository };
+export type { Account, AccountError };

package/src/version.ts

@@ -4,4 +4,4 @@
 // Mantemos a versao aqui, dentro de src/, para que a copia full-control seja
 // auto-contida: ao copiar so o conteudo de src/, o entry nao depende de um
 // `../package.json` que deixaria de existir no projeto consumidor.
-export const version = "1.0.11";
+export const version = "1.1.0";