@haskou/value-objects 1.0.1

package/jest.config.ts

@@ -0,0 +1,30 @@
+import type { Config } from '@jest/types';
+
+// Sync object
+const config: Config.InitialOptions = {
+  collectCoverageFrom: ['<rootDir>/src/**/*.ts'],
+  coverageDirectory: '<rootDir>/tests/coverage',
+  coveragePathIgnorePatterns: ['<rootDir>/node_modules/', 'index.ts'],
+  coverageReporters: ['html', 'lcov', 'text'],
+  globals: {
+    'ts-jest': {
+      tsconfig: 'tsconfig.jest.json',
+    },
+  },
+  moduleDirectories: ['node_modules', 'src'],
+  moduleFileExtensions: ['ts', 'tsx', 'js', 'jsx', 'json', 'node'],
+  moduleNameMapper: {
+    '^@app/(.*)$': '<rootDir>/src/$1',
+  },
+  preset: 'ts-jest',
+  roots: ['<rootDir>/src/', '<rootDir>/tests/'],
+  setupFilesAfterEnv: ['<rootDir>/tests/setup.jest.ts'],
+  testEnvironment: 'node',
+  testPathIgnorePatterns: ['<rootDir>/node_modules/', 'index.ts'],
+  transform: {
+    '^.+\\.ts': 'ts-jest',
+  },
+  verbose: true,
+};
+
+export default config;

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "@haskou/value-objects",
+  "version": "1.0.1",
+  "main": "index.js",
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/haskou/value-objects.git"
+  },
+  "bugs": {
+    "url": "https://github.com/haskou/value-objects/issues"
+  },
+  "homepage": "https://github.com/haskou/value-objects#readme",
+  "scripts": {
+    "lint": "eslint ./src --ext .ts",
+    "lint:fix": "eslint ./src --ext .ts --fix",
+    "test": "yarn lint && yarn test:unit",
+    "test:unit": "jest --passWithNoTests --runInBand",
+    "test:coverage": "NODE_ENV=test jest --collect-coverage",
+    "build": "rm -rf dist/ && tsc",
+    "publish:patch": "yarn lint && yarn test:coverage && yarn build && yarn version --patch && yarn publish && push",
+    "publish:minor": "yarn lint && yarn test:coverage && yarn build && yarn version --minor && yarn publish && push",
+    "publish:major": "yarn lint && yarn test:coverage && yarn build && yarn version --major && yarn publish && push"
+  },
+  "devDependencies": {
+    "@types/jest": "^30.0.0",
+    "@types/node": "^24.0.13",
+    "@typescript-eslint/eslint-plugin": "6.20.0",
+    "@typescript-eslint/parser": "6.20.0",
+    "eslint": "8.57.0",
+    "eslint-config-prettier": "^10.1.5",
+    "eslint-plugin-perfectionist": "^4.15.0",
+    "eslint-plugin-prettier": "^5.5.1",
+    "eslint-plugin-sonarjs": "^3.0.4",
+    "eslint-plugin-unused-imports": "^4.1.4",
+    "faker": "^6.6.6",
+    "jest": "^30.0.4",
+    "jest-extended": "^6.0.0",
+    "jest-runner-tsc": "^1.6.0",
+    "prettier": "^3.6.2",
+    "prettier-eslint": "^16.4.2",
+    "ts-jest": "^29.4.0",
+    "ts-node": "^10.9.2",
+    "typescript": "^5.8.3"
+  }
+}

package/src/errors/BaseError.ts

@@ -0,0 +1,20 @@
+export class BaseError extends Error {
+  private readonly isBaseError = true;
+  public static isBaseError(error: unknown): boolean {
+    return !!(error as BaseError).isBaseError;
+  }
+
+  constructor(message: string, prototype: object = BaseError.prototype) {
+    super(message);
+    this.name = this.constructor.name;
+    Object.setPrototypeOf(this, prototype);
+  }
+
+  public toString(): string {
+    return `[${this.name}]: ${this.message}`;
+  }
+
+  public getStack(): string {
+    return this.stack || '';
+  }
+}

package/src/errors/DomainError.ts

@@ -0,0 +1,12 @@
+import { BaseError } from './BaseError';
+
+export class DomainError extends BaseError {
+  protected readonly isDomainError = true;
+  public static isDomainError(error: unknown): boolean {
+    return !!(error as DomainError).isDomainError;
+  }
+
+  constructor(message: string) {
+    super(message, new.target.prototype);
+  }
+}

