@emkodev/emkore 1.0.3

package/src/common/type/money.class.ts

@@ -0,0 +1,384 @@
+/**
+ * Cents - Monetary amount stored as an integer in minor units (cents).
+ *
+ * All monetary values MUST be stored in cents (or equivalent minor units) to avoid
+ * floating-point precision errors in calculations (e.g., 0.1 + 0.2 = 0.30000000000004).
+ *
+ * Use this type in DTOs, value objects, and anywhere monetary amounts are stored or transmitted.
+ *
+ * @example USD: 14999 cents = $149.99
+ * @example EUR: 9999 cents = €99.99
+ * @example JPY: 1000000 cents = ¥10,000 (note: JPY has no minor units, but we store uniformly)
+ *
+ * @see {@link Money} - For type-safe monetary calculations with currency support
+ */
+export type Cents = number;
+
+/**
+ * Money - Type-safe monetary value with currency support.
+ *
+ * Immutable value object for monetary calculations that:
+ * - Stores amounts in cents (minor units) to avoid floating-point errors
+ * - Enforces currency consistency in arithmetic operations
+ * - Provides locale-aware formatting with Intl.NumberFormat
+ * - Supports all common monetary operations (add, subtract, multiply, divide)
+ * - Validates currency mixing (throws error on USD + EUR operations)
+ * - Returns new instances for all operations (immutability)
+ *
+ * **Architecture:**
+ * - DTOs store raw cents as `Cents` type (number)
+ * - Entities use Money class for business logic
+ * - Frontend receives DTOs, converts to Money for calculations
+ *
+ * **Critical Rules:**
+ * - ALWAYS store monetary values in cents, never in dollars/euros/etc
+ * - NEVER use floating-point numbers for money (0.1 + 0.2 ≠ 0.3)
+ * - ALWAYS explicitly specify currency - no defaults to prevent bugs
+ * - ALWAYS use Money class for calculations involving currency
+ * - DTOs use `Cents` type, business logic uses `Money` class
+ *
+ * @example Basic usage
+ * ```ts
+ * const price = Money.fromCents(14999, "USD"); // $149.99
+ * const tax = price.multiply(0.08);            // 8% tax
+ * const total = price.add(tax);                // $161.99
+ * console.log(total.format());                 // "$161.99"
+ * console.log(total.cents);                    // 16199
+ * ```
+ *
+ * @example Currency safety
+ * ```ts
+ * const usd = Money.fromCents(100, "USD");
+ * const eur = Money.fromCents(100, "EUR");
+ * usd.add(eur); // ❌ Throws: "Cannot operate on Money with different currencies"
+ * ```
+ *
+ * @example Multi-currency formatting
+ * ```ts
+ * const price = Money.fromCents(14999, "EUR");
+ * price.format("en-US"); // "€149.99"
+ * price.format("de-DE"); // "149,99 €"
+ * price.formatNumber();  // "149.99" (no symbol)
+ * ```
+ *
+ * @example Discount calculations
+ * ```ts
+ * const price = Money.fromCents(10000, "USD");     // $100.00
+ * const discount = price.multiply(0.2);            // 20% off = $20.00
+ * const final = price.subtract(discount);          // $80.00
+ * ```
+ *
+ * @see {@link Cents} - Type alias for raw cent values in DTOs
+ */
+export class Money {
+  private readonly _value: Cents;
+  private readonly _currency: string;
+
+  /**
+   * Create Money from cents (minor units).
+   *
+   * Currency is REQUIRED to prevent accidental currency mixing bugs.
+   * This forces explicit declaration of currency on every Money instance.
+   *
+   * @param cents - Amount in cents (integer, will be rounded if fractional)
+   * @param currency - ISO 4217 currency code (REQUIRED - e.g., "USD", "EUR", "JPY")
+   * @throws {Error} If cents is null or undefined
+   * @throws {Error} If currency is empty or not a string
+   *
+   * @example
+   * ```ts
+   * const usd = new Money(14999, "USD"); // $149.99
+   * const euro = new Money(9999, "EUR"); // €99.99
+   * const yen = new Money(1000000, "JPY"); // ¥10,000
+   * ```
+   */
+  constructor(cents: Cents | null | undefined, currency: string) {
+    if (cents == null) {
+      throw new Error("Money value cannot be null - amount is required");
+    }
+    if (!currency || typeof currency !== "string") {
+      throw new Error("Currency must be a non-empty string (ISO 4217 code)");
+    }
+    this._value = Math.round(cents); // Ensure integer cents
+    this._currency = currency.toUpperCase();
+  }
+
+  /**
+   * Create Money from cents (minor units).
+   * Alias for constructor for clarity.
+   *
+   * @param cents - Amount in cents (integer)
+   * @param currency - ISO 4217 currency code (REQUIRED)
+   * @returns Money instance
+   *
+   * @example
+   * ```ts
+   * const usd = Money.fromCents(14999, "USD"); // $149.99
+   * const eur = Money.fromCents(9999, "EUR");  // €99.99
+   * ```
+   */
+  static fromCents(cents: Cents, currency: string): Money {
+    return new Money(cents, currency);
+  }
+
+  /**
+   * Create Money from major units (dollars, euros, etc.).
+   *
+   * WARNING: Subject to floating-point precision issues.
+   * Prefer fromCents when possible.
+   *
+   * @param amount - Amount in major units (e.g., 149.99 for $149.99)
+   * @param currency - ISO 4217 currency code (REQUIRED)
+   * @returns Money instance
+   *
+   * @example
+   * ```ts
+   * const price = Money.fromMajorUnits(149.99, "USD"); // 14999 cents = $149.99
+   * const euro = Money.fromMajorUnits(99.50, "EUR");   // 9950 cents = €99.50
+   * ```
+   */
+  static fromMajorUnits(amount: number, currency: string): Money {
+    return new Money(Math.round(amount * 100), currency);
+  }
+
+  /**
+   * Create zero Money in the given currency.
+   *
+   * @param currency - ISO 4217 currency code (REQUIRED)
+   * @returns Money instance with zero value
+   *
+   * @example
+   * ```ts
+   * const usdTotal = Money.zero("USD"); // $0.00
+   * const eurTotal = Money.zero("EUR"); // €0.00
+   * ```
+   */
+  static zero(currency: string): Money {
+    return new Money(0, currency);
+  }
+
+  /**
+   * Add two Money amounts.
+   * Currencies must match.
+   *
+   * @throws Error if currencies don't match
+   * @example
+   * ```ts
+   * const a = Money.fromCents(100, "USD");
+   * const b = Money.fromCents(50, "USD");
+   * const total = a.add(b); // 150 cents
+   * ```
+   */
+  add(other: Money): Money {
+    this._validateSameCurrency(other);
+    return new Money(this._value + other._value, this._currency);
+  }
+
+  /**
+   * Subtract two Money amounts.
+   * Currencies must match.
+   *
+   * @throws Error if currencies don't match
+   * @example
+   * ```ts
+   * const a = Money.fromCents(100, "USD");
+   * const b = Money.fromCents(30, "USD");
+   * const diff = a.subtract(b); // 70 cents
+   * ```
+   */
+  subtract(other: Money): Money {
+    this._validateSameCurrency(other);
+    return new Money(this._value - other._value, this._currency);
+  }
+
+  /**
+   * Multiply Money by a number.
+   * Result is rounded to nearest cent.
+   *
+   * @example
+   * ```ts
+   * const price = Money.fromCents(100, "USD");
+   * const total = price.multiply(3); // 300 cents
+   * const taxed = price.multiply(1.08); // 108 cents (rounded)
+   * ```
+   */
+  multiply(multiplier: number): Money {
+    return new Money(Math.round(this._value * multiplier), this._currency);
+  }
+
+  /**
+   * Divide Money by a number.
+   * Result is rounded to nearest cent.
+   *
+   * @throws Error if divisor is zero
+   * @example
+   * ```ts
+   * const total = Money.fromCents(100, "USD");
+   * const perItem = total.divide(3); // 33 cents (rounded)
+   * ```
+   */
+  divide(divisor: number): Money {
+    if (divisor === 0) {
+      throw new Error("Cannot divide money by zero");
+    }
+    return new Money(Math.round(this._value / divisor), this._currency);
+  }
+
+  /**
+   * Check if two Money amounts are equal.
+   * Currencies must match.
+   *
+   * @throws Error if currencies don't match
+   */
+  equals(other: Money): boolean {
+    this._validateSameCurrency(other);
+    return this._value === other._value;
+  }
+
+  /**
+   * Check if this Money is less than another.
+   * Currencies must match.
+   *
+   * @throws Error if currencies don't match
+   */
+  lessThan(other: Money): boolean {
+    this._validateSameCurrency(other);
+    return this._value < other._value;
+  }
+
+  /**
+   * Check if this Money is less than or equal to another.
+   * Currencies must match.
+   *
+   * @throws Error if currencies don't match
+   */
+  lessThanOrEqual(other: Money): boolean {
+    this._validateSameCurrency(other);
+    return this._value <= other._value;
+  }
+
+  /**
+   * Check if this Money is greater than another.
+   * Currencies must match.
+   *
+   * @throws Error if currencies don't match
+   */
+  greaterThan(other: Money): boolean {
+    this._validateSameCurrency(other);
+    return this._value > other._value;
+  }
+
+  /**
+   * Check if this Money is greater than or equal to another.
+   * Currencies must match.
+   *
+   * @throws Error if currencies don't match
+   */
+  greaterThanOrEqual(other: Money): boolean {
+    this._validateSameCurrency(other);
+    return this._value >= other._value;
+  }
+
+  /**
+   * Get the amount in cents (minor units).
+   *
+   * @returns Amount in cents as integer
+   *
+   * @example
+   * ```ts
+   * const price = Money.fromCents(14999, "USD");
+   * console.log(price.cents); // 14999
+   * ```
+   */
+  get cents(): Cents {
+    return this._value;
+  }
+
+  /**
+   * Get the currency code (ISO 4217).
+   */
+  get currency(): string {
+    return this._currency;
+  }
+
+  /**
+   * Format Money for display with currency symbol.
+   *
+   * @param locale - BCP 47 language tag (default: "en-US")
+   * @example
+   * ```ts
+   * const price = Money.fromCents(14999, "USD");
+   * price.format();        // "$149.99"
+   * price.format("de-DE"); // "149,99 $"
+   *
+   * const euro = Money.fromCents(9999, "EUR");
+   * euro.format("en-US");  // "€99.99"
+   * euro.format("de-DE");  // "99,99 €"
+   * ```
+   */
+  format(locale = "en-US"): string {
+    return new Intl.NumberFormat(locale, {
+      style: "currency",
+      currency: this._currency,
+    }).format(this._value / 100);
+  }
+
+  /**
+   * Format Money as a number without currency symbol.
+   *
+   * @param locale - BCP 47 language tag (default: "en-US")
+   * @example
+   * ```ts
+   * const price = Money.fromCents(14999, "USD");
+   * price.formatNumber();        // "149.99"
+   * price.formatNumber("de-DE"); // "149,99"
+   * ```
+   */
+  formatNumber(locale = "en-US"): string {
+    return new Intl.NumberFormat(locale, {
+      minimumFractionDigits: 2,
+      maximumFractionDigits: 2,
+    }).format(this._value / 100);
+  }
+
+  /**
+   * Convert to string (major units without currency symbol).
+   * For display, prefer format() or formatNumber().
+   */
+  toString(): string {
+    return (this._value / 100).toString();
+  }
+
+  /**
+   * Convert to JSON (returns cents as number for storage/API).
+   *
+   * Use this when serializing Money to DTOs or API responses.
+   * The returned value is in cents and should be stored/transmitted as `Cents` type.
+   *
+   * @returns Amount in cents (integer)
+   *
+   * @example
+   * ```ts
+   * const price = Money.fromCents(14999, "USD");
+   * const dto = {
+   *   unitPrice: price.toJson(), // 14999 (Cents)
+   *   currency: price.currency    // "USD"
+   * };
+   * ```
+   */
+  toJson(): Cents {
+    return this._value;
+  }
+
+  /**
+   * Validate that two Money amounts have the same currency.
+   * @throws Error if currencies don't match
+   */
+  private _validateSameCurrency(other: Money): void {
+    if (this._currency !== other._currency) {
+      throw new Error(
+        `Cannot operate on Money with different currencies: ${this._currency} and ${other._currency}`,
+      );
+    }
+  }
+}

