@cullet/erp-core 1.1.0 → 1.3.0

package/dist/uuid-identifier.d.cts

@@ -0,0 +1,230 @@
+import { n as ContractVersion } from "./version.cjs";
+import { t as DeepReadonly } from "./immutable.cjs";
+import { t as PluginManager } from "./plugin.cjs";
+
+//#region src/core/domain/entity.d.ts
+
+/**
+ * The minimal persisted shape needed to reconstitute an {@link Entity}.
+ *
+ * This is the contract between storage and the domain: a repository maps a row
+ * (or document) onto these four fields and hands them to a subclass constructor.
+ * `aggregateVersion` travels with the state so optimistic-concurrency checks
+ * survive a round-trip through the database.
+ */
+interface EntityState<TIdentifier> {
+  readonly id: TIdentifier;
+  readonly createdAt: Date;
+  readonly updatedAt: Date;
+  readonly aggregateVersion: number;
+}
+/**
+ * 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).
+ */
+declare abstract class Entity<TIdentifier> {
+  static readonly CONTRACT_VERSION: ContractVersion;
+  private readonly _id;
+  private readonly _createdAt;
+  private _updatedAt;
+  private _aggregateVersion;
+  /**
+   * 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`.
+   */
+  protected constructor(state: EntityState<TIdentifier>);
+  /** The entity's stable identity — the basis for equality between entities. */
+  get id(): TIdentifier;
+  /**
+   * 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(): Date;
+  /**
+   * 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(): Date;
+  /**
+   * 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(): number;
+  /**
+   * 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(): ContractVersion;
+  /**
+   * 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`.
+   */
+  protected markAsModified(updatedAt?: Date): number;
+}
+//#endregion
+//#region src/core/domain/value-object.d.ts
+/**
+ * Extension point for value-object equality. A plugin implementing this
+ * contract overrides how any two value objects are compared, letting the host
+ * application swap in a structural comparator (e.g. `lodash.isEqual` over the
+ * wrapped `value`) without every value object having to implement `equals` by
+ * hand.
+ */
+type ValueObjectPluginContract = {
+  equals: (a: ValueObject<unknown, unknown>, b: ValueObject<unknown, unknown>) => boolean;
+};
+/**
+ * Base class for value objects — domain concepts defined entirely by their
+ * contents, with no identity of their own. Two value objects are
+ * interchangeable when they hold equal data, which is the opposite of an
+ * {@link Entity} (compared by id). Money, a CPF, a date range: replacing one
+ * instance with an equal one changes nothing about the model.
+ *
+ * Immutability is the defining guarantee here. The wrapped `value` is
+ * deep-frozen on construction, so a value object can be shared freely without
+ * any risk of a consumer mutating shared state. Subclasses seal the instance
+ * itself with {@link finalize} once their own fields are set.
+ *
+ * @typeParam T - The shape of the wrapped data.
+ * @typeParam P - The primitive form produced by {@link toPrimitive} / {@link toJSON}.
+ */
+declare abstract class ValueObject<T, P> {
+  static readonly CONTRACT_VERSION: ContractVersion;
+  /**
+   * Registry of equality plugins shared by every value object. Empty by
+   * default — when nothing is registered, {@link equals} falls back to a
+   * structural comparison of the wrapped `value`. Hosts register a plugin
+   * (e.g. `lodash.isEqual`) once at startup to customise equality globally.
+   */
+  static readonly plugins: PluginManager<ValueObjectPluginContract>;
+  /** The wrapped data, deep-frozen so it can never be mutated after construction. */
+  readonly value: DeepReadonly<T>;
+  /**
+   * Wraps `value`, deep-freezing it so the value object is immutable from the
+   * moment it exists. Declared `protected` because value objects are built
+   * through a validating subclass factory, never instantiated directly.
+   */
+  protected constructor(value: T);
+  /**
+   * The schema/contract version stamped on this value-object type by the
+   * `@version` decorator — used to detect state persisted under an older shape.
+   */
+  get contractVersion(): ContractVersion;
+  /**
+   * Freezes the instance shell, blocking reassignment of any own field.
+   *
+   * `value` is already deep-frozen by the constructor, so the wrapped data is
+   * immutable regardless. The instance itself is NOT frozen automatically
+   * because a subclass may still need to assign its own fields after
+   * `super(value)` runs. Call `finalize()` at the very end of the subclass
+   * constructor (after all fields are set) to make the whole value object
+   * immutable.
+   */
+  protected finalize(): void;
+  /**
+   * Hook for `JSON.stringify`. Delegates to {@link toPrimitive} so a value
+   * object serializes to its primitive form rather than exposing the internal
+   * `value` wrapper.
+   */
+  toJSON(): P;
+  /**
+   * Compares this value object with another by content. Because value objects
+   * carry no identity, two independently constructed instances holding the
+   * same data are considered equal.
+   *
+   * Delegates to the registered equality {@link plugins}; with no plugin
+   * registered it falls back to comparing the serialized wrapped `value`.
+   * Subclasses may still override for a faster or domain-specific comparison.
+   */
+  equals(other: this): boolean;
+  /**
+   * Projects the value object down to a plain, serializable primitive form —
+   * the representation suitable for persistence, transport, or comparison.
+   */
+  abstract toPrimitive(): P;
+}
+//#endregion
+//#region src/core/domain/uuid-identifier.d.ts
+/**
+ * Base class for UUID-backed identity value objects.
+ *
+ * A domain typically has many of these — `OrderId`, `CustomerId`, `InvoiceId` —
+ * all wrapping the same `string` shape. Two problems follow: the UUID format
+ * check gets copy-pasted into every one, and because the wrapped shape is
+ * identical, TypeScript's structural typing would happily accept an `OrderId`
+ * where a `CustomerId` is expected. `UuidIdentifier` solves both: the format
+ * lives here once ({@link isValid}), and the `TBrand` phantom tag makes each
+ * subtype nominally distinct so the ids cannot be swapped for one another.
+ *
+ * It deliberately does not impose a factory. Identifiers vary in how they
+ * report an invalid value (their own exception type, their own message), so a
+ * concrete id adds a validating `create` that calls {@link isValid} plus a
+ * `reconstitute` that trusts an already-persisted value:
+ *
+ * ```ts
+ * class OrderId extends UuidIdentifier<"OrderId"> {
+ *   private constructor(value: string) { super(value); }
+ *   static create(raw: string): OrderId {
+ *     if (!UuidIdentifier.isValid(raw)) throw new InvalidOrderIdError(raw);
+ *     return new OrderId(raw);
+ *   }
+ *   static reconstitute(value: string): OrderId { return new OrderId(value); }
+ * }
+ * ```
+ *
+ * @typeParam TBrand - A unique string literal that nominally tags the subtype.
+ */
+declare abstract class UuidIdentifier<TBrand extends string = string> extends ValueObject<string, string> {
+  /**
+   * Phantom brand. Never assigned at runtime (`declare`), it exists only so
+   * two identifiers with different brands are not interchangeable at the type
+   * level despite sharing the same `string` value.
+   */
+  protected readonly __brand: TBrand;
+  protected constructor(value: string);
+  toPrimitive(): string;
+  /** The wrapped UUID string — convenient for logging and interpolation. */
+  toString(): string;
+  /**
+   * Whether `candidate` is a canonical UUID (versions 1–5). The single source
+   * of truth for the format; concrete identifiers call this from `create`.
+   */
+  static isValid(candidate: string): boolean;
+}
+//#endregion
+export { EntityState as a, Entity as i, ValueObject as n, ValueObjectPluginContract as r, UuidIdentifier as t };
+//# sourceMappingURL=uuid-identifier.d.cts.map

