@vytches/ddd-value-objects 0.26.0

package/dist/base-value-object.d.ts

@@ -0,0 +1,35 @@
+export interface ValueObjectValidator<T> {
+    validate(value: T): boolean;
+}
+export declare abstract class BaseValueObject<T> implements ValueObjectValidator<T> {
+    protected readonly value: T;
+    constructor(value: T);
+    /**
+     * Compares this value object with another for equality.
+     * Uses deep structural comparison for object values, === for primitives.
+     * @param valueObject - The value object to compare with
+     * @returns True if they are equal, false otherwise
+     */
+    equals(valueObject: BaseValueObject<T>): boolean;
+    /**
+     * Returns a string representation of the value object
+     * @returns String representation
+     */
+    toString(): string;
+    /**
+     * Returns the value for JSON serialization.
+     * Returns T (not string) so JSON.stringify works correctly without double-encoding.
+     */
+    toJSON(): unknown;
+    /**
+     * Gets the underlying value as a readonly reference.
+     * @returns The underlying value (frozen for object types)
+     */
+    getValue(): Readonly<T>;
+    /**
+     * Abstract method to validate the value
+     * @param value The value to validate
+     * @returns True if valid, false otherwise
+     */
+    abstract validate(value: unknown): boolean;
+}

package/dist/branded-id.d.ts

@@ -0,0 +1,58 @@
+import { EntityId } from './id.value-object';
+declare const __brand: unique symbol;
+/**
+ * A branded EntityId that carries a compile-time tag.
+ * Prevents mixing IDs from different aggregate types.
+ *
+ * @public
+ * @stable
+ * @since 0.24.0
+ */
+export type BrandedId<Tag extends string> = EntityId<string> & {
+    readonly [__brand]: Tag;
+};
+/**
+ * Create a branded ID from an existing EntityId.
+ *
+ * @public
+ * @stable
+ * @since 0.24.0
+ *
+ * @example
+ * ```typescript
+ * type OrderId = BrandedId<'Order'>;
+ * const orderId = createBrandedId<'Order'>(EntityId.create());
+ * ```
+ */
+export declare function createBrandedId<Tag extends string>(id: EntityId<string>): BrandedId<Tag>;
+/**
+ * Create a new branded ID with a random UUID.
+ *
+ * @public
+ * @stable
+ * @since 0.24.0
+ *
+ * @example
+ * ```typescript
+ * type OrderId = BrandedId<'Order'>;
+ * const orderId = newBrandedId<'Order'>();
+ * ```
+ */
+export declare function newBrandedId<Tag extends string>(): BrandedId<Tag>;
+/**
+ * Create a branded ID from a UUID string.
+ *
+ * @public
+ * @stable
+ * @since 0.24.0
+ */
+export declare function brandedIdFromUUID<Tag extends string>(uuid: string): BrandedId<Tag>;
+/**
+ * Create a branded ID from a text value.
+ *
+ * @public
+ * @stable
+ * @since 0.24.0
+ */
+export declare function brandedIdFromText<Tag extends string>(text: string): BrandedId<Tag>;
+export {};

package/dist/id.value-object.d.ts