package/src/common/type/permission.type.ts

@@ -0,0 +1,43 @@
+export enum ResourceScope {
+  ALL = "all",
+  OWNED = "owned",
+  TEAM = "team",
+  PROJECT = "project",
+  BUSINESS = "business",
+}
+
+export interface ResourceConstraints {
+  scope?: ResourceScope;
+  statuses?: string[];
+  timeRestriction?: {
+    from: Date;
+    to: Date;
+  };
+  businessId?: string;
+  teamId?: string;
+  projectId?: string;
+  resourceId?: string;
+}
+
+export interface Permission {
+  readonly resource: string;
+  readonly action: string;
+  readonly constraints?: ResourceConstraints;
+}
+
+const COMMON_ACTIONS_ARRAY = [
+  "create",
+  "retrieve",
+  "list",
+  "count",
+  "update",
+  "delete",
+] as const;
+
+export type CommonAction = typeof COMMON_ACTIONS_ARRAY[number];
+
+const COMMON_ACTIONS = new Set(COMMON_ACTIONS_ARRAY);
+
+export function isCommonAction(action: string): action is CommonAction {
+  return COMMON_ACTIONS.has(action as CommonAction);
+}

package/src/common/validation/validation-result.ts

@@ -0,0 +1,52 @@
+export class ValidationResult {
+  constructor(
+    public readonly isValid: boolean,
+    public readonly errors: readonly string[] = [],
+    public readonly fieldErrors: Readonly<
+      Record<string, readonly string[]>
+    > = {},
+  ) {}
+
+  static success(): ValidationResult {
+    return new ValidationResult(true);
+  }
+
+  static failure(errors: string[]): ValidationResult {
+    return new ValidationResult(false, errors);
+  }
+
+  static fieldFailure(fieldErrors: Record<string, string[]>): ValidationResult {
+    const allErrors = Object.values(fieldErrors).flat();
+    return new ValidationResult(false, allErrors, fieldErrors);
+  }
+
+  merge(other: ValidationResult): ValidationResult {
+    if (this.isValid && other.isValid) {
+      return ValidationResult.success();
+    }
+
+    const mergedErrors = [...this.errors, ...other.errors];
+    const mergedFieldErrors: Record<string, readonly string[]> = {
+      ...this.fieldErrors,
+      ...other.fieldErrors,
+    };
+
+    // Merge field errors for same fields
+    for (const [field, errors] of Object.entries(other.fieldErrors)) {
+      if (this.fieldErrors[field]) {
+        mergedFieldErrors[field] = [...this.fieldErrors[field], ...errors];
+      }
+    }
+
+    return new ValidationResult(false, mergedErrors, mergedFieldErrors);
+  }
+
+  toString(): string {
+    if (this.isValid) return "ValidationResult.success()";
+    return `ValidationResult.failure(errors: ${
+      JSON.stringify(
+        this.errors,
+      )
+    }, fieldErrors: ${JSON.stringify(this.fieldErrors)})`;
+  }
+}