package/dist/uuid-identifier.d.ts

@@ -0,0 +1,230 @@
+import { n as ContractVersion } from "./version.js";
+import { t as DeepReadonly } from "./immutable.js";
+import { t as PluginManager } from "./plugin.js";
+
+//#region src/core/domain/entity.d.ts
+
+/**
+ * The minimal persisted shape needed to reconstitute an {@link Entity}.
+ *
+ * This is the contract between storage and the domain: a repository maps a row
+ * (or document) onto these four fields and hands them to a subclass constructor.
+ * `aggregateVersion` travels with the state so optimistic-concurrency checks
+ * survive a round-trip through the database.
+ */
+interface EntityState<TIdentifier> {
+  readonly id: TIdentifier;
+  readonly createdAt: Date;
+  readonly updatedAt: Date;
+  readonly aggregateVersion: number;
+}
+/**
+ * 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).
+ */
+declare abstract class Entity<TIdentifier> {
+  static readonly CONTRACT_VERSION: ContractVersion;
+  private readonly _id;
+  private readonly _createdAt;
+  private _updatedAt;
+  private _aggregateVersion;
+  /**
+   * 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`.
+   */
+  protected constructor(state: EntityState<TIdentifier>);
+  /** The entity's stable identity — the basis for equality between entities. */
+  get id(): TIdentifier;
+  /**
+   * 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(): Date;
+  /**
+   * 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(): Date;
+  /**
+   * 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(): number;
+  /**
+   * 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(): ContractVersion;
+  /**
+   * 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`.
+   */
+  protected markAsModified(updatedAt?: Date): number;
+}
+//#endregion
+//#region src/core/domain/value-object.d.ts
+/**
+ * Extension point for value-object equality. A plugin implementing this
+ * contract overrides how any two value objects are compared, letting the host
+ * application swap in a structural comparator (e.g. `lodash.isEqual` over the
+ * wrapped `value`) without every value object having to implement `equals` by
+ * hand.
+ */
+type ValueObjectPluginContract = {
+  equals: (a: ValueObject<unknown, unknown>, b: ValueObject<unknown, unknown>) => boolean;
+};
+/**
+ * Base class for value objects — domain concepts defined entirely by their
+ * contents, with no identity of their own. Two value objects are
+ * interchangeable when they hold equal data, which is the opposite of an
+ * {@link Entity} (compared by id). Money, a CPF, a date range: replacing one
+ * instance with an equal one changes nothing about the model.
+ *
+ * Immutability is the defining guarantee here. The wrapped `value` is
+ * deep-frozen on construction, so a value object can be shared freely without
+ * any risk of a consumer mutating shared state. Subclasses seal the instance
+ * itself with {@link finalize} once their own fields are set.
+ *
+ * @typeParam T - The shape of the wrapped data.
+ * @typeParam P - The primitive form produced by {@link toPrimitive} / {@link toJSON}.
+ */
+declare abstract class ValueObject<T, P> {
+  static readonly CONTRACT_VERSION: ContractVersion;
+  /**
+   * Registry of equality plugins shared by every value object. Empty by
+   * default — when nothing is registered, {@link equals} falls back to a
+   * structural comparison of the wrapped `value`. Hosts register a plugin
+   * (e.g. `lodash.isEqual`) once at startup to customise equality globally.
+   */
+  static readonly plugins: PluginManager<ValueObjectPluginContract>;
+  /** The wrapped data, deep-frozen so it can never be mutated after construction. */
+  readonly value: DeepReadonly<T>;
+  /**
+   * Wraps `value`, deep-freezing it so the value object is immutable from the
+   * moment it exists. Declared `protected` because value objects are built
+   * through a validating subclass factory, never instantiated directly.
+   */
+  protected constructor(value: T);
+  /**
+   * The schema/contract version stamped on this value-object type by the
+   * `@version` decorator — used to detect state persisted under an older shape.
+   */
+  get contractVersion(): ContractVersion;
+  /**
+   * Freezes the instance shell, blocking reassignment of any own field.
+   *
+   * `value` is already deep-frozen by the constructor, so the wrapped data is
+   * immutable regardless. The instance itself is NOT frozen automatically
+   * because a subclass may still need to assign its own fields after
+   * `super(value)` runs. Call `finalize()` at the very end of the subclass
+   * constructor (after all fields are set) to make the whole value object
+   * immutable.
+   */
+  protected finalize(): void;
+  /**
+   * Hook for `JSON.stringify`. Delegates to {@link toPrimitive} so a value
+   * object serializes to its primitive form rather than exposing the internal
+   * `value` wrapper.
+   */
+  toJSON(): P;
+  /**
+   * Compares this value object with another by content. Because value objects
+   * carry no identity, two independently constructed instances holding the
+   * same data are considered equal.
+   *
+   * Delegates to the registered equality {@link plugins}; with no plugin
+   * registered it falls back to comparing the serialized wrapped `value`.
+   * Subclasses may still override for a faster or domain-specific comparison.
+   */
+  equals(other: this): boolean;
+  /**
+   * Projects the value object down to a plain, serializable primitive form —
+   * the representation suitable for persistence, transport, or comparison.
+   */
+  abstract toPrimitive(): P;
+}
+//#endregion
+//#region src/core/domain/uuid-identifier.d.ts
+/**
+ * Base class for UUID-backed identity value objects.
+ *
+ * A domain typically has many of these — `OrderId`, `CustomerId`, `InvoiceId` —
+ * all wrapping the same `string` shape. Two problems follow: the UUID format
+ * check gets copy-pasted into every one, and because the wrapped shape is
+ * identical, TypeScript's structural typing would happily accept an `OrderId`
+ * where a `CustomerId` is expected. `UuidIdentifier` solves both: the format
+ * lives here once ({@link isValid}), and the `TBrand` phantom tag makes each
+ * subtype nominally distinct so the ids cannot be swapped for one another.
+ *
+ * It deliberately does not impose a factory. Identifiers vary in how they
+ * report an invalid value (their own exception type, their own message), so a
+ * concrete id adds a validating `create` that calls {@link isValid} plus a
+ * `reconstitute` that trusts an already-persisted value:
+ *
+ * ```ts
+ * class OrderId extends UuidIdentifier<"OrderId"> {
+ *   private constructor(value: string) { super(value); }
+ *   static create(raw: string): OrderId {
+ *     if (!UuidIdentifier.isValid(raw)) throw new InvalidOrderIdError(raw);
+ *     return new OrderId(raw);
+ *   }
+ *   static reconstitute(value: string): OrderId { return new OrderId(value); }
+ * }
+ * ```
+ *
+ * @typeParam TBrand - A unique string literal that nominally tags the subtype.
+ */
+declare abstract class UuidIdentifier<TBrand extends string = string> extends ValueObject<string, string> {
+  /**
+   * Phantom brand. Never assigned at runtime (`declare`), it exists only so
+   * two identifiers with different brands are not interchangeable at the type
+   * level despite sharing the same `string` value.
+   */
+  protected readonly __brand: TBrand;
+  protected constructor(value: string);
+  toPrimitive(): string;
+  /** The wrapped UUID string — convenient for logging and interpolation. */
+  toString(): string;
+  /**
+   * Whether `candidate` is a canonical UUID (versions 1–5). The single source
+   * of truth for the format; concrete identifiers call this from `create`.
+   */
+  static isValid(candidate: string): boolean;
+}
+//#endregion
+export { EntityState as a, Entity as i, ValueObject as n, ValueObjectPluginContract as r, UuidIdentifier as t };
+//# sourceMappingURL=uuid-identifier.d.ts.map

