Registry / serialization / number-format.js

number-format.js

library2.0.9jsnpmunverified

number-format.js is a lightweight and performant JavaScript library designed for formatting numerical values using mask patterns. Currently at stable version 2.0.9, it focuses on providing a small footprint (under 2KB production size) and fast execution. It supports a wide array of masking symbols for forced and optional digits, positive/negative signs, and flexible thousands/decimal separators, accommodating various international numbering conventions. A key feature is its ability to automatically round numbers. Unlike more comprehensive internationalization libraries such as `Intl.NumberFormat`, `number-format.js` intentionally limits its scope, specifically not handling scientific/engineering notation, dates, or phone numbers. Its primary differentiator is its simplicity and speed for number mask formatting, making it suitable for scenarios where bundle size and performance are critical.

serialization

npm install number-format.js

github ↗package ↗

INSTALL

IMPORT

SIG · NUMBER-FORMAT.JS

number-format.js

serializationjavascriptv2.0.9

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

format

✓ import format from 'number-format.js';

✗ import { format } from 'number-format.js';

The library exports the `format` function as its default export for ESM.

format

✓ const format = require('number-format.js');

✗ const { format } = require('number-format.js');

For CommonJS environments, the module directly exports the `format` function.

Demonstrates basic number formatting, currency handling, the `enforceMaskSign` option, and custom separators.

import format from 'number-format.js'; // Basic number formatting console.log(`Formatted 1234567.890 with '#,##0.####': ${format("#,##0.####", 1234567.890)}`); // Expected: "1,234,567.89" // Currency formatting with prefix console.log(`Formatted -1234567.890 with '$ #,###.00': ${format("$ #,###.00", -1234567.890)}`); // Expected: "$ -1,234,567.89" // Using enforceMaskSign option (added in v2.0.0) console.log(`Formatted -1234567.890 with '$ #,###.00' and enforceMaskSign: ${format("$ #,###.00", -1234567.890, { enforceMaskSign: true })}`); // Expected: "$ 1,234,567.89" // Forcing positive sign console.log(`Formatted 1234567.890 with '$ +#,###.00' and enforceMaskSign: ${format("$ +#,###.00", 1234567.890, { enforceMaskSign: true })}`); // Expected: "$ +1,234,567.89" // Custom decimal and thousands separators console.log(`Formatted 98765.432 with '#.##0,00': ${format("#.##0,00", 98765.432)}`); // Expected: "98.765,43"

Debug

Known issues

breakingVersion 2.0.0 introduced the `enforceMaskSign` option, which significantly alters how positive and negative signs are handled within the mask. Code relying on previous sign display behavior, especially for negative numbers or explicit positive signs, may need adjustment.

fix

Review mask patterns involving `+` or `-` symbols and explicitly use the `enforceMaskSign: true` option if signs should be enforced according to the mask rather than the value's inherent sign.

affects: >=2.0.0

gotchaWhen a mask contains only a single non-digit symbol (e.g., `#,###`), the library will always interpret this symbol as the decimal separator by default, even if it logically should be a thousands separator. This can lead to unexpected output where numbers like `1234567.890` formatted with `#,###` become `1234567,890`.

fix

To force a single symbol to be used as a thousands separator, append a trailing non-mask symbol (e.g., a period) to the end of the mask, such as `#,###.` This explicitly defines the last symbol as the decimal, forcing others to be separators.

affects: >=1.0.0

gotchaWhile the library supports prefixes and suffixes within the mask (e.g., `'$ #,###.00'`), the README states that a prefix or suffix *cannot* include any numbers (`0-9`), dashes (`-`), or plus signs (`+`). This is somewhat ambiguous as mask examples show `$` working, which implies this limitation primarily applies to non-mask symbols 'outside' the numerical pattern.

fix

Avoid using numerical digits, dashes, or plus signs as literal prefix/suffix characters within the mask itself if they are intended as non-formatting text. For complex prefixes/suffixes, consider concatenating them before/after the formatted string: `'$' + format('#,##0.00', 123.45)`.

affects: >=2.0.0

gotchaThis library is a dedicated number formatter with specific limitations. It does not support scientific/engineering notation, date formatting, or phone number formatting. Attempting to use it for these purposes will yield incorrect results.

fix

For date formatting, use `Intl.DateTimeFormat` or a dedicated date library like `date-fns`. For phone numbers, use a specialized library like `libphonenumber`. For scientific notation, utilize JavaScript's built-in `Number.prototype.toExponential()` or `Intl.NumberFormat` with `notation: 'scientific'`.

affects: >=1.0.0

Errors

Common errors & fixes

TypeError: (0 , number_format_js_1.format) is not a function

Attempting to import the default `format` function as a named import in an ESM environment.

fix

Change the import statement from `import { format } from 'number-format.js';` to `import format from 'number-format.js';`

Output '1234567,890' when expecting '1,234,567' with mask '#,###'

The library defaults a single non-digit symbol in the mask to be the decimal separator.

fix

To force the symbol as a thousands separator, add a trailing non-mask symbol (e.g., a period) to define the decimal: `format('#,###.', 1234567.890)` to get `1,234,567`.

Prefix or suffix characters (e.g., 'USD ') are unexpectedly stripped or not appearing in the output.

The prefix/suffix contains characters (numbers, dashes, plus signs) that the formatter is explicitly designed to exclude when used as general prefix/suffix symbols, or it's incorrectly positioned in the mask.

fix

Ensure that literal prefixes/suffixes outside the core numerical pattern do not contain `0-9`, `-`, or `+`. For complex cases, apply the prefix/suffix as string concatenation *after* the `format` call: `'$' + format('#,##0.00', 123.45)`.

Upgrade

Version history

2.0.9latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

5 hits · last 30 days

gptbot

script

Resources

githubhttps://github.com/Mottie/javascript-number-formatter ↗

packagehttps://www.npmjs.com/package/number-format.js ↗