Forem: Smiling Sloth

Building a Type-Safe Money Handling Library in TypeScript

Smiling Sloth — Thu, 09 Jan 2025 13:33:04 +0000

After years of wrestling with money-related bugs in financial applications, from rounding errors in e-commerce platforms to currency conversion mishaps in international payment systems, I decided to tackle these challenges head-on. The result is @thesmilingsloth/money-utils, a TypeScript library that brings bank-grade money handling to JavaScript applications. In this post, I'll share the journey, technical decisions, and lessons learned while building it.

The Money Problem in Software Engineering

Money seems simple at first glance—it's just numbers, right? But as Martin Fowler noted in his patterns of enterprise application architecture, money is one of the most complex domains in software engineering. Here's why:

The Floating-Point Trap

JavaScript's number type uses IEEE 754 floating-point arithmetic, which leads to infamous precision issues:

// The classic example
0.1 + 0.2; // => 0.30000000000000004

// But it gets worse with multiple operations
0.1 + 0.2 + 0.3 + 0.4 + 0.5; // => 1.5000000000000002
(0.1 * 100 + 0.2 * 100) / 100; // => 0.30000000000000004

In financial applications, these tiny discrepancies can accumulate into significant errors. Imagine calculating interest rates or processing thousands of transactions—the errors compound quickly.

Real-World Horror Stories

I've seen these issues manifest in production systems:

An e-commerce platform losing thousands of dollars due to rounding errors in bulk discounts
A payment processor having mismatched totals because of currency conversion rounding
An accounting system showing different balances depending on the calculation path

The Solution: @thesmilingsloth/money-utils

Our library addresses these challenges with several key features:

1. Precise Decimal Arithmetic

We chose decimal.js as our arithmetic engine after careful evaluation. It provides the precision needed for financial calculations while maintaining good performance:

import { Money } from "@thesmilingsloth/money-utils";

// Precise calculations, even with complex operations
const price = new Money("99.99", "USD");
const quantity = 2;

// All operations maintain precision
const subtotal = price.multiply(quantity);
const tax = subtotal.multiply("0.2"); // 20% tax
const total = subtotal.add(tax);

console.log(total.toString()); // "$239.98"

2. Type-Safe Currency Operations

The library treats currencies as first-class citizens, with built-in support for major currencies and custom currency definitions:

import { Money, Currency } from "@thesmilingsloth/money-utils";

// Built-in currencies with sensible defaults
const usd = Currency.USD; // Decimals: 2, Symbol: $
const eur = Currency.EUR; // Decimals: 2, Symbol: €
const jpy = Currency.JPY; // Decimals: 0, Symbol: ¥
const btc = Currency.BTC; // Decimals: 8, Symbol: ₿

// Example of built-in currency configurations
const USDDefaults = {
  name: "US Dollar",
  code: "USD",
  symbol: "$",
  symbolPosition: "prefix",
  decimals: 2,
  minorUnits: "100",
  decimalSeparator: ".",
  thousandsSeparator: ",",
  isCrypto: false,
};

const BTCDefaults = {
  name: "Bitcoin",
  code: "BTC",
  symbol: "₿",
  symbolPosition: "prefix",
  decimals: 8,
  minorUnits: "100000000",
  decimalSeparator: ".",
  thousandsSeparator: ",",
  isCrypto: true,
};

// Custom currency support
Currency.register({
  name: "Corporate Loyalty Points",
  code: "POINTS",
  symbol: "⭐",
  symbolPosition: "prefix",
  decimals: 0,
  minorUnits: "1",
  decimalSeparator: ".",
  thousandsSeparator: ",",
  isCrypto: false,
});

// Type-safe operations prevent mixing currencies
const dollars = new Money("100.00", "USD");
const euros = new Money("100.00", "EUR");
// This won't compile - TypeScript prevents currency mixing
// const invalid = dollars.add(euros);

3. Configurable Options with Sensible Defaults

One of our key design decisions was providing sensible defaults while allowing customization:

// Default options for Money instances
const defaultMoneyOptions = {
  decimals: undefined, // Uses the currency's default decimals
  displayDecimals: undefined, // Uses the currency's default decimals
  roundingMode: ROUNDING_MODE.ROUND_HALF_UP,
  symbol: undefined, // Uses the currency's default symbol
};

// Using defaults - clean and simple
const simple = new Money("100", "USD");
console.log(simple.toString()); // "$100.00"

// Custom configuration when needed
const custom = new Money("100.555", "USD", {
  decimals: 3, // Store with 3 decimal places
  displayDecimals: 2, // Display with 2 decimal places
  roundingMode: ROUNDING_MODE.ROUND_DOWN,
  symbol: "US$", // Custom symbol
});
console.log(custom.toString()); // "US$100.55"

