wsp-ms-core 1.0.0

package/README.md

@@ -0,0 +1,29 @@
+# README #
+
+This README would normally document whatever steps are necessary to get your application up and running.
+
+### What is this repository for? ###
+
+* Quick summary
+* Version
+* [Learn Markdown](https://bitbucket.org/tutorials/markdowndemo)
+
+### How do I get set up? ###
+
+* Summary of set up
+* Configuration
+* Dependencies
+* Database configuration
+* How to run tests
+* Deployment instructions
+
+### Contribution guidelines ###
+
+* Writing tests
+* Code review
+* Other guidelines
+
+### Who do I talk to? ###
+
+* Repo owner or admin
+* Other community or team contact

package/jest.config.cjs

@@ -0,0 +1,9 @@
+module.exports = {
+    preset: 'ts-jest',
+    moduleNameMapper: {
+        '^@domain/(.*)$': '<rootDir>/src/domain/$1',
+        '^@application/(.*)$': '<rootDir>/src/application/$1',
+        '^@infrastructure/(.*)$': '<rootDir>/src/infrastructure/$1',
+        '^@utils/(.*)$': '<rootDir>/src/utils/$1',
+    },
+};

package/package.json

@@ -0,0 +1,71 @@
+{
+  "name": "wsp-ms-core",
+  "version": "1.0.0",
+  "description": "",
+  "author": "Wonasports",
+  "license": "ISC",
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs",
+      "types": "./dist/index.d.ts"
+    },
+    "./infrastructure/mysql": {
+      "import": "./dist/infrastructure/mysql/index.js",
+      "require": "./dist/infrastructure/mysql/index.cjs",
+      "types": "./dist/infrastructure/mysql/index.d.ts"
+    },
+    "./infrastructure/kafka": {
+      "import": "./dist/infrastructure/kafka/index.js",
+      "require": "./dist/infrastructure/kafka/index.cjs",
+      "types": "./dist/infrastructure/kafka/index.d.ts"
+    },
+    "./package.json": "./package.json"
+  },
+  "peerDependencies": {
+    "kafkajs": "^2.2.4",
+    "mysql2": "^3.10.0"
+  },
+  "peerDependenciesMeta": {
+    "mysql2": {
+      "optional": true
+    },
+    "kafkajs": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@types/jest": "^30.0.0",
+    "@types/luxon": "^3.6.2",
+    "@types/node": "^20.10.0",
+    "@typescript-eslint/eslint-plugin": "^6.13.0",
+    "@typescript-eslint/parser": "^6.13.0",
+    "eslint": "^8.56.0",
+    "jest": "^29.7.0",
+    "rimraf": "^5.0.5",
+    "ts-jest": "^29.1.1",
+    "tsconfig-paths": "^4.2.0",
+    "tsup": "^7.2.0",
+    "typescript": "^5.4.0"
+  },
+  "dependencies": {
+    "esbuild-plugin-alias": "^0.2.1",
+    "kafkajs": "^2.2.4",
+    "luxon": "^3.4.4",
+    "mysql2": "^3.10.0"
+  },
+  "engines": {
+    "node": ">=20.0"
+  },
+  "scripts": {
+    "clean": "rimraf dist",
+    "build": "npm run clean && tsup src/index.ts --dts --format esm,cjs --out-dir dist",
+    "lint": "eslint \"src/**/*.ts\"",
+    "test": "jest",
+    "prepublishOnly": "npm run build && npm run test"
+  }
+}

package/src/application/contracts/EventBus.ts

@@ -0,0 +1,7 @@
+import {DomainEvent} from "@domain/contracts/DomainEvent";
+
+export interface EventBus {
+
+    publish(event: DomainEvent): Promise<void>;
+
+}

package/src/application/contracts/EventBusRepository.ts

@@ -0,0 +1,10 @@
+import {DomainEvent} from "@domain/contracts/DomainEvent";
+
+export interface EventBusRepository {
+
+    save(event: DomainEvent): Promise<void>;
+    listPending(limit: number): Promise<DomainEvent[]>;
+    markProcessed(id: number): Promise<void>;
+    incrementRetries(id: number): Promise<void>;
+
+}

package/src/domain/contracts/DomainEntity.ts

