@fin.cx/einvoice 5.0.2 → 5.1.2

package/ts/formats/utils/currency.calculator.decimal.ts

@@ -0,0 +1,323 @@
+/**
+ * Currency Calculator using Decimal Arithmetic
+ * EN16931-compliant monetary calculations with exact precision
+ */
+
+import { Decimal, decimal, RoundingMode } from './decimal.js';
+import type { TCurrency } from '@tsclass/tsclass/dist_ts/finance/index.js';
+import { getCurrencyMinorUnits } from './currency.utils.js';
+
+/**
+ * Currency-aware calculator using decimal arithmetic for EN16931 compliance
+ */
+export class DecimalCurrencyCalculator {
+  private readonly currency: TCurrency;
+  private readonly minorUnits: number;
+  private readonly roundingMode: RoundingMode;
+  
+  constructor(
+    currency: TCurrency,
+    roundingMode: RoundingMode = 'HALF_UP'
+  ) {
+    this.currency = currency;
+    this.minorUnits = getCurrencyMinorUnits(currency);
+    this.roundingMode = roundingMode;
+  }
+  
+  /**
+   * Round a decimal value according to currency rules
+   */
+  round(value: Decimal | number | string): Decimal {
+    const decimalValue = value instanceof Decimal ? value : new Decimal(value);
+    return decimalValue.round(this.minorUnits, this.roundingMode);
+  }
+  
+  /**
+   * Calculate line net amount: (quantity × unitPrice) - discount
+   */
+  calculateLineNet(
+    quantity: Decimal | number | string,
+    unitPrice: Decimal | number | string,
+    discount: Decimal | number | string = '0'
+  ): Decimal {
+    const qty = quantity instanceof Decimal ? quantity : new Decimal(quantity);
+    const price = unitPrice instanceof Decimal ? unitPrice : new Decimal(unitPrice);
+    const disc = discount instanceof Decimal ? discount : new Decimal(discount);
+    
+    const gross = qty.multiply(price);
+    const net = gross.subtract(disc);
+    
+    return this.round(net);
+  }
+  
+  /**
+   * Calculate VAT amount from base and rate
+   */
+  calculateVAT(
+    baseAmount: Decimal | number | string,
+    vatRate: Decimal | number | string
+  ): Decimal {
+    const base = baseAmount instanceof Decimal ? baseAmount : new Decimal(baseAmount);
+    const rate = vatRate instanceof Decimal ? vatRate : new Decimal(vatRate);
+    
+    const vat = base.percentage(rate);
+    return this.round(vat);
+  }
+  
+  /**
+   * Calculate total with VAT
+   */
+  calculateGrossAmount(
+    netAmount: Decimal | number | string,
+    vatAmount: Decimal | number | string
+  ): Decimal {
+    const net = netAmount instanceof Decimal ? netAmount : new Decimal(netAmount);
+    const vat = vatAmount instanceof Decimal ? vatAmount : new Decimal(vatAmount);
+    
+    return this.round(net.add(vat));
+  }
+  
+  /**
+   * Calculate sum of line items
+   */
+  sumLineItems(items: Array<{
+    quantity: Decimal | number | string;
+    unitPrice: Decimal | number | string;
+    discount?: Decimal | number | string;
+  }>): Decimal {
+    let total = Decimal.ZERO;
+    
+    for (const item of items) {
+      const lineNet = this.calculateLineNet(
+        item.quantity,
+        item.unitPrice,
+        item.discount
+      );
+      total = total.add(lineNet);
+    }
+    
+    return this.round(total);
+  }
+  
+  /**
+   * Calculate VAT breakdown by rate
+   */
+  calculateVATBreakdown(items: Array<{
+    netAmount: Decimal | number | string;
+    vatRate: Decimal | number | string;
+  }>): Array<{
+    rate: Decimal;
+    baseAmount: Decimal;
+    vatAmount: Decimal;
+  }> {
+    // Group by VAT rate
+    const groups = new Map<string, {
+      rate: Decimal;
+      baseAmount: Decimal;
+    }>();
+    
+    for (const item of items) {
+      const net = item.netAmount instanceof Decimal ? item.netAmount : new Decimal(item.netAmount);
+      const rate = item.vatRate instanceof Decimal ? item.vatRate : new Decimal(item.vatRate);
+      const rateKey = rate.toString();
+      
+      if (groups.has(rateKey)) {
+        const group = groups.get(rateKey)!;
+        group.baseAmount = group.baseAmount.add(net);
+      } else {
+        groups.set(rateKey, {
+          rate,
+          baseAmount: net
+        });
+      }
+    }
+    
+    // Calculate VAT for each group
+    const breakdown: Array<{
+      rate: Decimal;
+      baseAmount: Decimal;
+      vatAmount: Decimal;
+    }> = [];
+    
+    for (const group of groups.values()) {
+      breakdown.push({
+        rate: group.rate,
+        baseAmount: this.round(group.baseAmount),
+        vatAmount: this.calculateVAT(group.baseAmount, group.rate)
+      });
+    }
+    
+    return breakdown;
+  }
+  
+  /**
+   * Check if two amounts are equal within currency precision
+   */
+  areEqual(
+    amount1: Decimal | number | string,
+    amount2: Decimal | number | string
+  ): boolean {
+    const a1 = amount1 instanceof Decimal ? amount1 : new Decimal(amount1);
+    const a2 = amount2 instanceof Decimal ? amount2 : new Decimal(amount2);
+    
+    // Round both to currency precision before comparing
+    const rounded1 = this.round(a1);
+    const rounded2 = this.round(a2);
+    
+    return rounded1.equals(rounded2);
+  }
+  
+  /**
+   * Calculate payment terms discount
+   */
+  calculatePaymentDiscount(
+    amount: Decimal | number | string,
+    discountRate: Decimal | number | string
+  ): Decimal {
+    const amt = amount instanceof Decimal ? amount : new Decimal(amount);
+    const rate = discountRate instanceof Decimal ? discountRate : new Decimal(discountRate);
+    
+    const discount = amt.percentage(rate);
+    return this.round(discount);
+  }
+  
+  /**
+   * Distribute a total amount across items proportionally
+   */
+  distributeAmount(
+    totalToDistribute: Decimal | number | string,
+    items: Array<{ value: Decimal | number | string }>
+  ): Decimal[] {
+    const total = totalToDistribute instanceof Decimal ? totalToDistribute : new Decimal(totalToDistribute);
+    
+    // Calculate sum of all item values
+    const itemSum = items.reduce((sum, item) => {
+      const value = item.value instanceof Decimal ? item.value : new Decimal(item.value);
+      return sum.add(value);
+    }, Decimal.ZERO);
+    
+    if (itemSum.isZero()) {
+      // Can't distribute if sum is zero
+      return items.map(() => Decimal.ZERO);
+    }
+    
+    const distributed: Decimal[] = [];
+    let distributedSum = Decimal.ZERO;
+    
+    // Distribute proportionally
+    for (let i = 0; i < items.length; i++) {
+      const itemValue = items[i].value instanceof Decimal ? items[i].value : new Decimal(items[i].value);
+      
+      if (i === items.length - 1) {
+        // Last item gets the remainder to avoid rounding errors
+        distributed.push(total.subtract(distributedSum));
+      } else {
+        const itemDecimal = itemValue instanceof Decimal ? itemValue : new Decimal(itemValue);
+        const proportion = itemDecimal.divide(itemSum);
+        const distributedAmount = this.round(total.multiply(proportion));
+        distributed.push(distributedAmount);
+        distributedSum = distributedSum.add(distributedAmount);
+      }
+    }
+    
+    return distributed;
+  }
+  
+  /**
+   * Calculate compound amount (e.g., for multiple charges/allowances)
+   */
+  calculateCompoundAmount(
+    baseAmount: Decimal | number | string,
+    adjustments: Array<{
+      type: 'charge' | 'allowance';
+      value: Decimal | number | string;
+      isPercentage?: boolean;
+    }>
+  ): Decimal {
+    let result = baseAmount instanceof Decimal ? baseAmount : new Decimal(baseAmount);
+    
+    for (const adjustment of adjustments) {
+      const value = adjustment.value instanceof Decimal ? adjustment.value : new Decimal(adjustment.value);
+      
+      let adjustmentAmount: Decimal;
+      if (adjustment.isPercentage) {
+        adjustmentAmount = result.percentage(value);
+      } else {
+        adjustmentAmount = value;
+      }
+      
+      if (adjustment.type === 'charge') {
+        result = result.add(adjustmentAmount);
+      } else {
+        result = result.subtract(adjustmentAmount);
+      }
+    }
+    
+    return this.round(result);
+  }
+  
+  /**
+   * Validate monetary calculation according to EN16931 rules
+   */
+  validateCalculation(
+    expected: Decimal | number | string,
+    calculated: Decimal | number | string,
+    ruleName: string
+  ): {
+    valid: boolean;
+    expected: string;
+    calculated: string;
+    difference?: string;
+    rule: string;
+  } {
+    const exp = expected instanceof Decimal ? expected : new Decimal(expected);
+    const calc = calculated instanceof Decimal ? calculated : new Decimal(calculated);
+    
+    const roundedExp = this.round(exp);
+    const roundedCalc = this.round(calc);
+    
+    const valid = roundedExp.equals(roundedCalc);
+    
+    return {
+      valid,
+      expected: roundedExp.toFixed(this.minorUnits),
+      calculated: roundedCalc.toFixed(this.minorUnits),
+      difference: valid ? undefined : roundedExp.subtract(roundedCalc).abs().toFixed(this.minorUnits),
+      rule: ruleName
+    };
+  }
+  
+  /**
+   * Format amount for display
+   */
+  formatAmount(amount: Decimal | number | string): string {
+    const amt = amount instanceof Decimal ? amount : new Decimal(amount);
+    const rounded = this.round(amt);
+    return `${rounded.toFixed(this.minorUnits)} ${this.currency}`;
+  }
+  
+  /**
+   * Get currency information
+   */
+  getCurrencyInfo(): {
+    code: TCurrency;
+    minorUnits: number;
+    roundingMode: RoundingMode;
+  } {
+    return {
+      code: this.currency,
+      minorUnits: this.minorUnits,
+      roundingMode: this.roundingMode
+    };
+  }
+}
+
+/**
+ * Factory function to create a decimal currency calculator
+ */
+export function createDecimalCalculator(
+  currency: TCurrency,
+  roundingMode?: RoundingMode
+): DecimalCurrencyCalculator {
+  return new DecimalCurrencyCalculator(currency, roundingMode);
+}

