CtrlK
BlogDocsLog inGet started
Tessl Logo

tessl/npm-numeral

A javascript library for formatting and manipulating numbers.

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Overview
Eval results
Files

formatting.mddocs/

Number Formatting

Comprehensive formatting system with built-in plugins for currency, percentages, bytes, exponential notation, ordinals, basis points, and time duration formatting. All format plugins support both formatting numbers to strings and unformatting (parsing) strings back to numbers.

Capabilities

Format Plugin System

/**
 * Register a new format plugin
 * @param type - Must be 'format' for format plugins
 * @param name - Unique name for the format plugin
 * @param definition - Format plugin definition object
 * @returns The registered format plugin definition
 */
numeral.register(type: 'format', name: string, definition: FormatPlugin): FormatPlugin;

interface FormatPlugin {
  regexps: {
    format: RegExp;      // Pattern to detect when this format should be used
    unformat?: RegExp;   // Pattern to detect when unformatting with this plugin
  };
  format: (value: number, format: string, roundingFunction: Function) => string;
  unformat?: (string: string) => number;
}

Currency Formatting

Format numbers with currency symbols and locale-aware placement. Supports prefix and suffix positioning with proper negative number handling.

// Currency format detection pattern: /(\$)/
// Triggered by '$' symbol in format string

// Format patterns:
// '$0,0.00' → "$1,234.56"
// '0,0.00$' → "1,234.56$"  
// '$ 0,0.00' → "$ 1,234.56"
// '($ 0,0.00)' → negative: "($ 1,234.56)"

Usage Examples:

const numeral = require('numeral');

// Basic currency formatting
console.log(numeral(1234.56).format('$0,0.00')); // "$1,234.56"
console.log(numeral(1234.56).format('0,0.00$')); // "1,234.56$"

// Currency with spaces
console.log(numeral(1234.56).format('$ 0,0.00')); // "$ 1,234.56"

// Negative currency with parentheses
console.log(numeral(-1234.56).format('($0,0.00)')); // "($1,234.56)"

// Different currency symbols (when locale is set)
numeral.locale('fr'); // Sets currency symbol to '€'
console.log(numeral(1234.56).format('$0,0.00')); // "€1 234,56"

Percentage Formatting

Format numbers as percentages with optional scaling by 100 (configurable globally).

// Percentage format detection pattern: /(%)/
// Triggered by '%' symbol in format string
// Unformat pattern: /(%)/

// Format patterns:
// '0%' → "95%" (0.95 × 100 with scalePercentBy100: true)
// '0.00%' → "95.00%"
// '0 %' → "95 %" (with space)
// '(0%)' → negative: "(5%)" for -0.05

Usage Examples:

// Basic percentage (scaling enabled by default)
console.log(numeral(0.95).format('0%')); // "95%"
console.log(numeral(0.9567).format('0.00%')); // "95.67%"

// Percentage with space
console.log(numeral(0.95).format('0 %')); // "95 %"

// Negative percentages
console.log(numeral(-0.05).format('0%')); // "-5%"
console.log(numeral(-0.05).format('(0%)')); // "(5%)"

// Parse percentage strings
console.log(numeral('95%').value()); // 0.95
console.log(numeral('95.67%').value()); // 0.9567

// Disable percentage scaling
numeral.options.scalePercentBy100 = false;
console.log(numeral(95).format('0%')); // "95%"
console.log(numeral('95%').value()); // 95

Bytes Formatting

Format numbers as file sizes with both decimal (1000-based) and binary (1024-based) calculations.

// Bytes format detection pattern: /([0\s]i?b)/
// Triggered by 'b' or 'ib' in format string
// Supports: B, KB, MB, GB, TB, PB, EB, ZB, YB (decimal)
//          B, KiB, MiB, GiB, TiB, PiB, EiB, ZiB, YiB (binary)

// Format patterns:
// '0b' → "1KB" (decimal, base 1000)
// '0ib' → "1KiB" (binary, base 1024)  
// '0.0b' → "1.2KB"
// '0 b' → "1 KB" (with space)

Usage Examples:

// Decimal bytes (base 1000)
console.log(numeral(1024).format('0b')); // "1KB"
console.log(numeral(1536).format('0.0b')); // "1.5KB"
console.log(numeral(1048576).format('0b')); // "1MB"