@@ -0,0 +1,58 @@
+import {UUID} from "@domain/value-objects/UUID";
+import {DateTime} from "@domain/value-objects/DateTime";
+
+export abstract class DomainEntity<T extends Record<string, string | number | boolean>> {
+
+    public readonly uuid: UUID;
+
+    private readonly _createdAt: DateTime;
+    private _updatedAt: DateTime;
+    private _deletedAt?: DateTime;
+
+    protected readonly props: T;
+
+    protected constructor(
+        uuid: UUID,
+        props: T,
+        audit?: { createdAt?: DateTime; updatedAt?: DateTime; deletedAt?: DateTime },
+    ) {
+        this.uuid = uuid;
+        this.props = props;
+
+        this._createdAt = audit?.createdAt ?? DateTime.create();
+        this._updatedAt = audit?.updatedAt ?? this.createdAt;
+        this._deletedAt = audit?.deletedAt;
+    }
+
+    protected touch(): void {
+        this._updatedAt = DateTime.create();
+    }
+
+    public get createdAt(): DateTime {
+        return this._createdAt;
+    }
+
+    public get updatedAt(): DateTime {
+        return this._updatedAt;
+    }
+
+    public get deletedAt(): DateTime | undefined {
+        return this._deletedAt;
+    }
+
+    public get isDeleted(): boolean {
+        return Boolean(this._deletedAt);
+    }
+
+    public abstract equals(entity?: DomainEntity<T>): boolean;
+
+    public softDelete(): void {
+        if (!this._deletedAt) {
+            this._deletedAt = DateTime.create();
+            this.touch();
+        }
+    }
+
+    public abstract toPrimitives(): Record<string, unknown>;
+
+}

package/src/domain/contracts/DomainError.ts

@@ -0,0 +1,9 @@
+export abstract class DomainError extends Error {
+
+    public readonly type: string;
+
+    protected constructor(type: string, message = '') {
+        super(message);
+        this.type = type;
+    }
+}

package/src/domain/contracts/DomainEvent.ts

@@ -0,0 +1,22 @@
+import {DateTime} from "../value-objects/DateTime";
+
+export abstract class DomainEvent<T = unknown> {
+
+    readonly type: string;
+    private readonly _occurredAt: DateTime;
+    private readonly _payload: T;
+
+    protected constructor(payload: T) {
+        this._payload = payload;
+        this._occurredAt = DateTime.create();
+    }
+
+    get payload(): T {
+        return this._payload;
+    }
+
+    get occurredAt(): DateTime {
+        return this._occurredAt;
+    }
+
+}

package/src/domain/contracts/ValueObject.ts

@@ -0,0 +1,26 @@
+
+export abstract class ValueObject<TPrimitive = unknown> {
+
+    protected readonly _value: TPrimitive;
+
+    protected constructor(value: TPrimitive) {
+        this.validate(value);
+        this._value = Object.freeze(value);
+    }
+
+    protected abstract validate(value: TPrimitive): void;
+
+    public get value(): TPrimitive {
+        return this._value;
+    }
+
+    public toString(): string {
+        return String(this._value);
+    }
+
+    public equals(vo?: ValueObject<TPrimitive> | null): boolean {
+        if (vo === null || vo === undefined) return false;
+        if (vo.constructor !== this.constructor) return false;
+        return vo.value === this._value;
+    }
+}

package/src/domain/errors/FatalError.ts

@@ -0,0 +1,9 @@
+import {DomainError} from "@domain/contracts/DomainError";
+
+export class FatalError extends DomainError {
+
+    public constructor(type: string, message: string = '') {
+        super(type, message);
+    }
+
+}

package/src/domain/errors/InternalError.ts

@@ -0,0 +1,9 @@
+import {DomainError} from "@domain/contracts/DomainError";
+
+export class InternalError extends DomainError {
+
+    public constructor(type: string, message: string = '') {
+        super(type, message);
+    }
+
+}

package/src/domain/errors/UsageError.ts

@@ -0,0 +1,12 @@
+import {DomainError} from "@domain/contracts/DomainError";
+
+export class UsageError extends DomainError {
+
+    public readonly vars: Record<string, any>;
+
+    public constructor(type: string, vars: Record<string, any> = {}) {
+        super(type);
+        this.vars = vars;
+    }
+
+}

package/src/domain/value-objects/Currency.ts

