localized-price-parse-kit

Parse localized price strings into structured decimal and currency parts.

Package quality

• TypeScript types are generated from the source.
• ESM-only package marked as side-effect free for bundlers.
• CI runs npm ci, typecheck, build, and test.
• Tested on Node.js 20 and 22 with GitHub Actions.

Demo

Try the interactive demo

import {
  isLocalizedPrice,
  parseLocalizedPrice,
  parseLocalizedPriceParts
} from "localized-price-parse-kit";

parseLocalizedPrice("€1.234,56");
// {
//   ok: true,
//   value: 1234.56,
//   decimal: "1234.56",
//   amount: { sign: 1, integer: "1234", fraction: "56", scale: 2 },
//   currency: { symbol: "€", code: "EUR" },
//   separators: { decimal: ",", group: "." }
// }

Why

Localized prices often arrive as display text: €1.234,56, US$ 1,234.56, CHF 1’234.50, 1 234,56 руб, or -$8,202.97.

This package returns a small structured result instead of only returning a JavaScript number or NaN:

• decimal string for safe storage;
• optional numeric value for convenience;
• currency symbol and common ISO code when recognizable;
• diagnostics for empty, ambiguous, or malformed input;
• browser-friendly core with no runtime dependencies.

Install

npm install localized-price-parse-kit

API

parseLocalizedPrice(input, options?)

Returns a discriminated result instead of throwing:

type ParseLocalizedPriceResult =
  | {
      ok: true;
      input: string;
      value: number;
      decimal: string;
      amount: PriceAmountParts;
      currency: CurrencyInfo;
      separators: PriceSeparators;
      issues: [];
    }
  | {
      ok: false;
      input: string;
      value: null;
      decimal: null;
      amount: null;
      currency: CurrencyInfo;
      separators: PriceSeparators;
      issues: PriceParseIssue[];
    };

Use decimal for storage when precision matters. value is provided as a convenience JavaScript number for UI and lightweight calculations.

parseLocalizedPriceParts(input, options?)

Returns only the parsed numeric parts, or null when validation fails.

isLocalizedPrice(input, options?)

Returns true when the input can be parsed successfully.

Options

type ParseLocalizedPriceOptions = {
  decimalSeparator?: "." | "," | "auto";
  allowNegative?: boolean;
  allowCurrencyCode?: boolean;
  maxFractionDigits?: number;
};

decimalSeparator defaults to auto, which chooses the rightmost . or , as the decimal separator when both appear. If only one separator appears, a final group of one or two digits is treated as decimals; groups of three digits are treated as thousands.

Examples

parseLocalizedPrice("£1,234.56").decimal;
// "1234.56"

parseLocalizedPrice("1 234,56 руб").currency;
// { symbol: "руб", code: "RUB" }

parseLocalizedPrice("CHF 1’234.50").separators;
// { decimal: ".", group: "apostrophe" }

parseLocalizedPrice("12,34,56").ok;
// false

Notes

This is a small parser for common product, invoice, and ecommerce display prices. It is not a full CLDR implementation and does not infer locale-specific currency minor units.

Browser compatibility

The core uses only strings, objects, arrays, numbers, and regular expressions. It has no runtime dependencies and no required Node APIs.

CLI

No CLI is included. The package is meant to be embedded in import tools, forms, scrapers, ecommerce admin screens, and browser UIs.

License

MPL-2.0