@cullet/erp-core 1.4.0 → 2.0.0

package/dist/entity.js

@@ -1,115 +0,0 @@
-import { t as InvariantViolationException } from "./invariant-violation-exception.js";
-import { i as version, n as __decorate } from "./immutable.js";
-import { n as cloneDate, t as assertValidDate } from "./temporal-guards.js";
-//#region src/core/shared/aggregate-version.ts
-function assertValidAggregateVersion(aggregateVersion) {
-	if (!Number.isInteger(aggregateVersion) || aggregateVersion < 0) throw new InvariantViolationException(`aggregateVersion must be a non-negative integer. Received: ${aggregateVersion}`);
-}
-//#endregion
-//#region src/core/domain/entity.ts
-var _Entity;
-/**
-* Base class for domain entities — objects defined by a stable identity rather
-* than by their attributes. Two entities are "the same" when their `id`
-* matches, even if every other field differs; this is the opposite of a
-* {@link ValueObject}, which is defined entirely by its contents.
-*
-* The class owns the bookkeeping common to every aggregate root: a creation
-* timestamp that never changes, a last-modified timestamp, and an
-* `aggregateVersion` counter used for optimistic concurrency control. All three
-* are validated on construction and the dates are defensively cloned, so an
-* entity can never be built into — or leak — an inconsistent temporal state.
-*
-* @typeParam TIdentifier - The identity type (e.g. a branded string id or a VO).
-*/
-let Entity = class Entity {
-	static {
-		_Entity = this;
-	}
-	/**
-	* Reconstitutes an entity from its persisted {@link EntityState}.
-	*
-	* Validates the temporal invariants up front so an invalid entity is
-	* impossible to construct: both dates must be valid, the aggregate version
-	* must be a non-negative integer, and `updatedAt` may not predate
-	* `createdAt`. Both dates are cloned on the way in so a later mutation of
-	* the caller's `Date` objects cannot reach into the entity's internal state.
-	*
-	* Declared `protected` because entities are reconstituted through a
-	* subclass factory, never instantiated directly by application code.
-	*
-	* @throws {InvariantViolationException} When `updatedAt` is earlier than `createdAt`.
-	*/
-	constructor(state) {
-		assertValidDate("createdAt", state.createdAt);
-		assertValidDate("updatedAt", state.updatedAt);
-		assertValidAggregateVersion(state.aggregateVersion);
-		if (state.updatedAt.getTime() < state.createdAt.getTime()) throw new InvariantViolationException("updatedAt cannot be earlier than createdAt");
-		this._id = state.id;
-		this._createdAt = cloneDate(state.createdAt);
-		this._updatedAt = cloneDate(state.updatedAt);
-		this._aggregateVersion = state.aggregateVersion;
-	}
-	/** The entity's stable identity — the basis for equality between entities. */
-	get id() {
-		return this._id;
-	}
-	/**
-	* When the entity was first created.
-	*
-	* Returns a clone so callers cannot mutate the entity's internal `Date`;
-	* the value is fixed at construction and never changes thereafter.
-	*/
-	get createdAt() {
-		return cloneDate(this._createdAt);
-	}
-	/**
-	* When the entity was last modified.
-	*
-	* Returns a clone for the same encapsulation reason as {@link createdAt};
-	* the underlying value advances only through {@link markAsModified}.
-	*/
-	get updatedAt() {
-		return cloneDate(this._updatedAt);
-	}
-	/**
-	* Monotonic counter incremented on every mutation, used for optimistic
-	* concurrency control: a writer reads this value, and the persistence layer
-	* rejects the write if the stored version has moved on in the meantime.
-	*/
-	get aggregateVersion() {
-		return this._aggregateVersion;
-	}
-	/**
-	* The schema/contract version stamped on this entity type by the
-	* `@version` decorator — used to detect and migrate state persisted under
-	* an older shape.
-	*/
-	get contractVersion() {
-		return _Entity.CONTRACT_VERSION;
-	}
-	/**
-	* The single seam through which an entity records a mutation: it advances
-	* `updatedAt` and bumps {@link aggregateVersion} by one. Subclasses must
-	* call this from every state-changing method so the version counter stays
-	* an accurate optimistic-lock token.
-	*
-	* @param updatedAt - The modification instant; defaults to now. Validated
-	*   and required not to predate `createdAt`, preserving the same invariant
-	*   the constructor enforces.
-	* @returns The new aggregate version after the increment.
-	* @throws {InvariantViolationException} When `updatedAt` is earlier than `createdAt`.
-	*/
-	markAsModified(updatedAt = /* @__PURE__ */ new Date()) {
-		assertValidDate("updatedAt", updatedAt);
-		if (updatedAt.getTime() < this._createdAt.getTime()) throw new InvariantViolationException("updatedAt cannot be earlier than createdAt");
-		this._updatedAt = cloneDate(updatedAt);
-		this._aggregateVersion += 1;
-		return this._aggregateVersion;
-	}
-};
-Entity = _Entity = __decorate([version("1.0")], Entity);
-//#endregion
-export { assertValidAggregateVersion as n, Entity as t };
-
-//# sourceMappingURL=entity.js.map