@@ -0,0 +1,68 @@
+import { ValueObject } from '@domain/contracts/ValueObject';
+
+export class Currency extends ValueObject<string> {
+
+    public static readonly ALPHA_REGEX = /^[A-Z]{3}$/u;
+    public static readonly NUM_REGEX   = /^\d{3}$/u;
+
+    private static readonly ALPHA_TO_NUM: Record<string, number> = {
+        USD: 840,
+        EUR: 978,
+        UYU: 858,
+        ARS: 32,
+        BRL: 986,
+    };
+
+    private static readonly NUM_TO_ALPHA: Record<number, string> =
+        Object.entries(Currency.ALPHA_TO_NUM).reduce(
+            (acc, [alpha, num]) => {
+                acc[num as number] = alpha;
+                return acc;
+            },
+            {} as Record<number, string>,
+        );
+
+    public static readonly USD = new Currency('USD');
+    public static readonly EUR = new Currency('EUR');
+    public static readonly UYU = new Currency('UYU');
+    public static readonly ARS = new Currency('ARS');
+    public static readonly BRL = new Currency('BRL');
+
+    public readonly numeric: number;
+
+    private constructor(alpha: string) {
+        super(alpha.toUpperCase().trim());
+        this.numeric = Currency.ALPHA_TO_NUM[this.value];
+    }
+
+    protected validate(alpha: string): void {
+        const code = alpha.toUpperCase().trim();
+        if (!Currency.ALPHA_REGEX.test(code)) {
+            throw new Error(`Currency code <${alpha}> is not a valid ISO‑4217 alpha value`);
+        }
+        if (!(code in Currency.ALPHA_TO_NUM)) {
+            throw new Error(`Currency <${code}> is not supported`);
+        }
+    }
+
+    public static create(raw: string | number): Currency {
+        if (typeof raw === 'number' || Currency.NUM_REGEX.test(raw)) {
+            const num = Number(raw);
+            const alpha = Currency.NUM_TO_ALPHA[num];
+            if (!alpha) {
+                throw new Error(`Numeric currency <${raw}> is not supported`);
+            }
+            return new Currency(alpha);
+        }
+        return new Currency(String(raw));
+    }
+
+    public static isValid(raw: string | number): boolean {
+        try {
+            Currency.create(raw);
+            return true;
+        } catch {
+            return false;
+        }
+    }
+}

package/src/domain/value-objects/DateTime.ts

@@ -0,0 +1,132 @@
+import {DateTime as LuxonDateTime} from 'luxon';
+import {ValueObject} from "@domain/contracts/ValueObject";
+
+
+export class DateTime extends ValueObject<string> {
+
+    public static readonly DEFAULT_FORMAT: string = 'yyyy-MM-dd HH:mm:ss';
+
+    private readonly _dt: LuxonDateTime;
+
+    private static fromLuxon(dt: LuxonDateTime): DateTime {
+        return new DateTime(DateTime.toUtcFormat(dt));
+    }
+
+    private static toUtcFormat(dt: LuxonDateTime): string {
+        return dt.setZone('utc').toFormat(DateTime.DEFAULT_FORMAT);
+    }
+
+    private constructor(value: string) {
+        super(value);
+        this._dt = LuxonDateTime.fromFormat(value, DateTime.DEFAULT_FORMAT, { zone: 'utc' });
+    }
+
+    protected validate(value: string): void {
+        const q = LuxonDateTime.fromFormat(value, DateTime.DEFAULT_FORMAT, { zone: 'utc' });
+        if (!q.isValid) {
+            throw new Error(`Invalid DateTime: ${q.invalidExplanation}`);
+        }
+    }
+
+    public plusYears(years: number): DateTime {
+        return DateTime.fromLuxon(this._dt.plus({years}));
+    }
+
+    public plusMonths(months: number): DateTime {
+        return DateTime.fromLuxon(this._dt.plus({months}));
+    }
+
+    public plusDays(days: number): DateTime {
+        return DateTime.fromLuxon(this._dt.plus({days}));
+    }
+
+    public plusHours(hours: number): DateTime {
+        return DateTime.fromLuxon(this._dt.plus({hours}));
+    }
+
+    public plusMinutes(minutes: number): DateTime {
+        return DateTime.fromLuxon(this._dt.plus({minutes}));
+    }
+
+    public plusSeconds(seconds: number): DateTime {
+        return DateTime.fromLuxon(this._dt.plus({seconds}));
+    }
+
+    public minusYears(years: number): DateTime {
+        return DateTime.fromLuxon(this._dt.minus({years}));
+    }
+
+    public minusMonths(months: number): DateTime {
+        return DateTime.fromLuxon(this._dt.minus({months}));
+    }
+
+    public minusDays(days: number): DateTime {
+        return DateTime.fromLuxon(this._dt.minus({days}));
+    }
+
+    public minusHours(hours: number): DateTime {
+        return DateTime.fromLuxon(this._dt.minus({hours}));
+    }
+
+    public minusMinutes(minutes: number): DateTime {
+        return DateTime.fromLuxon(this._dt.minus({minutes}));
+    }
+
+    public minusSeconds(seconds: number): DateTime {
+        return DateTime.fromLuxon(this._dt.minus({seconds}));
+    }
+
+    public get year(): number {
+        return this._dt.year;
+    }
+
+    public get month(): number {
+        return this._dt.month;
+    }
+
+    public get day(): number {
+        return this._dt.day;
+    }
+
+    public get hour(): number {
+        return this._dt.hour;
+    }
+
+    public get minute(): number {
+        return this._dt.minute;
+    }
+
+    public get second(): number {
+        return this._dt.second;
+    }
+
+    public getMonthName(locale: string = 'en'): string {
+        return this._dt.setLocale(locale).toFormat('LLLL');
+    }
+
+    public getWeekdayName(locale: string = 'en'): string {
+        return this._dt.setLocale(locale).toFormat('cccc');
+    }
+
+    public static create(input?: string | number): DateTime {
+        if (input === undefined) {
+            return new DateTime(DateTime.toUtcFormat(LuxonDateTime.now()));
+        }
+
+        /* ① timestamp */
+        if (typeof input === 'number') {
+            return new DateTime(
+                DateTime.toUtcFormat(LuxonDateTime.fromMillis(input, { zone: 'utc' })),
+            );
+        }
+
+        /* ② ISO string o ya formateado */
+        const iso = LuxonDateTime.fromISO(input, { zone: 'utc' });
+        if (iso.isValid) {
+            return new DateTime(DateTime.toUtcFormat(iso));
+        }
+
+        /* ③ se asume que viene en formato DEFAULT_FORMAT (UTC) */
+        return new DateTime(input);
+    }
+}

