Make money class currency data configurable

[jbojcic1]

I think we should make money class configurable so that in entry file we can set any currency data we want. That way Agicash app can specify sats as base unit while money class can still stay with more sane default btc. That would then also make it possible for us to get rid of that getDefaultUnit from the agicash app because entry point would configure sat to be the default for the entire app.

I will create a separate ticket for this

Originally posted by @jbojcic1 in #767 (comment)

[jbojcic1]

@claude can you check this ticket and the original conversation that started it and tell us how would you implement it.

[claude]

Claude finished @jbojcic1's task in 1m 54s —— View job

---

Implementation Proposal

After analyzing the current Money class implementation and how getDefaultUnit is used throughout the codebase, here's my proposed approach to make the Money class currency data configurable:

---

Current State

Problem:

• The Money class has hardcoded currencyDataMap with baseUnit set to:
  • BTC: 'btc' (Bitcoin as base unit)
  • USD: 'usd' (Dollar as base unit)
• Agicash app prefers 'sat' (Satoshi) as the default display unit for BTC
• This requires a separate getDefaultUnit helper in app/features/shared/currencies.ts that returns 'sat' for BTC
• Every place that displays money must call getDefaultUnit() instead of using the Money class's natural defaults

Current usage pattern:

// Throughout the app (12+ files):
import { getDefaultUnit } from '~/features/shared/currencies';

// When formatting or displaying money:
money.toString(getDefaultUnit(money.currency))
money.toLocaleString({ unit: getDefaultUnit(money.currency) })

---

Proposed Solution

Create a configuration system that allows the app to override currency defaults at the entry point, making the Money class adapt to application-specific needs while staying generically useful.

Design Approach

1. Add Configuration API to Money class

// app/lib/money/money.ts

type MoneyConfiguration = {
  currencyDefaults?: {
    [K in Currency]?: {
      baseUnit?: CurrencyUnit<K>;
    };
  };
};

class Money<T extends Currency = Currency> {
  private static configuration: MoneyConfiguration = {};

  /**
   * Configure Money class defaults. Should be called once at app initialization.
   */
  static configure(config: MoneyConfiguration): void {
    Money.configuration = { ...config };
  }

  /**
   * Get the configured base unit for a currency, falling back to hardcoded defaults
   */
  private static getBaseUnit<T extends Currency>(currency: T): CurrencyUnit<T> {
    const configuredBase = Money.configuration.currencyDefaults?.[currency]?.baseUnit;
    if (configuredBase) {
      return configuredBase as CurrencyUnit<T>;
    }
    
    // Fall back to original defaults
    const currencyData = currencyDataMap[currency];
    return currencyData.baseUnit as CurrencyUnit<T>;
  }
  
  // Update getCurrencyData to use configured base unit
  private get currencyData(): CurrencyData<T> {
    const data = currencyDataMap[this.currency];
    const configuredBase = Money.getBaseUnit(this.currency);
    
    return {
      ...data,
      baseUnit: configuredBase,
    };
  }
  
  // ... rest of the Money class remains the same
}

2. Configure in entry.client.tsx

// app/entry.client.tsx

import { Money } from '~/lib/money';

// Configure Money class for Agicash defaults
Money.configure({
  currencyDefaults: {
    BTC: {
      baseUnit: 'sat', // Override BTC base unit from 'btc' to 'sat'
    },
    USD: {
      baseUnit: 'usd', // Explicit, but not necessary (already the default)
    },
  },
});

// ... rest of entry.client.tsx

3. Remove getDefaultUnit helper

Delete app/features/shared/currencies.ts entirely, as it's no longer needed.

4. Update all usage sites

Replace all instances of:

money.toString(getDefaultUnit(money.currency))

With:

money.toString() // Uses configured base unit automatically

This affects 12+ files across:

• app/hooks/use-money-input.ts
• app/features/send/*.tsx
• app/features/receive/*.tsx
• app/features/transactions/*.tsx
• app/components/money-display.tsx
• And others

---

Benefits

1. Cleaner API: No need to pass unit everywhere - the Money class knows the app's preferred defaults
2. Single source of truth: Configuration happens once at app initialization
3. Backwards compatible: The Money class library remains generic with sensible defaults (BTC = 'btc')
4. App-specific customization: Agicash can configure 'sat' as preferred without changing the library
5. Eliminates helper: Removes the need for getDefaultUnit() scattered throughout the codebase
6. Better DX: Developers don't need to remember to call getDefaultUnit() - it's automatic

---

Alternative Approaches Considered

Alternative 1: Make baseUnit mutable in currencyDataMap

• ❌ Requires modifying hardcoded data structure
• ❌ Less explicit and harder to test
• ❌ Could lead to race conditions if modified after initialization

Alternative 2: Context/Provider pattern

• ❌ More complex - requires React context
• ❌ Server-side rendering complications
• ❌ Money class would depend on React

Alternative 3: Factory function

• ❌ Would require changing new Money() to createMoney() everywhere
• ❌ More invasive change to existing code

---

Implementation Steps

If this approach looks good, I can implement it with these steps:

1. Add Money.configure() static method and configuration storage
2. Update currencyData getter to respect configuration
3. Add configuration call in entry.client.tsx
4. Remove getDefaultUnit from currencies.ts
5. Update all call sites to remove getDefaultUnit() usage
6. Run bun run fix:all to ensure type safety
7. Update tests if needed

Would you like me to proceed with this implementation?

---

[jbojcic1]

@claude that looks pretty good but can you also show me how would the plan look if you would make entire currency data map configurable? That way the app that uses the money class can configure everything including units but curreny values would still be the default. Also the app ideally should be able to change only portions of the default currency data (overrides get merged with default).

[claude]

Claude finished @jbojcic1's task in 1m 38s —— View job

---

Enhanced Configuration Proposal: Full Currency Data Map Configuration

• Read Money class implementation
• Understand full CurrencyData structure
• Design configuration API with deep merge
• Provide implementation examples
• Show benefits and trade-offs

---

After reviewing your request, here's a comprehensive proposal for making the entire currency data map configurable with deep merge support. This approach allows apps to override any aspect of currency configuration while preserving sensible defaults.

---

Current State Analysis

CurrencyData Structure:

type CurrencyData<T extends Currency> = {
  baseUnit: CurrencyUnit<T>;           // Default display unit
  units: Array<UnitData<T>>;           // Available units with formatting
};

type UnitData<T extends Currency> = {
  name: CurrencyUnit<T>;               // Unit name (e.g., 'sat', 'btc')
  decimals: number;                     // Decimal precision
  symbol: string;                       // Display symbol (e.g., '₿')
  factor: Big;                          // Conversion factor
  formatToParts: (value, options) => Intl.NumberFormatPart[];
  format: (value, options) => string;
};

Problem:

• Entire currencyDataMap is hardcoded
• Apps can't customize base units, symbols, decimals, or formatting
• Requires workaround helpers like getDefaultUnit()

---

Proposed Solution: Deep Merge Configuration System

Design Goals

1. ✅ Allow apps to override any property of currency data
2. ✅ Support partial overrides (merge with defaults)
3. ✅ Keep sensible defaults when not configured
4. ✅ Single configuration point at app initialization
5. ✅ Type-safe configuration API

---

Implementation Design

1. Add Configuration Types

// app/lib/money/types.ts

/**
 * Partial unit data for configuration (functions optional)
 */
export type PartialUnitData<T extends Currency> = {
  name: CurrencyUnit<T>;
  decimals?: number;
  symbol?: string;
  factor?: Big;
  formatToParts?: (
    value: number,
    options?: FormatOptions,
  ) => Intl.NumberFormatPart[];
  format?: (value: number, options?: FormatOptions) => string;
};

/**
 * Partial currency data for configuration
 */
export type PartialCurrencyData<T extends Currency> = {
  baseUnit?: CurrencyUnit<T>;
  units?: Array<PartialUnitData<T>>;
};

/**
 * Configuration type for Money class
 */
export type MoneyConfiguration = {
  currencyData?: {
    [K in Currency]?: PartialCurrencyData<K>;
  };
};

2. Update Money Class with Configuration API

// app/lib/money/money.ts

export class Money<T extends Currency = Currency> {
  private static configuration: MoneyConfiguration = {};
  private static mergedCurrencyDataMap: CurrencyDataMap | null = null;

  /**
   * Configure Money class. Should be called once at app initialization.
   * Performs deep merge of provided config with default currency data.
   */
  static configure(config: MoneyConfiguration): void {
    Money.configuration = config;
    Money.mergedCurrencyDataMap = Money.buildMergedCurrencyDataMap();
  }

  /**
   * Reset configuration to defaults (useful for testing)
   */
  static resetConfiguration(): void {
    Money.configuration = {};
    Money.mergedCurrencyDataMap = null;
  }

  /**
   * Build merged currency data map by deep merging config with defaults
   */
  private static buildMergedCurrencyDataMap(): CurrencyDataMap {
    const currencies: Currency[] = ['BTC', 'USD'];
    const merged: Partial<CurrencyDataMap> = {};

    for (const currency of currencies) {
      const defaultData = currencyDataMap[currency];
      const configData = Money.configuration.currencyData?.[currency];

      if (!configData) {
        // No config for this currency, use defaults
        merged[currency] = defaultData;
        continue;
      }

      // Deep merge currency data
      const mergedUnits = Money.mergeUnits(
        defaultData.units,
        configData.units || [],
      );

      merged[currency] = {
        baseUnit: configData.baseUnit ?? defaultData.baseUnit,
        units: mergedUnits,
      } as CurrencyData<typeof currency>;
    }

    return merged as CurrencyDataMap;
  }

  /**
   * Merge unit arrays: config units override matching default units by name
   */
  private static mergeUnits<T extends Currency>(
    defaultUnits: Array<UnitData<T>>,
    configUnits: Array<PartialUnitData<T>>,
  ): Array<UnitData<T>> {
    const merged = [...defaultUnits];

    for (const configUnit of configUnits) {
      const index = merged.findIndex((u) => u.name === configUnit.name);
      
      if (index !== -1) {
        // Merge with existing unit (override specified properties)
        merged[index] = {
          ...merged[index],
          ...configUnit,
          // Keep default formatting functions if not provided
          formatToParts: configUnit.formatToParts ?? merged[index].formatToParts,
          format: configUnit.format ?? merged[index].format,
        } as UnitData<T>;
      } else {
        // New unit not in defaults - add it (must be complete)
        if (!Money.isCompleteUnitData(configUnit)) {
          throw new Error(
            `Incomplete unit data for new unit "${configUnit.name}". ` +
            `All properties (decimals, symbol, factor, formatToParts, format) are required for new units.`
          );
        }
        merged.push(configUnit as UnitData<T>);
      }
    }

    return merged;
  }

  /**
   * Type guard to check if partial unit data is complete
   */
  private static isCompleteUnitData<T extends Currency>(
    unit: PartialUnitData<T>,
  ): unit is UnitData<T> {
    return (
      unit.decimals !== undefined &&
      unit.symbol !== undefined &&
      unit.factor !== undefined &&
      unit.formatToParts !== undefined &&
      unit.format !== undefined
    );
  }

  /**
   * Get effective currency data map (merged or default)
   */
  private static getEffectiveCurrencyDataMap(): CurrencyDataMap {
    return Money.mergedCurrencyDataMap ?? currencyDataMap;
  }

  // Update all places that access currencyDataMap to use the effective map
  private get currencyData(): CurrencyData<T> {
    return Money.getEffectiveCurrencyDataMap()[this.currency];
  }