package/ts/formats/utils/currency.utils.ts

@@ -0,0 +1,299 @@
+/**
+ * ISO 4217 Currency utilities for EN16931 compliance
+ * Provides currency-aware rounding and decimal handling
+ */
+
+/**
+ * ISO 4217 Currency minor units (decimal places)
+ * Based on ISO 4217:2015 standard
+ * 
+ * Most currencies use 2 decimal places, but there are exceptions:
+ * - 0 decimals: JPY, KRW, CLP, etc.
+ * - 3 decimals: BHD, IQD, JOD, KWD, OMR, TND
+ * - 4 decimals: CLF (Chilean Unit of Account)
+ */
+export const ISO4217MinorUnits: Record<string, number> = {
+  // Major currencies
+  'EUR': 2, // Euro
+  'USD': 2, // US Dollar
+  'GBP': 2, // British Pound
+  'CHF': 2, // Swiss Franc
+  'CAD': 2, // Canadian Dollar
+  'AUD': 2, // Australian Dollar
+  'NZD': 2, // New Zealand Dollar
+  'CNY': 2, // Chinese Yuan
+  'INR': 2, // Indian Rupee
+  'MXN': 2, // Mexican Peso
+  'BRL': 2, // Brazilian Real
+  'RUB': 2, // Russian Ruble
+  'ZAR': 2, // South African Rand
+  'SGD': 2, // Singapore Dollar
+  'HKD': 2, // Hong Kong Dollar
+  'NOK': 2, // Norwegian Krone
+  'SEK': 2, // Swedish Krona
+  'DKK': 2, // Danish Krone
+  'PLN': 2, // Polish Zloty
+  'CZK': 2, // Czech Koruna
+  'HUF': 2, // Hungarian Forint (technically 2, though often shown as 0)
+  'RON': 2, // Romanian Leu
+  'BGN': 2, // Bulgarian Lev
+  'HRK': 2, // Croatian Kuna
+  'TRY': 2, // Turkish Lira
+  'ISK': 0, // Icelandic Króna (0 decimals)
+  
+  // Zero decimal currencies
+  'JPY': 0, // Japanese Yen
+  'KRW': 0, // South Korean Won
+  'CLP': 0, // Chilean Peso
+  'PYG': 0, // Paraguayan Guaraní
+  'RWF': 0, // Rwandan Franc
+  'VND': 0, // Vietnamese Dong
+  'XAF': 0, // CFA Franc BEAC
+  'XOF': 0, // CFA Franc BCEAO
+  'XPF': 0, // CFP Franc
+  'BIF': 0, // Burundian Franc
+  'DJF': 0, // Djiboutian Franc
+  'GNF': 0, // Guinean Franc
+  'KMF': 0, // Comorian Franc
+  'MGA': 0, // Malagasy Ariary
+  'UGX': 0, // Ugandan Shilling
+  'VUV': 0, // Vanuatu Vatu
+  
+  // Three decimal currencies
+  'BHD': 3, // Bahraini Dinar
+  'IQD': 3, // Iraqi Dinar
+  'JOD': 3, // Jordanian Dinar
+  'KWD': 3, // Kuwaiti Dinar
+  'LYD': 3, // Libyan Dinar
+  'OMR': 3, // Omani Rial
+  'TND': 3, // Tunisian Dinar
+  
+  // Four decimal currencies
+  'CLF': 4, // Chilean Unit of Account (UF)
+  'UYW': 4, // Unidad Previsional (Uruguay)
+};
+
+/**
+ * Rounding modes for currency calculations
+ */
+export enum RoundingMode {
+  HALF_UP = 'HALF_UP',           // Round half values up (0.5 → 1, -0.5 → -1)
+  HALF_DOWN = 'HALF_DOWN',       // Round half values down (0.5 → 0, -0.5 → 0)
+  HALF_EVEN = 'HALF_EVEN',       // Banker's rounding (0.5 → 0, 1.5 → 2)
+  UP = 'UP',                     // Always round up
+  DOWN = 'DOWN',                 // Always round down (truncate)
+  CEILING = 'CEILING',           // Round toward positive infinity
+  FLOOR = 'FLOOR'                // Round toward negative infinity
+}
+
+/**
+ * Currency configuration for calculations
+ */
+export interface CurrencyConfig {
+  code: string;
+  minorUnits: number;
+  roundingMode: RoundingMode;
+  tolerance?: number; // Override default tolerance if needed
+}
+
+/**
+ * Get minor units (decimal places) for a currency
+ */
+export function getCurrencyMinorUnits(currencyCode: string): number {
+  const code = currencyCode.toUpperCase();
+  return ISO4217MinorUnits[code] ?? 2; // Default to 2 if unknown
+}
+
+/**
+ * Round a value according to currency rules
+ */
+export function roundToCurrency(
+  value: number,
+  currencyCode: string,
+  mode: RoundingMode = RoundingMode.HALF_UP
+): number {
+  const minorUnits = getCurrencyMinorUnits(currencyCode);
+  
+  if (minorUnits === 0) {
+    // For zero decimal currencies, round to integer
+    return Math.round(value);
+  }
+  
+  const multiplier = Math.pow(10, minorUnits);
+  const scaled = value * multiplier;
+  let rounded: number;
+  
+  switch (mode) {
+    case RoundingMode.HALF_UP:
+      // Round half values away from zero
+      if (scaled >= 0) {
+        rounded = Math.floor(scaled + 0.5);
+      } else {
+        rounded = Math.ceil(scaled - 0.5);
+      }
+      break;
+    case RoundingMode.HALF_DOWN:
+      // Round half values toward zero
+      const fraction = Math.abs(scaled % 1);
+      if (fraction === 0.5) {
+        // Exactly 0.5 - round toward zero
+        rounded = scaled >= 0 ? Math.floor(scaled) : Math.ceil(scaled);
+      } else {
+        // Not exactly 0.5 - use normal rounding
+        rounded = Math.round(scaled);
+      }
+      break;
+    case RoundingMode.HALF_EVEN:
+      // Banker's rounding
+      const isHalf = Math.abs(scaled % 1) === 0.5;
+      if (isHalf) {
+        const floor = Math.floor(scaled);
+        rounded = floor % 2 === 0 ? floor : Math.ceil(scaled);
+      } else {
+        rounded = Math.round(scaled);
+      }
+      break;
+    case RoundingMode.UP:
+      rounded = scaled >= 0 ? Math.ceil(scaled) : Math.floor(scaled);
+      break;
+    case RoundingMode.DOWN:
+      rounded = Math.trunc(scaled);
+      break;
+    case RoundingMode.CEILING:
+      rounded = Math.ceil(scaled);
+      break;
+    case RoundingMode.FLOOR:
+      rounded = Math.floor(scaled);
+      break;
+    default:
+      rounded = Math.round(scaled);
+  }
+  
+  return rounded / multiplier;
+}
+
+/**
+ * Get tolerance for currency comparison
+ * Based on the smallest representable unit for the currency
+ */
+export function getCurrencyTolerance(currencyCode: string): number {
+  const minorUnits = getCurrencyMinorUnits(currencyCode);
+  // Tolerance is half of the smallest unit
+  return 0.5 * Math.pow(10, -minorUnits);
+}
+
+/**
+ * Compare two monetary values with currency-aware tolerance
+ */
+export function areMonetaryValuesEqual(
+  value1: number,
+  value2: number,
+  currencyCode: string
+): boolean {
+  const tolerance = getCurrencyTolerance(currencyCode);
+  return Math.abs(value1 - value2) <= tolerance;
+}
+
+/**
+ * Format a value according to currency decimal places
+ */
+export function formatCurrencyValue(
+  value: number,
+  currencyCode: string
+): string {
+  const minorUnits = getCurrencyMinorUnits(currencyCode);
+  return value.toFixed(minorUnits);
+}
+
+/**
+ * Validate if a value has correct decimal places for a currency
+ */
+export function hasValidDecimalPlaces(
+  value: number,
+  currencyCode: string
+): boolean {
+  const minorUnits = getCurrencyMinorUnits(currencyCode);
+  const multiplier = Math.pow(10, minorUnits);
+  const scaled = Math.round(value * multiplier);
+  const reconstructed = scaled / multiplier;
+  return Math.abs(value - reconstructed) < Number.EPSILON;
+}
+
+/**
+ * Currency calculation context for EN16931 compliance
+ */
+export class CurrencyCalculator {
+  private currency: string;
+  private minorUnits: number;
+  private roundingMode: RoundingMode;
+  
+  constructor(config: CurrencyConfig | string) {
+    if (typeof config === 'string') {
+      this.currency = config;
+      this.minorUnits = getCurrencyMinorUnits(config);
+      this.roundingMode = RoundingMode.HALF_UP;
+    } else {
+      this.currency = config.code;
+      this.minorUnits = config.minorUnits;
+      this.roundingMode = config.roundingMode;
+    }
+  }
+  
+  /**
+   * Round a value according to configured rules
+   */
+  round(value: number): number {
+    return roundToCurrency(value, this.currency, this.roundingMode);
+  }
+  
+  /**
+   * Calculate line net amount with rounding
+   * EN16931: Line net = (quantity × unit price) - line discounts
+   */
+  calculateLineNet(
+    quantity: number,
+    unitPrice: number,
+    discount: number = 0
+  ): number {
+    const gross = quantity * unitPrice;
+    const net = gross - discount;
+    return this.round(net);
+  }
+  
+  /**
+   * Calculate VAT amount with rounding
+   * EN16931: VAT amount = taxable amount × (rate / 100)
+   */
+  calculateVAT(taxableAmount: number, rate: number): number {
+    const vat = taxableAmount * (rate / 100);
+    return this.round(vat);
+  }
+  
+  /**
+   * Compare values with currency-aware tolerance
+   */
+  areEqual(value1: number, value2: number): boolean {
+    return areMonetaryValuesEqual(value1, value2, this.currency);
+  }
+  
+  /**
+   * Get the tolerance for comparisons
+   */
+  getTolerance(): number {
+    return getCurrencyTolerance(this.currency);
+  }
+  
+  /**
+   * Format value for display
+   */
+  format(value: number): string {
+    return formatCurrencyValue(value, this.currency);
+  }
+}
+
+/**
+ * Get version info for ISO 4217 data
+ */
+export function getISO4217Version(): string {
+  return '2015'; // Update when currency list is updated
+}