package/src/errors/InvalidColorError.ts

@@ -0,0 +1,7 @@
+import { DomainError } from './DomainError';
+
+export class InvalidColorError extends DomainError {
+  constructor(value: string) {
+    super(`Invalid color value: ${value}. Must be a valid hex color code.`);
+  }
+}

package/src/errors/InvalidDayError.ts

@@ -0,0 +1,7 @@
+import { DomainError } from './DomainError';
+
+export class InvalidDayError extends DomainError {
+  constructor(invalidDay: unknown) {
+    super(`Invalid day ${String(invalidDay)}`);
+  }
+}

package/src/errors/InvalidDayFormatError.ts

@@ -0,0 +1,7 @@
+import { DomainError } from './DomainError';
+
+export class InvalidDayFormatError extends DomainError {
+  constructor(invalidDate: string) {
+    super(`Invalid day ${invalidDate}. Expected YYYY-MM-DD. `);
+  }
+}

package/src/errors/InvalidEmailError.ts

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

package/src/errors/InvalidHourError.ts

@@ -0,0 +1,7 @@
+import { DomainError } from './DomainError';
+
+export class InvalidHourError extends DomainError {
+  constructor() {
+    super(`Invalid hour`);
+  }
+}

package/src/errors/InvalidIntegerError.ts

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

package/src/errors/InvalidLatitudeError.ts

@@ -0,0 +1,7 @@
+import { DomainError } from './DomainError';
+
+export class InvalidLatitudeError extends DomainError {
+  constructor(value: number) {
+    super(`Invalid latitude: ${value}. Must be between -90 and 90`);
+  }
+}

package/src/errors/InvalidLongitudeError.ts

@@ -0,0 +1,7 @@
+import { DomainError } from './DomainError';
+
+export class InvalidLongitudeError extends DomainError {
+  constructor(value: number) {
+    super(`Invalid longitude: ${value}. Must be between -180 and 180`);
+  }
+}

package/src/errors/InvalidMinutesError.ts

@@ -0,0 +1,7 @@
+import { DomainError } from './DomainError';
+
+export class InvalidMinutesError extends DomainError {
+  constructor() {
+    super(`Invalid minutes`);
+  }
+}

package/src/errors/InvalidNumberError.ts

@@ -0,0 +1,7 @@
+import { DomainError } from './DomainError';
+
+export class InvalidNumberError extends DomainError {
+  constructor(invalidNumber: unknown) {
+    super(`Invalid number ${String(invalidNumber)}`);
+  }
+}

package/src/errors/InvalidPositiveNumberError.ts

@@ -0,0 +1,7 @@
+import { DomainError } from './DomainError';
+
+export class InvalidPositiveNumberError extends DomainError {
+  constructor() {
+    super(`Value must be greater or equal than 0`);
+  }
+}

package/src/errors/InvalidStringLengthError.ts

@@ -0,0 +1,9 @@
+import { DomainError } from './DomainError';
+
+export class InvalidStringLengthError extends DomainError {
+  constructor(value: string, length: number) {
+    super(
+      `String length '${value.length}' exceeds the expected length: '${length}'`,
+    );
+  }
+}

package/src/errors/InvalidTimestampIntervalError.ts

@@ -0,0 +1,10 @@
+import { Timestamp } from '../value-objects/time/Timestamp';
+import { DomainError } from './DomainError';
+
+export class InvalidTimestampIntervalError extends DomainError {
+  constructor(start: Timestamp, end: Timestamp) {
+    super(
+      `Invalid TimestampInterval, start (${start.valueOf()}) must be before the end (${end.valueOf()})`,
+    );
+  }
+}

package/src/errors/NullObjectError.ts

@@ -0,0 +1,8 @@
+import { DomainError } from './DomainError';
+
+export class NullObjectError extends DomainError {
+  constructor(message: string) {
+    super(`[NullObjectError]: ${message} is NullObject`);
+    Object.setPrototypeOf(this, NullObjectError.prototype);
+  }
+}

package/src/errors/ValueNotInEnumError.ts

@@ -0,0 +1,9 @@
+import { DomainError } from './DomainError';
+
+export class ValueNotInEnumError extends DomainError {
+  constructor(value: unknown, enumerate: unknown) {
+    super(
+      `${Object.values(enumerate as object).join(',')} enum does not include value: ${value}`,
+    );
+  }
+}

