accounting.js

accounting.js

accounting.js is a lightweight JavaScript library designed for parsing and formatting numbers, money, and currencies. It is fully localisable, has no dependencies, and is compatible with both client-side and server-side (NodeJS) environments.

Key Features:

• Parsing and formatting for numbers and currency.
• Support for AMD/requireJS and NodeJS/npm.
• Localisable settings.
• Works well with money.js for currency conversion and the Open Exchange Rates API for real-time data.

You can use accounting.js as a standalone script, an AMD/requireJS module, or via npm for NodeJS environments. For NodeJS projects, install the package using npm and require it in your scripts.

npm install accounting

var accounting = require("accounting");

You can customize the default behavior for number and currency formatting by modifying the accounting.settings object. This object contains two main configuration blocks:

• currency: Controls how money is displayed. Key properties include symbol (e.g., "$"), format (using %s for symbol and %v for value), decimal, thousand, precision, and grouping.
• number: Controls standard number formatting. Key properties include precision, grouping, thousand, and decimal.

Note: grouping is currently marked as not implemented in the library source.

The formatColumn() method takes an array of numbers and returns an array of formatted strings, padded with whitespace so that currency symbols, thousands separators, and decimal points align vertically.

Arguments:

1. list: An array of numbers (or a multi-dimensional array).
2. symbol: The currency symbol (or a configuration object).
3. precision, thousand, decimal, format: Standard formatting options.

Important: To prevent browsers from collapsing the padding whitespace, you MUST apply the CSS rule white-space: pre; to the HTML element containing the output.

The formatMoney() method converts a number into a formatted currency string.

Arguments:

1. number: The value to format.
2. symbol: The currency symbol (or an object matching accounting.settings.currency).
3. precision: Decimal places.
4. thousand: Thousands separator.
5. decimal: Decimal separator.
6. format: A format string (e.g., "%s%v") or an object containing pos, neg, and zero format strings. The %s placeholder represents the symbol and %v represents the value.

It supports arrays of numbers and allows for easy localization by passing a single configuration object as the second argument.

Note: For the output to display correctly in browsers, the container holding the result should use the CSS rule white-space: pre; if you are using formatColumn().

If accounting.js was loaded in a way that it overwrote an existing global accounting variable, you can use noConflict() to restore the original value and remove the noConflict method from the library instance.

Example:

var originalAccounting = accounting.noConflict();
// 'accounting' is now restored to its previous value
// 'originalAccounting' is the accounting.js instance

The format() method (aliased as formatNumber()) converts a number into a formatted string with thousands separators and specific decimal precision.

It accepts a number as the first argument. The second argument can be a precision value or an object matching the accounting.settings.number schema to override precision, thousand, and decimal settings. It also accepts arrays of numbers for recursive formatting.

To ensure financial accuracy, format() uses an internal toFixed() implementation that avoids common binary floating-point rounding errors.

The unformat() method (aliased as parse()) takes a string or an array of strings and removes all formatting characters (like currency symbols or thousands separators) to return a raw float value. It also handles bracketed negatives (e.g., "$ (1.99)" becomes -1.99).

If your input uses a non-standard decimal separator, you must provide it as the second argument.

If the input is invalid, it returns 0 instead of throwing an error.