4. Comprehensive Formatting Options

Our formatting engine goes beyond basic toString() operations:

const amount = new Money("1234567.89", "USD");

// Basic formatting with defaults
console.log(amount.toString()); // "$1,234,567.89"
console.log(amount.formattedValue()); // "1,234,567.89"
console.log(amount.formattedValueWithSymbol()); // "$1,234,567.89"

// Locale-aware formatting
console.log(amount.toLocaleString()); // Uses browser's default locale
console.log(amount.toLocaleString("en-US")); // "$1,234,567.89"
console.log(amount.toLocaleString("de-DE")); // "1.234.567,89 $"
console.log(amount.toLocaleString("ja-JP")); // "￥1,234,567.89"

// Advanced formatting options
console.log(
  amount.toLocaleString("en-US", {
    style: "currency",
    currencyDisplay: "name",
  })
); // "1,234,567.89 US dollars"

Advanced Features and Edge Cases

1. Configurable Rounding Behavior

import { Money, ROUNDING_MODE } from "@thesmilingsloth/money-utils";

const amount = new Money("100.555", "USD", {
  roundingMode: ROUNDING_MODE.ROUND_HALF_UP,
  decimals: 2,
});

// Different rounding modes for different use cases
const roundDown = new Money("100.555", "USD", {
  roundingMode: ROUNDING_MODE.ROUND_DOWN,
});
console.log(roundDown.toString()); // "$100.55"

const roundUp = new Money("100.555", "USD", {
  roundingMode: ROUNDING_MODE.ROUND_UP,
});
console.log(roundUp.toString()); // "$100.56"

2. Cryptocurrency Support

// Bitcoin with 8 decimal places
const bitcoin = new Money("1.23456789", "BTC");
console.log(bitcoin.toString()); // "₿1.23456789"

// Ethereum with 18 decimal places
Currency.register({
  name: "Ethereum",
  code: "ETH",
  symbol: "Ξ",
  symbolPosition: "prefix",
  decimals: 18,
  minorUnits: "1000000000000000000",
  decimalSeparator: ".",
  thousandsSeparator: ",",
  isCrypto: true,
});

const eth = new Money("1.234567890123456789", "ETH");

3. Complex Allocation Scenarios

// Investment profit distribution with different stakeholder percentages
const profit = new Money("1000000.00", "USD");
const shares = profit.allocate([
  15, // 15% - Founder
  30, // 30% - Operations
  20, // 20% - Development
  35, // 35% - Investors
]);

console.log(shares.map((s) => s.toString()));
// [
//   "$150,000.00",
//   "$300,000.00",
//   "$200,000.00",
//   "$350,000.00"
// ]

Technical Decisions and Lessons Learned

Type Safety is Non-Negotiable: TypeScript's type system caught countless potential bugs during development. For example:

   // This won't compile - type safety prevents invalid operations
   const money = new Money("100.00", "USD");
   const result = money.multiply("invalid");

Immutability Prevents Bugs: All operations return new instances, preventing accidental mutations:

   const original = new Money("100.00", "USD");
   const doubled = original.multiply(2);
   console.log(original.toString()); // Still "$100.00"

Default Configurations Matter: We carefully chose sensible defaults while allowing customization:

   // Uses currency defaults
   const simple = new Money("100", "USD");

   // Custom configuration when needed
   const custom = new Money("100", "USD", {
     decimals: 4,
     displayDecimals: 2,
     roundingMode: ROUNDING_MODE.ROUND_DOWN,
   });

Comprehensive Testing is Crucial: Our test suite covers:
- Edge cases in arithmetic operations
- Rounding behavior across different modes
- Internationalization scenarios
- Type safety validations
- Performance benchmarks

Conclusion

Building a robust money handling library taught us valuable lessons about type safety, precision, and the importance of real-world testing. The library is now being used in production systems handling millions in transactions, proving that careful attention to detail in financial software pays off.

Key takeaways:

Type safety prevents costly mistakes
Immutability simplifies reasoning about code
Comprehensive testing is non-negotiable
Sensible defaults with flexibility for edge cases

The library is MIT licensed and maintained by Smiling Sloth. We welcome contributions and feedback from the community!

Introducing EventFlow: A Type-Safe Event Broker for Modern Frontend Applications

Smiling Sloth — Sat, 04 Jan 2025 07:58:57 +0000

Frontend applications are becoming increasingly complex, with components and modules needing to communicate across the application without creating tight coupling. While solutions like Redux or global state management tools work well for application state, they can be overkill for simple event-based communication or introduce unnecessary complexity.