package/src/errors/index.ts

@@ -0,0 +1,17 @@
+export * from './BaseError';
+export * from './DomainError';
+export * from './InvalidColorError';
+export * from './InvalidDayError';
+export * from './InvalidDayFormatError';
+export * from './InvalidHourError';
+export * from './InvalidIntegerError';
+export * from './InvalidLatitudeError';
+export * from './InvalidLongitudeError';
+export * from './InvalidEmailError';
+export * from './InvalidMinutesError';
+export * from './InvalidNumberError';
+export * from './InvalidPositiveNumberError';
+export * from './InvalidStringLengthError';
+export * from './InvalidTimestampIntervalError';
+export * from './NullObjectError';
+export * from './ValueNotInEnumError';

package/src/index.ts

@@ -0,0 +1,5 @@
+export * from './errors';
+export * from './interfaces';
+export * from './patterns';
+export * from './types';
+export * from './value-objects';

package/src/interfaces/PrimitiveOf.ts

@@ -0,0 +1,5 @@
+import { Primitive } from '../types/Primitive';
+
+export type PrimitiveOf<
+  T extends { toPrimitives(): Primitive | Record<string, Primitive> },
+> = ReturnType<T['toPrimitives']>;

package/src/interfaces/index.ts

@@ -0,0 +1 @@
+export * from './PrimitiveOf';

package/src/patterns/Assert.ts

@@ -0,0 +1,15 @@
+import { BaseError } from '../errors/BaseError';
+import { DomainError } from '../errors/DomainError';
+
+export type Errors = Error | BaseError | DomainError | string;
+
+export function assert(
+  condition: boolean | unknown | undefined,
+  error: string | Errors,
+): void {
+  if (condition) {
+    return;
+  }
+
+  throw typeof error === 'string' ? new DomainError(error) : error;
+}

package/src/patterns/NullObject.ts

@@ -0,0 +1,60 @@
+import { NullObjectError } from '../errors/NullObjectError';
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+type Constructor<T> = abstract new (...args: any[]) => T;
+type NullableObject = Nullable & Record<string, unknown>;
+interface Nullable {
+  isNullObject: boolean;
+  valueOf(): undefined;
+}
+
+export abstract class NullObject {
+  private static setFakeProps<T>(
+    nullObject: NullableObject,
+    klass: Constructor<T>,
+  ): void {
+    const visited = new Set<string>();
+    let proto = klass.prototype;
+
+    while (proto && proto !== Object.prototype) {
+      const props = Object.getOwnPropertyNames(proto);
+
+      for (const prop of props) {
+        if (
+          prop === 'constructor' ||
+          prop === 'isNullObject' ||
+          prop === 'valueOf' ||
+          visited.has(prop)
+        ) {
+          continue;
+        }
+
+        visited.add(prop);
+        // eslint-disable-next-line no-param-reassign
+        nullObject[prop] = () => {
+          throw new NullObjectError(klass.name);
+        };
+      }
+
+      proto = Object.getPrototypeOf(proto);
+    }
+
+    Object.setPrototypeOf(nullObject, NullObject.prototype);
+  }
+
+  public static new<T>(klass: Constructor<T>): T {
+    const nullObject: NullableObject = {
+      isNullObject: true,
+      valueOf: () => {
+        return undefined;
+      },
+    };
+    NullObject.setFakeProps(nullObject, klass);
+
+    return nullObject as T;
+  }
+
+  public static isNullObject(nullable: unknown): boolean {
+    return !!(nullable as NullableObject)?.isNullObject;
+  }
+}

package/src/patterns/ValueObject.ts

@@ -0,0 +1,40 @@
+import { Nullish } from '../types/Nullish';
+import { Primitive } from '../types/Primitive';
+import { NullObject } from './NullObject';
+
+export abstract class ValueObject<T extends Primitive = Primitive> {
+  protected readonly value!: T;
+
+  constructor(value: T | Nullish) {
+    if (this.isNullish(value)) {
+      return NullObject.new(new.target);
+    }
+    this.value = value;
+  }
+
+  private isNullish(value: T | Nullish): value is null | undefined {
+    return value === null || value === undefined;
+  }
+
+  protected clone(value: T): this {
+    return new (this.constructor as new (value: Primitive) => this)(
+      this.isNullish(value) ? this.value : value,
+    ) as this;
+  }
+
+  public isEqual(other: unknown): boolean {
+    return this.value === other?.valueOf();
+  }
+
+  public isNotEqual(other: unknown): boolean {
+    return this.isEqual(other) === false;
+  }
+
+  public valueOf(): T {
+    return this.value;
+  }
+
+  public toString(): string {
+    return this.value!.toString();
+  }
+}

