Currency converter in JavaScript and Node.js

export CURRENCYAPI_KEY="your-api-key"
npm install express

// currencyapi.js — server only: the API key never leaves this file
export class CurrencyApiError extends Error {
  constructor(status, code, message, errors) {
    super(`currencyapi ${status} (${code}): ${message}`);
    this.status = status;
    this.code = code;
    this.errors = errors; // 422: which parameter is wrong, and why
  }
}

export async function currencyApi(endpoint, params = {}) {
  const url = new URL(`https://api.currencyapi.com/v3/${endpoint}`);
  for (const [name, value] of Object.entries(params)) url.searchParams.set(name, value);

  const res = await fetch(url, {
    headers: { apikey: process.env.CURRENCYAPI_KEY },
    signal: AbortSignal.timeout(10_000),
  });
  const body = await res.json().catch(() => null);
  if (!res.ok) {
    const code = body?.error?.code ?? (res.status === 422 ? "validation_error" : "error");
    throw new CurrencyApiError(res.status, code, body?.message ?? res.statusText, body?.errors);
  }
  return body;
}

// { EUR: { code: "EUR", value: 0.918456 }, … } → { USD: "1", EUR: "0.918456", … }
export function toRateStrings(data, base) {
  const rates = {};
  for (const { code, value } of Object.values(data)) rates[code] = String(value);
  rates[base] = "1"; // the base itself, also when you filter with `currencies`
  return rates;
}

// rates.js — one API request per hour, however many visitors convert
import { currencyApi, toRateStrings } from "./currencyapi.js";

const TTL_MS = 60 * 60 * 1000; // Free plan: daily updates, Small: hourly, Pro: every 15 min, Medium and up: every 60 s
let cached = null; // { base, rates, updatedAt, fetchedAt }
let pending = null; // the request in flight, shared by concurrent callers

export async function getRates() {
  if (cached && Date.now() - cached.fetchedAt < TTL_MS) return cached;

  pending ??= currencyApi("latest", { base_currency: "USD" })
    .then((body) => {
      cached = {
        base: "USD",
        rates: toRateStrings(body.data, "USD"),
        updatedAt: body.meta.last_updated_at,
        fetchedAt: Date.now(),
      };
      return cached;
    })
    .catch((err) => {
      if (cached) return cached; // API unreachable or quota used up: keep the last rates
      throw err;
    })
    .finally(() => {
      pending = null;
    });
  return pending;
}

// End-of-day rates for up to 31 past dates in one call; each date counts as one request
export async function historicalRates(dates, base = "USD") {
  const body = await currencyApi("historical", { dates: dates.join(","), base_currency: base });
  return Object.fromEntries(
    Object.entries(body.data).map(([date, data]) => [date, toRateStrings(data, base)]),
  );
}

10 * 1.0005; // 10.004999999999999, not 10.005
Math.round(10 * 1.0005 * 100) / 100; // 10, commercial rounding gives 10.01
(10 * 1.0005).toFixed(2); // "10.00"

// money.js — exact conversion with BigInt, for Node.js and the browser

// "0.918456" → { units: 918456n, scale: 6 }; also reads "8.8123e-6"
export function parseDecimal(text) {
  const match = /^([+-]?)(\d+)(?:\.(\d*))?(?:e([+-]?\d+))?$/i.exec(String(text).trim());
  if (!match) throw new TypeError(`Not a decimal number: ${text}`);
  const [, sign, int, frac = "", exp = "0"] = match;
  let units = BigInt(sign + int + frac);
  let scale = frac.length - Number(exp);
  if (scale < 0) {
    units *= 10n ** BigInt(-scale);
    scale = 0;
  }
  return { units, scale };
}

