@haskou/value-objects 1.0.3 → 1.1.0

package/README.md

@@ -2,7 +2,7 @@
 
 # Value Objects
 
-A TypeScript dependency-less library for creating safe, immutable,
+A TypeScript lightweight library for creating safe, immutable,
 and validated **Value Objects**. Perfect for applications that require **Domain-Driven Design (DDD)** and **type safety**.
 
 ## 🚀 Quick Start
@@ -58,6 +58,10 @@ your application.
 - **`Integer`** - Whole numbers
 - **`PositiveNumber`** - Positive numbers (> 0)
 
+### 🆔 Identifiers
+- **`ShortId`** - MongoDB ObjectId strings (24‑character hex)
+- **`UUID`** - Universally Unique Identifier (v4)
+
 ### ✨ Specialized
 - **`Email`** - Email addresses with automatic validation
 - **`Color`** - Hex colors (#FF0000)
@@ -79,7 +83,12 @@ your application.
 - **`Longitude`** - Longitude (-180 to 180)
 - **`Coordinates`** - Coordinate pairs
 
-### 📝 Other
+### � Hashes
+- **`MD5Hash`** - MD5 hashes with helpers
+- **`SHA256Hash`** - SHA‑256 hashes with helpers
+- **`SHA512Hash`** - SHA‑512 hashes with helpers
+
+### �📝 Other
 - **`Enum`** - Base class for typed enumerations
 
 ## 💡 Basic Examples
@@ -111,6 +120,16 @@ const coords = new Coordinates(latitude, longitude);
 const hour = new Hour('09:30');
 const year = new Year(2024);
 console.log(year.isLeapYear()); // true
+
+// IDs
+const id = ShortId.generate(); // 69ad70897364ee0d1406b1d0
+const uuid = UUID.generate(); // 3fd4c04a-8e73-4e10-aef3-f491b32ec538
+
+// Hashes
+const md5 = MD5Hash.from('hello'); // 5d41402abc4b2a76b9719d911017c592
+const sha256 = SHA256Hash.from('hello'); // 2cf24dba5fb0a30e26e83b2ac5b9e29e1b161e5c1fa7425e73043362938b9824
+const sha512 = SHA512Hash.from('hello'); // 9b71d224bd62f3785d96d46ad3ea3d73319bfbc2890caadae2dff72519673ca72323c3d99ba5c11d7c7acc6e14b8c5da0c4663475c2e5c3adef46f73bcdec043
+console.log(md5.toBase64());
 ```
 
 ## 📚 Technical Documentation

package/TECHNICAL_DOCUMENTATION.md

@@ -13,6 +13,7 @@ Comprehensive technical documentation for the Value Objects library.
   - [Year Value Objects](#year-value-objects)
   - [Color Value Objects](#color-value-objects)
   - [Email Value Objects](#email-value-objects)
+  - [ID Value Objects](#id-value-objects)
   - [Hour Value Objects](#hour-value-objects)
   - [Time Value Objects](#time-value-objects)
   - [Enum Value Objects](#enum-value-objects)
@@ -471,6 +472,171 @@ const validEmails = [
 ];
 ```
 
+### ID Value Objects
+
+#### ShortId
+
+Represents immutable MongoDB ObjectId values with automatic generation and validation.
+
+```typescript
+class ShortId extends ValueObject<string> {
+  public static generate(): ShortId;
+  constructor(value: string | StringValueObject);
+}
+```
+
+**Example:**
+```typescript
+// Generate a new ObjectId
+const id = ShortId.generate();
+console.log(id.toString()); // '507f1f77bcf86cd799439011' (24-character hex string)
+
+// Create from existing ObjectId string
+const existingId = new ShortId('507f1f77bcf86cd799439011');
+
+// From StringValueObject
+const idString = new StringValueObject('507f1f77bcf86cd799439011');
+const idFromString = new ShortId(idString);
+
+// String representation
+console.log(existingId.toString()); // '507f1f77bcf86cd799439011'
+console.log(existingId.valueOf());  // '507f1f77bcf86cd799439011'
+
+// Equality comparison
+const id1 = new ShortId('507f1f77bcf86cd799439011');
+const id2 = new ShortId('507f1f77bcf86cd799439011');
+console.log(id1.isEqual(id2)); // true
+
+// Validation
+try {
+  new ShortId('invalid-id');        // Throws InvalidFormatError
+  new ShortId('short');             // Throws InvalidLengthError
+} catch (error) {
+  console.error('Invalid ObjectId format');
+}
+```
+
+#### UUID
+
+Represents immutable UUID (Universally Unique Identifier) values with automatic generation and validation.
+
+```typescript
+class UUID extends ValueObject<string> {
+  public static generate(): UUID;
+  constructor(value: string | StringValueObject);
+}
+```
+
+**Example:**
+```typescript
+// Generate a new UUID v4
+const uuid = UUID.generate();
+console.log(uuid.toString()); // '550e8400-e29b-41d4-a716-446655440000' (36-character string)
+
+// Create from existing UUID string
+const existingUuid = new UUID('550e8400-e29b-41d4-a716-446655440000');
+
+// From StringValueObject
+const uuidString = new StringValueObject('550e8400-e29b-41d4-a716-446655440000');
+const uuidFromString = new UUID(uuidString);
+
+// String representation
+console.log(existingUuid.toString()); // '550e8400-e29b-41d4-a716-446655440000'
+console.log(existingUuid.valueOf());  // '550e8400-e29b-41d4-a716-446655440000'
+
+// Equality comparison
+const uuid1 = new UUID('550e8400-e29b-41d4-a716-446655440000');
+const uuid2 = new UUID('550e8400-e29b-41d4-a716-446655440000');
+console.log(uuid1.isEqual(uuid2)); // true
+
+// Validation
+try {
+  new UUID('invalid-uuid');         // Throws InvalidFormatError
+  new UUID('short-uuid');           // Throws InvalidLengthError
+} catch (error) {
+  console.error('Invalid UUID format');
+}
+```
+
+### Hash Value Objects
+
+#### MD5Hash
+Represents immutable MD5 hashes with validation and utility methods.
+
+```typescript
+class MD5Hash extends Hash {
+  public static isValid(hash: string | StringValueObject): boolean;
+  public static from(buffer: Buffer | string | StringValueObject): MD5Hash;
+  constructor(source: string | StringValueObject);
+}
+```
+
+**Example:**
+```typescript
+// Compute an MD5 hash from a string or buffer
+const md5 = MD5Hash.from('hello');
+console.log(md5.toString());        // '5d41402abc4b2a76b9719d911017c592'
+console.log(md5.toBase64());        // 'XUEQKvLG6avlckeQEAXGSw=='
+
+// Create from existing hash string
+const existing = new MD5Hash('5d41402abc4b2a76b9719d911017c592');
+
+// Validation
+try {
+  new MD5Hash('invalid');          // Throws InvalidHashError
+} catch (err) {
+  console.error('Invalid MD5 hash');
+}
+```
+
+#### SHA256Hash
+Represents immutable SHA‑256 hashes with validation and utility methods.
+
+```typescript
+class SHA256Hash extends ValueObject<string> {
+  public static isValid(hash: string | StringValueObject): boolean;
+  public static from(buffer: Buffer | string | StringValueObject): SHA256Hash;
+  constructor(source: string | StringValueObject);
+}
+```
+
+**Example:**
+```typescript
+const sha256 = SHA256Hash.from('hello');
+console.log(sha256.toString().length); // 64
+console.log(sha256.toBase64());
+
+try {
+  new SHA256Hash('abc');            // Throws InvalidHashError
+} catch (err) {
+  console.error('Invalid SHA256 hash');
+}
+```
+
+#### SHA512Hash
+Represents immutable SHA‑512 hashes with validation and utility methods.
+
+```typescript
+class SHA512Hash extends ValueObject<string> {
+  public static isValid(hash: string | StringValueObject): boolean;
+  public static from(buffer: Buffer | string | StringValueObject): SHA512Hash;
+  constructor(source: string | StringValueObject);
+}
+```
+
+**Example:**
+```typescript
+const sha512 = SHA512Hash.from('hello');
+console.log(sha512.toString().length); // 128
+console.log(sha512.toBase64());
+
+try {
+  new SHA512Hash('abc');            // Throws InvalidHashError
+} catch (err) {
+  console.error('Invalid SHA512 hash');
+}
+```
+
 ### Hour Value Objects
 
 #### Hour

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@haskou/value-objects",
-  "version": "1.0.3",
+  "version": "1.1.0",
   "main": "src/index.ts",
   "license": "MIT",
   "publishConfig": {
@@ -28,6 +28,7 @@
   "devDependencies": {
     "@types/jest": "^30.0.0",
     "@types/node": "^24.0.13",
+    "@types/uuid": "8",
     "@typescript-eslint/eslint-plugin": "6.20.0",
     "@typescript-eslint/parser": "6.20.0",
     "eslint": "8.57.0",
@@ -45,5 +46,9 @@
     "ts-jest": "^29.4.0",
     "ts-node": "^10.9.2",
     "typescript": "^5.8.3"
+  },
+  "dependencies": {
+    "bson-objectid": "^2.0.4",
+    "uuid": "8"
   }
 }

package/src/errors/InvalidFormatError.ts

@@ -0,0 +1,7 @@
+import { DomainError } from '../errors/DomainError';
+
+export class InvalidFormatError extends DomainError {
+  constructor(value?: string) {
+    super(`Invalid Format Error with value: '${value}'`);
+  }
+}

package/src/errors/InvalidHashError.ts

@@ -0,0 +1,7 @@
+import { DomainError } from './DomainError';
+
+export class InvalidHashError extends DomainError {
+  constructor(type: string, value: string) {
+    super(`Invalid ${type} hash: ${value}`);
+  }
+}

package/src/errors/InvalidLengthError.ts

@@ -0,0 +1,9 @@
+import { DomainError } from './DomainError';
+
+export class InvalidLengthError extends DomainError {
+  constructor(value: unknown, length: number) {
+    super(
+      `Invalid Length Error with value: '${value}' expected length: '${length}'`,
+    );
+  }
+}

package/src/errors/InvalidValueError.ts

@@ -0,0 +1,7 @@
+import { DomainError } from './DomainError';
+
+export class InvalidValueError extends DomainError {
+  constructor(message: string = 'Invalid Value Error', value?: unknown) {
+    super(`${message} with value: '${value}'`);
+  }
+}

package/src/errors/index.ts

@@ -4,6 +4,9 @@ export * from './InvalidColorError';
 export * from './InvalidDayError';
 export * from './InvalidDayFormatError';
 export * from './InvalidHourError';
+export * from './InvalidEmailError';
+export * from './InvalidFormatError';
+export * from './InvalidHashError';
 export * from './InvalidIntegerError';
 export * from './InvalidLatitudeError';
 export * from './InvalidLongitudeError';

package/src/patterns/index.ts

@@ -1,3 +1 @@
 export * from './Assert';
-export * from '../value-objects/NullObject';
-export * from '../value-objects/ValueObject';

package/src/value-objects/hashes/Hash.ts

@@ -0,0 +1,19 @@
+import { NullObject } from '../NullObject';
+import { StringValueObject } from '../StringValueObject';
+import { ValueObject } from '../ValueObject';
+
+export abstract class Hash extends ValueObject<string> {
+  constructor(source: string | StringValueObject) {
+    super(source?.valueOf());
+
+    if (NullObject.isNullObject(this)) {
+      return this;
+    }
+  }
+
+  public toBase64(): StringValueObject {
+    return new StringValueObject(
+      Buffer.from(this.valueOf(), 'hex').toString('base64'),
+    );
+  }
+}

package/src/value-objects/hashes/MD5Hash.ts

@@ -0,0 +1,32 @@
+import crypto from 'node:crypto';
+
+import { InvalidHashError } from '../../errors/InvalidHashError';
+import { assert } from '../../patterns';
+import { NullObject } from '../NullObject';
+import { StringValueObject } from '../StringValueObject';
+import { Hash } from './Hash';
+
+export class MD5Hash extends Hash {
+  public static isValid(hash: string | StringValueObject): boolean {
+    return !!hash.valueOf().match(/^[a-f0-9]{32}$/);
+  }
+
+  public static from(buffer: Buffer | string | StringValueObject): MD5Hash {
+    return new MD5Hash(
+      crypto.createHash('md5').update(buffer.valueOf()).digest('hex'),
+    );
+  }
+
+  constructor(source: string | StringValueObject) {
+    super(source?.valueOf());
+
+    if (NullObject.isNullObject(this)) {
+      return this;
+    }
+
+    assert(
+      MD5Hash.isValid(this.valueOf()),
+      new InvalidHashError('MD5', source.valueOf()),
+    );
+  }
+}

package/src/value-objects/hashes/SHA256Hash.ts

@@ -0,0 +1,38 @@
+import { createHash } from 'crypto';
+
+import { InvalidHashError } from '../../errors/InvalidHashError';
+import { assert } from '../../patterns';
+import { NullObject } from '../NullObject';
+import { StringValueObject } from '../StringValueObject';
+import { ValueObject } from '../ValueObject';
+
+export class SHA256Hash extends ValueObject<string> {
+  public static isValid(hash: string | StringValueObject): boolean {
+    return !!hash.valueOf().match(/^[a-f0-9]{64}$/i);
+  }
+
+  public static from(buffer: Buffer | string | StringValueObject): SHA256Hash {
+    return new SHA256Hash(
+      createHash('sha256').update(buffer.valueOf()).digest('hex'),
+    );
+  }
+
+  constructor(source: string | StringValueObject) {
+    super(source?.valueOf());
+
+    if (NullObject.isNullObject(this)) {
+      return this;
+    }
+
+    assert(
+      SHA256Hash.isValid(this.valueOf()),
+      new InvalidHashError('SHA256', source.valueOf()),
+    );
+  }
+
+  public toBase64(): StringValueObject {
+    return new StringValueObject(
+      Buffer.from(this.valueOf(), 'hex').toString('base64'),
+    );
+  }
+}

package/src/value-objects/hashes/SHA512Hash.ts

@@ -0,0 +1,38 @@
+import { createHash } from 'crypto';
+
+import { InvalidHashError } from '../../errors/InvalidHashError';
+import { assert } from '../../patterns';
+import { NullObject } from '../NullObject';
+import { StringValueObject } from '../StringValueObject';
+import { ValueObject } from '../ValueObject';
+
+export class SHA512Hash extends ValueObject<string> {
+  public static isValid(hash: string | StringValueObject): boolean {
+    return !!hash.valueOf().match(/^[a-f0-9]{128}$/i);
+  }
+
+  public static from(buffer: Buffer | string | StringValueObject): SHA512Hash {
+    return new SHA512Hash(
+      createHash('sha512').update(buffer.valueOf()).digest('hex'),
+    );
+  }
+
+  constructor(source: string | StringValueObject) {
+    super(source?.valueOf());
+
+    if (NullObject.isNullObject(this)) {
+      return this;
+    }
+
+    assert(
+      SHA512Hash.isValid(this.valueOf()),
+      new InvalidHashError('SHA512', source.valueOf()),
+    );
+  }
+
+  public toBase64(): StringValueObject {
+    return new StringValueObject(
+      Buffer.from(this.valueOf(), 'hex').toString('base64'),
+    );
+  }
+}

package/src/value-objects/hashes/index.ts

@@ -0,0 +1,4 @@
+export * from './Hash';
+export * from './MD5Hash';
+export * from './SHA256Hash';
+export * from './SHA512Hash';

package/src/value-objects/ids/ShortId.ts

@@ -0,0 +1,34 @@
+import ObjectId from 'bson-objectid';
+
+import { InvalidFormatError } from '../../errors/InvalidFormatError';
+import { InvalidLengthError } from '../../errors/InvalidLengthError';
+import { assert } from '../../patterns';
+import { NullObject } from '../NullObject';
+import { StringValueObject } from '../StringValueObject';
+import { ValueObject } from '../ValueObject';
+
+export class ShortId extends ValueObject<string> {
+  private static readonly LENGTH = 24;
+  private static readonly PATTERN = new RegExp(`[a-zA-Z0-9]{${this.LENGTH}}$`);
+
+  public static generate(): ShortId {
+    return new ShortId(ObjectId().toHexString());
+  }
+
+  constructor(value: string | StringValueObject) {
+    super(value?.valueOf());
+
+    if (NullObject.isNullObject(this)) {
+      return this;
+    }
+    this.ensureIsShortId(this.value);
+  }
+
+  private ensureIsShortId(value: string): void {
+    assert(
+      value.length === ShortId.LENGTH,
+      new InvalidLengthError(this.value, ShortId.LENGTH),
+    );
+    assert(ShortId.PATTERN.test(value), new InvalidFormatError(this.value));
+  }
+}

package/src/value-objects/ids/UUID.ts

@@ -0,0 +1,34 @@
+import { v4 } from 'uuid';
+
+import { InvalidFormatError } from '../../errors/InvalidFormatError';
+import { InvalidLengthError } from '../../errors/InvalidLengthError';
+import { assert } from '../../patterns';
+import { NullObject } from '../NullObject';
+import { StringValueObject } from '../StringValueObject';
+import { ValueObject } from '../ValueObject';
+
+export class UUID extends ValueObject<string> {
+  private static readonly LENGTH = 36;
+  private static readonly PATTERN = new RegExp(`^[a-z0-9-]{${this.LENGTH}}$`);
+
+  public static generate(): UUID {
+    return new UUID(v4());
+  }
+
+  constructor(value: string | StringValueObject) {
+    super(value?.valueOf());
+
+    if (NullObject.isNullObject(this)) {
+      return this;
+    }
+    this.ensureIsUUID(this.value);
+  }
+
+  private ensureIsUUID(value: string): void {
+    assert(
+      value.length === UUID.LENGTH,
+      new InvalidLengthError(this.value, UUID.LENGTH),
+    );
+    assert(UUID.PATTERN.test(value), new InvalidFormatError(this.value));
+  }
+}

package/src/value-objects/index.ts

@@ -1,4 +1,5 @@
 export * from './coordinates';
+export * from './hashes';
 export * from './time';
 export * from './Color';
 export * from './Email';
@@ -7,3 +8,4 @@ export * from './Integer';
 export * from './NumberValueObject';
 export * from './PositiveNumber';
 export * from './StringValueObject';
+export * from './NullObject';

package/src/value-objects/time/CalendarDay.ts

@@ -1,7 +1,7 @@
 import { InvalidDayError } from '../../errors/InvalidDayError';
 import { InvalidDayFormatError } from '../../errors/InvalidDayFormatError';
-import { ValueObject } from '../../patterns';
 import { assert } from '../../patterns/Assert';
+import { ValueObject } from '../ValueObject';
 import { Day } from './Day';
 import { DayOfWeek } from './DayOfWeek';
 import { Month } from './Month';

package/tests/value-objects/Email.spec.ts

@@ -1,9 +1,5 @@
-import {
-  Email,
-  InvalidEmailError,
-  NullObject,
-  StringValueObject,
-} from '../../src';
+import { Email, InvalidEmailError, StringValueObject } from '../../src';
+import { NullObject } from '../../src/value-objects/NullObject';
 
 describe('Email', () => {
   describe('constructor', () => {