package/src/patterns/index.ts

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

package/src/types/Nullish.ts

@@ -0,0 +1 @@
+export type Nullish = null | undefined;

package/src/types/Primitive.ts

@@ -0,0 +1 @@
+export type Primitive = string | number | boolean | bigint | symbol;

package/src/types/index.ts

@@ -0,0 +1,2 @@
+export * from './Primitive';
+export * from './Nullish';

package/src/value-objects/Color.ts

@@ -0,0 +1,39 @@
+import { InvalidColorError } from '../errors/InvalidColorError';
+import { assert } from '../patterns/Assert';
+import { NullObject } from '../patterns/NullObject';
+import { StringValueObject } from './StringValueObject';
+
+export class Color extends StringValueObject {
+  public static readonly RED = new Color('#FF0000');
+  public static readonly GREEN = new Color('#00FF00');
+  public static readonly BLUE = new Color('#0000FF');
+  public static readonly BLACK = new Color('#000000');
+  public static readonly WHITE = new Color('#FFFFFF');
+  public static readonly YELLOW = new Color('#FFFF00');
+  public static readonly CYAN = new Color('#00FFFF');
+  public static readonly MAGENTA = new Color('#FF00FF');
+  public static readonly ORANGE = new Color('#FFA500');
+  public static readonly PURPLE = new Color('#800080');
+  public static readonly PINK = new Color('#FFC0CB');
+  public static readonly BROWN = new Color('#A52A2A');
+
+  constructor(value: string | StringValueObject) {
+    super(value?.valueOf());
+
+    if (NullObject.isNullObject(this)) {
+      return this;
+    }
+
+    this.ensureIsValidColor();
+  }
+
+  private ensureIsValidColor(): void {
+    const hexColorPattern = /^#([0-9A-Fa-f]{3}|[0-9A-Fa-f]{6})$/;
+
+    assert(hexColorPattern.test(this.value), new InvalidColorError(this.value));
+  }
+
+  public isEqual(other: Color): boolean {
+    return this.value.toLowerCase() === other?.toString().toLowerCase();
+  }
+}

package/src/value-objects/Email.ts

@@ -0,0 +1,23 @@
+import { InvalidEmailError } from '../errors/InvalidEmailError';
+import { assert } from '../patterns/Assert';
+import { NullObject } from '../patterns/NullObject';
+import { StringValueObject } from './StringValueObject';
+
+export class Email extends StringValueObject {
+  constructor(value: string | StringValueObject) {
+    super(value?.valueOf());
+
+    if (NullObject.isNullObject(this)) {
+      return this;
+    }
+
+    this.ensureIsValidEmail(this.value);
+  }
+
+  private ensureIsValidEmail(value: string): void {
+    assert(
+      new RegExp(/^[\w+\-.]+@(?:[\w-]+\.)+[a-zA-Z]{2,13}$/).test(value),
+      new InvalidEmailError(value),
+    );
+  }
+}

package/src/value-objects/Enum.ts

@@ -0,0 +1,31 @@
+import { ValueNotInEnumError } from '../errors/ValueNotInEnumError';
+import { assert } from '../patterns/Assert';
+import { NullObject } from '../patterns/NullObject';
+import { ValueObject } from '../patterns/ValueObject';
+import { Primitive } from '../types/Primitive';
+
+export abstract class Enum<
+  T extends Primitive = Primitive,
+> extends ValueObject<T> {
+  constructor(protected readonly value: T) {
+    super(value);
+
+    if (NullObject.isNullObject(this)) {
+      return this;
+    }
+
+    this.ensureIsValidValue();
+  }
+
+  private ensureIsValidValue(): void {
+    const isValueInEnum = this.getValues().some((enumValue) =>
+      this.isEqual(enumValue),
+    );
+    assert(
+      isValueInEnum,
+      new ValueNotInEnumError(this.valueOf(), this.getValues()),
+    );
+  }
+
+  public abstract getValues(): T[];
+}