  private static getCurrencyDataForInput<T extends Currency>(
    data: MoneyInput<T>,
  ): {
    baseUnit: UnitData<T>;
    minUnit: UnitData<T>;
    selectedUnit: UnitData<T> | undefined;
  } {
    const currencyData = Money.getEffectiveCurrencyDataMap()[data.currency];
    if (!currencyData) {
      throw new Error(`Unsupported currency: ${data.currency}`);
    }

    const minUnit = currencyData.units.reduce((minItem, currentItem) => {
      return currentItem.factor.lt(minItem.factor) ? currentItem : minItem;
    });
    const baseUnit = currencyData.units.find(
      (x) => x.name === currencyData.baseUnit,
    );
    if (!minUnit || !baseUnit) {
      throw new Error(`Misconfigured currency: ${data.currency}`);
    }

    const selectedUnit = data.unit
      ? currencyData.units.find((x) => x.name === data.unit)
      : undefined;
    if (data.unit && !selectedUnit) {
      throw new Error(
        `Unsupported unit: ${data.unit} for currency ${data.currency}`,
      );
    }

    return { baseUnit, minUnit, selectedUnit };
  }
  
  // ... rest of Money class remains the same
}

// Update helper functions to use effective map
const getCurrencyData = <T extends Currency>(currency: T) => {
  const currencyData = Money.getEffectiveCurrencyDataMap()[currency];
  if (!currencyData) {
    throw new Error(`Unsupported currency: ${currency}`);
  }
  return currencyData;
};

// ... rest of file

3. Configure in Entry Point

// app/entry.client.tsx

import { Money } from '~/lib/money';

// Configure Money class for Agicash
Money.configure({
  currencyData: {
    BTC: {
      baseUnit: 'sat', // Override: change base unit from 'btc' to 'sat'
      // units array not specified - all BTC units keep their default properties
    },
    // USD not specified - uses all defaults
  },
});

// ... rest of entry.client.tsx

Advanced configuration example (if Agicash wanted to customize more):

Money.configure({
  currencyData: {
    BTC: {
      baseUnit: 'sat',
      units: [
        {
          name: 'sat',
          symbol: 'sats', // Override: change symbol from '₿' to 'sats'
          // Other properties (decimals, factor, format functions) keep defaults
        },
        // Other units ('btc', 'msat') not specified - keep all defaults
      ],
    },
  },
});

4. Remove getDefaultUnit Helper

Delete app/features/shared/currencies.ts entirely.

5. Update All Usage Sites

Replace all instances throughout the codebase:

// Before (12+ files):
import { getDefaultUnit } from '~/features/shared/currencies';
money.toString(getDefaultUnit(money.currency));
money.toLocaleString({ unit: getDefaultUnit(money.currency) });

// After:
money.toString(); // Uses configured baseUnit automatically
money.toLocaleString(); // Uses configured baseUnit automatically

---

Configuration Capabilities

What Can Be Configured?

Property	Scope	Example
baseUnit	Per currency	Change BTC from 'btc' to 'sat'
units[].decimals	Per unit	Change sat decimals from 0 to 2
units[].symbol	Per unit	Change '₿' to 'sats' or 'BTC'
units[].factor	Per unit	Add custom unit with conversion factor
units[].format	Per unit	Custom formatting function
units[].formatToParts	Per unit	Custom parts formatter

Merge Behavior

Partial override (most common):

Money.configure({
  currencyData: {
    BTC: {
      baseUnit: 'sat', // Override just the base unit
      // All 3 units (btc, sat, msat) keep their default properties
    },
  },
});

Unit-level override:

Money.configure({
  currencyData: {
    BTC: {
      units: [
        {
          name: 'sat',
          symbol: 'sats', // Override symbol for 'sat' unit
          // decimals, factor, formatToParts, format keep defaults
        },
        // 'btc' and 'msat' not mentioned - keep all defaults
      ],
    },
  },
});

Add new unit:

Money.configure({
  currencyData: {
    BTC: {
      units: [
        {
          name: 'ksat', // New unit
          decimals: 0,
          symbol: 'ksat',
          factor: new Big(10 ** -5), // 1 ksat = 1000 sats
          formatToParts: function(value, options) { /* ... */ },
          format: function(value, options) { /* ... */ },
        },
      ],
    },
  },
});

---

Benefits

1. Maximum Flexibility: Apps can customize any aspect of currency handling
2. Minimal Configuration: Only specify what you want to change
3. Sensible Defaults: Unconfigured properties use Money class defaults
4. Type Safety: TypeScript ensures correct currency/unit types
5. Single Source of Truth: Configuration happens once at initialization
6. No Helper Functions: Eliminates getDefaultUnit() and similar workarounds
7. Backward Compatible: Money class still works without configuration
8. Better DX: Developers don't need to remember app-specific conventions

---

Trade-offs vs. Simple BaseUnit-Only Approach

Aspect	BaseUnit-Only	Full Data Map	Winner
Simplicity	Simple API, less code	More complex deep merge logic	BaseUnit-Only
Flexibility	Can't customize symbols/decimals/formatting	Full control over all properties	Full Data Map
Type Safety	Easier to type	Complex partial types	BaseUnit-Only
Future-Proofing	Limited to base unit changes	Can adapt to any requirement	Full Data Map
Configuration Size	Minimal (1-2 lines)	Can be large if heavily customized	BaseUnit-Only
Common Use Case	Covers Agicash's current need (sat as default)	Covers current + future needs	Depends

---

Recommendation

For Agicash's current requirements (just changing base unit to 'sat'), the simpler baseUnit-only approach from my first proposal is sufficient and easier to maintain.

However, if you anticipate:

• Custom currency symbols (e.g., "sats" instead of "₿")
• Custom decimal precision
• Custom formatting logic
• Adding new units
• Supporting future customization needs

Then the full currency data map approach is worth the added complexity.

---

Alternative: Hybrid Approach

A middle ground could be:

1. Start with the simple baseUnit-only configuration
2. Keep the full data map approach in mind for future extensibility
3. Migrate to full configuration only when actually needed