package/dist/uuid-identifier.js

@@ -0,0 +1,60 @@
+import { t as ValueObject } from "./value-object.js";
+//#region src/core/domain/uuid-identifier.ts
+/**
+* Canonical RFC-4122 UUID (versions 1–5), matched case-insensitively. Declared
+* once here so the dozens of typed identifiers a domain accumulates never have
+* to re-state the pattern.
+*/
+const UUID_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
+/**
+* Base class for UUID-backed identity value objects.
+*
+* A domain typically has many of these — `OrderId`, `CustomerId`, `InvoiceId` —
+* all wrapping the same `string` shape. Two problems follow: the UUID format
+* check gets copy-pasted into every one, and because the wrapped shape is
+* identical, TypeScript's structural typing would happily accept an `OrderId`
+* where a `CustomerId` is expected. `UuidIdentifier` solves both: the format
+* lives here once ({@link isValid}), and the `TBrand` phantom tag makes each
+* subtype nominally distinct so the ids cannot be swapped for one another.
+*
+* It deliberately does not impose a factory. Identifiers vary in how they
+* report an invalid value (their own exception type, their own message), so a
+* concrete id adds a validating `create` that calls {@link isValid} plus a
+* `reconstitute` that trusts an already-persisted value:
+*
+* ```ts
+* class OrderId extends UuidIdentifier<"OrderId"> {
+*   private constructor(value: string) { super(value); }
+*   static create(raw: string): OrderId {
+*     if (!UuidIdentifier.isValid(raw)) throw new InvalidOrderIdError(raw);
+*     return new OrderId(raw);
+*   }
+*   static reconstitute(value: string): OrderId { return new OrderId(value); }
+* }
+* ```
+*
+* @typeParam TBrand - A unique string literal that nominally tags the subtype.
+*/
+var UuidIdentifier = class extends ValueObject {
+	constructor(value) {
+		super(value);
+	}
+	toPrimitive() {
+		return this.value;
+	}
+	/** The wrapped UUID string — convenient for logging and interpolation. */
+	toString() {
+		return this.value;
+	}
+	/**
+	* Whether `candidate` is a canonical UUID (versions 1–5). The single source
+	* of truth for the format; concrete identifiers call this from `create`.
+	*/
+	static isValid(candidate) {
+		return UUID_PATTERN.test(candidate);
+	}
+};
+//#endregion
+export { UuidIdentifier as t };
+
+//# sourceMappingURL=uuid-identifier.js.map