package/src/value-objects/Integer.ts

@@ -0,0 +1,22 @@
+import { InvalidIntegerError } from '../errors/InvalidIntegerError';
+import { assert } from '../patterns/Assert';
+import { NullObject } from '../patterns/NullObject';
+import { NumberValueObject } from './NumberValueObject';
+
+export class Integer extends NumberValueObject {
+  constructor(value: number | NumberValueObject) {
+    super(value?.valueOf());
+
+    if (NullObject.isNullObject(this)) {
+      return this;
+    }
+    this.ensureIsInteger();
+  }
+
+  private ensureIsInteger(): void {
+    assert(
+      this.value.valueOf() % 1 === 0,
+      new InvalidIntegerError(this.value.valueOf()),
+    );
+  }
+}

package/src/value-objects/NumberValueObject.ts

@@ -0,0 +1,56 @@
+import { InvalidNumberError } from '../errors/InvalidNumberError';
+import { assert } from '../patterns/Assert';
+import { NullObject } from '../patterns/NullObject';
+import { ValueObject } from '../patterns/ValueObject';
+
+export class NumberValueObject extends ValueObject<number> {
+  constructor(value: number | NumberValueObject) {
+    super(value?.valueOf());
+
+    if (NullObject.isNullObject(this)) {
+      return this;
+    }
+
+    assert(this.isValidNumber(this.value), new InvalidNumberError(this.value));
+  }
+
+  private isValidNumber(value: number): boolean {
+    return !isNaN(value.valueOf());
+  }
+
+  public isZero(): boolean {
+    return this.value === 0;
+  }
+
+  public isGreaterThan(other: number | NumberValueObject): boolean {
+    return this.value > other.valueOf();
+  }
+
+  public isGreaterOrEqualThan(other: number | NumberValueObject): boolean {
+    return this.value >= other.valueOf();
+  }
+
+  public isLessThan(other: number | NumberValueObject): boolean {
+    return this.value < other.valueOf();
+  }
+
+  public isLessOrEqualThan(other: number | NumberValueObject): boolean {
+    return this.value <= other.valueOf();
+  }
+
+  public add(other: number | NumberValueObject): NumberValueObject {
+    return this.clone(this.value + other.valueOf());
+  }
+
+  public subtract(other: number | NumberValueObject): NumberValueObject {
+    return this.clone(this.value - other.valueOf());
+  }
+
+  public multiply(other: number | NumberValueObject): NumberValueObject {
+    return this.clone(this.value * other.valueOf());
+  }
+
+  public divide(other: number | NumberValueObject): NumberValueObject {
+    return this.clone(this.value / other.valueOf());
+  }
+}

package/src/value-objects/PositiveNumber.ts

@@ -0,0 +1,20 @@
+import { InvalidPositiveNumberError } from '../errors/InvalidPositiveNumberError';
+import { assert } from '../patterns/Assert';
+import { NullObject } from '../patterns/NullObject';
+import { NumberValueObject } from './NumberValueObject';
+
+export class PositiveNumber extends NumberValueObject {
+  constructor(value: number | NumberValueObject) {
+    super(value?.valueOf());
+
+    if (NullObject.isNullObject(this)) {
+      return this;
+    }
+
+    this.ensureIsPositive(this.value);
+  }
+
+  private ensureIsPositive(value: number): void {
+    assert(value >= 0, new InvalidPositiveNumberError());
+  }
+}

package/src/value-objects/StringValueObject.ts

@@ -0,0 +1,27 @@
+import { InvalidStringLengthError } from '../errors/InvalidStringLengthError';
+import { assert } from '../patterns/Assert';
+import { NullObject } from '../patterns/NullObject';
+import { ValueObject } from '../patterns/ValueObject';
+
+export class StringValueObject extends ValueObject<string> {
+  constructor(value: string | StringValueObject, maxLength: number = 512) {
+    super(value?.valueOf());
+
+    if (NullObject.isNullObject(this)) {
+      return this;
+    }
+
+    this.ensureDoesNotExceedsMaxLength(maxLength);
+  }
+
+  private ensureDoesNotExceedsMaxLength(maxLength: number): void {
+    assert(
+      this.value.length <= maxLength,
+      new InvalidStringLengthError(this.value, maxLength),
+    );
+  }
+
+  public isEmpty(): boolean {
+    return !this.value;
+  }
+}