@@ -0,0 +1,106 @@
+import { EntityId as BaseEntityId, IEntityIdFactory, IdType } from '@vytches/ddd-contracts';
+import { Result } from '@vytches/ddd-utils';
+export declare class EntityId<T = string> extends BaseEntityId<T> {
+    constructor(value: T, type: IdType);
+    validate(value: T): boolean;
+    /**
+     * Primary factory method - creates a new EntityId with a randomly generated UUID
+     * @returns New EntityId with random UUID
+     * @example
+     * ```typescript
+     * const id = EntityId.create();
+     * console.log(id.getValue()); // Returns: '550e8400-e29b-41d4-a716-446655440000'
+     * ```
+     */
+    static create(): EntityId<string>;
+    /**
+     * @deprecated Use `create()` instead. Will be removed in next major version.
+     */
+    static createWithRandomUUID(): EntityId<string>;
+    /**
+     * @returns EntityId instance
+     * @throws {MissingValueError} if value is empty
+     * @throws {InvalidParameterError} if value is not a valid UUID
+     */
+    static fromUUID(value: string): EntityId<string>;
+    static fromInteger(value: number): EntityId<string>;
+    static fromBigInt(value: string | bigint): EntityId<string>;
+    static fromText(value: string): EntityId<string>;
+    /**
+     * Create EntityId from UUID string, returning Result instead of throwing.
+     * @public
+     * @stable
+     * @since 0.24.0
+     */
+    static tryFromUUID(value: string): Result<EntityId<string>, Error>;
+    /**
+     * Create EntityId from integer, returning Result instead of throwing.
+     * @public
+     * @stable
+     * @since 0.24.0
+     */
+    static tryFromInteger(value: number): Result<EntityId<string>, Error>;
+    /**
+     * Create EntityId from bigint, returning Result instead of throwing.
+     * @public
+     * @stable
+     * @since 0.24.0
+     */
+    static tryFromBigInt(value: string | bigint): Result<EntityId<string>, Error>;
+    /**
+     * Create EntityId from text, returning Result instead of throwing.
+     * @public
+     * @stable
+     * @since 0.24.0
+     */
+    static tryFromText(value: string): Result<EntityId<string>, Error>;
+}
+/**
+ * @deprecated Use EntityId static methods directly instead. This class will be removed in the next major version.
+ * @example
+ * ```typescript
+ * // Before (deprecated):
+ * const id = EntityIdFactory.createWithRandomUUID();
+ *
+ * // After (recommended):
+ * const id = EntityId.create();
+ * ```
+ */
+export declare class EntityIdFactory implements IEntityIdFactory {
+    /**
+     * @deprecated Use EntityId.create() instead. Will be removed in v1.0.0.
+     */
+    static createWithRandomUUID(): EntityId<string>;
+    /**
+     * @deprecated Use EntityId.fromUUID() instead. Will be removed in v1.0.0.
+     * @throws {MissingValueError} if value is empty
+     * @throws {InvalidParameterError} if value is empty
+     */
+    static fromUUID(value: string): EntityId<string>;
+    /**
+     * @deprecated Use EntityId.fromInteger() instead. Will be removed in v1.0.0.
+     * @throws {InvalidParameterError} if value is empty
+     */
+    static fromInteger(value: number): EntityId<string>;
+    /**
+     * @deprecated Use EntityId.fromBigInt() instead. Will be removed in v1.0.0.
+     * @throws {InvalidParameterError} if value is empty
+     */
+    static fromBigInt(value: string | bigint): EntityId<string>;
+    /**
+     * @deprecated Use EntityId.fromText() instead. Will be removed in v1.0.0.
+     * @throws {MissingValueError} if value is empty
+     * @throws {InvalidParameterError} if value is empty
+     */
+    static fromText(value: string): EntityId<string>;
+    /** @deprecated Use EntityId.create() instead */
+    createWithRandomUUID(): EntityId<string>;
+    /** @deprecated Use EntityId.fromUUID() instead */
+    fromUUID(value: string): EntityId<string>;
+    /** @deprecated Use EntityId.fromInteger() instead */
+    fromInteger(value: number): EntityId<string>;
+    /** @deprecated Use EntityId.fromBigInt() instead */
+    fromBigInt(value: string | bigint): EntityId<string>;
+    /** @deprecated Use EntityId.fromText() instead */
+    fromText(value: string): EntityId<string>;
+}

package/dist/index.cjs