package/src/domain/value-objects/Email.ts

@@ -0,0 +1,24 @@
+import { ValueObject } from '@domain/contracts/ValueObject';
+
+export class Email extends ValueObject<string> {
+
+    public static readonly REGEX: RegExp = /^[^\s@]+@[^\s@]+\.[^\s@]+$/u;
+
+    private constructor(email: string) {
+        super(email.trim());
+    }
+
+    protected validate(value: string): void {
+        if (!Email.REGEX.test(value)) {
+            throw new Error(`Email <${value}> is not a valid address`);
+        }
+    }
+
+    public static create(raw: string): Email {
+        return new Email(raw);
+    }
+
+    public static isValid(raw: string): boolean {
+        return Email.REGEX.test(raw.trim());
+    }
+}

package/src/domain/value-objects/Language.ts

@@ -0,0 +1,94 @@
+import { ValueObject } from '@domain/contracts/ValueObject';
+
+export class Language extends ValueObject<string> {
+
+    public static readonly SUPPORTED: readonly string[] = [
+        'es',
+        'en',
+        'en-us',
+        'en-gb',
+        'en-au',
+        'en-ca',
+        'en-nz',
+        'en-ie',
+        'en-za',
+        'en-jm',
+        'en-bz',
+        'en-tt',
+        'pt-br',
+        'pt',
+        'es',
+        'es-ar',
+        'es-gt',
+        'es-cr',
+        'es-pa',
+        'es-do',
+        'es-mx',
+        'es-ve',
+        'es-co',
+        'es-pe',
+        'es-ec',
+        'es-cl',
+        'es-uy',
+        'es-py',
+        'es-bo',
+        'es-sv',
+        'es-hn',
+        'es-ni',
+        'es-pr',
+    ] as const;
+
+    public static readonly DEFAULT: Language                 = new Language('es');
+    public static readonly ENGLISH: Language                 = new Language('en');
+    public static readonly ENGLISH_UNITED_STATES: Language   = new Language('en-us');
+    public static readonly ENGLISH_UNITED_KINGDOM: Language  = new Language('en-gb');
+    public static readonly ENGLISH_AUSTRALIA: Language       = new Language('en-au');
+    public static readonly ENGLISH_CANADA: Language           = new Language('en-ca');
+    public static readonly ENGLISH_NEW_ZEALAND: Language     = new Language('en-nz');
+    public static readonly ENGLISH_IRELAND: Language         = new Language('en-ie');
+    public static readonly ENGLISH_SOUTH_AFRICA: Language    = new Language('en-za');
+    public static readonly ENGLISH_JAMAICA: Language         = new Language('en-jm');
+    public static readonly ENGLISH_BELIZE: Language          = new Language('en-bz');
+    public static readonly ENGLISH_TRINIDAD: Language        = new Language('en-tt');
+    public static readonly PORTUGUESE_BRAZIL: Language       = new Language('pt-br');
+    public static readonly PORTUGUESE_PORTUGAL: Language     = new Language('pt');
+    public static readonly SPANISH: Language                 = new Language('es');
+    public static readonly SPANISH_ARGENTINA: Language       = new Language('es-ar');
+    public static readonly SPANISH_GUATEMALA: Language       = new Language('es-gt');
+    public static readonly SPANISH_COSTA_RICA: Language      = new Language('es-cr');
+    public static readonly SPANISH_PANAMA: Language          = new Language('es-pa');
+    public static readonly SPANISH_REPUBLICA_DOMINICANA: Language = new Language('es-do');
+    public static readonly SPANISH_MEXICO: Language          = new Language('es-mx');
+    public static readonly SPANISH_VENEZUELA: Language       = new Language('es-ve');
+    public static readonly SPANISH_COLOMBIA: Language        = new Language('es-co');
+    public static readonly SPANISH_PERU: Language            = new Language('es-pe');
+    public static readonly SPANISH_ECUADOR: Language         = new Language('es-ec');
+    public static readonly SPANISH_CHILE: Language           = new Language('es-cl');
+    public static readonly SPANISH_URUGUAY: Language         = new Language('es-uy');
+    public static readonly SPANISH_PARAGUAY: Language        = new Language('es-py');
+    public static readonly SPANISH_BOLIVIA: Language         = new Language('es-bo');
+    public static readonly SPANISH_EL_SALVADOR: Language     = new Language('es-sv');
+    public static readonly SPANISH_HONDURAS: Language        = new Language('es-hn');
+    public static readonly SPANISH_NICARAGUA: Language       = new Language('es-ni');
+    public static readonly SPANISH_PUERTO_RICO: Language     = new Language('es-pr');
+
+    private constructor(code: string) {
+        super(code.trim().toLowerCase());
+    }
+
+    protected validate(value: string): void {
+        if (!Language.SUPPORTED.includes(value)) {
+            throw new Error(`Language <${value}> is not supported`);
+        }
+    }
+
+    public base(): string {
+        return this.value.split('-')[0];
+    }
+
+    public static create(raw: string): Language {
+        const normalized = raw.trim().toLowerCase().replace('_', '-');
+        return new Language(normalized);
+    }
+
+}