Today, I'm excited to introduce EventFlow, a lightweight, type-safe event broker designed specifically for frontend applications.

What is EventFlow?

EventFlow is a TypeScript-first event broker that provides a simple yet powerful way to handle events in your frontend applications. It combines the simplicity of event emitters with the safety of TypeScript, making it an ideal choice for modern web applications.

Key Features

🎯 Type Safety: Full TypeScript support with type inference for events and their payloads
⚡ Lightweight: Zero dependencies for core functionality
🔌 Middleware System: Extensible through a powerful middleware system
🛡️ Error Handling: Configurable error policies for robust applications
⚛️ React Integration: First-class React support with hooks and context
📦 Tree-shakeable: Only bundle what you use

Why Another Event Library?

While there are many event libraries available, EventFlow addresses several common challenges in frontend development:

Type Safety: Unlike traditional event emitters, EventFlow ensures your events and their payloads are fully typed.
Decoupled Communication: Enable components to communicate without direct dependencies.
Cross-Cutting Concerns: Handle application-wide concerns through the middleware system.
Framework Independence: Works with any JavaScript environment while providing first-class React support.
Predictable Error Handling: Configure how your application behaves when events fail.

Getting Started

Installation is straightforward:

# Using npm
npm install @thesmilingsloth/eventflow-core
npm install @thesmilingsloth/eventflow-react # Optional React integration

# Using pnpm
pnpm add @thesmilingsloth/eventflow-core
pnpm add @thesmilingsloth/eventflow-react # Optional React integration

Basic Usage

import { createEventBroker } from "@thesmilingsloth/eventflow-core";

// Define your events
interface MyEvents {
  "user:login": {
    userId: string;
    timestamp: number;
  };
  "app:notification": {
    message: string;
    type: "success" | "error";
  };
}

// Create broker
const broker = createEventBroker<MyEvents>({
  // Enable console logging middleware
  logger: true,
  // Configure max listeners per event
  maxListeners: 10,
  // Add custom middlewares
  middlewares: [
    // Example: Analytics middleware
    (next) => (event) => {
      console.log(`[Analytics] Event ${event.name} triggered`);
      next(event);
    },
    // Example: Error tracking middleware
    (next) => (event) => {
      try {
        next(event);
      } catch (error) {
        console.error(`[Error] in event ${event.name}:`, error);
        throw error;
      }
    },
  ],
});

// Subscribe to events
const unsubscribe = broker.on("user:login", (data) => {
  console.log(`User ${data.userId} logged in`);
});

// Emit events
broker.emit("user:login", {
  userId: "123",
  timestamp: Date.now(),
});

React Integration

The React integration package provides hooks for seamless integration with React components:

import {
  EventBrokerProvider,
  useEventListener,
  useEventEmitter,
} from "@thesmilingsloth/eventflow-react";

function App() {
  return (
    <EventBrokerProvider broker={broker}>
      <LoginButton />
      <NotificationListener />
    </EventBrokerProvider>
  );
}

function LoginButton() {
  const emitLogin = useEventEmitter("user:login");

  return (
    <button
      onClick={() =>
        emitLogin({
          userId: "123",
          timestamp: Date.now(),
        })
      }
    >
      Login
    </button>
  );
}

function NotificationListener() {
  useEventListener("app:notification", (data) => {
    alert(`${data.type}: ${data.message}`);
  });

  return null;
}

Advanced Features

Middleware System

EventFlow's middleware system allows you to intercept and transform events:

const analyticsMiddleware: Middleware<MyEvents> = (next) => (event) => {
  // Before event
  trackEvent(event.name, event.data);

  // Process event
  next(event);

  // After event
  console.log("Event processed:", event.name);
};

broker.use(analyticsMiddleware);

Error Handling

Configure how your application handles errors:

const broker = createEventBroker<MyEvents>({
  errorPolicy: {
    onListenerError: "continue",
    onEmitError: "stop",
    onMiddlewareError: (error, event) => {
      reportError(error);
    },
  },
});

Use Cases

EventFlow is particularly useful for:

Cross-Component Communication: When components need to communicate without direct coupling
Application-Wide Events: For handling global notifications, theme changes, or user actions
Analytics and Logging: Using middleware to track events across your application
State Synchronization: When multiple components need to react to the same state changes
Error Handling: Centralizing error handling and reporting

Conclusion

EventFlow brings type-safe event handling to frontend applications with a focus on developer experience and flexibility. Whether you're building a small React application or a large-scale frontend system, EventFlow provides the tools you need for robust event-based communication.

Try it out today and let me know what you think! The project is open source and contributions are welcome.

GitHub Repository | npm Package