package/dist/uuid-identifier.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"uuid-identifier.js","names":[],"sources":["../src/core/domain/uuid-identifier.ts"],"sourcesContent":["import { ValueObject } from \"./value-object.js\";\n\n/**\n * Canonical RFC-4122 UUID (versions 1–5), matched case-insensitively. Declared\n * once here so the dozens of typed identifiers a domain accumulates never have\n * to re-state the pattern.\n */\nconst UUID_PATTERN =\n    /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;\n\n/**\n * Base class for UUID-backed identity value objects.\n *\n * A domain typically has many of these — `OrderId`, `CustomerId`, `InvoiceId` —\n * all wrapping the same `string` shape. Two problems follow: the UUID format\n * check gets copy-pasted into every one, and because the wrapped shape is\n * identical, TypeScript's structural typing would happily accept an `OrderId`\n * where a `CustomerId` is expected. `UuidIdentifier` solves both: the format\n * lives here once ({@link isValid}), and the `TBrand` phantom tag makes each\n * subtype nominally distinct so the ids cannot be swapped for one another.\n *\n * It deliberately does not impose a factory. Identifiers vary in how they\n * report an invalid value (their own exception type, their own message), so a\n * concrete id adds a validating `create` that calls {@link isValid} plus a\n * `reconstitute` that trusts an already-persisted value:\n *\n * ```ts\n * class OrderId extends UuidIdentifier<\"OrderId\"> {\n *   private constructor(value: string) { super(value); }\n *   static create(raw: string): OrderId {\n *     if (!UuidIdentifier.isValid(raw)) throw new InvalidOrderIdError(raw);\n *     return new OrderId(raw);\n *   }\n *   static reconstitute(value: string): OrderId { return new OrderId(value); }\n * }\n * ```\n *\n * @typeParam TBrand - A unique string literal that nominally tags the subtype.\n */\nabstract class UuidIdentifier<\n    TBrand extends string = string,\n> extends ValueObject<string, string> {\n    /**\n     * Phantom brand. Never assigned at runtime (`declare`), it exists only so\n     * two identifiers with different brands are not interchangeable at the type\n     * level despite sharing the same `string` value.\n     */\n    protected declare readonly __brand: TBrand;\n\n    protected constructor(value: string) {\n        super(value);\n    }\n\n    public toPrimitive(): string {\n        return this.value;\n    }\n\n    /** The wrapped UUID string — convenient for logging and interpolation. */\n    public toString(): string {\n        return this.value;\n    }\n\n    /**\n     * Whether `candidate` is a canonical UUID (versions 1–5). The single source\n     * of truth for the format; concrete identifiers call this from `create`.\n     */\n    public static isValid(candidate: string): boolean {\n        return UUID_PATTERN.test(candidate);\n    }\n}\n\nexport { UuidIdentifier };\n"],"mappings":";;;;;;;AAOA,MAAM,eACF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA+BJ,IAAe,iBAAf,cAEU,YAA4B;CAQlC,YAAsB,OAAe;EACjC,MAAM,KAAK;CACf;CAEA,cAA6B;EACzB,OAAO,KAAK;CAChB;;CAGA,WAA0B;EACtB,OAAO,KAAK;CAChB;;;;;CAMA,OAAc,QAAQ,WAA4B;EAC9C,OAAO,aAAa,KAAK,SAAS;CACtC;AACJ"}