This follows YAGNI (You Aren't Gonna Need It) - implement the simplest thing that works now, and enhance later if requirements emerge.

---

Next Steps

Which approach would you prefer?

Option A: Simple (baseUnit-only)

• Pros: Less code, easier to understand, covers current need
• Cons: Limited to base unit configuration

Option B: Comprehensive (full data map)

• Pros: Maximum flexibility, future-proof
• Cons: More complex, more code to maintain

Option C: Hybrid (start simple, design for expansion)

• Pros: Ship quickly, can extend later
• Cons: May require refactoring if full config needed

Let me know which direction you'd like, and I can implement it!

---

[jbojcic1]

@claude can you now update it to also make supported currencies configurable? E.g. some app might want to use EUR. Or maybe currency from the money class perspective should be just string instead of 'USD' | 'BTC'. See what makes more sense and then also suggest a plan that covers this too.

[claude]

Claude finished @jbojcic1's task in 3m 48s —— View job

---

Enhanced Configuration: Configurable Supported Currencies

After analyzing the Money class implementation and type system, here's a comprehensive proposal for making supported currencies configurable while maintaining type safety where possible.

---

Current State Analysis

Type System:

• Currency = 'USD' | 'BTC' - Hardcoded union type
• CurrencyUnit<T> - Conditional type that maps currency to its units
  • 'USD' → 'usd' | 'cent'
  • 'BTC' → 'btc' | 'sat' | 'msat'
• currencyDataMap - Hardcoded object with only USD and BTC

Problems:

1. Adding new currencies (e.g., EUR) requires modifying the Money library
2. Apps using Money class can't add custom currencies without forking
3. Type system is tightly coupled to hardcoded currencies

---

Design Decision: Currency as String vs. Union Type

Option A: Keep Strong Typing (Currency = 'USD' | 'BTC' | ...)

Pros:

• ✅ Full TypeScript autocomplete for currency codes
• ✅ Compile-time errors for invalid currencies
• ✅ Type-safe unit mapping (CurrencyUnit<'BTC'> knows about 'sat', 'btc', 'msat')

Cons:

• ❌ Requires code changes to add new currencies
• ❌ Apps can't dynamically register currencies
• ❌ Can't support user-defined currencies at runtime

Example:

// Compile-time safety
const money = new Money({ amount: 100, currency: 'BTC' }); // ✓
const money = new Money({ amount: 100, currency: 'EUR' }); // ✗ TypeScript error

Option B: Generic String Type (Currency = string)

Pros:

• ✅ Apps can register any currency at runtime
• ✅ No code changes needed to support new currencies
• ✅ Fully flexible and extensible

Cons:

• ❌ No TypeScript autocomplete for currency codes
• ❌ Typos not caught at compile time
• ❌ Lose type-safe unit mapping (can't infer units from currency)
• ❌ Runtime errors instead of compile-time errors

Example:

// Runtime validation only
const money = new Money({ amount: 100, currency: 'BTC' }); // ✓
const money = new Money({ amount: 100, currency: 'EUR' }); // ✓ (if registered)
const money = new Money({ amount: 100, currency: 'XYZ' }); // ✗ Runtime error

Option C: Hybrid Approach (Recommended)

Concept: Use a generic type parameter with a default union type, allowing both compile-time safety for known currencies AND runtime extensibility for custom currencies.

Pros:

• ✅ Known currencies get full type safety
• ✅ Apps can register custom currencies at runtime
• ✅ Backward compatible with existing code
• ✅ Best of both worlds

Cons:

• ⚠️ More complex type system
• ⚠️ Custom currencies lose some type safety (acceptable trade-off)

---

Recommended Implementation: Hybrid Approach

1. Update Type Definitions

// app/lib/money/types.ts

/**
 * Known currencies with full type support
 */
export type KnownCurrency = 'USD' | 'BTC';

/**
 * Currency type - can be a known currency or a custom string
 */
export type Currency = KnownCurrency | string;

/**
 * Known unit types for built-in currencies
 */
export type UsdUnit = 'usd' | 'cent';
export type BtcUnit = 'btc' | 'sat' | 'msat';

/**
 * Unit type mapping for known currencies
 */
type KnownCurrencyUnit<T extends KnownCurrency> = T extends 'USD'
  ? UsdUnit
  : T extends 'BTC'
    ? BtcUnit
    : never;

/**
 * Currency unit type - for known currencies returns specific units,
 * for custom currencies returns generic string
 */
export type CurrencyUnit<T extends Currency = Currency> = T extends KnownCurrency
  ? KnownCurrencyUnit<T>
  : string;

// Rest of types remain the same...
export type MoneyInput<T extends Currency = Currency> = {
  amount: NumberInput;
  currency: T;
  unit?: CurrencyUnit<T>;
};

export type UnitData<T extends Currency> = {
  name: CurrencyUnit<T>;
  decimals: number;
  symbol: string;
  factor: Big;
  formatToParts: (value: number, options?: FormatOptions) => Intl.NumberFormatPart[];
  format: (value: number, options?: FormatOptions) => string;
};

export type CurrencyData<T extends Currency> = {
  baseUnit: CurrencyUnit<T>;
  units: Array<UnitData<T>>;
};

/**
 * Configuration types for custom currencies
 */
export type PartialUnitData<T extends Currency> = {
  name: CurrencyUnit<T>;
  decimals?: number;
  symbol?: string;
  factor?: Big;
  formatToParts?: (value: number, options?: FormatOptions) => Intl.NumberFormatPart[];
  format?: (value: number, options?: FormatOptions) => string;
};

export type PartialCurrencyData<T extends Currency> = {
  baseUnit?: CurrencyUnit<T>;
  units?: Array<PartialUnitData<T>>;
};

export type MoneyConfiguration = {
  currencies?: {
    [key: string]: PartialCurrencyData<any>;
  };
};

/**
 * Currency data map type - now supports any string key
 */
export type CurrencyDataMap = {
  [key: string]: CurrencyData<any>;
};

2. Update Money Class with Currency Registration

// app/lib/money/money.ts

export class Money<T extends Currency = Currency> {
  private static configuration: MoneyConfiguration = {};
  private static customCurrencyDataMap: CurrencyDataMap = {};
  private static isConfigured = false;

  /**
   * Configure Money class with custom currency data.
   * Should be called once at app initialization.
   */
  static configure(config: MoneyConfiguration): void {
    if (Money.isConfigured) {
      console.warn('Money.configure() called multiple times. Later calls override earlier ones.');
    }
    
    Money.configuration = config;
    Money.customCurrencyDataMap = Money.buildCurrencyDataMap(config);
    Money.isConfigured = true;
  }

  /**
   * Reset configuration (useful for testing)
   */
  static resetConfiguration(): void {
    Money.configuration = {};
    Money.customCurrencyDataMap = {};
    Money.isConfigured = false;
  }

  /**
   * Register a new currency or override existing currency data
   */
  static registerCurrency<T extends Currency>(
    currency: T,
    data: CurrencyData<T>,
  ): void {
    Money.customCurrencyDataMap[currency] = data;
  }

  /**
   * Build currency data map from configuration
   */
  private static buildCurrencyDataMap(config: MoneyConfiguration): CurrencyDataMap {
    const customMap: CurrencyDataMap = {};

    if (!config.currencies) {
      return customMap;
    }

    for (const [currency, partialData] of Object.entries(config.currencies)) {
      // Check if this is overriding a known currency
      const defaultData = currencyDataMap[currency];

      if (defaultData && partialData) {
        // Merge with default data
        customMap[currency] = Money.mergeCurrencyData(
          defaultData,
          partialData,
        );
      } else if (partialData) {
        // New currency - validate it's complete
        if (!Money.isCompleteCurrencyData(partialData)) {
          throw new Error(
            `Incomplete currency data for "${currency}". ` +
            `New currencies require complete baseUnit and units configuration.`
          );
        }
        customMap[currency] = partialData as CurrencyData<any>;
      }
    }

    return customMap;
  }

  /**
   * Deep merge currency data (override defaults with config)
   */
  private static mergeCurrencyData<T extends Currency>(
    defaultData: CurrencyData<T>,
    partialData: PartialCurrencyData<T>,
  ): CurrencyData<T> {
    const mergedUnits = Money.mergeUnits(
      defaultData.units,
      partialData.units || [],
    );

    return {
      baseUnit: partialData.baseUnit ?? defaultData.baseUnit,
      units: mergedUnits,
    };
  }

  /**
   * Merge unit arrays: config units override matching default units by name
   */
  private static mergeUnits<T extends Currency>(
    defaultUnits: Array<UnitData<T>>,
    configUnits: Array<PartialUnitData<T>>,
  ): Array<UnitData<T>> {
    const merged = [...defaultUnits];

    for (const configUnit of configUnits) {
      const index = merged.findIndex((u) => u.name === configUnit.name);
      
      if (index !== -1) {
        // Merge with existing unit
        merged[index] = {
          ...merged[index],
          ...configUnit,
          formatToParts: configUnit.formatToParts ?? merged[index].formatToParts,
          format: configUnit.format ?? merged[index].format,
        } as UnitData<T>;
      } else {
        // New unit - must be complete
        if (!Money.isCompleteUnitData(configUnit)) {
          throw new Error(
            `Incomplete unit data for new unit "${configUnit.name}". ` +
            `All properties required for new units.`
          );
        }
        merged.push(configUnit as UnitData<T>);
      }
    }

    return merged;
  }

  /**
   * Check if currency data is complete (for new currencies)
   */
  private static isCompleteCurrencyData(data: PartialCurrencyData<any>): boolean {
    return (
      data.baseUnit !== undefined &&
      data.units !== undefined &&
      data.units.length > 0 &&
      data.units.every(Money.isCompleteUnitData)
    );
  }

  /**
   * Check if unit data is complete (for new units)
   */
  private static isCompleteUnitData(unit: PartialUnitData<any>): boolean {
    return (
      unit.name !== undefined &&
      unit.decimals !== undefined &&
      unit.symbol !== undefined &&
      unit.factor !== undefined &&
      unit.formatToParts !== undefined &&
      unit.format !== undefined
    );
  }

  /**
   * Get effective currency data (custom override or default)
   */
  private static getEffectiveCurrencyDataMap(): CurrencyDataMap {
    return {
      ...currencyDataMap,
      ...Money.customCurrencyDataMap,
    };
  }

  /**
   * Get currency data for a specific currency
   */
  private static getCurrencyDataFor<T extends Currency>(currency: T): CurrencyData<T> {
    const map = Money.getEffectiveCurrencyDataMap();
    const data = map[currency];
    
    if (!data) {
      throw new Error(
        `Unsupported currency: "${currency}". ` +
        `Register it using Money.configure() or Money.registerCurrency().`
      );
    }
    
    return data;
  }

  // Update all internal methods to use getEffectiveCurrencyDataMap()
  
  private get currencyData(): CurrencyData<T> {
    return Money.getCurrencyDataFor(this.currency);
  }

  private static getCurrencyDataForInput<T extends Currency>(
    data: MoneyInput<T>,
  ): {
    baseUnit: UnitData<T>;
    minUnit: UnitData<T>;
    selectedUnit: UnitData<T> | undefined;
  } {
    const currencyData = Money.getCurrencyDataFor(data.currency);

    const minUnit = currencyData.units.reduce((minItem, currentItem) => {
      return currentItem.factor.lt(minItem.factor) ? currentItem : minItem;
    });
    const baseUnit = currencyData.units.find(
      (x) => x.name === currencyData.baseUnit,
    );
    if (!minUnit || !baseUnit) {
      throw new Error(`Misconfigured currency: ${data.currency}`);
    }

    const selectedUnit = data.unit
      ? currencyData.units.find((x) => x.name === data.unit)
      : undefined;
    if (data.unit && !selectedUnit) {
      throw new Error(
        `Unsupported unit: ${data.unit} for currency ${data.currency}`,
      );
    }

    return { baseUnit, minUnit, selectedUnit };
  }

  // ... rest of Money class remains the same
}

// Update helper functions to use effective map
const getCurrencyData = <T extends Currency>(currency: T) => {
  return Money['getCurrencyDataFor'](currency); // Access private static method
};

// ... rest of file

3. Configuration Examples

Basic: Override base unit for known currency (Agicash use case)

// app/entry.client.tsx

import { Money } from '~/lib/money';

Money.configure({
  currencies: {
    BTC: {
      baseUnit: 'sat', // Override BTC base unit from 'btc' to 'sat'
    },
    // USD not specified - uses default
  },
});

Advanced: Add EUR currency

// app/entry.client.tsx

import { Money } from '~/lib/money';
import { Big } from 'big.js';

Money.configure({
  currencies: {
    BTC: {
      baseUnit: 'sat',
    },
    EUR: {
      baseUnit: 'eur',
      units: [
        {
          name: 'eur',
          decimals: 2,
          symbol: '€',
          factor: new Big(1),
          formatToParts: function(value, options = {}) {
            const formatter = new Intl.NumberFormat(options.locale, {
              style: 'currency',
              currency: 'EUR',
              minimumFractionDigits: options.minimumFractionDigits === 'max' 
                ? this.decimals 
                : options.minimumFractionDigits,
              maximumFractionDigits: this.decimals,
            });
            return formatter.formatToParts(value);
          },
          format: function(value, options = {}) {
            return this.formatToParts(value, options)
              .map(({ value }) => value)
              .join('');
          },
        },
        {
          name: 'cent',
          decimals: 0,
          symbol: 'c',
          factor: new Big(10 ** -2),
          formatToParts: function(value, options = {}) {
            const formatter = new Intl.NumberFormat(options.locale, {
              minimumFractionDigits: options.minimumFractionDigits === 'max' 
                ? this.decimals 
                : options.minimumFractionDigits,
              maximumFractionDigits: this.decimals,
            });
            const parts = formatter.formatToParts(value);
            return [
              ...parts.filter(p => p.type !== 'currency'),
              { type: 'currency' as const, value: this.symbol },
            ];
          },
          format: function(value, options = {}) {
            return this.formatToParts(value, options)
              .map(({ value }) => value)
              .join('');
          },
        },
      ],
    },
  },
});

Using new currency:

// Now EUR works!
const money = new Money({ amount: 100, currency: 'EUR' });
console.log(money.toLocaleString()); // "€100.00"

// TypeScript allows it (Currency = KnownCurrency | string)
// Runtime validates it's registered

4. Update Currency Switcher

// app/features/accounts/default-currency-switcher.tsx

// Instead of hardcoded array:
const CURRENCY_OPTIONS: CurrencyOption[] = [
  { label: 'Bitcoin', currency: 'BTC' },
  { label: 'US Dollar', currency: 'USD' },
  { label: 'Euro', currency: 'EUR' }, // Now possible!
];

// Or fetch from Money class:
const CURRENCY_OPTIONS = Money.getRegisteredCurrencies().map(currency => ({
  label: getCurrencyLabel(currency), // Helper function
  currency,
}));

5. Helper Methods (Optional but useful)

// Add to Money class:

/**
 * Get list of all registered currencies
 */
static getRegisteredCurrencies(): string[] {
  return Object.keys(Money.getEffectiveCurrencyDataMap());
}

/**
 * Check if a currency is registered
 */
static isCurrencyRegistered(currency: string): boolean {
  return currency in Money.getEffectiveCurrencyDataMap();
}

/**
 * Get currency data (useful for displaying available units)
 */
static getCurrencyInfo<T extends Currency>(currency: T): CurrencyData<T> {
  return Money.getCurrencyDataFor(currency);
}

---

Benefits of Hybrid Approach

Aspect	Benefit
Type Safety	Known currencies ('BTC', 'USD') get full autocomplete and compile-time checks
Extensibility	Apps can add any currency at runtime (EUR, GBP, JPY, custom tokens)
Backward Compat	Existing code continues to work without changes
Agicash Use Case	Can configure 'sat' as default AND add EUR if needed in future
Library Reusability	Money class works for any app without code changes
Runtime Safety	Unregistered currencies throw clear errors with instructions

---

Type Safety Comparison

Known currencies (BTC, USD):

// Full type safety
const btc = new Money({ amount: 100, currency: 'BTC', unit: 'sat' }); // ✓
const btc = new Money({ amount: 100, currency: 'BTC', unit: 'eur' }); // ✗ TS error

Custom currencies (EUR):

// Relaxed typing (string units)
const eur = new Money({ amount: 100, currency: 'EUR', unit: 'eur' }); // ✓
const eur = new Money({ amount: 100, currency: 'EUR', unit: 'xyz' }); // ✓ TS, ✗ runtime

This is acceptable because:

1. Known currencies (built into Money library) deserve strict safety
2. Custom currencies (app-specific) can't have strict types (not known at compile time)
3. Runtime validation catches errors for custom currencies

---

Migration Path

Phase 1: Make currency data configurable (current proposal)

• Support overriding existing currency data (BTC, USD)
• Support registering new currencies (EUR, etc.)
• Maintain backward compatibility

Phase 2: Use configuration in Agicash

• Configure BTC baseUnit = 'sat'
• Remove getDefaultUnit() helper
• Update all call sites to use default units

Phase 3: Optional future enhancements

• Add common currencies as presets (EUR, GBP, JPY)
• Currency label configuration
• Currency icon configuration
• UI helpers for currency selection

---

Alternative: Pure String Approach

If you prefer maximum simplicity and flexibility over type safety:

// types.ts
export type Currency = string; // That's it!
export type CurrencyUnit<T extends Currency = Currency> = string;

// No conditional types, no unit mapping, fully dynamic

Pros:

• Simplest possible implementation
• Maximum flexibility
• Easy to understand

Cons:

• Lose ALL type safety for known currencies
• No autocomplete for 'BTC', 'USD'
• Higher chance of typos

---

Recommendation

I recommend the Hybrid Approach because:

1. ✅ Agicash gets type safety for BTC/USD (99% of usage)
2. ✅ Future-proof for adding EUR or other currencies
3. ✅ Minimal complexity increase
4. ✅ Best developer experience (autocomplete + flexibility)
5. ✅ Clear error messages when currency not registered

The pure string approach is simpler but sacrifices too much type safety for the common case.

---

Implementation Plan

If you approve this approach, here's the implementation plan:

1. Update type definitions (types.ts)

   • Add KnownCurrency type
   • Change Currency to union with string
   • Add configuration types

2. Update Money class (money.ts)

   • Add configure() static method
   • Add registerCurrency() helper
   • Add currency data merging logic
   • Update all currency data lookups to use effective map

3. Configure in entry point (entry.client.tsx)

   • Call Money.configure({ currencies: { BTC: { baseUnit: 'sat' } } })

4. Remove getDefaultUnit helper (currencies.ts)

   • Delete file entirely

5. Update all call sites (12+ files)

   • Remove getDefaultUnit() usage
   • Use money.toString() instead of money.toString(getDefaultUnit(...))

6. Run tests and linting

   • bun run fix:all
   • bun test (if approved)

7. Optional: Add EUR example (if desired)

   • Show how to register EUR in docs or example

---

Would you like me to proceed with implementing the hybrid approach? Or would you prefer the simpler pure string approach?

---

[jbojcic1]

@claude can you explore one more option. If we go with hybrid approach is it possible to make it type safe for custom added currencies somehow by using typescript generics?

[claude]

Claude finished @jbojcic1's task in 1m 55s —— View job

---

Exploring Type-Safe Custom Currencies with TypeScript Generics

• Read Money class implementation
• Explore TypeScript generics approaches for runtime-registered types
• Design type-safe configuration system
• Provide concrete examples
• Compare trade-offs with previous hybrid approach

---

Analysis: Type-Safe Custom Currencies with Generics

After exploring TypeScript's capabilities, here are four approaches for achieving type safety with runtime-registered currencies, ranging from simple to sophisticated:

---

Option 1: Module Augmentation (Recommended)

Concept: Allow apps to extend the Money class's type definitions using TypeScript's module augmentation feature. Apps declare their custom currencies in their own type files, and TypeScript merges them with the Money library's types.

Implementation

// app/lib/money/types.ts (Money library)

export type Currency = 'USD' | 'BTC';
export type UsdUnit = 'usd' | 'cent';
export type BtcUnit = 'btc' | 'sat' | 'msat';

// Conditional type for unit mapping
export type CurrencyUnit<T extends Currency = Currency> = T extends 'USD'
  ? UsdUnit
  : T extends 'BTC'
    ? BtcUnit
    : never;

// NEW: Add declaration merging interface for custom currencies
declare global {
  interface CustomCurrencies {
    // Apps will augment this interface with their custom currencies
    // Example: EUR: { units: 'eur' | 'cent' }
  }
}

// Union of built-in and custom currencies
export type AllCurrencies = Currency | keyof CustomCurrencies;

// Enhanced CurrencyUnit that supports custom currencies
export type CurrencyUnit<T extends AllCurrencies = AllCurrencies> = 
  T extends Currency
    ? T extends 'USD'
      ? UsdUnit
      : T extends 'BTC'
        ? BtcUnit
        : never
    : T extends keyof CustomCurrencies
      ? CustomCurrencies[T]['units']
      : string;

// ... rest of types use AllCurrencies instead of Currency

// app/types/currency-augmentation.ts (Agicash app)

import type { Big } from 'big.js';

declare global {
  interface CustomCurrencies {
    EUR: {
      units: 'eur' | 'cent';
    };
    GBP: {
      units: 'gbp' | 'pence';
    };
  }
}

export {}; // Make this a module

// app/entry.client.tsx (Agicash app)

import { Money } from '~/lib/money';
import { Big } from 'big.js';
import '~/types/currency-augmentation'; // Import augmentation

// Configure EUR with full type safety
Money.configure({
  currencies: {
    BTC: {
      baseUnit: 'sat', // ✓ Type-safe
    },
    EUR: {
      baseUnit: 'eur', // ✓ Type-safe (knows about 'eur' | 'cent')
      units: [
        {
          name: 'eur', // ✓ Autocomplete works!
          decimals: 2,
          symbol: '€',
          factor: new Big(1),
          formatToParts: function(value, options = {}) {
            // ... formatter implementation
          },
          format: function(value, options = {}) {
            // ... formatter implementation
          },
        },
        {
          name: 'cent', // ✓ Autocomplete works!
          decimals: 0,
          symbol: 'c',
          factor: new Big(10 ** -2),
          formatToParts: function(value, options = {}) { /* ... */ },
          format: function(value, options = {}) { /* ... */ },
        },
      ],
    },
  },
});

// Using custom currencies with full type safety

// ✓ EUR is now fully type-safe
const money = new Money({ amount: 100, currency: 'EUR', unit: 'eur' });
money.amount('cent'); // ✓ Autocomplete shows 'eur' | 'cent'

// ✗ TypeScript error - 'xyz' is not a valid EUR unit
const invalid = new Money({ amount: 100, currency: 'EUR', unit: 'xyz' });

Pros

• ✅ Full type safety for custom currencies after declaration
• ✅ Autocomplete works for custom currency units
• ✅ Compile-time errors for invalid units
• ✅ App-specific - each app declares only the currencies it needs
• ✅ Clean separation - Money library doesn't need to know about app currencies
• ✅ Standard TypeScript - uses well-known module augmentation pattern

Cons

• ⚠️ Requires an extra type declaration file in the app
• ⚠️ Type safety only applies within the app (not at library boundary)
• ⚠️ Augmentation must be imported/side-effected before use

---

Option 2: Generic Configuration Builder (Type-Safe Config API)

Concept: Use a configuration builder that captures currency types at configuration time and returns a type-safe Money class instance.

Implementation

// app/lib/money/money-factory.ts

import type { Currency, CurrencyUnit, CurrencyData } from './types';
import { Money as BaseMoneyClass } from './money';

type ConfiguredCurrency<
  Name extends string,
  Units extends string
> = {
  name: Name;
  units: Units;
};

type CurrencyConfig<T extends ConfiguredCurrency<string, string>> = {
  baseUnit: T['units'];
  units: Array<{
    name: T['units'];
    decimals: number;
    symbol: string;
    factor: Big;
    formatToParts: (value: number, options?: FormatOptions) => Intl.NumberFormatPart[];
    format: (value: number, options?: FormatOptions) => string;
  }>;
};

class MoneyConfigurator {
  private config: Record<string, CurrencyData<any>> = {};

  /**
   * Register a custom currency with full type safety
   */
  addCurrency<Name extends string, Units extends string>(
    name: Name,
    config: CurrencyConfig<ConfiguredCurrency<Name, Units>>
  ): MoneyConfigurator {
    this.config[name] = config as any;
    return this;
  }

  /**
   * Build and return a configured Money class
   */
  build() {
    BaseMoneyClass.configure({ currencies: this.config });
    return BaseMoneyClass;
  }
}

export function createMoneyConfigurator() {
  return new MoneyConfigurator();
}

// app/entry.client.tsx

import { createMoneyConfigurator } from '~/lib/money/money-factory';
import { Big } from 'big.js';

// Configure with builder pattern
const Money = createMoneyConfigurator()
  .addCurrency('EUR', {
    baseUnit: 'eur', // ✓ Type-safe
    units: [
      {
        name: 'eur', // ✓ Type-safe
        decimals: 2,
        symbol: '€',
        factor: new Big(1),
        formatToParts: function(value, options = {}) { /* ... */ },
        format: function(value, options = {}) { /* ... */ },
      },
      {
        name: 'cent', // ✓ Type-safe
        decimals: 0,
        symbol: 'c',
        factor: new Big(10 ** -2),
        formatToParts: function(value, options = {}) { /* ... */ },
        format: function(value, options = {}) { /* ... */ },
      },
    ],
  })
  .addCurrency('GBP', {
    baseUnit: 'gbp',
    units: [
      { name: 'gbp', /* ... */ },
      { name: 'pence', /* ... */ },
    ],
  })
  .build();

// Export configured Money class
export { Money };

// Using the configured Money class

import { Money } from '~/entry.client';

// ❌ Problem: Lost type information after .build()
const money = new Money({ amount: 100, currency: 'EUR', unit: 'eur' });
// EUR is treated as generic string, not fully type-safe

Pros

• ✅ Type-safe during configuration
• ✅ Fluent builder API
• ✅ Explicit configuration registration

Cons

• ❌ Loses type information after .build() - the returned Money class is generic
• ❌ Cannot infer registered currencies at usage sites
• ❌ More complex implementation
• ⚠️ TypeScript cannot track runtime-registered types through factory functions

---

Option 3: Const Assertion with Type Inference

Concept: Use as const assertions and type inference to capture custom currency configuration types at compile time.

Implementation

// app/lib/money/types.ts

import type { Big } from 'big.js';

export type Currency = 'USD' | 'BTC';

// Helper type to extract currency names from config
type ExtractCurrencyNames<T> = T extends { currencies: infer C } 
  ? C extends Record<infer K extends string, any> 
    ? K 
    : never
  : never;

// Helper type to extract units for a currency from config
type ExtractCurrencyUnits<Config, CurrencyName extends string> = 
  Config extends { currencies: Record<CurrencyName, infer Data> }
    ? Data extends { units: ReadonlyArray<infer Unit> }
      ? Unit extends { name: infer Name }
        ? Name
        : never
      : never
    : never;

// Configuration type with const assertion
export type MoneyConfiguration = {
  currencies?: Record<string, {
    baseUnit?: string;
    units?: ReadonlyArray<{
      readonly name: string;
      readonly decimals: number;
      readonly symbol: string;
      readonly factor: Big;
      readonly formatToParts: (value: number, options?: FormatOptions) => Intl.NumberFormatPart[];
      readonly format: (value: number, options?: FormatOptions) => string;
    }>;
  }>;
};

// Generic Money class that knows about custom config
export class ConfiguredMoney<Config extends MoneyConfiguration> {
  // Type-safe currency based on config
  constructor(data: {
    amount: NumberInput;
    currency: Currency | ExtractCurrencyNames<Config>;
    unit?: ExtractCurrencyUnits<Config, any>; // Can we make this more specific?
  }) {
    // ... implementation
  }
}

// app/entry.client.tsx

import { ConfiguredMoney, type MoneyConfiguration } from '~/lib/money';
import { Big } from 'big.js';

const moneyConfig = {
  currencies: {
    EUR: {
      baseUnit: 'eur',
      units: [
        {
          name: 'eur',
          decimals: 2,
          symbol: '€',
          factor: new Big(1),
          formatToParts: function(v, o) { /* ... */ },
          format: function(v, o) { /* ... */ },
        },
        {
          name: 'cent',
          decimals: 0,
          symbol: 'c',
          factor: new Big(10 ** -2),
          formatToParts: function(v, o) { /* ... */ },
          format: function(v, o) { /* ... */ },
        },
      ] as const, // ← const assertion
    },
  },
} as const satisfies MoneyConfiguration; // ← const assertion + satisfies

export type AppMoneyConfig = typeof moneyConfig;
export class Money extends ConfiguredMoney<AppMoneyConfig> {}

// Using the configured Money class

import { Money } from '~/entry.client';

// ✓ EUR is recognized
const money = new Money({ amount: 100, currency: 'EUR' });

// ❌ Problem: Unit inference is difficult
// TypeScript struggles to infer 'eur' | 'cent' from the config
money.amount('eur'); // May not have autocomplete

Pros

• ✅ Pure TypeScript - no runtime magic
• ✅ Configuration captured at type level with as const
• ✅ Currency names are type-safe

Cons

• ❌ Complex type inference - very difficult to extract unit types correctly
• ❌ Poor DX - requires as const everywhere, verbose
• ❌ Limited unit type safety - hard to infer unit unions from config
• ⚠️ TypeScript's type inference has limits with deeply nested const objects
• ⚠️ Error messages become cryptic

---

Option 4: Code Generation

Concept: Generate TypeScript type definitions from runtime configuration using a build-time code generator.

Implementation

// scripts/generate-currency-types.ts

import fs from 'fs';

const currencyConfig = {
  EUR: {
    units: ['eur', 'cent'],
  },
  GBP: {
    units: ['gbp', 'pence'],
  },
};

// Generate types file
const typeDefinitions = `
// Auto-generated by scripts/generate-currency-types.ts
// Do not edit manually

declare global {
  interface CustomCurrencies {
${Object.entries(currencyConfig)
  .map(([name, { units }]) => 
    `    ${name}: { units: ${units.map(u => `'${u}'`).join(' | ')} };`
  )
  .join('\n')}
  }
}

export {};
`;

fs.writeFileSync('app/types/generated-currencies.d.ts', typeDefinitions);
console.log('Generated currency types');

// app/entry.client.tsx

import { Money } from '~/lib/money';
import '~/types/generated-currencies'; // Import generated types

// Now EUR is fully type-safe!
Money.configure({
  currencies: {
    EUR: {
      baseUnit: 'eur', // ✓ Type-safe
      units: [
        { name: 'eur', /* ... */ }, // ✓ Type-safe
        { name: 'cent', /* ... */ }, // ✓ Type-safe
      ],
    },
  },
});

// package.json
{
  "scripts": {
    "generate:types": "tsx scripts/generate-currency-types.ts",
    "prebuild": "bun run generate:types"
  }
}

Pros

• ✅ Full type safety for generated currencies
• ✅ DRY - single source of truth (config file)
• ✅ Flexible - can generate from JSON, YAML, or TypeScript config
• ✅ No TypeScript hacks - straightforward generated types

Cons

• ❌ Requires build step
• ❌ Generated files to manage
• ❌ More complex tooling
• ⚠️ Types may be out of sync if generation is skipped

---

Comparison Table

Approach	Type Safety	DX	Complexity	Autocomplete	Limitations
Module Augmentation	✅ Full	✅ Good	⭐ Low	✅ Yes	Requires type file
Configuration Builder	⚠️ Partial	⭐ Great	⭐⭐ Medium	❌ Lost after build	Loses types at build
Const Assertion	⚠️ Partial	❌ Poor	⭐⭐⭐ High	⚠️ Limited	Complex inference
Code Generation	✅ Full	✅ Good	⭐⭐ Medium	✅ Yes	Requires build step

---

Detailed Recommendation

For Agicash: Module Augmentation (Option 1)

This is the best balance of simplicity, type safety, and developer experience for a React app.

Why Module Augmentation?

1. Standard TypeScript Pattern: Widely used (e.g., styled-components, @emotion/react, module augmentation for Express.js types)
2. Full Type Safety: Once declared, custom currencies are indistinguishable from built-in ones
3. Minimal Overhead: Just one type declaration file
4. No Build Step: Works with standard TypeScript compilation
5. Great DX: Autocomplete works perfectly after augmentation

Implementation Steps

Step 1: Update Money library types to support augmentation

// app/lib/money/types.ts

export type Currency = 'USD' | 'BTC';
export type UsdUnit = 'usd' | 'cent';
export type BtcUnit = 'btc' | 'sat' | 'msat';

// Allow apps to extend this interface
declare global {
  interface CustomCurrencies {}
}

// All supported currencies (built-in + custom)
export type AllCurrencies = Currency | keyof CustomCurrencies;

// Type-safe unit mapping
type KnownCurrencyUnit<T extends Currency> = T extends 'USD'
  ? UsdUnit
  : T extends 'BTC'
    ? BtcUnit
    : never;

export type CurrencyUnit<T extends AllCurrencies = AllCurrencies> = 
  T extends Currency
    ? KnownCurrencyUnit<T>
    : T extends keyof CustomCurrencies
      ? CustomCurrencies[T] extends { units: infer U }
        ? U
        : string
      : string;

// Update other types to use AllCurrencies
export type MoneyInput<T extends AllCurrencies = AllCurrencies> = {
  amount: NumberInput;
  currency: T;
  unit?: CurrencyUnit<T>;
};

// ... rest of types updated similarly

Step 2: Update Money class to accept AllCurrencies

// app/lib/money/money.ts

export class Money<T extends AllCurrencies = AllCurrencies> {
  // ... implementation remains mostly the same
  // Just replace Currency with AllCurrencies in type parameters
}

Step 3: Create currency augmentation file in app

// app/types/custom-currencies.d.ts

declare global {
  interface CustomCurrencies {
    EUR: {
      units: 'eur' | 'cent';
    };
  }
}

export {}; // Make it a module

Step 4: Configure and use

// app/entry.client.tsx

import '~/types/custom-currencies'; // Side-effect import for augmentation
import { Money } from '~/lib/money';

Money.configure({
  currencies: {
    BTC: {
      baseUnit: 'sat', // ✓ Type-safe
    },
    EUR: {
      baseUnit: 'eur', // ✓ Type-safe
      units: [
        { name: 'eur', /* ... */ }, // ✓ Autocomplete works!
        { name: 'cent', /* ... */ }, // ✓ Autocomplete works!
      ],
    },
  },
});

// Anywhere in the app

import { Money } from '~/lib/money';

// ✓ Full type safety
const euros = new Money({ amount: 100, currency: 'EUR', unit: 'eur' });
euros.amount('cent'); // ✓ Autocomplete: 'eur' | 'cent'

// ✗ TypeScript error
const invalid = new Money({ amount: 100, currency: 'EUR', unit: 'xyz' });
//                                                                ^^^^^ Type error!

---

Alternative for Maximum Flexibility: Hybrid (Module Augmentation Optional)

If you want to support both type-safe custom currencies (via augmentation) and fully dynamic currencies (for runtime-only scenarios), you can use:

// Allow both augmented currencies AND any string
export type AllCurrencies = Currency | keyof CustomCurrencies | string;

// Unit mapping with fallback
export type CurrencyUnit<T extends AllCurrencies = AllCurrencies> = 
  T extends Currency
    ? KnownCurrencyUnit<T>
    : T extends keyof CustomCurrencies
      ? CustomCurrencies[T] extends { units: infer U }
        ? U
        : string
      : string; // ← Fallback to string for fully dynamic currencies

This way:

• Apps that want type safety can augment CustomCurrencies
• Apps that need dynamic currencies can use strings without augmentation
• Best of both worlds!

---

Summary

Recommendation: Module Augmentation (Option 1) with optional dynamic currency support.

Why?

• ✅ Achieves full type safety for custom currencies
• ✅ Standard TypeScript pattern (like styled-components)
• ✅ Minimal complexity (just one type file)
• ✅ Great developer experience with autocomplete
• ✅ No build step required
• ✅ Can coexist with dynamic currencies if needed

Trade-off: Requires apps to create a type declaration file for custom currencies, but this is a small price for full type safety.

Would you like me to implement the module augmentation approach?

---

[jbojcic1]

@claude with module augmentation you mentioned this con Type safety only applies within the app (not at library boundary). Can you expand on that? What does it mean in practice?

[claude]

Claude finished @jbojcic1's task in 59s —— View job

---

Clarifying "Type Safety at Library Boundary"

• Understand the question about module augmentation limitations
• Prepare concrete examples showing boundary issues
• Explain practical implications

---

Great question! Let me clarify what "type safety only applies within the app (not at library boundary)" means with concrete examples.

What is the "Library Boundary"?

The library boundary is the interface between:

• Inside the library: The Money class code itself (in app/lib/money/)
• Outside the library: The application code that uses the Money class (in app/features/, app/routes/, etc.)

The Core Issue

With module augmentation, the Money library's internal implementation doesn't know about custom currencies at compile time. Only the consuming application knows about them after augmentation.

Practical Example: Where It Works ✅

// app/types/custom-currencies.d.ts
declare global {
  interface CustomCurrencies {
    EUR: { units: 'eur' | 'cent' };
  }
}

// app/features/payments/some-component.tsx
import { Money } from '~/lib/money';

// ✅ WORKS: Full type safety in application code
const euros = new Money({ 
  amount: 100, 
  currency: 'EUR',  // ✓ TypeScript knows 'EUR' is valid
  unit: 'eur'       // ✓ Autocomplete shows 'eur' | 'cent'
});

euros.amount('cent'); // ✓ Autocomplete works!
euros.toString();     // ✓ Works perfectly

Why it works: Your application code has imported the augmentation, so TypeScript knows about EUR and its units.

---

Where It Doesn't Work ❌

Problem 1: Generic Functions Inside the Library

// app/lib/money/money.ts (INSIDE the library)

export class Money<T extends AllCurrencies = AllCurrencies> {
  
  // This function is defined INSIDE the library
  static sum<T extends AllCurrencies>(moneys: Money<T>[]): Money<T> {
    // ❌ TypeScript here doesn't know about EUR at compile time
    // because the library is compiled independently
    
    if (moneys.length === 0) {
      throw new Error('Cannot sum empty array');
    }
    
    const currency = moneys[0].currency;
    
    // ❌ If this code tried to do currency-specific logic:
    if (currency === 'EUR') {  
      // ^ TypeScript error: 'EUR' is not assignable to type 'USD' | 'BTC'
      // The library doesn't know about EUR!
    }
    
    return moneys.reduce((sum, money) => sum.add(money));
  }
}

Why it fails: When the Money library is compiled, TypeScript doesn't know about EUR because the augmentation happens in the app code, not the library code.

Problem 2: Library Helper Functions

// app/lib/money/utils.ts (INSIDE the library)

import type { AllCurrencies } from './types';

// This function is part of the library
export function getCurrencySymbol<T extends AllCurrencies>(
  currency: T
): string {
  // ❌ Can't use switch with exhaustiveness checking for custom currencies
  switch (currency) {
    case 'BTC':
      return '₿';
    case 'USD':
      return '$';
    // EUR is not known here - TypeScript can't enforce it
    default:
      throw new Error(`Unknown currency: ${currency}`);
  }
}

Why it fails: The library code is compiled separately and doesn't have access to the augmented types from the application.

---

What This Means in Practice

✅ You CAN do (Application side - where augmentation is imported):

1. Create Money instances with custom currencies

   const eur = new Money({ amount: 100, currency: 'EUR' });

2. Get full autocomplete for custom currency units

   eur.amount('cent'); // ✓ Autocomplete: 'eur' | 'cent'

3. Type-safe operations on custom currency instances

   const double = eur.multiply(2);
   const formatted = eur.toLocaleString();

4. Type-safe conditionals in your app code

   if (money.currency === 'EUR') {
     // ✓ TypeScript knows EUR is valid here
   }

❌ You CANNOT do (Library side - internal implementation):

1. Library functions can't have compile-time knowledge of custom currencies

   // Inside Money class:
   static someLibraryMethod() {
     if (currency === 'EUR') {  // ❌ TypeScript error
       // ...
     }
   }

2. Can't use exhaustive switch statements on custom currencies in library code

   // Inside library utils:
   switch (currency) {
     case 'BTC': return '₿';
     case 'USD': return '$';
     case 'EUR': return '€';  // ❌ TypeScript error - EUR unknown
   }

3. Generic constraints in library code can't reference custom currencies

   // Inside Money class:
   static onlyEuros<T extends 'EUR'>(money: Money<T>) {
     // ❌ TypeScript error: 'EUR' is not a valid currency
   }

---

Is This a Problem for Agicash?

Short answer: No, this is not a problem.

Why not:

1. The Money library is generic - it doesn't need to know about specific currencies
2. All currency-specific logic happens at runtime via the configuration system
3. Application code gets full type safety where it matters (your components, hooks, services)
4. The library boundary limitation only affects library internals, not your app

Real-World Scenario

Let's trace through a real use case to show it works fine:

// 1. Configure EUR in entry.client.tsx ✓
Money.configure({
  currencies: {
    EUR: {
      baseUnit: 'eur',
      units: [ /* ... */ ]
    }
  }
});

// 2. Use EUR in your app component ✓
function PaymentForm() {
  const [amount, setAmount] = useState(
    new Money({ amount: 0, currency: 'EUR' }) // ✓ Type-safe!
  );
  
  const formatted = amount.toLocaleString(); // ✓ Works!
  const doubled = amount.multiply(2);        // ✓ Works!
  
  return <div>{formatted}</div>;
}

// 3. Even complex operations work ✓
function convertEurToUsd(eur: Money<'EUR'>, rate: number): Money<'USD'> {
  // ✓ Type-safe function signature in app code!
  const eurAmount = eur.amount('eur');
  return new Money({ 
    amount: eurAmount * rate, 
    currency: 'USD' 
  });
}

Everything works because:

• Your application code (where you use Money) has the augmentation imported
• The Money class methods are generic and work with any currency at runtime
• Type safety is enforced at the call sites in your app

---

When Would This Actually Be a Problem?

The boundary limitation would only matter if:

1. You wanted to extend the Money library itself with EUR-specific logic

   // If you wanted to add this INSIDE the Money class:
   get isEuropeanCurrency(): boolean {
     return this.currency === 'EUR'; // ❌ Won't work in library code
   }

   Solution: Add such logic in your app code instead:

   // In your app (outside the library):
   function isEuropeanCurrency(money: Money): boolean {
     return money.currency === 'EUR'; // ✓ Works fine!
   }

2. You needed exhaustive type checking of currencies in library code

   • This isn't needed because the library is currency-agnostic
   • All currency-specific behavior is data-driven (via configuration)

---

Comparison: How Would Other Approaches Handle This?

Pure String Approach (Currency = string):

• ❌ Same limitation at library boundary
• ❌ Also loses type safety in application code

Code Generation:

• ✅ Library boundary not an issue (types are generated)
• ❌ Requires build step
• ❌ More tooling complexity

Module Augmentation:

• ⚠️ Library boundary limitation exists
• ✅ But full type safety where it matters (app code)
• ✅ No build step
• ✅ Simple implementation

---

Bottom Line

The "library boundary" limitation means:

• The Money library's internal code doesn't know about EUR at compile time
• Your application code gets full type safety for EUR
• This is not a problem in practice because:
  • The library is designed to be generic
  • All your actual usage (in components, hooks, etc.) is type-safe
  • Any EUR-specific logic can go in your app code, not the library

Think of it like this: The Money class is like a generic container that works with any currency. It doesn't need to know the specific currencies at compile time—that's what the runtime configuration is for. Your application code, which does know about EUR (via augmentation), can use the Money class with full type safety.

Does this clarify the limitation? Let me know if you want me to explore any specific scenario!

---

[jbojcic1]

@claude It does clarify. Ok lets implement this with module augmentation with option to also add it without augmentation (Hybrid (Module Augmentation Optional) approach mentioned above). Not that we are clear that we want that, please just print once more the detailed plan for me to confirm before we start the implementation.

[claude]

Claude finished @jbojcic1's task in 1m 47s —— View job

---

Implementation Plan: Hybrid Module Augmentation Approach

• Understand the request for detailed plan
• Gather context from codebase
• Present comprehensive implementation plan for approval

---

Complete Implementation Plan

Here's the detailed plan for implementing the Hybrid Module Augmentation approach that allows both:

• ✅ Type-safe custom currencies (via TypeScript module augmentation)
• ✅ Fully dynamic currencies (runtime-only, without augmentation)

---

Phase 1: Update Type System (app/lib/money/types.ts)

1.1 Add Global Interface for Custom Currencies

// Add after existing type definitions, before other exports

declare global {
  /**
   * Extend this interface to add type-safe custom currencies.
   * 
   * Example:
   * ```typescript
   * declare global {
   *   interface CustomCurrencies {
   *     EUR: { units: 'eur' | 'cent' };
   *   }
   * }
   * ```
   */
  interface CustomCurrencies {
    // Apps will augment this interface with their custom currencies
  }
}

1.2 Update Currency Type

// Change from:
export type Currency = 'USD' | 'BTC';

// To:
/** Built-in currencies with full type support */
export type KnownCurrency = 'USD' | 'BTC';

/** All supported currencies: known currencies, custom currencies, and runtime strings */
export type Currency = KnownCurrency | keyof CustomCurrencies | (string & {});
// Note: `(string & {})` is a TypeScript trick to allow any string while preserving autocomplete for known types

1.3 Update CurrencyUnit Type

// Change from:
export type CurrencyUnit<T extends Currency = Currency> = T extends 'USD'
  ? UsdUnit
  : T extends 'BTC'
    ? BtcUnit
    : never;

// To:
type KnownCurrencyUnit<T extends KnownCurrency> = T extends 'USD'
  ? UsdUnit
  : T extends 'BTC'
    ? BtcUnit
    : never;

export type CurrencyUnit<T extends Currency = Currency> = 
  T extends KnownCurrency
    ? KnownCurrencyUnit<T>
    : T extends keyof CustomCurrencies
      ? CustomCurrencies[T] extends { units: infer U }
        ? U
        : string
      : string;

1.4 Add Configuration Types

// Add new types for configuration

/**
 * Partial unit data for configuration (functions optional for overrides)
 */
export type PartialUnitData<T extends Currency> = {
  name: CurrencyUnit<T>;
  decimals?: number;
  symbol?: string;
  factor?: Big;
  formatToParts?: (
    value: number,
    options?: FormatOptions,
  ) => Intl.NumberFormatPart[];
  format?: (value: number, options?: FormatOptions) => string;
};

/**
 * Complete unit data (all fields required for new units)
 */
export type CompleteUnitData<T extends Currency> = {
  name: CurrencyUnit<T>;
  decimals: number;
  symbol: string;
  factor: Big;
  formatToParts: (
    value: number,
    options?: FormatOptions,
  ) => Intl.NumberFormatPart[];
  format: (value: number, options?: FormatOptions) => string;
};

/**
 * Partial currency data for configuration
 */
export type PartialCurrencyData<T extends Currency> = {
  baseUnit?: CurrencyUnit<T>;
  units?: Array<PartialUnitData<T>>;
};

/**
 * Complete currency data (all fields required for new currencies)
 */
export type CompleteCurrencyData<T extends Currency> = {
  baseUnit: CurrencyUnit<T>;
  units: Array<CompleteUnitData<T>>;
};

/**
 * Configuration for Money class
 */
export type MoneyConfiguration = {
  currencies?: {
    [K in Currency]?: PartialCurrencyData<K>;
  };
};

1.5 Update CurrencyDataMap Type

// Change from:
export type CurrencyDataMap = {
  [K in Currency]: CurrencyData<K>;
};

// To:
export type CurrencyDataMap = {
  [key: string]: CurrencyData<any>;
};

---

Phase 2: Update Money Class (app/lib/money/money.ts)

2.1 Add Configuration State

// Add at the top of the Money class (inside the class definition)

export class Money<T extends Currency = Currency> {
  private static configuration: MoneyConfiguration = {};
  private static customCurrencyDataMap: CurrencyDataMap = {};
  private static isConfigured = false;

  // ... rest of class
}

2.2 Add Configuration Methods

// Add static methods to Money class

/**
 * Configure Money class with custom currency data.
 * Should be called once at app initialization.
 * 
 * @example
 * ```typescript
 * Money.configure({
 *   currencies: {
 *     BTC: { baseUnit: 'sat' }, // Override BTC base unit
 *     EUR: { // Add new currency
 *       baseUnit: 'eur',
 *       units: [...]
 *     }
 *   }
 * });
 * ```
 */
static configure(config: MoneyConfiguration): void {
  if (Money.isConfigured) {
    console.warn(
      'Money.configure() called multiple times. Later calls override earlier ones.'
    );
  }
  
  Money.configuration = config;
  Money.customCurrencyDataMap = Money.buildCurrencyDataMap(config);
  Money.isConfigured = true;
}

/**
 * Reset configuration to defaults (useful for testing)
 */
static resetConfiguration(): void {
  Money.configuration = {};
  Money.customCurrencyDataMap = {};
  Money.isConfigured = false;
}

/**
 * Get list of all registered currencies (built-in + custom)
 */
static getRegisteredCurrencies(): string[] {
  const effectiveMap = Money.getEffectiveCurrencyDataMap();
  return Object.keys(effectiveMap);
}

/**
 * Check if a currency is registered
 */
static isCurrencyRegistered(currency: string): boolean {
  const effectiveMap = Money.getEffectiveCurrencyDataMap();
  return currency in effectiveMap;
}

2.3 Add Configuration Building Logic

// Add private static methods for building configuration

/**
 * Build currency data map from configuration
 */
private static buildCurrencyDataMap(config: MoneyConfiguration): CurrencyDataMap {
  const customMap: CurrencyDataMap = {};

  if (!config.currencies) {
    return customMap;
  }

  for (const [currency, partialData] of Object.entries(config.currencies)) {
    // Check if this is overriding a known currency
    const defaultData = currencyDataMap[currency];

    if (defaultData && partialData) {
      // Merge with default data
      customMap[currency] = Money.mergeCurrencyData(
        defaultData,
        partialData,
      );
    } else if (partialData) {
      // New currency - validate it's complete
      if (!Money.isCompleteCurrencyData(partialData)) {
        throw new Error(
          `Incomplete currency data for "${currency}". ` +
          `New currencies require complete baseUnit and units configuration.`
        );
      }
      customMap[currency] = partialData as CurrencyData<any>;
    }
  }

  return customMap;
}

/**
 * Deep merge currency data (override defaults with config)
 */
private static mergeCurrencyData<T extends Currency>(
  defaultData: CurrencyData<T>,
  partialData: PartialCurrencyData<T>,
): CurrencyData<T> {
  const mergedUnits = Money.mergeUnits(
    defaultData.units,
    partialData.units || [],
  );

  return {
    baseUnit: partialData.baseUnit ?? defaultData.baseUnit,
    units: mergedUnits,
  };
}

/**
 * Merge unit arrays: config units override matching default units by name
 */
private static mergeUnits<T extends Currency>(
  defaultUnits: Array<UnitData<T>>,
  configUnits: Array<PartialUnitData<T>>,
): Array<UnitData<T>> {
  const merged = [...defaultUnits];

  for (const configUnit of configUnits) {
    const index = merged.findIndex((u) => u.name === configUnit.name);
    
    if (index !== -1) {
      // Merge with existing unit (override specified properties)
      merged[index] = {
        ...merged[index],
        ...configUnit,
        // Keep default formatting functions if not provided
        formatToParts: configUnit.formatToParts ?? merged[index].formatToParts,
        format: configUnit.format ?? merged[index].format,
      } as UnitData<T>;
    } else {
      // New unit - must be complete
      if (!Money.isCompleteUnitData(configUnit)) {
        throw new Error(
          `Incomplete unit data for new unit "${configUnit.name}". ` +
          `All properties (decimals, symbol, factor, formatToParts, format) are required for new units.`
        );
      }
      merged.push(configUnit as UnitData<T>);
    }
  }

  return merged;
}

/**
 * Check if currency data is complete (for new currencies)
 */
private static isCompleteCurrencyData(
  data: PartialCurrencyData<any>
): data is CompleteCurrencyData<any> {
  return (
    data.baseUnit !== undefined &&
    data.units !== undefined &&
    data.units.length > 0 &&
    data.units.every(Money.isCompleteUnitData)
  );
}

/**
 * Check if unit data is complete (for new units)
 */
private static isCompleteUnitData(
  unit: PartialUnitData<any>
): unit is CompleteUnitData<any> {
  return (
    unit.decimals !== undefined &&
    unit.symbol !== undefined &&
    unit.factor !== undefined &&
    unit.formatToParts !== undefined &&
    unit.format !== undefined
  );
}

/**
 * Get effective currency data map (custom overrides + defaults)
 */
private static getEffectiveCurrencyDataMap(): CurrencyDataMap {
  return {
    ...currencyDataMap,
    ...Money.customCurrencyDataMap,
  };
}

/**
 * Get currency data for a specific currency
 */
private static getCurrencyDataFor<T extends Currency>(currency: T): CurrencyData<T> {
  const map = Money.getEffectiveCurrencyDataMap();
  const data = map[currency];
  
  if (!data) {
    throw new Error(
      `Unsupported currency: "${currency}". ` +
      `Register it using Money.configure().`
    );
  }
  
  return data;
}

2.4 Update Existing Methods to Use Effective Map

Update these existing methods/getters:

// Change from:
private get currencyData(): CurrencyData<T> {
  return currencyDataMap[this.currency];
}

// To:
private get currencyData(): CurrencyData<T> {
  return Money.getCurrencyDataFor(this.currency);
}

// Change from (in getCurrencyDataForInput):
const currencyData = currencyDataMap[data.currency];

// To:
const currencyData = Money.getCurrencyDataFor(data.currency);

2.5 Update Helper Functions

// Update these standalone helper functions to use effective map:

const getCurrencyData = <T extends Currency>(currency: T) => {
  // Change from:
  // const currencyData = currencyDataMap[currency];
  
  // To:
  return Money['getCurrencyDataFor'](currency);
};

const getCurrencyBaseUnit = <T extends Currency>(currency: T) => {
  const currencyData = getCurrencyData(currency);
  const baseUnit = currencyData.units.find(
    (x) => x.name === currencyData.baseUnit,
  );
  if (!baseUnit) {
    throw new Error(`Misconfigured currency: ${currency}`);
  }
  return baseUnit;
};

const getCurrencyMinUnit = <T extends Currency>(currency: T) => {
  const currencyData = getCurrencyData(currency);
  const minUnit = currencyData.units.sort((a, b) => a.factor.cmp(b.factor))[0];
  if (!minUnit) {
    throw new Error(`Misconfigured currency: ${currency}`);
  }
  return minUnit;
};

---

Phase 3: Configure Money Class in Entry Point (app/entry.client.tsx)

3.1 Add Configuration Call

// Add near the top of entry.client.tsx, after imports

import { Money } from '~/lib/money';

// Configure Money class for Agicash
Money.configure({
  currencies: {
    BTC: {
      baseUnit: 'sat', // Override BTC base unit from 'btc' to 'sat'
    },
    // USD not specified - uses all defaults
  },
});

// ... rest of entry.client.tsx

---

Phase 4: Remove getDefaultUnit Helper

4.1 Delete currencies.ts File

# Delete the file entirely
rm app/features/shared/currencies.ts

---

Phase 5: Update All Call Sites (12 files)

Update all files that use getDefaultUnit:

Files to Update:

1. app/hooks/use-money-input.ts
2. app/features/transactions/transaction-details.tsx
3. app/features/transactions/transaction-list.tsx
4. app/features/shared/money-with-converted-amount.tsx
5. app/features/shared/spark.ts
6. app/features/send/send-confirmation.tsx
7. app/features/send/send-input.tsx
8. app/features/send/cashu-send-quote-service.ts
9. app/features/send/cashu-send-swap-service.ts
10. app/features/receive/receive-cashu.tsx
11. app/features/receive/receive-input.tsx

Pattern to Replace:

// Before:
import { getDefaultUnit } from '~/features/shared/currencies';
money.toString(getDefaultUnit(money.currency))
money.toLocaleString({ unit: getDefaultUnit(money.currency) })

// After:
money.toString() // Uses configured baseUnit automatically
money.toLocaleString() // Uses configured baseUnit automatically

---

Phase 6: Optional - Add Type Augmentation Example

6.1 Create Example File (for documentation)

Create app/types/custom-currencies.example.d.ts:

/**
 * Example of how to add type-safe custom currencies to Money class.
 * 
 * To use this:
 * 1. Copy this file to `app/types/custom-currencies.d.ts`
 * 2. Uncomment the currencies you want to add
 * 3. Configure them in `app/entry.client.tsx`
 * 
 * Note: This provides compile-time type safety for custom currencies.
 * You can also add currencies at runtime without augmentation,
 * but they will be typed as generic strings.
 */

declare global {
  interface CustomCurrencies {
    // Example: Add Euro
    // EUR: {
    //   units: 'eur' | 'cent';
    // };
    
    // Example: Add British Pound
    // GBP: {
    //   units: 'gbp' | 'pence';
    // };
  }
}

export {};

---

Testing Strategy

Test Cases to Add (if tests are approved):

1. Configuration Tests

   • Test overriding baseUnit for known currency (BTC → sat)
   • Test adding complete new currency
   • Test partial unit override (change symbol only)
   • Test error when incomplete currency data provided
   • Test error when incomplete unit data provided

2. Type Safety Tests (compile-time)

   • Known currencies have autocomplete (BTC, USD)
   • Custom currencies work after augmentation
   • Runtime strings allowed for dynamic currencies

3. Integration Tests

   • Money operations work with custom currencies
   • Formatting works with custom currencies
   • Conversion works between known and custom currencies

---

Migration Impact Analysis

Files Changed:

• Modified: 14 files (2 library files + 12 call sites)
• Deleted: 1 file (currencies.ts)
• Created: 1 example file (optional)

Breaking Changes:

• None for existing Money class API
• getDefaultUnit helper removed (internal to app)

Risk Level: Low

• Type system changes are backward compatible
• Existing Money class functionality unchanged
• Configuration is optional (defaults work without it)

---

Implementation Order

1. ✅ Phase 1: Update type system (types.ts)
2. ✅ Phase 2: Update Money class (money.ts)
3. ✅ Phase 3: Add configuration (entry.client.tsx)
4. ✅ Phase 4: Delete getDefaultUnit file
5. ✅ Phase 5: Update all call sites (12 files)
6. ✅ Phase 6: Add example documentation (optional)
7. ✅ Run linting: bun run fix:all
8. ✅ Run tests: If approved by user

---

Expected Outcome

Before:

import { getDefaultUnit } from '~/features/shared/currencies';

const btc = new Money({ amount: 100, currency: 'BTC' });
const formatted = btc.toLocaleString({ 
  unit: getDefaultUnit(btc.currency) // Returns 'sat'
});
// Output: "₿100" (shows 100 sats)

After:

// Configuration in entry.client.tsx:
Money.configure({
  currencies: {
    BTC: { baseUnit: 'sat' }
  }
});

// Usage anywhere in app:
const btc = new Money({ amount: 100, currency: 'BTC' });
const formatted = btc.toLocaleString(); // Automatically uses 'sat'
// Output: "₿100" (shows 100 sats)

// Bonus: Add EUR with type safety
declare global {
  interface CustomCurrencies {
    EUR: { units: 'eur' | 'cent' };
  }
}

Money.configure({
  currencies: {
    EUR: {
      baseUnit: 'eur',
      units: [/* ... */]
    }
  }
});

const eur = new Money({ amount: 100, currency: 'EUR' }); // ✓ Type-safe!

---

Summary

This implementation provides:

✅ Configurability: Override currency defaults (baseUnit, units, symbols, etc.)
✅ Type Safety: Known currencies (BTC, USD) keep full autocomplete
✅ Extensibility: Add custom currencies (EUR, GBP, etc.) with optional type safety
✅ Flexibility: Support both augmented (type-safe) and dynamic (runtime) currencies
✅ Backward Compatibility: Existing Money class API unchanged
✅ Clean Code: Removes getDefaultUnit workaround
✅ Single Source of Truth: Configuration in one place (entry.client.tsx)

---

Please confirm if this plan looks good to proceed with implementation!

[jbojcic1]

@claude looks good, I would just like if you could somehow extract configuration merge and build code outside the Money class so it doesn't clutter the actual money operations which are the primary concern of that class. Can you give some ideas for that?

[claude]

Claude finished @jbojcic1's task in 1m 57s —— View job

---

Exploring Configuration Extraction Options

• Read current Money class implementation
• Analyze configuration logic from plan
• Design architectural alternatives
• Provide code examples and trade-offs
• Make recommendation

---

Current Structure Analysis

The Money class (660 lines) currently handles:

• Core money operations: add, subtract, multiply, divide, comparisons
• Formatting: toString, toLocaleString, toLocalizedStringParts
• Conversions: convert, toNumber, toJSON
• Currency data access: via hardcoded currencyDataMap

The planned configuration logic would add ~150-200 lines of:

• Configuration state management
• Deep merge logic for currency data
• Validation for complete/incomplete data
• Registry methods

This would make the Money class ~850 lines and mix two concerns:

1. Money operations (core domain logic)
2. Configuration management (infrastructure/setup)

---

Architectural Options for Extracting Configuration

Option 1: Separate CurrencyRegistry Class (Recommended)

Concept: Extract all configuration logic into a dedicated CurrencyRegistry class that the Money class depends on.

Structure

app/lib/money/
├── money.ts                    # Money class (operations only)
├── currency-registry.ts        # NEW: Configuration & registry
├── currency-data.ts            # Default currency definitions (extracted)
├── types.ts                    # Type definitions
└── index.ts                    # Public exports

Implementation

// app/lib/money/currency-registry.ts

import type { Big } from 'big.js';
import type {
  Currency,
  CurrencyData,
  CurrencyDataMap,
  PartialCurrencyData,
  MoneyConfiguration,
  UnitData,
  PartialUnitData,
  CompleteCurrencyData,
  CompleteUnitData,
} from './types';
import { defaultCurrencyDataMap } from './currency-data';

/**
 * Registry for currency configuration.
 * Manages currency data and allows runtime configuration.
 */
export class CurrencyRegistry {
  private static instance: CurrencyRegistry | null = null;
  private customCurrencyDataMap: CurrencyDataMap = {};
  private isConfigured = false;

  private constructor() {}

  /**
   * Get the singleton instance
   */
  static getInstance(): CurrencyRegistry {
    if (!CurrencyRegistry.instance) {
      CurrencyRegistry.instance = new CurrencyRegistry();
    }
    return CurrencyRegistry.instance;
  }

  /**
   * Configure currency data. Should be called once at app initialization.
   */
  configure(config: MoneyConfiguration): void {
    if (this.isConfigured) {
      console.warn(
        'CurrencyRegistry.configure() called multiple times. Later calls override earlier ones.'
      );
    }
    
    this.customCurrencyDataMap = this.buildCurrencyDataMap(config);
    this.isConfigured = true;
  }

  /**
   * Reset configuration (useful for testing)
   */
  reset(): void {
    this.customCurrencyDataMap = {};
    this.isConfigured = false;
  }

  /**
   * Get currency data for a specific currency
   */
  getCurrencyData<T extends Currency>(currency: T): CurrencyData<T> {
    const effectiveMap = this.getEffectiveCurrencyDataMap();
    const data = effectiveMap[currency];
    
    if (!data) {
      throw new Error(
        `Unsupported currency: "${currency}". ` +
        `Register it using Money.configure().`
      );
    }
    
    return data;
  }

  /**
   * Get list of all registered currencies
   */
  getRegisteredCurrencies(): string[] {
    return Object.keys(this.getEffectiveCurrencyDataMap());
  }

  /**
   * Check if a currency is registered
   */
  isCurrencyRegistered(currency: string): boolean {
    return currency in this.getEffectiveCurrencyDataMap();
  }

  /**
   * Get effective currency data map (custom overrides + defaults)
   */
  private getEffectiveCurrencyDataMap(): CurrencyDataMap {
    return {
      ...defaultCurrencyDataMap,
      ...this.customCurrencyDataMap,
    };
  }

  /**
   * Build currency data map from configuration
   */
  private buildCurrencyDataMap(config: MoneyConfiguration): CurrencyDataMap {
    const customMap: CurrencyDataMap = {};

    if (!config.currencies) {
      return customMap;
    }

    for (const [currency, partialData] of Object.entries(config.currencies)) {
      const defaultData = defaultCurrencyDataMap[currency];

      if (defaultData && partialData) {
        // Merge with default data
        customMap[currency] = this.mergeCurrencyData(defaultData, partialData);
      } else if (partialData) {
        // New currency - validate it's complete
        if (!this.isCompleteCurrencyData(partialData)) {
          throw new Error(
            `Incomplete currency data for "${currency}". ` +
            `New currencies require complete baseUnit and units configuration.`
          );
        }
        customMap[currency] = partialData as CurrencyData<any>;
      }
    }

    return customMap;
  }

  /**
   * Deep merge currency data
   */
  private mergeCurrencyData<T extends Currency>(
    defaultData: CurrencyData<T>,
    partialData: PartialCurrencyData<T>,
  ): CurrencyData<T> {
    const mergedUnits = this.mergeUnits(
      defaultData.units,
      partialData.units || [],
    );

    return {
      baseUnit: partialData.baseUnit ?? defaultData.baseUnit,
      units: mergedUnits,
    };
  }

  /**
   * Merge unit arrays
   */
  private mergeUnits<T extends Currency>(
    defaultUnits: Array<UnitData<T>>,
    configUnits: Array<PartialUnitData<T>>,
  ): Array<UnitData<T>> {
    const merged = [...defaultUnits];

    for (const configUnit of configUnits) {
      const index = merged.findIndex((u) => u.name === configUnit.name);
      
      if (index !== -1) {
        // Merge with existing unit
        merged[index] = {
          ...merged[index],
          ...configUnit,
          formatToParts: configUnit.formatToParts ?? merged[index].formatToParts,
          format: configUnit.format ?? merged[index].format,
        } as UnitData<T>;
      } else {
        // New unit - must be complete
        if (!this.isCompleteUnitData(configUnit)) {
          throw new Error(
            `Incomplete unit data for new unit "${configUnit.name}". ` +
            `All properties required for new units.`
          );
        }
        merged.push(configUnit as UnitData<T>);
      }
    }

    return merged;
  }

  private isCompleteCurrencyData(
    data: PartialCurrencyData<any>
  ): data is CompleteCurrencyData<any> {
    return (
      data.baseUnit !== undefined &&
      data.units !== undefined &&
      data.units.length > 0 &&
      data.units.every(this.isCompleteUnitData)
    );
  }

  private isCompleteUnitData(
    unit: PartialUnitData<any>
  ): unit is CompleteUnitData<any> {
    return (
      unit.decimals !== undefined &&
      unit.symbol !== undefined &&
      unit.factor !== undefined &&
      unit.formatToParts !== undefined &&
      unit.format !== undefined
    );
  }
}

// app/lib/money/currency-data.ts (NEW file)
// Extract default currency definitions

import { Big } from 'big.js';
import type { CurrencyDataMap } from './types';

// ... move getCurrencyFormatter, trimWhitespaceFromEnds here

export const defaultCurrencyDataMap: CurrencyDataMap = {
  USD: { /* ... current USD definition ... */ },
  BTC: { /* ... current BTC definition ... */ },
};

// app/lib/money/money.ts (updated)

import { CurrencyRegistry } from './currency-registry';

export class Money<T extends Currency = Currency> {
  private static registry = CurrencyRegistry.getInstance();

  /**
   * Configure Money class. Delegates to CurrencyRegistry.
   */
  static configure(config: MoneyConfiguration): void {
    Money.registry.configure(config);
  }

  /**
   * Get registered currencies
   */
  static getRegisteredCurrencies(): string[] {
    return Money.registry.getRegisteredCurrencies();
  }

  // ... rest of Money class uses registry:
  
  private get currencyData(): CurrencyData<T> {
    return Money.registry.getCurrencyData(this.currency);
  }

  private static getCurrencyDataForInput<T extends Currency>(
    data: MoneyInput<T>,
  ) {
    const currencyData = Money.registry.getCurrencyData(data.currency);
    // ... rest of logic
  }
}

// Helper functions also use registry
const getCurrencyData = <T extends Currency>(currency: T) => {
  return CurrencyRegistry.getInstance().getCurrencyData(currency);
};

Pros

• ✅ Clear separation of concerns: Money = operations, Registry = configuration
• ✅ Money class stays focused on domain logic (~660 lines)
• ✅ Registry is testable independently
• ✅ Singleton pattern ensures single source of truth
• ✅ Easy to understand: "Registry manages currencies, Money uses them"
• ✅ Extensible: Can add more registry methods without touching Money

Cons

• ⚠️ Adds one more file to the library
• ⚠️ Singleton pattern (some consider it an anti-pattern, but it's appropriate here)

---

Option 2: Pure Functions Module

Concept: Extract configuration logic into a module of pure functions instead of a class.

Structure

app/lib/money/
├── money.ts                    # Money class
├── currency-config.ts          # NEW: Pure functions for config
├── currency-data.ts            # Default definitions
├── types.ts
└── index.ts

Implementation

// app/lib/money/currency-config.ts

import type {
  Currency,
  CurrencyData,
  CurrencyDataMap,
  MoneyConfiguration,
} from './types';
import { defaultCurrencyDataMap } from './currency-data';

// Module-level state
let customCurrencyDataMap: CurrencyDataMap = {};
let isConfigured = false;

/**
 * Configure currency data
 */
export function configureCurrencies(config: MoneyConfiguration): void {
  if (isConfigured) {
    console.warn('configureCurrencies() called multiple times.');
  }
  
  customCurrencyDataMap = buildCurrencyDataMap(config);
  isConfigured = true;
}

/**
 * Reset configuration
 */
export function resetCurrencyConfiguration(): void {
  customCurrencyDataMap = {};
  isConfigured = false;
}

/**
 * Get currency data
 */
export function getCurrencyData<T extends Currency>(currency: T): CurrencyData<T> {
  const effectiveMap = getEffectiveCurrencyDataMap();
  const data = effectiveMap[currency];
  
  if (!data) {
    throw new Error(`Unsupported currency: "${currency}"`);
  }
  
  return data;
}

/**
 * Get all registered currencies
 */
export function getRegisteredCurrencies(): string[] {
  return Object.keys(getEffectiveCurrencyDataMap());
}

/**
 * Check if currency is registered
 */
export function isCurrencyRegistered(currency: string): boolean {
  return currency in getEffectiveCurrencyDataMap();
}

/**
 * Get effective currency data map
 */
function getEffectiveCurrencyDataMap(): CurrencyDataMap {
  return {
    ...defaultCurrencyDataMap,
    ...customCurrencyDataMap,
  };
}

// ... other private helper functions (buildCurrencyDataMap, mergeCurrencyData, etc.)

// app/lib/money/money.ts (updated)

import * as CurrencyConfig from './currency-config';

export class Money<T extends Currency = Currency> {
  /**
   * Configure Money class
   */
  static configure(config: MoneyConfiguration): void {
    CurrencyConfig.configureCurrencies(config);
  }

  static getRegisteredCurrencies(): string[] {
    return CurrencyConfig.getRegisteredCurrencies();
  }

  private get currencyData(): CurrencyData<T> {
    return CurrencyConfig.getCurrencyData(this.currency);
  }

  // ... rest of Money class
}

Pros

• ✅ Functional approach: Pure functions (easier to test)
• ✅ Clear separation: Configuration in separate module
• ✅ No classes: Simpler for those who prefer functional style
• ✅ Tree-shakable: Unused functions can be dropped by bundler

Cons

• ⚠️ Module-level state (hidden singleton)
• ⚠️ Harder to mock in tests (module state vs. instance)
• ⚠️ Less explicit than class-based registry

---

Option 3: Configuration Builder Pattern

Concept: Use a builder that returns a configured Money class factory.

Structure

app/lib/money/
├── money.ts                    # Money class (generic)
├── money-builder.ts            # NEW: Builder for configuration
├── currency-data.ts            # Default definitions
├── types.ts
└── index.ts

Implementation

// app/lib/money/money-builder.ts

import type {
  Currency,
  CurrencyData,
  CurrencyDataMap,
  MoneyConfiguration,
} from './types';
import { defaultCurrencyDataMap } from './currency-data';
import { Money as BaseMoney } from './money';

/**
 * Builder for configuring Money class
 */
export class MoneyBuilder {
  private currencyDataMap: CurrencyDataMap;

  constructor() {
    this.currencyDataMap = { ...defaultCurrencyDataMap };
  }

  /**
   * Configure currencies
   */
  configure(config: MoneyConfiguration): this {
    const customMap = buildCurrencyDataMap(config, defaultCurrencyDataMap);
    this.currencyDataMap = {
      ...defaultCurrencyDataMap,
      ...customMap,
    };
    return this;
  }

  /**
   * Get currency data map (used by Money class)
   */
  getCurrencyDataMap(): CurrencyDataMap {
    return this.currencyDataMap;
  }

  /**
   * Get currency data for specific currency
   */
  getCurrencyData<T extends Currency>(currency: T): CurrencyData<T> {
    const data = this.currencyDataMap[currency];
    if (!data) {
      throw new Error(`Unsupported currency: "${currency}"`);
    }
    return data;
  }

  // ... merge/validation logic here
}

// Create default builder instance
const defaultBuilder = new MoneyBuilder();

// Attach builder to Money class
BaseMoney['builder'] = defaultBuilder;

export { BaseMoney as Money };

// app/lib/money/money.ts (updated)

export class Money<T extends Currency = Currency> {
  private static builder: any; // Injected by money-builder.ts

  static configure(config: MoneyConfiguration): void {
    Money.builder.configure(config);
  }

  private get currencyData(): CurrencyData<T> {
    return Money.builder.getCurrencyData(this.currency);
  }

  // ... rest of Money class
}

// app/entry.client.tsx

import { Money } from '~/lib/money';

// Configure via builder
Money.configure({
  currencies: {
    BTC: { baseUnit: 'sat' }
  }
});

Pros

• ✅ Builder pattern: Explicit construction
• ✅ Separation: Configuration logic separate
• ✅ Testable: Can inject different builders

Cons

• ❌ Coupling: Money class depends on builder being injected
• ❌ Implicit dependency: Money['builder'] is not type-safe
• ⚠️ More complex: Harder to understand the relationship

---

Comparison Table

Aspect	Registry Class	Pure Functions	Builder Pattern
Separation of Concerns	⭐⭐⭐ Excellent	⭐⭐⭐ Excellent	⭐⭐ Good
Testability	⭐⭐⭐ Easy to mock	⭐⭐ Module state	⭐⭐⭐ Injectable
Clarity	⭐⭐⭐ Very clear	⭐⭐ Clear	⭐ Complex
Type Safety	⭐⭐⭐ Full	⭐⭐⭐ Full	⭐⭐ Partial
Simplicity	⭐⭐ Singleton pattern	⭐⭐⭐ Simple functions	⭐ Most complex
Extensibility	⭐⭐⭐ Easy to extend	⭐⭐ Add more functions	⭐⭐ Builder methods
Lines Added to Money	~10 lines	~10 lines	~10 lines
New Files	2 files	2 files	2 files

---

Recommendation: Option 1 - CurrencyRegistry Class

Why CurrencyRegistry?

1. Best Separation of Concerns

   • Money class: Domain operations (660 lines)
   • CurrencyRegistry: Configuration & data access (150 lines)
   • Clear responsibility boundaries

2. Excellent Developer Experience

   • CurrencyRegistry.getInstance() is explicit and understandable
   • Easy to document and reason about
   • Familiar pattern (widely used in JS/TS ecosystem)

3. Testing Benefits

   • Registry can be tested independently
   • Money class tests can mock the registry if needed
   • reset() method makes tests clean

4. Extensibility

   • Easy to add new registry methods without touching Money
   • Can add features like:
     • registry.registerCurrency(currency, data)
     • registry.validateCurrency(currency)
     • registry.getDefaultCurrency()

5. Type Safety

   • Full TypeScript support
   • Generic methods preserve currency types

Alternative: Pure Functions Module

If you strongly prefer functional programming over OOP, Option 2 (Pure Functions) is a solid alternative:

• Simpler implementation (no class/singleton)
• More functional style
• Still achieves separation of concerns

However, the class-based registry is more explicit and easier to understand for most developers.

---

Updated Implementation Plan

If you approve the CurrencyRegistry approach, the implementation would be:

1. Create app/lib/money/currency-registry.ts

   • Move all configuration logic here
   • Implement merge/validation methods

2. Create app/lib/money/currency-data.ts

   • Extract defaultCurrencyDataMap from money.ts
   • Move helper formatters

3. Update app/lib/money/money.ts

   • Remove configuration logic (~150 lines removed)
   • Add private static registry = CurrencyRegistry.getInstance()
   • Update currencyData getter to use registry
   • Update getCurrencyDataForInput to use registry
   • Keep Money.configure() as a convenience method that delegates

4. Update app/lib/money/types.ts

   • Add configuration types (PartialCurrencyData, etc.)

5. Rest of implementation (entry.client.tsx, remove getDefaultUnit, etc.)

   • Same as original plan

---

Does the CurrencyRegistry approach look good to you? Or would you prefer the pure functions approach?

---