package/dist/entity.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"entity.js","names":[],"sources":["../src/core/shared/aggregate-version.ts","../src/core/domain/entity.ts"],"sourcesContent":["import { InvariantViolationException } from \"../exceptions/invariant-violation-exception.js\";\n\nfunction assertValidAggregateVersion(aggregateVersion: number): void {\n    if (!Number.isInteger(aggregateVersion) || aggregateVersion < 0) {\n        throw new InvariantViolationException(\n            `aggregateVersion must be a non-negative integer. Received: ${aggregateVersion}`,\n        );\n    }\n}\n\nexport { assertValidAggregateVersion };\n","import { InvariantViolationException } from \"../exceptions/invariant-violation-exception.js\";\nimport { assertValidAggregateVersion } from \"../shared/aggregate-version.js\";\nimport { assertValidDate, cloneDate } from \"../shared/temporal-guards.js\";\nimport { type ContractVersion, version } from \"../versioning/version.js\";\n\n/**\n * The minimal persisted shape needed to reconstitute an {@link Entity}.\n *\n * This is the contract between storage and the domain: a repository maps a row\n * (or document) onto these four fields and hands them to a subclass constructor.\n * `aggregateVersion` travels with the state so optimistic-concurrency checks\n * survive a round-trip through the database.\n */\ninterface EntityState<TIdentifier> {\n    readonly id: TIdentifier;\n    readonly createdAt: Date;\n    readonly updatedAt: Date;\n    readonly aggregateVersion: number;\n}\n\n/**\n * Base class for domain entities — objects defined by a stable identity rather\n * than by their attributes. Two entities are \"the same\" when their `id`\n * matches, even if every other field differs; this is the opposite of a\n * {@link ValueObject}, which is defined entirely by its contents.\n *\n * The class owns the bookkeeping common to every aggregate root: a creation\n * timestamp that never changes, a last-modified timestamp, and an\n * `aggregateVersion` counter used for optimistic concurrency control. All three\n * are validated on construction and the dates are defensively cloned, so an\n * entity can never be built into — or leak — an inconsistent temporal state.\n *\n * @typeParam TIdentifier - The identity type (e.g. a branded string id or a VO).\n */\n@version(\"1.0\")\nabstract class Entity<TIdentifier> {\n    declare public static readonly CONTRACT_VERSION: ContractVersion;\n\n    private readonly _id: TIdentifier;\n    private readonly _createdAt: Date;\n    private _updatedAt: Date;\n    private _aggregateVersion: number;\n\n    /**\n     * Reconstitutes an entity from its persisted {@link EntityState}.\n     *\n     * Validates the temporal invariants up front so an invalid entity is\n     * impossible to construct: both dates must be valid, the aggregate version\n     * must be a non-negative integer, and `updatedAt` may not predate\n     * `createdAt`. Both dates are cloned on the way in so a later mutation of\n     * the caller's `Date` objects cannot reach into the entity's internal state.\n     *\n     * Declared `protected` because entities are reconstituted through a\n     * subclass factory, never instantiated directly by application code.\n     *\n     * @throws {InvariantViolationException} When `updatedAt` is earlier than `createdAt`.\n     */\n    protected constructor(state: EntityState<TIdentifier>) {\n        assertValidDate(\"createdAt\", state.createdAt);\n        assertValidDate(\"updatedAt\", state.updatedAt);\n        assertValidAggregateVersion(state.aggregateVersion);\n\n        if (state.updatedAt.getTime() < state.createdAt.getTime()) {\n            throw new InvariantViolationException(\n                \"updatedAt cannot be earlier than createdAt\",\n            );\n        }\n\n        this._id = state.id;\n        this._createdAt = cloneDate(state.createdAt);\n        this._updatedAt = cloneDate(state.updatedAt);\n        this._aggregateVersion = state.aggregateVersion;\n    }\n\n    /** The entity's stable identity — the basis for equality between entities. */\n    public get id(): TIdentifier {\n        return this._id;\n    }\n\n    /**\n     * When the entity was first created.\n     *\n     * Returns a clone so callers cannot mutate the entity's internal `Date`;\n     * the value is fixed at construction and never changes thereafter.\n     */\n    public get createdAt(): Date {\n        return cloneDate(this._createdAt);\n    }\n\n    /**\n     * When the entity was last modified.\n     *\n     * Returns a clone for the same encapsulation reason as {@link createdAt};\n     * the underlying value advances only through {@link markAsModified}.\n     */\n    public get updatedAt(): Date {\n        return cloneDate(this._updatedAt);\n    }\n\n    /**\n     * Monotonic counter incremented on every mutation, used for optimistic\n     * concurrency control: a writer reads this value, and the persistence layer\n     * rejects the write if the stored version has moved on in the meantime.\n     */\n    public get aggregateVersion(): number {\n        return this._aggregateVersion;\n    }\n\n    /**\n     * The schema/contract version stamped on this entity type by the\n     * `@version` decorator — used to detect and migrate state persisted under\n     * an older shape.\n     */\n    public get contractVersion(): ContractVersion {\n        return Entity.CONTRACT_VERSION;\n    }\n\n    /**\n     * The single seam through which an entity records a mutation: it advances\n     * `updatedAt` and bumps {@link aggregateVersion} by one. Subclasses must\n     * call this from every state-changing method so the version counter stays\n     * an accurate optimistic-lock token.\n     *\n     * @param updatedAt - The modification instant; defaults to now. Validated\n     *   and required not to predate `createdAt`, preserving the same invariant\n     *   the constructor enforces.\n     * @returns The new aggregate version after the increment.\n     * @throws {InvariantViolationException} When `updatedAt` is earlier than `createdAt`.\n     */\n    protected markAsModified(updatedAt: Date = new Date()): number {\n        assertValidDate(\"updatedAt\", updatedAt);\n\n        if (updatedAt.getTime() < this._createdAt.getTime()) {\n            throw new InvariantViolationException(\n                \"updatedAt cannot be earlier than createdAt\",\n            );\n        }\n\n        this._updatedAt = cloneDate(updatedAt);\n        this._aggregateVersion += 1;\n\n        return this._aggregateVersion;\n    }\n}\n\nexport { Entity, type EntityState };\n"],"mappings":";;;;AAEA,SAAS,4BAA4B,kBAAgC;CACjE,IAAI,CAAC,OAAO,UAAU,gBAAgB,KAAK,mBAAmB,GAC1D,MAAM,IAAI,4BACN,8DAA8D,kBAClE;AAER;;;;;;;;;;;;;;;;;;AC0BA,IAAA,SAAA,MACe,OAAoB;;;;;;;;;;;;;;;;;;CAsB/B,YAAsB,OAAiC;EACnD,gBAAgB,aAAa,MAAM,SAAS;EAC5C,gBAAgB,aAAa,MAAM,SAAS;EAC5C,4BAA4B,MAAM,gBAAgB;EAElD,IAAI,MAAM,UAAU,QAAQ,IAAI,MAAM,UAAU,QAAQ,GACpD,MAAM,IAAI,4BACN,4CACJ;EAGJ,KAAK,MAAM,MAAM;EACjB,KAAK,aAAa,UAAU,MAAM,SAAS;EAC3C,KAAK,aAAa,UAAU,MAAM,SAAS;EAC3C,KAAK,oBAAoB,MAAM;CACnC;;CAGA,IAAW,KAAkB;EACzB,OAAO,KAAK;CAChB;;;;;;;CAQA,IAAW,YAAkB;EACzB,OAAO,UAAU,KAAK,UAAU;CACpC;;;;;;;CAQA,IAAW,YAAkB;EACzB,OAAO,UAAU,KAAK,UAAU;CACpC;;;;;;CAOA,IAAW,mBAA2B;EAClC,OAAO,KAAK;CAChB;;;;;;CAOA,IAAW,kBAAmC;EAC1C,OAAA,QAAc;CAClB;;;;;;;;;;;;;CAcA,eAAyB,4BAAkB,IAAI,KAAK,GAAW;EAC3D,gBAAgB,aAAa,SAAS;EAEtC,IAAI,UAAU,QAAQ,IAAI,KAAK,WAAW,QAAQ,GAC9C,MAAM,IAAI,4BACN,4CACJ;EAGJ,KAAK,aAAa,UAAU,SAAS;EACrC,KAAK,qBAAqB;EAE1B,OAAO,KAAK;CAChB;AACJ;+BA7GC,QAAQ,KAAK,CAAA,GAAA,MAAA"}