// Binary bytes (base 1024)  
console.log(numeral(1024).format('0ib')); // "1KiB"
console.log(numeral(1536).format('0.0ib')); // "1.5KiB"
console.log(numeral(1048576).format('0ib')); // "1MiB"

// Bytes with space
console.log(numeral(1024).format('0 b')); // "1 KB"

// Large sizes
console.log(numeral(1099511627776).format('0.0b')); // "1.1TB"

// Parse byte strings
console.log(numeral('1.5KB').value()); // 1500
console.log(numeral('1.5KiB').value()); // 1536

Ordinal Formatting

Format numbers with ordinal suffixes (1st, 2nd, 3rd, etc.) based on current locale rules.

// Ordinal format detection pattern: /(o)/
// Triggered by 'o' in format string

// Format patterns:
// '0o' → "1st", "2nd", "3rd", "4th"
// '0 o' → "1 st" (with space)
// Locale-specific: French "1er", "2e"

Usage Examples:

// Basic ordinals (English)
console.log(numeral(1).format('0o')); // "1st"
console.log(numeral(2).format('0o')); // "2nd"  
console.log(numeral(3).format('0o')); // "3rd"
console.log(numeral(4).format('0o')); // "4th"
console.log(numeral(21).format('0o')); // "21st"
console.log(numeral(22).format('0o')); // "22nd"

// Ordinals with space
console.log(numeral(1).format('0 o')); // "1 st"

// Different locales
numeral.locale('fr');
console.log(numeral(1).format('0o')); // "1er"
console.log(numeral(2).format('0o')); // "2e"

Exponential/Scientific Notation

Format numbers in exponential (scientific) notation with customizable precision.

// Exponential format detection pattern: /(e\+|e-)/
// Triggered by 'e+' or 'e-' in format string
// Unformat pattern: /(e\+|e-)/

// Format patterns:
// '0e+0' → "1e+3" (for 1000)
// '0.00e+0' → "1.23e+3" (for 1230)
// '0e-0' → "1e-3" (for 0.001)

Usage Examples:

// Basic exponential
console.log(numeral(1000).format('0e+0')); // "1e+3"
console.log(numeral(0.001).format('0e+0')); // "1e-3"

// Exponential with decimals
console.log(numeral(1234).format('0.00e+0')); // "1.23e+3"
console.log(numeral(0.001234).format('0.00e+0')); // "1.23e-3"

// Large numbers
console.log(numeral(1234567).format('0.0e+0')); // "1.2e+6"

// Parse exponential strings
console.log(numeral('1.23e+3').value()); // 1230
console.log(numeral('1.23e-3').value()); // 0.00123

Basis Points (BPS) Formatting

Format numbers as basis points (1/100th of a percent). Commonly used in finance.

// BPS format detection pattern: /(BPS)/
// Triggered by 'BPS' in format string  
// Unformat pattern: /(BPS)/
// Conversion: value × 10000 for display

// Format patterns:
// '0BPS' → "9500BPS" (for 0.95)
// '0.0BPS' → "9500.0BPS"
// '0 BPS' → "9500 BPS" (with space)

Usage Examples:

// Basic BPS formatting (multiply by 10000)
console.log(numeral(0.95).format('0BPS')); // "9500BPS"
console.log(numeral(0.0025).format('0BPS')); // "25BPS"

// BPS with decimals
console.log(numeral(0.9567).format('0.0BPS')); // "9567.0BPS"

// BPS with space
console.log(numeral(0.95).format('0 BPS')); // "9500 BPS"

// Negative BPS
console.log(numeral(-0.0025).format('0BPS')); // "-25BPS"

// Parse BPS strings (divide by 10000)
console.log(numeral('9500BPS').value()); // 0.95
console.log(numeral('25BPS').value()); // 0.0025

Time Duration Formatting

Format numbers as time duration in HH:MM:SS format. Input is total seconds.

// Time format detection pattern: /(:)/
// Triggered by ':' in format string
// Unformat pattern: /(:)/
// Input: total seconds, Output: HH:MM:SS or MM:SS

// Format patterns:
// '00:00:00' → "01:23:45" (for 5025 seconds)
// '0:0:0' → "1:23:45" (no leading zeros)