@@ -0,0 +1 @@
+"use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const l=require("@vytches/ddd-contracts"),r=require("@vytches/ddd-domain-primitives"),e=require("@vytches/ddd-utils");class u{constructor(t){t!==null&&typeof t=="object"?this.value=Object.freeze(t):this.value=t}equals(t){return t?this.value===t.value?!0:typeof this.value=="object"&&this.value!==null?JSON.stringify(this.value)===JSON.stringify(t.value):!1:!1}toString(){return String(this.value)}toJSON(){return this.value}getValue(){return this.value}}const d=new Set;function o(n,t){d.has(n)||(d.add(n),console.warn(`[@vytches/ddd-value-objects] EntityIdFactory.${n}() is deprecated and will be removed in v1.0.0. Use ${t} instead. See https://github.com/vytches/ddd/blob/main/CHANGELOG.md for migration details.`))}class i extends l.EntityId{constructor(t,a){super(t,a)}validate(t){switch(this.getType()){case"uuid":return e.LibUtils.isValidUUID(t);case"integer":return e.LibUtils.isValidInteger(t);case"bigint":return e.LibUtils.isValidBigInt(t);case"text":return e.LibUtils.isValidTextId(t);default:throw new r.InvalidParameterError(`Unsupported IdType: ${this.getType()}`)}}static create(){return new i(e.LibUtils.getUUID(),"uuid")}static createWithRandomUUID(){return i.create()}static fromUUID(t){if(!e.LibUtils.hasValue(t))throw r.MissingValueError.withValue("entity identifier");if(!e.LibUtils.isValidUUID(t))throw r.InvalidParameterError.withParameter("entity identifier");return new i(t,"uuid")}static fromInteger(t){if(!e.LibUtils.isValidInteger(t))throw r.InvalidParameterError.withParameter("entity identifier must be a non-negative integer");return new i(t.toString(),"integer")}static fromBigInt(t){const a=e.LibUtils.normalizeIdToString(t);if(!e.LibUtils.isValidBigInt(a))throw r.InvalidParameterError.withParameter("entity identifier must be a valid bigint");return new i(a,"bigint")}static fromText(t){if(!e.LibUtils.hasValue(t))throw r.MissingValueError.withValue("entity identifier");if(!e.LibUtils.isValidTextId(t))throw r.InvalidParameterError.withParameter("entity identifier contains invalid characters");return new i(t,"text")}static tryFromUUID(t){return e.LibUtils.hasValue(t)?e.LibUtils.isValidUUID(t)?e.Result.ok(new i(t,"uuid")):e.Result.fail(r.InvalidParameterError.withParameter("entity identifier")):e.Result.fail(r.MissingValueError.withValue("entity identifier"))}static tryFromInteger(t){return e.LibUtils.isValidInteger(t)?e.Result.ok(new i(t.toString(),"integer")):e.Result.fail(r.InvalidParameterError.withParameter("entity identifier must be a non-negative integer"))}static tryFromBigInt(t){const a=e.LibUtils.normalizeIdToString(t);return e.LibUtils.isValidBigInt(a)?e.Result.ok(new i(a,"bigint")):e.Result.fail(r.InvalidParameterError.withParameter("entity identifier must be a valid bigint"))}static tryFromText(t){return e.LibUtils.hasValue(t)?e.LibUtils.isValidTextId(t)?e.Result.ok(new i(t,"text")):e.Result.fail(r.InvalidParameterError.withParameter("entity identifier contains invalid characters")):e.Result.fail(r.MissingValueError.withValue("entity identifier"))}}class s{static createWithRandomUUID(){return o("createWithRandomUUID","EntityId.create()"),i.create()}static fromUUID(t){if(o("fromUUID","EntityId.fromUUID()"),!e.LibUtils.hasValue(t))throw r.MissingValueError.withValue("entity identifier");if(!e.LibUtils.isValidUUID(t))throw r.InvalidParameterError.withParameter("entity identifier");return new i(t,"uuid")}static fromInteger(t){if(o("fromInteger","EntityId.fromInteger()"),!e.LibUtils.isValidInteger(t))throw r.InvalidParameterError.withParameter("entity identifier must be a non-negative integer");return new i(t.toString(),"integer")}static fromBigInt(t){o("fromBigInt","EntityId.fromBigInt()");const a=e.LibUtils.normalizeIdToString(t);if(!e.LibUtils.isValidBigInt(a))throw r.InvalidParameterError.withParameter("entity identifier must be a valid bigint");return new i(a,"bigint")}static fromText(t){if(o("fromText","EntityId.fromText()"),!e.LibUtils.hasValue(t))throw r.MissingValueError.withValue("entity identifier");if(!e.LibUtils.isValidTextId(t))throw r.InvalidParameterError.withParameter("entity identifier contains invalid characters");return new i(t,"text")}createWithRandomUUID(){return i.create()}fromUUID(t){return s.fromUUID(t)}fromInteger(t){return s.fromInteger(t)}fromBigInt(t){return s.fromBigInt(t)}fromText(t){return s.fromText(t)}}function f(n){return n}function m(){return i.create()}function c(n){return i.fromUUID(n)}function I(n){return i.fromText(n)}exports.BaseValueObject=u;exports.EntityId=i;exports.EntityIdFactory=s;exports.brandedIdFromText=I;exports.brandedIdFromUUID=c;exports.createBrandedId=f;exports.newBrandedId=m;