// numerator / denominator rounded to a whole number:
// "halfExpand" rounds .5 away from zero, "halfEven" to the even neighbour (banker's rounding)
export function divideRounded(numerator, denominator, mode = "halfExpand") {
  if (denominator < 0n) [numerator, denominator] = [-numerator, -denominator];
  const quotient = numerator / denominator; // BigInt division truncates toward zero
  const remainder = numerator % denominator;
  const twice = 2n * (remainder < 0n ? -remainder : remainder);
  const roundAway =
    twice > denominator ||
    (twice === denominator && (mode === "halfExpand" || quotient % 2n !== 0n));
  return roundAway ? quotient + (numerator < 0n ? -1n : 1n) : quotient;
}

// Decimal places of a currency: EUR 2, JPY 0, KWD 3
export function minorUnits(currency) {
  return new Intl.NumberFormat("en", { style: "currency", currency }).resolvedOptions()
    .maximumFractionDigits;
}

// 18368n with 2 decimals → "183.68"
export function formatMinor(minor, digits) {
  const sign = minor < 0n ? "-" : "";
  const text = (minor < 0n ? -minor : minor).toString().padStart(digits + 1, "0");
  return digits ? `${sign}${text.slice(0, -digits)}.${text.slice(-digits)}` : sign + text;
}

// amount (a decimal string) from one currency to another; rates are units per 1 base unit.
// amount ÷ rate(from) × rate(to) is computed exactly and rounded once, to the minor units of `to`.
export function convert(amount, from, to, rates, mode = "halfExpand") {
  if (rates[from] === undefined) throw new RangeError(`No rate for ${from}`);
  if (rates[to] === undefined) throw new RangeError(`No rate for ${to}`);
  const a = parseDecimal(amount);
  const rateFrom = parseDecimal(rates[from]);
  const rateTo = parseDecimal(rates[to]);
  const digits = minorUnits(to);

  const numerator = a.units * rateTo.units * 10n ** BigInt(rateFrom.scale + digits);
  const denominator = rateFrom.units * 10n ** BigInt(a.scale + rateTo.scale);
  return formatMinor(divideRounded(numerator, denominator, mode), digits);
}

// example.js
import { getRates } from "./rates.js";
import { convert } from "./money.js";

const { rates, updatedAt } = await getRates();
const eur = convert("199.99", "USD", "EUR", rates);
const text = new Intl.NumberFormat("de-DE", { style: "currency", currency: "EUR" }).format(eur);
console.log(eur, text, updatedAt); // 183.68 183,68 € 2023-06-23T10:15:59Z

// server.js — Express 5
import express from "express";
import { getRates } from "./rates.js";

const app = express();
app.use(express.static("public")); // index.html and a copy of money.js

app.get("/api/rates", async (req, res) => {
  try {
    const { base, rates, updatedAt } = await getRates();
    res.set("Cache-Control", "public, max-age=300");
    res.json({ base, rates, updatedAt });
  } catch (err) {
    console.error(err); // e.g. currencyapi 401 (invalid_api_key): Unauthorized
    res.status(503).json({ error: "Exchange rates are unavailable" });
  }
});

app.listen(3000, () => console.log("http://localhost:3000"));

<form id="converter">
  <input name="amount" inputmode="decimal" value="100" aria-label="Amount">
  <select name="from" aria-label="From"><option>USD</option><option>EUR</option><option>GBP</option><option>JPY</option></select>
  <select name="to" aria-label="To"><option>EUR</option><option>USD</option><option>GBP</option><option>JPY</option></select>
  <output name="result"></output>
  <small id="updated"></small>
</form>

<script type="module">
  import { convert } from "./money.js";

  const res = await fetch("/api/rates");
  if (!res.ok) throw new Error(`Rates unavailable (${res.status})`);
  const { rates, updatedAt } = await res.json();

  const form = document.querySelector("#converter");
  document.querySelector("#updated").textContent = `Rates of ${updatedAt}`;

  function update() {
    const { amount, from, to, result } = form.elements;
    try {
      const value = convert(amount.value.replace(",", "."), from.value, to.value, rates);
      result.value = new Intl.NumberFormat(navigator.language, {
        style: "currency",
        currency: to.value,
      }).format(value);
    } catch {
      result.value = "–"; // not a number yet, e.g. while typing
    }
  }

  form.addEventListener("input", update);
  update();
</script>