or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

core.mdformatting.mdindex.mdlocalization.md
tile.json

tessl/npm-numeral

A javascript library for formatting and manipulating numbers.

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/numeral@2.0.x

To install, run

npx @tessl/cli install tessl/npm-numeral@2.0.0

index.mddocs/

Numeral.js

Numeral.js is a JavaScript library that provides comprehensive number formatting and manipulation capabilities for web applications and Node.js environments. It offers extensive formatting options including currency, percentages, bytes, exponential notation, ordinals, and support for multiple locales with customizable number formatting rules.

Package Information

  • Package Name: numeral
  • Package Type: npm
  • Language: JavaScript (with TypeScript-compatible API patterns)
  • Installation: npm install numeral

Core Imports

const numeral = require('numeral');

For ES modules:

import numeral from 'numeral';

Browser (global):

// Include script tag, then use:
const num = numeral(1234);

Basic Usage

const numeral = require('numeral');

// Create and format numbers
const num = numeral(1234.56);
console.log(num.format('0,0.00')); // "1,234.56"
console.log(num.format('$0,0.00')); // "$1,234.56"

// Parse formatted strings back to numbers
const parsed = numeral('$1,234.56');
console.log(parsed.value()); // 1234.56

// Chain mathematical operations
const result = numeral(100)
    .add(50)
    .multiply(2)
    .subtract(25)
    .format('0,0');
console.log(result); // "275"

// Format with different styles
console.log(numeral(1000000).format('0.0a')); // "1.0m"
console.log(numeral(0.95).format('0%')); // "95%"
console.log(numeral(1024).format('0b')); // "1KB"

Architecture

Numeral.js is built around several key components:

  • Factory Function: Main numeral() function creates instances from various input types
  • Instance Methods: Chainable methods for mathematical operations and formatting
  • Plugin System: Modular format plugins (currency, percentage, bytes, etc.) and locale definitions
  • Static Configuration: Global settings for default formats, zero/null handling, and locale management
  • Precision Handling: Built-in correction factors to handle JavaScript floating-point arithmetic issues

Capabilities

Core Functionality

Core number creation, manipulation, and basic formatting operations including mathematical operations with precision handling.

function numeral(input: number | string | Numeral | null | undefined): Numeral;

interface Numeral {
  format(inputString?: string, roundingFunction?: Function): string;
  value(): number | null;
  set(value: number): Numeral;
  add(value: number): Numeral;
  subtract(value: number): Numeral;
  multiply(value: number): Numeral;
  divide(value: number): Numeral;
  difference(value: number): number;
  clone(): Numeral;
}

Core Functionality

Number Formatting

Comprehensive formatting system with built-in plugins for currency, percentages, bytes, exponential notation, ordinals, basis points, and time duration formatting.

// Built-in format plugins
format(formatString: string, roundingFunction?: Function): string;

// Format patterns:
// Currency: '$0,0.00' → "$1,234.56"
// Percentage: '0.00%' → "95.00%"  
// Bytes: '0.0b' → "1.2KB"
// Ordinal: '0o' → "1st", "2nd", "3rd"
// BPS: '0BPS' → "9500BPS" (basis points)
// Time: '00:00:00' → "01:23:45"
// Exponential: '0.00e+0' → "1.23e+4"

Number Formatting

Localization

Multi-locale support with 35 built-in locales and customizable number formatting rules including thousands separators, decimal points, currency symbols, and abbreviations.

// Locale management
numeral.locale(key?: string): string;
numeral.localeData(key?: string): LocaleData;
numeral.register(type: 'locale', name: string, definition: LocaleData): LocaleData;

interface LocaleData {
  delimiters: {
    thousands: string;
    decimal: string;
  };
  abbreviations: {
    thousand: string;
    million: string;
    billion: string;
    trillion: string;
  };
  ordinal: (number: number) => string;
  currency: {
    symbol: string;
  };
}

Localization

Static Methods

// Version and utilities
numeral.version: string;
numeral.isNumeral(obj: any): boolean;
numeral.validate(val: string, culture?: string): boolean;

// Configuration
numeral.reset(): void;
numeral.defaultFormat(format: string): void;
numeral.zeroFormat(format?: string): void;
numeral.nullFormat(format?: string): void;

// Plugin registration
numeral.register(type: 'format' | 'locale', name: string, definition: object): object;

// Access to registries
numeral.options: ConfigOptions;
numeral.formats: Record<string, FormatPlugin>;
numeral.locales: Record<string, LocaleData>;

Configuration Types

interface ConfigOptions {
  currentLocale: string;
  zeroFormat: string | null;
  nullFormat: string | null;
  defaultFormat: string;
  scalePercentBy100: boolean;
}

interface FormatPlugin {
  regexps: {
    format: RegExp;
    unformat?: RegExp;
  };
  format: (value: number, format: string, roundingFunction: Function) => string;
  unformat?: (string: string) => number;
}