package/dist/index.d.ts

@@ -0,0 +1,5 @@
+export { BaseValueObject, type ValueObjectValidator } from './base-value-object';
+export { EntityId, EntityIdFactory } from './id.value-object';
+export type { BrandedId } from './branded-id';
+export { createBrandedId, newBrandedId, brandedIdFromUUID, brandedIdFromText } from './branded-id';
+export type { IEntityId, IEntityIdFactory, IdType } from '@vytches/ddd-contracts';

package/dist/index.js

@@ -0,0 +1,248 @@
+import { EntityId as m } from "@vytches/ddd-contracts";
+import { InvalidParameterError as r, MissingValueError as o } from "@vytches/ddd-domain-primitives";
+import { LibUtils as e, Result as s } from "@vytches/ddd-utils";
+class l {
+  constructor(t) {
+    t !== null && typeof t == "object" ? this.value = Object.freeze(t) : this.value = t;
+  }
+  /**
+   * Compares this value object with another for equality.
+   * Uses deep structural comparison for object values, === for primitives.
+   * @param valueObject - The value object to compare with
+   * @returns True if they are equal, false otherwise
+   */
+  equals(t) {
+    return t ? this.value === t.value ? !0 : typeof this.value == "object" && this.value !== null ? JSON.stringify(this.value) === JSON.stringify(t.value) : !1 : !1;
+  }
+  /**
+   * Returns a string representation of the value object
+   * @returns String representation
+   */
+  toString() {
+    return String(this.value);
+  }
+  /**
+   * Returns the value for JSON serialization.
+   * Returns T (not string) so JSON.stringify works correctly without double-encoding.
+   */
+  toJSON() {
+    return this.value;
+  }
+  /**
+   * Gets the underlying value as a readonly reference.
+   * @returns The underlying value (frozen for object types)
+   */
+  getValue() {
+    return this.value;
+  }
+}
+const u = /* @__PURE__ */ new Set();
+function f(n, t) {
+  u.has(n) || (u.add(n), console.warn(
+    `[@vytches/ddd-value-objects] EntityIdFactory.${n}() is deprecated and will be removed in v1.0.0. Use ${t} instead. See https://github.com/vytches/ddd/blob/main/CHANGELOG.md for migration details.`
+  ));
+}
+class i extends m {
+  constructor(t, a) {
+    super(t, a);
+  }
+  validate(t) {
+    switch (this.getType()) {
+      case "uuid":
+        return e.isValidUUID(t);
+      case "integer":
+        return e.isValidInteger(t);
+      case "bigint":
+        return e.isValidBigInt(t);
+      case "text":
+        return e.isValidTextId(t);
+      default:
+        throw new r(`Unsupported IdType: ${this.getType()}`);
+    }
+  }
+  /**
+   * Primary factory method - creates a new EntityId with a randomly generated UUID
+   * @returns New EntityId with random UUID
+   * @example
+   * ```typescript
+   * const id = EntityId.create();
+   * console.log(id.getValue()); // Returns: '550e8400-e29b-41d4-a716-446655440000'
+   * ```
+   */
+  static create() {
+    return new i(e.getUUID(), "uuid");
+  }
+  /**
+   * @deprecated Use `create()` instead. Will be removed in next major version.
+   */
+  static createWithRandomUUID() {
+    return i.create();
+  }
+  /**
+   * @returns EntityId instance
+   * @throws {MissingValueError} if value is empty
+   * @throws {InvalidParameterError} if value is not a valid UUID
+   */
+  static fromUUID(t) {
+    if (!e.hasValue(t))
+      throw o.withValue("entity identifier");
+    if (!e.isValidUUID(t))
+      throw r.withParameter("entity identifier");
+    return new i(t, "uuid");
+  }
+  static fromInteger(t) {
+    if (!e.isValidInteger(t))
+      throw r.withParameter("entity identifier must be a non-negative integer");
+    return new i(t.toString(), "integer");
+  }
+  static fromBigInt(t) {
+    const a = e.normalizeIdToString(t);
+    if (!e.isValidBigInt(a))
+      throw r.withParameter("entity identifier must be a valid bigint");
+    return new i(a, "bigint");
+  }
+  static fromText(t) {
+    if (!e.hasValue(t))
+      throw o.withValue("entity identifier");
+    if (!e.isValidTextId(t))
+      throw r.withParameter("entity identifier contains invalid characters");
+    return new i(t, "text");
+  }
+  // --- Result-returning factory methods (non-throwing) ---
+  /**
+   * Create EntityId from UUID string, returning Result instead of throwing.
+   * @public
+   * @stable
+   * @since 0.24.0
+   */
+  static tryFromUUID(t) {
+    return e.hasValue(t) ? e.isValidUUID(t) ? s.ok(new i(t, "uuid")) : s.fail(r.withParameter("entity identifier")) : s.fail(o.withValue("entity identifier"));
+  }
+  /**
+   * Create EntityId from integer, returning Result instead of throwing.
+   * @public
+   * @stable
+   * @since 0.24.0
+   */
+  static tryFromInteger(t) {
+    return e.isValidInteger(t) ? s.ok(new i(t.toString(), "integer")) : s.fail(
+      r.withParameter("entity identifier must be a non-negative integer")
+    );
+  }
+  /**
+   * Create EntityId from bigint, returning Result instead of throwing.
+   * @public
+   * @stable
+   * @since 0.24.0
+   */
+  static tryFromBigInt(t) {
+    const a = e.normalizeIdToString(t);
+    return e.isValidBigInt(a) ? s.ok(new i(a, "bigint")) : s.fail(
+      r.withParameter("entity identifier must be a valid bigint")
+    );
+  }
+  /**
+   * Create EntityId from text, returning Result instead of throwing.
+   * @public
+   * @stable
+   * @since 0.24.0
+   */
+  static tryFromText(t) {
+    return e.hasValue(t) ? e.isValidTextId(t) ? s.ok(new i(t, "text")) : s.fail(
+      r.withParameter("entity identifier contains invalid characters")
+    ) : s.fail(o.withValue("entity identifier"));
+  }
+}
+class d {
+  /**
+   * @deprecated Use EntityId.create() instead. Will be removed in v1.0.0.
+   */
+  static createWithRandomUUID() {
+    return f("createWithRandomUUID", "EntityId.create()"), i.create();
+  }
+  /**
+   * @deprecated Use EntityId.fromUUID() instead. Will be removed in v1.0.0.
+   * @throws {MissingValueError} if value is empty
+   * @throws {InvalidParameterError} if value is empty
+   */
+  static fromUUID(t) {
+    if (f("fromUUID", "EntityId.fromUUID()"), !e.hasValue(t))
+      throw o.withValue("entity identifier");
+    if (!e.isValidUUID(t))
+      throw r.withParameter("entity identifier");
+    return new i(t, "uuid");
+  }
+  /**
+   * @deprecated Use EntityId.fromInteger() instead. Will be removed in v1.0.0.
+   * @throws {InvalidParameterError} if value is empty
+   */
+  static fromInteger(t) {
+    if (f("fromInteger", "EntityId.fromInteger()"), !e.isValidInteger(t))
+      throw r.withParameter("entity identifier must be a non-negative integer");
+    return new i(t.toString(), "integer");
+  }
+  /**
+   * @deprecated Use EntityId.fromBigInt() instead. Will be removed in v1.0.0.
+   * @throws {InvalidParameterError} if value is empty
+   */
+  static fromBigInt(t) {
+    f("fromBigInt", "EntityId.fromBigInt()");
+    const a = e.normalizeIdToString(t);
+    if (!e.isValidBigInt(a))
+      throw r.withParameter("entity identifier must be a valid bigint");
+    return new i(a, "bigint");
+  }
+  /**
+   * @deprecated Use EntityId.fromText() instead. Will be removed in v1.0.0.
+   * @throws {MissingValueError} if value is empty
+   * @throws {InvalidParameterError} if value is empty
+   */
+  static fromText(t) {
+    if (f("fromText", "EntityId.fromText()"), !e.hasValue(t))
+      throw o.withValue("entity identifier");
+    if (!e.isValidTextId(t))
+      throw r.withParameter("entity identifier contains invalid characters");
+    return new i(t, "text");
+  }
+  /** @deprecated Use EntityId.create() instead */
+  createWithRandomUUID() {
+    return i.create();
+  }
+  /** @deprecated Use EntityId.fromUUID() instead */
+  fromUUID(t) {
+    return d.fromUUID(t);
+  }
+  /** @deprecated Use EntityId.fromInteger() instead */
+  fromInteger(t) {
+    return d.fromInteger(t);
+  }
+  /** @deprecated Use EntityId.fromBigInt() instead */
+  fromBigInt(t) {
+    return d.fromBigInt(t);
+  }
+  /** @deprecated Use EntityId.fromText() instead */
+  fromText(t) {
+    return d.fromText(t);
+  }
+}
+function w(n) {
+  return n;
+}
+function I() {
+  return i.create();
+}
+function U(n) {
+  return i.fromUUID(n);
+}
+function V(n) {
+  return i.fromText(n);
+}
+export {
+  l as BaseValueObject,
+  i as EntityId,
+  d as EntityIdFactory,
+  V as brandedIdFromText,
+  U as brandedIdFromUUID,
+  w as createBrandedId,
+  I as newBrandedId
+};

