0
# Humanize Plus
1

2
Humanize Plus is a simple utility library for making the web more humane. It provides functions for formatting numbers with commas and compact representations, converting integers to ordinals, pluralizing words, truncating and capitalizing strings, formatting file sizes in human-readable formats, and creating readable lists from arrays.
3

4
## Package Information
5

6
- **Package Name**: humanize-plus
7
- **Package Type**: npm
8
- **Language**: JavaScript
9
- **Installation**: `npm install humanize-plus`
10

11
## Core Imports
12

13
```javascript
14
const Humanize = require('humanize-plus');
15
```
16

17
For ES6 modules:
18

19
```javascript
20
import Humanize from 'humanize-plus';
21
```
22

23
Browser global:
24

25
```html
26
<script src="humanize.min.js"></script>
27
<script>
28
  // Humanize is available globally
29
</script>
30
```
31

32
## Basic Usage
33

34
```javascript
35
const Humanize = require('humanize-plus');
36

37
// Format numbers
38
console.log(Humanize.intComma(1234567)); // "1,234,567"
39
console.log(Humanize.compactInteger(1234567, 1)); // "1.2M"
40

41
// File sizes
42
console.log(Humanize.fileSize(1024 * 1024)); // "1.00 MB"
43

44
// String operations
45
console.log(Humanize.capitalize('hello world')); // "Hello world"
46
console.log(Humanize.truncate('This is a long string', 10)); // "This is..."
47

48
// Pluralization and lists
49
console.log(Humanize.pluralize(3, 'cat')); // "cats"
50
console.log(Humanize.oxford(['red', 'green', 'blue'])); // "red, green, and blue"
51
```
52

53
## Architecture
54

55
Humanize Plus exposes a single Humanize object containing all utility functions. The library uses a UMD wrapper for compatibility across CommonJS, AMD, and browser global environments. All functions are stateless utilities that accept input parameters and return formatted strings or numbers.
56

57
## Capabilities
58

59
### Number Formatting
60

61
Functions for formatting numbers with thousand separators, compact notation, ordinals, and bounded values.
62

63
```javascript { .api }
64
// Add commas to numbers
65
function intComma(number: number, decimals?: number): string;
66

67
// Compact integer representation (1k, 1M, 1B, 1T)
68
function compactInteger(input: number, decimals?: number): string;
69

70
// Convert to ordinal (1st, 2nd, 3rd, etc.)
71
function ordinal(value: number): string;
72

73
// Format with custom separators
74
function formatNumber(
75
  number: number, 
76
  precision?: number, 
77
  thousand?: string, 
78
  decimal?: string
79
): string;
80

81
// Bound number to upper limit
82
function boundedNumber(num: number, bound?: number, ending?: string): string;
83
```
84

85
[Number Formatting](./number-formatting.md)
86

87
### File Size Formatting
88

89
Human-readable file size formatting with appropriate units.
90

91
```javascript { .api }
92
// Convert bytes to human-readable format
93
function fileSize(filesize: number, precision?: number): string;
94
```
95

96
[File Size Formatting](./file-size.md)
97

98
### String Operations
99

100
Text manipulation including capitalization, truncation, and line break conversion.
101

102
```javascript { .api }
103
// Capitalize first letter
104
function capitalize(string: string, downCaseTail?: boolean): string;
105

106
// Capitalize all words
107
function capitalizeAll(string: string): string;
108

109
// Title case with proper grammar
110
function titleCase(string: string): string;
111

112
// Truncate to character or word limit
113
function truncate(str: string, length?: number, ending?: string): string;
114
function truncateWords(string: string, length: number): string;
115

116
// Convert line breaks
117
function nl2br(string: string, replacement?: string): string;
118
function br2nl(string: string, replacement?: string): string;
119
```
120

121
[String Operations](./string-operations.md)
122

123
### Pluralization and Lists
124

125
Functions for handling pluralization and converting arrays to readable strings.
126

127
```javascript { .api }
128
// Pluralize words based on count
129
function pluralize(number: number, singular: string, plural?: string): string;
130

131
// Convert arrays to Oxford comma lists
132
function oxford(items: string[], limit?: number, limitStr?: string): string;
133

134
// Convert occurrence counts to words
135
function times(value: number, overrides?: object): string;
136
```
137

138
[Pluralization and Lists](./pluralization-lists.md)
139

140
### Utility Functions
141

142
Helper functions for precision handling and object conversion.
143

144
```javascript { .api }
145
// Fix JavaScript's toFixed rounding issues
146
function toFixed(value: number, precision?: number): string;
147

148
// Normalize precision to positive integer
149
function normalizePrecision(value: number, base?: number): number;
150

151
// Convert objects to definition strings
152
function dictionary(object: object, joiner?: string, separator?: string): string;
153

154
// Calculate pace/frequency
155
function pace(value: number, intervalMs: number, unit?: string): string;
156

157
// Describe array frequency
158
function frequency(list: any[], verb: string): string;
159
```
160

161
[Utility Functions](./utility-functions.md)
162

163
## Deprecated Functions
164

165
The following functions are deprecated and will be removed in the next major version:
166

167
- `intword` → use `compactInteger`
168
- `intcomma` → use `intComma`
169
- `filesize` → use `fileSize`
170
- `truncatewords` → use `truncateWords`
171
- `truncatenumber` → use `boundedNumber`
172
- `titlecase` → use `titleCase`