numis — Natural Language Money Parser for JavaScript

Name: numis
Author: Ritvij Kumar Sharma

numis is a lightweight JavaScript/TypeScript library that parses monetary expressions from free-form text into structured data. It supports currency symbols ($, €, £, ¥, ₹ and 70+ more), ISO-4217 codes (USD, EUR, GBP), worded numbers ("one hundred dollars"), slang ("bucks", "quid", "grand"), magnitude suffixes ("10k", "5M"), ranges ("$50 to $100"), comparison operators ("< 30k"), regional formats, and negative indicators.

Quick start

npm install numis

import { parseMoney } from "numis";
const result = parseMoney("The price is $49.99");
// { original: "The price is $49.99", currency: "USD", amount: 49.99 }

Features

Symbols & ISO codes — 70+ currency symbols and all ISO-4217 codes
Worded numbers — English worded amounts, fractions, and scales up to billions
Ranges — hyphens, "to", "through", "between"
Comparison bounds — < and > expressions
Slang & idioms — bucks, quid, fiver, tenner, grand
Regional formats — European, Swiss, and Brazilian number formatting

How to use numis

Install the package

Add numis to your project with your preferred package manager:

npm install numis

Parse your first amount

Import parseMoney and pass it any text containing money:

import { parseMoney } from "numis";

const result = parseMoney("The price is $49.99");
// { original: "The price is $49.99", currency: "USD", amount: 49.99 }

Understanding the output

parseMoney() returns an object with these fields:

Property	Type	Description
original	string	The input text you passed
amount	number \| undefined	The numeric value (undefined for ranges)
currency	string \| undefined	ISO-4217 code (e.g. "USD", "EUR")
currencyWasDefault	boolean	True if currency came from defaultCurrency option
isNegative	boolean	True if a negative indicator was detected
isRange	boolean	True if the result is a range expression
min	number \| undefined	Range minimum (only when isRange is true)
max	number \| undefined	Range maximum (only when isRange is true)

Default currency fallback

When text has no currency symbol, provide a fallback:

// Without default — currency is undefined
parseMoney("I have 100");
// => { original: "I have 100", amount: 100, currency: undefined }

// With default — uses your fallback
parseMoney("I have 100", { defaultCurrency: "USD" });
// => { original: "I have 100", amount: 100, currency: "USD", currencyWasDefault: true }

Range parsing

numis detects monetary ranges with multiple separator styles. When a range is found, isRange is true and amount is undefined.

parseMoney("$500 to $1000");
// => { isRange: true, min: 500, max: 1000, currency: "USD" }

parseMoney("between 50 and 100 euros");
// => { isRange: true, min: 50, max: 100, currency: "EUR" }

parseMoney("< 30k");
// => { isRange: true, min: null, max: 30000, currency: undefined }

Find all expressions in text

Use parseAll() to extract every monetary expression from a string, including ranges. Each result includes its position in the original text.

import { parseAll } from "numis";

const results = parseAll("Price is $50 - $100 or $500");
// [
//   { type: "range", raw: "$50 - $100", min: 50, max: 100, currency: "USD", startIndex: 9, endIndex: 19 },
//   { type: "single", raw: "$500", amount: 500, currency: "USD", startIndex: 23, endIndex: 27 }
// ]

Supported formats

numis understands money written in many different ways:

Symbols: $100, €50, £25.99, ¥1000, ₹500
ISO Codes: USD 100, 50 EUR, GBP 20.50
Words: one hundred dollars, fifty euros, half a million
Abbreviations: $10k, €2.5m, 1 billion USD
Slang: 20 bucks, fifty quid, a fiver, ten grand
Compounds: 5 dollars and 50 cents, two pounds and 30 pence
Negative: -$100, ($50), -€25.99
Ranges: $10 - $20, 5k to 10k, between 50 and 100 EUR

Error handling

numis throws typed errors for invalid inputs. Always wrap calls in try/catch for user-provided strings.

import { ValueOverflowError } from "numis";

try {
  parseMoney("$999999999999999999");
} catch (err) {
  if (err instanceof ValueOverflowError) {
    console.log("Number too large!");
  }
}

Quick reference

parseMoney signature:

parseMoney(
  text: string,
  options?: { defaultCurrency?: string }
)

parseAll signature:

parseAll(text: string): MonetaryExpression[]

Return type:

{
  original: string;
  currency?: string;
  amount?: number;
  currencyWasDefault?: boolean;
  isNegative?: boolean;
  isRange?: boolean;
  min?: number;
  max?: number;
}

Documentation

Visit the interactive playground on this page to try numis live, or read the full documentation on GitHub and npm.

Author

Built by Ritvij Kumar Sharma.