package/package.json

@@ -0,0 +1,68 @@
+{
+  "name": "@vytches/ddd-value-objects",
+  "version": "0.26.0",
+  "description": "Enhanced value objects and EntityId implementations",
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "sideEffects": false,
+  "files": [
+    "dist",
+    "README.md",
+    "LLMGUIDE.md"
+  ],
+  "keywords": [
+    "ddd",
+    "domain-driven-design",
+    "typescript",
+    "value, objects"
+  ],
+  "author": "VytchesDDD",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/vytches/ddd.git",
+    "directory": "packages/value-objects"
+  },
+  "dependencies": {
+    "@vytches/ddd-utils": "0.26.0",
+    "@vytches/ddd-domain-primitives": "0.26.0",
+    "@vytches/ddd-contracts": "0.26.0"
+  },
+  "devDependencies": {
+    "typescript": "^5.0.0",
+    "vite": "^7.3.2",
+    "vite-plugin-dts": "^4.0.0",
+    "vitest": "^2.0.0",
+    "@vytches/ddd-testing": "0.26.0"
+  },
+  "nx": {
+    "tags": [
+      "scope:value-objects",
+      "type:lib",
+      "layer:foundation"
+    ]
+  },
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org",
+    "access": "public"
+  },
+  "scripts": {
+    "build": "vite build",
+    "dev": "vite build --watch",
+    "clean": "rm -rf dist .tsbuildinfo",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage",
+    "lint": "eslint src --ext .ts",
+    "type-check": "tsc --noEmit"
+  }
+}