package/dist/validation-code.cjs

@@ -0,0 +1,60 @@
+//#region src/core/exceptions/validation-code.ts
+var ValidationCode = class ValidationCode {
+	constructor(value) {
+		this.value = value;
+	}
+	static of(value) {
+		return new ValidationCode(value);
+	}
+	static {
+		this.BLANK = new ValidationCode("blank");
+	}
+	static {
+		this.REQUIRED = new ValidationCode("required");
+	}
+	static {
+		this.INVALID_FORMAT = new ValidationCode("invalid_format");
+	}
+	static {
+		this.INVALID_CHARACTERS = new ValidationCode("invalid_characters");
+	}
+	static {
+		this.INVALID_LENGTH = new ValidationCode("invalid_length");
+	}
+	static {
+		this.TOO_SHORT = new ValidationCode("too_short");
+	}
+	static {
+		this.TOO_LONG = new ValidationCode("too_long");
+	}
+	static {
+		this.OUT_OF_RANGE = new ValidationCode("out_of_range");
+	}
+	static {
+		this.INVALID_CHECKSUM = new ValidationCode("invalid_checksum");
+	}
+	static {
+		this.INVALID_CHECKING_DIGIT = new ValidationCode("invalid_checking_digit");
+	}
+	static {
+		this.ALREADY_EXISTS = new ValidationCode("already_exists");
+	}
+	static {
+		this.NOT_FOUND = new ValidationCode("not_found");
+	}
+	static {
+		this.NOT_ALLOWED = new ValidationCode("not_allowed");
+	}
+	static {
+		this.UNEXPECTED = new ValidationCode("unexpected");
+	}
+};
+//#endregion
+Object.defineProperty(exports, "ValidationCode", {
+	enumerable: true,
+	get: function() {
+		return ValidationCode;
+	}
+});
+
+//# sourceMappingURL=validation-code.cjs.map

