0
# Numeral.js
1

2
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.
3

4
## Package Information
5

6
- **Package Name**: numeral
7
- **Package Type**: npm
8
- **Language**: JavaScript (with TypeScript-compatible API patterns)
9
- **Installation**: `npm install numeral`
10

11
## Core Imports
12

13
```javascript
14
const numeral = require('numeral');
15
```
16

17
For ES modules:
18

19
```javascript
20
import numeral from 'numeral';
21
```
22

23
Browser (global):
24

25
```javascript
26
// Include script tag, then use:
27
const num = numeral(1234);
28
```
29

30
## Basic Usage
31

32
```javascript
33
const numeral = require('numeral');
34

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

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

44
// Chain mathematical operations
45
const result = numeral(100)
46
    .add(50)
47
    .multiply(2)
48
    .subtract(25)
49
    .format('0,0');
50
console.log(result); // "275"
51

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

58
## Architecture
59

60
Numeral.js is built around several key components:
61

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

68
## Capabilities
69

70
### Core Functionality
71

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

74
```javascript { .api }
75
function numeral(input: number | string | Numeral | null | undefined): Numeral;
76

77
interface Numeral {
78
  format(inputString?: string, roundingFunction?: Function): string;
79
  value(): number | null;
80
  set(value: number): Numeral;
81
  add(value: number): Numeral;
82
  subtract(value: number): Numeral;
83
  multiply(value: number): Numeral;
84
  divide(value: number): Numeral;
85
  difference(value: number): number;
86
  clone(): Numeral;
87
}
88
```
89

90
[Core Functionality](./core.md)
91

92
### Number Formatting
93

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

96
```javascript { .api }
97
// Built-in format plugins
98
format(formatString: string, roundingFunction?: Function): string;
99

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

110
[Number Formatting](./formatting.md)
111

112
### Localization
113

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

116
```javascript { .api }
117
// Locale management
118
numeral.locale(key?: string): string;
119
numeral.localeData(key?: string): LocaleData;
120
numeral.register(type: 'locale', name: string, definition: LocaleData): LocaleData;
121

122
interface LocaleData {
123
  delimiters: {
124
    thousands: string;
125
    decimal: string;
126
  };
127
  abbreviations: {
128
    thousand: string;
129
    million: string;
130
    billion: string;
131
    trillion: string;
132
  };
133
  ordinal: (number: number) => string;
134
  currency: {
135
    symbol: string;
136
  };
137
}
138
```
139

140
[Localization](./localization.md)
141

142
## Static Methods
143

144
```javascript { .api }
145
// Version and utilities
146
numeral.version: string;
147
numeral.isNumeral(obj: any): boolean;
148
numeral.validate(val: string, culture?: string): boolean;
149

150
// Configuration
151
numeral.reset(): void;
152
numeral.defaultFormat(format: string): void;
153
numeral.zeroFormat(format?: string): void;
154
numeral.nullFormat(format?: string): void;
155

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

159
// Access to registries
160
numeral.options: ConfigOptions;
161
numeral.formats: Record<string, FormatPlugin>;
162
numeral.locales: Record<string, LocaleData>;
163
```
164

165
## Configuration Types
166

167
```javascript { .api }
168
interface ConfigOptions {
169
  currentLocale: string;
170
  zeroFormat: string | null;
171
  nullFormat: string | null;
172
  defaultFormat: string;
173
  scalePercentBy100: boolean;
174
}
175

176
interface FormatPlugin {
177
  regexps: {
178
    format: RegExp;
179
    unformat?: RegExp;
180
  };
181
  format: (value: number, format: string, roundingFunction: Function) => string;
182
  unformat?: (string: string) => number;
183
}
184
```