0
# Normalize Package Data
1

2
Normalize Package Data provides comprehensive normalization and validation of package.json metadata. It transforms inconsistent package.json data into standardized formats by cleaning version numbers, converting string dependencies to objects, normalizing people fields, and inferring missing metadata from related fields.
3

4
## Package Information
5

6
- **Package Name**: normalize-package-data
7
- **Package Type**: npm
8
- **Language**: JavaScript
9
- **Node.js Version**: ^20.17.0 || >=22.9.0
10
- **Installation**: `npm install normalize-package-data`
11

12
## Core Imports
13

14
```javascript
15
const normalize = require("normalize-package-data");
16
```
17

18
## Basic Usage
19

20
```javascript
21
const normalize = require("normalize-package-data");
22

23
// Load package data
24
const packageData = require("./package.json");
25

26
// Basic normalization
27
normalize(packageData);
28
// packageData is now normalized in-place
29

30
// With warning callback
31
const warnings = [];
32
normalize(packageData, (warning) => {
33
  warnings.push(warning);
34
});
35

36
// Strict mode (Semver 2.0 compliance)
37
normalize(packageData, true);
38

39
// Strict mode with warning callback
40
normalize(packageData, (warning) => {
41
  console.error("Warning:", warning);
42
}, true);
43
```
44

45
## Architecture
46

47
Normalize Package Data operates through a central normalize function that orchestrates field-specific normalization tasks:
48

49
- **Main Function**: `normalize()` coordinates all normalization operations
50
- **Fixer Module**: Contains individual field normalization functions
51
- **Warning System**: Provides detailed feedback about data quality issues
52
- **Utility Modules**: Support functions for description extraction, safe formatting, and warning message generation
53

54
## Capabilities
55

56
### Package Normalization
57

58
Core normalization function that transforms package.json data into standardized format.
59

60
```javascript { .api }
61
/**
62
 * Normalizes package.json data in-place
63
 * @param {Object} data - Package data object to normalize
64
 * @param {Function|boolean} [warn] - Warning callback function or strict mode flag
65
 * @param {boolean} [strict] - Enable strict validation mode
66
 */
67
function normalize(data, warn, strict);
68
```
69

70
**Parameters:**
71
- `data` (Object): Package.json data to normalize (modified in-place)
72
- `warn` (Function|boolean): Warning callback function or `true` for strict mode
73
- `strict` (boolean): When `true`, enforces strict Semver 2.0 compliance and name validation
74

75
**Normalization Operations:**
76
- Version field validation and cleaning using semver
77
- Name field validation and encoding checks
78
- Repository field normalization with hosted git provider support
79
- Dependencies conversion from arrays/strings to objects
80
- People fields (author, contributors, maintainers) parsing
81
- Files, bin, man field type validation and conversion
82
- Keywords field normalization from strings to arrays
83
- License field validation against SPDX standards
84
- Bugs and homepage inference from repository data
85
- Description extraction from README when missing
86
- Common typo correction across all fields
87

88
### Advanced Access
89

90
Access to the underlying fixer module for custom normalization workflows.
91

92
```javascript { .api }
93
/**
94
 * Direct access to the fixer module with individual field normalization functions
95
 */
96
normalize.fixer: {
97
  warn: Function;
98
  fixRepositoryField: Function;
99
  fixTypos: Function;
100
  fixScriptsField: Function;
101
  fixFilesField: Function;
102
  fixBinField: Function;
103
  fixManField: Function;
104
  fixBundleDependenciesField: Function;
105
  fixDependencies: Function;
106
  fixModulesField: Function;
107
  fixKeywordsField: Function;
108
  fixVersionField: Function;
109
  fixPeople: Function;
110
  fixNameField: Function; // fixNameField(data, options)
111
  fixDescriptionField: Function;
112
  fixReadmeField: Function;
113
  fixBugsField: Function;
114
  fixHomepageField: Function;
115
  fixLicenseField: Function;
116
}
117
```
118

119
### Warning System
120

121
The warning system provides detailed feedback about data quality issues during normalization.
122

123
**Warning Callback Usage:**
124
```javascript
125
const warnings = [];
126
normalize(packageData, (message) => {
127
  warnings.push(message);
128
});
129

130
// Warning types (29 total warning messages):
131
// Missing data: missingRepository, missingDescription, missingReadme, missingLicense
132
// Invalid types: nonObjectScripts, nonStringScript, nonArrayFiles, nonArrayKeywords
133
// Invalid values: invalidFilename, invalidLicense, nonEmailUrlBugsString
134
// Dependencies: nonObjectDependencies, nonStringDependency, deprecatedArrayDependencies
135
// Typos: repositories (should be repository), dependancies (should be dependencies)
136
// URLs: brokenGitUrl, nonUrlHomepage, nonUrlBugsUrlField
137
// Deprecated: deprecatedModules
138
// Name conflicts: conflictingName (conflicts with Node.js core modules)
139
```
140