package/dist/validation-code.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"validation-code.cjs","names":[],"sources":["../src/core/exceptions/validation-code.ts"],"sourcesContent":["// Object-oriented representation of validation codes (similar to Kotlin inline class).\n// Provides common reusable codes while allowing custom codes via `of`.\n\nclass ValidationCode {\n    public readonly value: string;\n\n    private constructor(value: string) {\n        this.value = value;\n    }\n\n    // Factory for custom codes\n    public static of(value: string): ValidationCode {\n        return new ValidationCode(value);\n    }\n\n    // Common, domain-friendly codes\n    public static readonly BLANK = new ValidationCode(\"blank\");\n    public static readonly REQUIRED = new ValidationCode(\"required\");\n    public static readonly INVALID_FORMAT = new ValidationCode(\n        \"invalid_format\",\n    );\n    public static readonly INVALID_CHARACTERS = new ValidationCode(\n        \"invalid_characters\",\n    );\n    public static readonly INVALID_LENGTH = new ValidationCode(\n        \"invalid_length\",\n    );\n    public static readonly TOO_SHORT = new ValidationCode(\"too_short\");\n    public static readonly TOO_LONG = new ValidationCode(\"too_long\");\n    public static readonly OUT_OF_RANGE = new ValidationCode(\"out_of_range\");\n    public static readonly INVALID_CHECKSUM = new ValidationCode(\n        \"invalid_checksum\",\n    );\n    public static readonly INVALID_CHECKING_DIGIT = new ValidationCode(\n        \"invalid_checking_digit\",\n    );\n    public static readonly ALREADY_EXISTS = new ValidationCode(\n        \"already_exists\",\n    );\n    public static readonly NOT_FOUND = new ValidationCode(\"not_found\");\n    public static readonly NOT_ALLOWED = new ValidationCode(\"not_allowed\");\n    public static readonly UNEXPECTED = new ValidationCode(\"unexpected\");\n}\n\nexport { ValidationCode };\n"],"mappings":";AAGA,IAAM,iBAAN,MAAM,eAAe;CAGjB,YAAoB,OAAe;EAC/B,KAAK,QAAQ;CACjB;CAGA,OAAc,GAAG,OAA+B;EAC5C,OAAO,IAAI,eAAe,KAAK;CACnC;;eAG+B,IAAI,eAAe,OAAO;;;kBACvB,IAAI,eAAe,UAAU;;;wBACvB,IAAI,eACxC,gBACJ;;;4BAC4C,IAAI,eAC5C,oBACJ;;;wBACwC,IAAI,eACxC,gBACJ;;;mBACmC,IAAI,eAAe,WAAW;;;kBAC/B,IAAI,eAAe,UAAU;;;sBACzB,IAAI,eAAe,cAAc;;;0BAC7B,IAAI,eAC1C,kBACJ;;;gCACgD,IAAI,eAChD,wBACJ;;;wBACwC,IAAI,eACxC,gBACJ;;;mBACmC,IAAI,eAAe,WAAW;;;qBAC5B,IAAI,eAAe,aAAa;;;oBACjC,IAAI,eAAe,YAAY;;AACvE"}