package/src/domain/value-objects/Price.ts

@@ -0,0 +1,54 @@
+import { ValueObject } from '@domain/contracts/ValueObject';
+import { Currency }   from '@domain/value-objects/Currency';
+
+export class Price extends ValueObject<{ amount: number; currency: Currency }> {
+
+    public static readonly MIN_AMOUNT: number = -1000000;
+
+    public readonly amount: number;
+    public readonly currency: Currency;
+
+    private constructor(amount: number, currency: Currency) {
+        super({ amount, currency });
+        this.amount   = amount;
+        this.currency = currency;
+    }
+
+    protected validate(props: { amount: number; currency: Currency }): void {
+        const { amount, currency } = props;
+
+        if (typeof amount !== 'number' || Number.isNaN(amount) || !Number.isFinite(amount)) {
+            throw new Error(`Price amount <${amount}> is not a valid number`);
+        }
+        if (amount < Price.MIN_AMOUNT) {
+            throw new Error(`Price amount <${amount}> must be ≥ ${Price.MIN_AMOUNT}`);
+        }
+    }
+
+    public equals(other?: Price | null): boolean {
+        if (!other) return false;
+        return this.amount === other.amount && this.currency.equals(other.currency);
+    }
+
+    private assertSameCurrency(other: Price): void {
+        if (!this.currency.equals(other.currency)) {
+            throw new Error('Cannot operate on Price objects with different currencies');
+        }
+    }
+
+    public add(other: Price): Price {
+        this.assertSameCurrency(other);
+        return Price.create(this.amount + other.amount, this.currency);
+    }
+
+    public subtract(other: Price): Price {
+        this.assertSameCurrency(other);
+        return Price.create(this.amount - other.amount, this.currency);
+    }
+
+    public static create(amount: number, currency: Currency | string | number): Price {
+        const cur = currency instanceof Currency ? currency : Currency.create(currency);
+        return new Price(amount, cur);
+    }
+
+}

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

@@ -0,0 +1,23 @@
+import {ValueObject} from "@domain/contracts/ValueObject";
+
+export class UUID extends ValueObject<string> {
+
+    private constructor(value: string) {
+        super(value);
+    }
+
+    protected validate(uuid: string) {
+        if (!UUID.isValid(uuid)) {
+            throw new Error(`Invalid uuid ${uuid}`);
+        }
+    }
+
+    public static create(uuid?: string): UUID {
+        return new UUID(uuid ?? crypto.randomUUID());
+    }
+
+    public static isValid(uuid: string): boolean {
+        return /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i.test(uuid);
+    }
+
+}