141
**Strict Mode:**
142
When strict mode is enabled:
143
- Only Semver 2.0 version strings are accepted (vs Semver 1.0 in lenient mode)
144
- Package names must not contain leading/trailing whitespace
145
- Name field is required and cannot be empty
146
- Enhanced validation across all fields
147

148
### Field-Specific Normalization
149

150
Individual field normalization functions available through `normalize.fixer`:
151

152
#### Version Field
153
```javascript { .api }
154
/**
155
 * Validates and cleans version field using semver
156
 * @param {Object} data - Package data
157
 * @param {boolean} strict - Strict mode flag
158
 */
159
fixVersionField(data, strict);
160
```
161

162
#### Dependencies
163
```javascript { .api }
164
/**
165
 * Normalizes all dependency fields (dependencies, devDependencies, optionalDependencies)
166
 * Converts arrays/strings to objects, validates URLs, merges optionalDependencies
167
 * @param {Object} data - Package data
168
 */
169
fixDependencies(data);
170
```
171

172
#### Name Field
173
```javascript { .api }
174
/**
175
 * Validates and normalizes the package name field
176
 * @param {Object} data - Package data
177
 * @param {Object|boolean} [options] - Options object or strict boolean
178
 * @param {boolean} [options.strict] - Enable strict validation
179
 * @param {boolean} [options.allowLegacyCase] - Allow legacy case patterns
180
 */
181
fixNameField(data, options);
182
```
183

184
#### People Fields
185
```javascript { .api }
186
/**
187
 * Normalizes author, contributors, and maintainers fields
188
 * Converts strings to structured objects with name, email, url properties
189
 * @param {Object} data - Package data
190
 */
191
fixPeople(data);
192
```
193

194
#### Repository Field
195
```javascript { .api }
196
/**
197
 * Normalizes repository field and infers bugs/homepage URLs
198
 * Supports hosted git providers (GitHub, GitLab, etc.)
199
 * @param {Object} data - Package data
200
 */
201
fixRepositoryField(data);
202
```
203

204
## Error Handling
205

206
The normalize function may throw errors for critical validation failures:
207

208
- **Invalid version**: Throws `Error` when version field contains invalid semver
209
- **Invalid name**: Throws `Error` when package name violates npm naming rules
210
- **Type errors**: Internal utility functions may throw `TypeError` for invalid arguments
211

212
Non-critical issues are reported through the warning callback system rather than throwing errors.
213

214
## Internal Processing
215

216
The normalize function processes fields in a specific order and performs special transformations:
217

218
**Field Processing Order:**
219
1. Basic fields: name, version, description, repository, modules, scripts, files, bin, man, bugs, keywords, readme, homepage, license
220
2. Additional processing: dependencies, people (author/contributors/maintainers), typos
221

222
**Special Behaviors:**
223
- Sets `gypfile: true` when install script is "node-gyp rebuild" and no preinstall script exists
224
- Automatically generates `_id` field as `name@version`
225
- Processes typo corrections for 22 common field misspellings:
226
  * Top-level fields: "dependancies"/"dependecies"/"depdenencies" → "dependencies", "repostitory" → "repository", "autohr"/"autor" → "author", "contributers" → "contributors", etc.
227
  * Script fields: "tests" → "test", "server" → "start"
228
  * Bugs fields: "web"/"name" → "url"
229
- Infers bugs and homepage URLs from repository information when missing
230

231
## Types
232

233
*Note: Type definitions below use TypeScript syntax for clarity, but this is a JavaScript package.*
234

235
```javascript { .api }
236
/**
237
 * Warning callback function type
238
 * @callback WarningCallback
239
 * @param {string} message - Formatted warning message
240
 */
241

242
/**
243
 * Person object structure (normalized from string format)
244
 */
245
interface PersonObject {
246
  name?: string;
247
  email?: string;
248
  url?: string;
249
}
250

251
/**
252
 * Repository object structure
253
 */
254
interface RepositoryObject {
255
  type: string;
256
  url: string;
257
}
258

259
/**
260
 * Bugs object structure
261
 */
262
interface BugsObject {
263
  url?: string;
264
  email?: string;
265
}
266
```