package/dist/validation-code.d.cts

@@ -0,0 +1,23 @@
+//#region src/core/exceptions/validation-code.d.ts
+declare class ValidationCode {
+  readonly value: string;
+  private constructor();
+  static of(value: string): ValidationCode;
+  static readonly BLANK: ValidationCode;
+  static readonly REQUIRED: ValidationCode;
+  static readonly INVALID_FORMAT: ValidationCode;
+  static readonly INVALID_CHARACTERS: ValidationCode;
+  static readonly INVALID_LENGTH: ValidationCode;
+  static readonly TOO_SHORT: ValidationCode;
+  static readonly TOO_LONG: ValidationCode;
+  static readonly OUT_OF_RANGE: ValidationCode;
+  static readonly INVALID_CHECKSUM: ValidationCode;
+  static readonly INVALID_CHECKING_DIGIT: ValidationCode;
+  static readonly ALREADY_EXISTS: ValidationCode;
+  static readonly NOT_FOUND: ValidationCode;
+  static readonly NOT_ALLOWED: ValidationCode;
+  static readonly UNEXPECTED: ValidationCode;
+}
+//#endregion
+export { ValidationCode as t };
+//# sourceMappingURL=validation-code.d.cts.map

package/dist/validation-code.d.ts

@@ -0,0 +1,23 @@
+//#region src/core/exceptions/validation-code.d.ts
+declare class ValidationCode {
+  readonly value: string;
+  private constructor();
+  static of(value: string): ValidationCode;
+  static readonly BLANK: ValidationCode;
+  static readonly REQUIRED: ValidationCode;
+  static readonly INVALID_FORMAT: ValidationCode;
+  static readonly INVALID_CHARACTERS: ValidationCode;
+  static readonly INVALID_LENGTH: ValidationCode;
+  static readonly TOO_SHORT: ValidationCode;
+  static readonly TOO_LONG: ValidationCode;
+  static readonly OUT_OF_RANGE: ValidationCode;
+  static readonly INVALID_CHECKSUM: ValidationCode;
+  static readonly INVALID_CHECKING_DIGIT: ValidationCode;
+  static readonly ALREADY_EXISTS: ValidationCode;
+  static readonly NOT_FOUND: ValidationCode;
+  static readonly NOT_ALLOWED: ValidationCode;
+  static readonly UNEXPECTED: ValidationCode;
+}
+//#endregion
+export { ValidationCode as t };
+//# sourceMappingURL=validation-code.d.ts.map