package/dist/use-case.cjs

@@ -1,96 +0,0 @@
-const require_immutable = require("./immutable.cjs");
-//#region src/core/application/use-case.ts
-var _UseCase;
-const EXECUTION_COUNTER = "use_case.executions";
-const DURATION_HISTOGRAM = "use_case.duration_ms";
-let UseCase = class UseCase {
-	static {
-		_UseCase = this;
-	}
-	get contractVersion() {
-		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.
-	*/
-	async run(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.
-	*/
-	observability() {
-		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.
-	*/
-	get useCaseName() {
-		return this.constructor.name;
-	}
-	async runInstrumented(input, observability) {
-		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 = 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());
-		}
-	}
-};
-UseCase = _UseCase = require_immutable.__decorate([require_immutable.version("1.0")], UseCase);
-/**
-* Invokes an observability side effect, isolating any adapter failure so it
-* cannot alter the use case outcome.
-*/
-function safely(effect) {
-	try {
-		return effect();
-	} catch {
-		return;
-	}
-}
-//#endregion
-Object.defineProperty(exports, "UseCase", {
-	enumerable: true,
-	get: function() {
-		return UseCase;
-	}
-});
-
-//# sourceMappingURL=use-case.cjs.map

package/dist/use-case.cjs.map

@@ -1 +0,0 @@
-{"version":3,"file":"use-case.cjs","names":["version"],"sources":["../src/core/application/use-case.ts"],"sourcesContent":["import { type ContractVersion, version } from \"../versioning/version.js\";\nimport type { Result } from \"../result/result.js\";\n\nimport type { LoggerPort } from \"./ports/logger.port.js\";\nimport type { MetricsPort } from \"./ports/metrics.port.js\";\nimport type { TracerPort } from \"./ports/tracer.port.js\";\n\ntype MaybePromise<T> = T | Promise<T>;\n\n/**\n * Observability adapters a use case may opt into.\n *\n * All fields are optional: a use case that provides none keeps the plain\n * `input → Result` behavior with zero overhead. When provided, {@link UseCase.run}\n * instruments every execution around `execute()` — opening a span, recording\n * duration, counting outcomes, and logging business/unexpected failures.\n */\ninterface UseCaseObservability {\n    readonly logger?: LoggerPort;\n    readonly metrics?: MetricsPort;\n    readonly tracer?: TracerPort;\n}\n\nconst EXECUTION_COUNTER = \"use_case.executions\";\nconst DURATION_HISTOGRAM = \"use_case.duration_ms\";\n\ntype ExecutionOutcome = \"ok\" | \"error\" | \"exception\";\n\n@version(\"1.0\")\nabstract class UseCase<\n    Input = void,\n    Output extends Result<unknown, unknown> = Result<void, never>,\n> {\n    declare public static readonly CONTRACT_VERSION: ContractVersion;\n\n    public get contractVersion(): ContractVersion {\n        return UseCase.CONTRACT_VERSION;\n    }\n\n    /**\n     * Runs the use case.\n     *\n     * `run()` is the single seam every use case crosses, so it is where\n     * cross-cutting instrumentation lives. When {@link observability} exposes\n     * any adapter, the call to `execute()` is wrapped with tracing, metrics and\n     * failure logging; otherwise it delegates directly with no overhead.\n     *\n     * Observability is strictly side-effecting: a misbehaving adapter never\n     * changes the business result nor masks a thrown error — its own failures\n     * are swallowed.\n     */\n    public async run(input: Input): Promise<Output> {\n        const observability = this.observability();\n        if (\n            !observability.logger &&\n            !observability.metrics &&\n            !observability.tracer\n        ) {\n            return await this.execute(input);\n        }\n\n        return await this.runInstrumented(input, observability);\n    }\n\n    /**\n     * Adapters used to instrument {@link run}. Override to opt a use case into\n     * tracing/metrics/logging. Returns an empty object by default, which keeps\n     * the plain delegating behavior.\n     */\n    protected observability(): UseCaseObservability {\n        return {};\n    }\n\n    /**\n     * Stable identity used for span names and metric labels. Defaults to the\n     * runtime class name; override when bundling/minification would otherwise\n     * erase a meaningful name.\n     */\n    protected get useCaseName(): string {\n        return this.constructor.name;\n    }\n\n    protected abstract execute(input: Input): MaybePromise<Output>;\n\n    private async runInstrumented(\n        input: Input,\n        observability: UseCaseObservability,\n    ): Promise<Output> {\n        const { logger, metrics, tracer } = observability;\n        const name = this.useCaseName;\n        const span = safely(() =>\n            tracer?.startSpan(name, { \"use_case.name\": name }),\n        );\n        const startedAt = Date.now();\n\n        try {\n            const output = await this.execute(input);\n            const outcome: ExecutionOutcome = output.isOk() ? \"ok\" : \"error\";\n\n            if (outcome === \"error\") {\n                safely(() =>\n                    logger?.warn(`${name} returned a business error`, {\n                        useCase: name,\n                    }),\n                );\n            }\n            safely(() => span?.setAttribute(\"use_case.outcome\", outcome));\n            safely(() =>\n                metrics?.counter(EXECUTION_COUNTER, 1, {\n                    useCase: name,\n                    outcome,\n                }),\n            );\n\n            return output;\n        } catch (error) {\n            safely(() =>\n                logger?.error(`${name} threw an unexpected error`, {\n                    useCase: name,\n                }),\n            );\n            safely(() => span?.setAttribute(\"use_case.outcome\", \"exception\"));\n            safely(() => span?.recordException(error));\n            safely(() =>\n                metrics?.counter(EXECUTION_COUNTER, 1, {\n                    useCase: name,\n                    outcome: \"exception\",\n                }),\n            );\n\n            throw error;\n        } finally {\n            safely(() =>\n                metrics?.histogram(DURATION_HISTOGRAM, Date.now() - startedAt, {\n                    useCase: name,\n                }),\n            );\n            safely(() => span?.end());\n        }\n    }\n}\n\n/**\n * Invokes an observability side effect, isolating any adapter failure so it\n * cannot alter the use case outcome.\n */\nfunction safely<R>(effect: () => R): R | undefined {\n    try {\n        return effect();\n    } catch {\n        return undefined;\n    }\n}\n\nexport { type MaybePromise, UseCase, type UseCaseObservability };\n"],"mappings":";;;AAuBA,MAAM,oBAAoB;AAC1B,MAAM,qBAAqB;AAI3B,IAAA,UAAA,MACe,QAGb;;;;CAGE,IAAW,kBAAmC;EAC1C,OAAA,SAAe;CACnB;;;;;;;;;;;;;CAcA,MAAa,IAAI,OAA+B;EAC5C,MAAM,gBAAgB,KAAK,cAAc;EACzC,IACI,CAAC,cAAc,UACf,CAAC,cAAc,WACf,CAAC,cAAc,QAEf,OAAO,MAAM,KAAK,QAAQ,KAAK;EAGnC,OAAO,MAAM,KAAK,gBAAgB,OAAO,aAAa;CAC1D;;;;;;CAOA,gBAAgD;EAC5C,OAAO,CAAC;CACZ;;;;;;CAOA,IAAc,cAAsB;EAChC,OAAO,KAAK,YAAY;CAC5B;CAIA,MAAc,gBACV,OACA,eACe;EACf,MAAM,EAAE,QAAQ,SAAS,WAAW;EACpC,MAAM,OAAO,KAAK;EAClB,MAAM,OAAO,aACT,QAAQ,UAAU,MAAM,EAAE,iBAAiB,KAAK,CAAC,CACrD;EACA,MAAM,YAAY,KAAK,IAAI;EAE3B,IAAI;GACA,MAAM,SAAS,MAAM,KAAK,QAAQ,KAAK;GACvC,MAAM,UAA4B,OAAO,KAAK,IAAI,OAAO;GAEzD,IAAI,YAAY,SACZ,aACI,QAAQ,KAAK,GAAG,KAAK,6BAA6B,EAC9C,SAAS,KACb,CAAC,CACL;GAEJ,aAAa,MAAM,aAAa,oBAAoB,OAAO,CAAC;GAC5D,aACI,SAAS,QAAQ,mBAAmB,GAAG;IACnC,SAAS;IACT;GACJ,CAAC,CACL;GAEA,OAAO;EACX,SAAS,OAAO;GACZ,aACI,QAAQ,MAAM,GAAG,KAAK,6BAA6B,EAC/C,SAAS,KACb,CAAC,CACL;GACA,aAAa,MAAM,aAAa,oBAAoB,WAAW,CAAC;GAChE,aAAa,MAAM,gBAAgB,KAAK,CAAC;GACzC,aACI,SAAS,QAAQ,mBAAmB,GAAG;IACnC,SAAS;IACT,SAAS;GACb,CAAC,CACL;GAEA,MAAM;EACV,UAAU;GACN,aACI,SAAS,UAAU,oBAAoB,KAAK,IAAI,IAAI,WAAW,EAC3D,SAAS,KACb,CAAC,CACL;GACA,aAAa,MAAM,IAAI,CAAC;EAC5B;CACJ;AACJ;mDAhHCA,kBAAAA,QAAQ,KAAK,CAAA,GAAA,OAAA;;;;;AAsHd,SAAS,OAAU,QAAgC;CAC/C,IAAI;EACA,OAAO,OAAO;CAClB,QAAQ;EACJ;CACJ;AACJ"}

package/dist/use-case.js

@@ -1,91 +0,0 @@
-import { i as version, n as __decorate } from "./immutable.js";
-//#region src/core/application/use-case.ts
-var _UseCase;
-const EXECUTION_COUNTER = "use_case.executions";
-const DURATION_HISTOGRAM = "use_case.duration_ms";
-let UseCase = class UseCase {
-	static {
-		_UseCase = this;
-	}
-	get contractVersion() {
-		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.
-	*/
-	async run(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.
-	*/
-	observability() {
-		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.
-	*/
-	get useCaseName() {
-		return this.constructor.name;
-	}
-	async runInstrumented(input, observability) {
-		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 = 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());
-		}
-	}
-};
-UseCase = _UseCase = __decorate([version("1.0")], UseCase);
-/**
-* Invokes an observability side effect, isolating any adapter failure so it
-* cannot alter the use case outcome.
-*/
-function safely(effect) {
-	try {
-		return effect();
-	} catch {
-		return;
-	}
-}
-//#endregion
-export { UseCase as t };
-
-//# sourceMappingURL=use-case.js.map

package/dist/use-case.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"use-case.js","names":[],"sources":["../src/core/application/use-case.ts"],"sourcesContent":["import { type ContractVersion, version } from \"../versioning/version.js\";\nimport type { Result } from \"../result/result.js\";\n\nimport type { LoggerPort } from \"./ports/logger.port.js\";\nimport type { MetricsPort } from \"./ports/metrics.port.js\";\nimport type { TracerPort } from \"./ports/tracer.port.js\";\n\ntype MaybePromise<T> = T | Promise<T>;\n\n/**\n * Observability adapters a use case may opt into.\n *\n * All fields are optional: a use case that provides none keeps the plain\n * `input → Result` behavior with zero overhead. When provided, {@link UseCase.run}\n * instruments every execution around `execute()` — opening a span, recording\n * duration, counting outcomes, and logging business/unexpected failures.\n */\ninterface UseCaseObservability {\n    readonly logger?: LoggerPort;\n    readonly metrics?: MetricsPort;\n    readonly tracer?: TracerPort;\n}\n\nconst EXECUTION_COUNTER = \"use_case.executions\";\nconst DURATION_HISTOGRAM = \"use_case.duration_ms\";\n\ntype ExecutionOutcome = \"ok\" | \"error\" | \"exception\";\n\n@version(\"1.0\")\nabstract class UseCase<\n    Input = void,\n    Output extends Result<unknown, unknown> = Result<void, never>,\n> {\n    declare public static readonly CONTRACT_VERSION: ContractVersion;\n\n    public get contractVersion(): ContractVersion {\n        return UseCase.CONTRACT_VERSION;\n    }\n\n    /**\n     * Runs the use case.\n     *\n     * `run()` is the single seam every use case crosses, so it is where\n     * cross-cutting instrumentation lives. When {@link observability} exposes\n     * any adapter, the call to `execute()` is wrapped with tracing, metrics and\n     * failure logging; otherwise it delegates directly with no overhead.\n     *\n     * Observability is strictly side-effecting: a misbehaving adapter never\n     * changes the business result nor masks a thrown error — its own failures\n     * are swallowed.\n     */\n    public async run(input: Input): Promise<Output> {\n        const observability = this.observability();\n        if (\n            !observability.logger &&\n            !observability.metrics &&\n            !observability.tracer\n        ) {\n            return await this.execute(input);\n        }\n\n        return await this.runInstrumented(input, observability);\n    }\n\n    /**\n     * Adapters used to instrument {@link run}. Override to opt a use case into\n     * tracing/metrics/logging. Returns an empty object by default, which keeps\n     * the plain delegating behavior.\n     */\n    protected observability(): UseCaseObservability {\n        return {};\n    }\n\n    /**\n     * Stable identity used for span names and metric labels. Defaults to the\n     * runtime class name; override when bundling/minification would otherwise\n     * erase a meaningful name.\n     */\n    protected get useCaseName(): string {\n        return this.constructor.name;\n    }\n\n    protected abstract execute(input: Input): MaybePromise<Output>;\n\n    private async runInstrumented(\n        input: Input,\n        observability: UseCaseObservability,\n    ): Promise<Output> {\n        const { logger, metrics, tracer } = observability;\n        const name = this.useCaseName;\n        const span = safely(() =>\n            tracer?.startSpan(name, { \"use_case.name\": name }),\n        );\n        const startedAt = Date.now();\n\n        try {\n            const output = await this.execute(input);\n            const outcome: ExecutionOutcome = output.isOk() ? \"ok\" : \"error\";\n\n            if (outcome === \"error\") {\n                safely(() =>\n                    logger?.warn(`${name} returned a business error`, {\n                        useCase: name,\n                    }),\n                );\n            }\n            safely(() => span?.setAttribute(\"use_case.outcome\", outcome));\n            safely(() =>\n                metrics?.counter(EXECUTION_COUNTER, 1, {\n                    useCase: name,\n                    outcome,\n                }),\n            );\n\n            return output;\n        } catch (error) {\n            safely(() =>\n                logger?.error(`${name} threw an unexpected error`, {\n                    useCase: name,\n                }),\n            );\n            safely(() => span?.setAttribute(\"use_case.outcome\", \"exception\"));\n            safely(() => span?.recordException(error));\n            safely(() =>\n                metrics?.counter(EXECUTION_COUNTER, 1, {\n                    useCase: name,\n                    outcome: \"exception\",\n                }),\n            );\n\n            throw error;\n        } finally {\n            safely(() =>\n                metrics?.histogram(DURATION_HISTOGRAM, Date.now() - startedAt, {\n                    useCase: name,\n                }),\n            );\n            safely(() => span?.end());\n        }\n    }\n}\n\n/**\n * Invokes an observability side effect, isolating any adapter failure so it\n * cannot alter the use case outcome.\n */\nfunction safely<R>(effect: () => R): R | undefined {\n    try {\n        return effect();\n    } catch {\n        return undefined;\n    }\n}\n\nexport { type MaybePromise, UseCase, type UseCaseObservability };\n"],"mappings":";;;AAuBA,MAAM,oBAAoB;AAC1B,MAAM,qBAAqB;AAI3B,IAAA,UAAA,MACe,QAGb;;;;CAGE,IAAW,kBAAmC;EAC1C,OAAA,SAAe;CACnB;;;;;;;;;;;;;CAcA,MAAa,IAAI,OAA+B;EAC5C,MAAM,gBAAgB,KAAK,cAAc;EACzC,IACI,CAAC,cAAc,UACf,CAAC,cAAc,WACf,CAAC,cAAc,QAEf,OAAO,MAAM,KAAK,QAAQ,KAAK;EAGnC,OAAO,MAAM,KAAK,gBAAgB,OAAO,aAAa;CAC1D;;;;;;CAOA,gBAAgD;EAC5C,OAAO,CAAC;CACZ;;;;;;CAOA,IAAc,cAAsB;EAChC,OAAO,KAAK,YAAY;CAC5B;CAIA,MAAc,gBACV,OACA,eACe;EACf,MAAM,EAAE,QAAQ,SAAS,WAAW;EACpC,MAAM,OAAO,KAAK;EAClB,MAAM,OAAO,aACT,QAAQ,UAAU,MAAM,EAAE,iBAAiB,KAAK,CAAC,CACrD;EACA,MAAM,YAAY,KAAK,IAAI;EAE3B,IAAI;GACA,MAAM,SAAS,MAAM,KAAK,QAAQ,KAAK;GACvC,MAAM,UAA4B,OAAO,KAAK,IAAI,OAAO;GAEzD,IAAI,YAAY,SACZ,aACI,QAAQ,KAAK,GAAG,KAAK,6BAA6B,EAC9C,SAAS,KACb,CAAC,CACL;GAEJ,aAAa,MAAM,aAAa,oBAAoB,OAAO,CAAC;GAC5D,aACI,SAAS,QAAQ,mBAAmB,GAAG;IACnC,SAAS;IACT;GACJ,CAAC,CACL;GAEA,OAAO;EACX,SAAS,OAAO;GACZ,aACI,QAAQ,MAAM,GAAG,KAAK,6BAA6B,EAC/C,SAAS,KACb,CAAC,CACL;GACA,aAAa,MAAM,aAAa,oBAAoB,WAAW,CAAC;GAChE,aAAa,MAAM,gBAAgB,KAAK,CAAC;GACzC,aACI,SAAS,QAAQ,mBAAmB,GAAG;IACnC,SAAS;IACT,SAAS;GACb,CAAC,CACL;GAEA,MAAM;EACV,UAAU;GACN,aACI,SAAS,UAAU,oBAAoB,KAAK,IAAI,IAAI,WAAW,EAC3D,SAAS,KACb,CAAC,CACL;GACA,aAAa,MAAM,IAAI,CAAC;EAC5B;CACJ;AACJ;iCAhHC,QAAQ,KAAK,CAAA,GAAA,OAAA;;;;;AAsHd,SAAS,OAAU,QAAgC;CAC/C,IAAI;EACA,OAAO,OAAO;CAClB,QAAQ;EACJ;CACJ;AACJ"}