Usage Examples:

// Basic time formatting (input in seconds)
console.log(numeral(3661).format('00:00:00')); // "01:01:01" (1hr 1min 1sec)
console.log(numeral(5025).format('00:00:00')); // "01:23:45" (1hr 23min 45sec)

// Time without leading zeros
console.log(numeral(125).format('0:0:0')); // "2:5" (2min 5sec)

// Short durations
console.log(numeral(65).format('00:00:00')); // "00:01:05" (1min 5sec)
console.log(numeral(30).format('00:00:00')); // "00:00:30" (30sec)

// Parse time strings to seconds
console.log(numeral('01:23:45').value()); // 5025
console.log(numeral('02:05').value()); // 125 (2min 5sec)
console.log(numeral('1:23:45').value()); // 5025

Advanced Formatting Features

Abbreviations

Built-in support for number abbreviations that work with the current locale.

// Abbreviation patterns (work with any base format):
// '0a' → "1k", "1m", "1b", "1t" (thousand, million, billion, trillion)
// '0.0a' → "1.2k", "1.5m"  
// '0 a' → "1 k" (with space)
// Force specific: '0ak' (force thousands), '0am' (force millions)

Usage Examples:

// Auto abbreviations
console.log(numeral(1000).format('0a')); // "1k"
console.log(numeral(1200).format('0.0a')); // "1.2k"
console.log(numeral(1000000).format('0a')); // "1m"
console.log(numeral(1234567).format('0.0a')); // "1.2m"

// Forced abbreviations
console.log(numeral(1000000).format('0ak')); // "1000k" (force thousands)
console.log(numeral(1000).format('0am')); // "0m" (force millions)

// Currency with abbreviations
console.log(numeral(1234567).format('$0.0a')); // "$1.2m"

Negative Number Handling

Multiple ways to handle negative numbers in formatting.

// Negative number patterns:
// Standard: '-0,0' → "-1,234"
// Parentheses: '(0,0)' → "(1,234)" for negatives
// Signed: '+0,0' → "+1,234" or "-1,234"

Usage Examples:

// Standard negative
console.log(numeral(-1234).format('0,0')); // "-1,234"

// Parentheses for negatives
console.log(numeral(-1234).format('(0,0)')); // "(1,234)"
console.log(numeral(1234).format('(0,0)')); // "1,234"

// Always show sign
console.log(numeral(1234).format('+0,0')); // "+1,234"
console.log(numeral(-1234).format('+0,0')); // "-1,234"

Optional Decimals

Show decimals only when needed.

// Optional decimal patterns:
// '0[.]0' → "1" for 1.0, "1.5" for 1.5
// '0[.]00' → "1" for 1.0, "1.50" for 1.5

Usage Examples:

// Optional single decimal
console.log(numeral(1.0).format('0[.]0')); // "1"
console.log(numeral(1.5).format('0[.]0')); // "1.5"

// Optional double decimals
console.log(numeral(1.0).format('0[.]00')); // "1"
console.log(numeral(1.5).format('0[.]00')); // "1.50"
console.log(numeral(1.56).format('0[.]00')); // "1.56"

Format String Reference

Basic Patterns

  • 0 - Required digit (shows 0 if no digit)
  • # - Optional digit (omitted if zero)
  • . - Decimal separator
  • , - Thousands separator
  • [.] - Optional decimal point

Special Symbols

  • $ - Currency (uses locale currency symbol)
  • % - Percentage (multiplies by 100 if scalePercentBy100 is true)
  • a - Abbreviations (k, m, b, t)
  • o - Ordinal suffixes (st, nd, rd, th)
  • e+0 / e-0 - Exponential notation
  • : - Time format (HH:MM:SS)
  • BPS - Basis points (multiplies by 10000)
  • b - Bytes (decimal base 1000)
  • ib - Bytes (binary base 1024)

Sign Handling

  • () - Parentheses for negative numbers
  • + - Always show sign (+ or -)
  • - - Show sign only for negative numbers (default)

Spacing

  • Add spaces around symbols: $ 0,0.00, 0 %, 0 BPS

Install with Tessl CLI

npx tessl i tessl/npm-numeral

docs

core.md

formatting.md

index.md

localization.md

tile.json