README.md
1# normalize-package-data [](https://travis-ci.org/npm/normalize-package-data)
2
3normalize-package-data exports a function that normalizes package metadata. This data is typically found in a package.json file, but in principle could come from any source - for example the npm registry.
4
5normalize-package-data is used by [read-package-json](https://npmjs.org/package/read-package-json) to normalize the data it reads from a package.json file. In turn, read-package-json is used by [npm](https://npmjs.org/package/npm) and various npm-related tools.
6
7## Installation
8
9```
10npm install normalize-package-data
11```
12
13## Usage
14
15Basic usage is really simple. You call the function that normalize-package-data exports. Let's call it `normalizeData`.
16
17```javascript
18normalizeData = require('normalize-package-data')
19packageData = require("./package.json")
20normalizeData(packageData)
21// packageData is now normalized
22```
23
24#### Strict mode
25
26You may activate strict validation by passing true as the second argument.
27
28```javascript
29normalizeData = require('normalize-package-data')
30packageData = require("./package.json")
31normalizeData(packageData, true)
32// packageData is now normalized
33```
34
35If strict mode is activated, only Semver 2.0 version strings are accepted. Otherwise, Semver 1.0 strings are accepted as well. Packages must have a name, and the name field must not have contain leading or trailing whitespace.
36
37#### Warnings
38
39Optionally, you may pass a "warning" function. It gets called whenever the `normalizeData` function encounters something that doesn't look right. It indicates less than perfect input data.
40
41```javascript
42normalizeData = require('normalize-package-data')
43packageData = require("./package.json")
44warnFn = function(msg) { console.error(msg) }
45normalizeData(packageData, warnFn)
46// packageData is now normalized. Any number of warnings may have been logged.
47```
48
49You may combine strict validation with warnings by passing `true` as the second argument, and `warnFn` as third.
50
51When `private` field is set to `true`, warnings will be suppressed.
52
53### Potential exceptions
54
55If the supplied data has an invalid name or version vield, `normalizeData` will throw an error. Depending on where you call `normalizeData`, you may want to catch these errors so can pass them to a callback.
56
57## What normalization (currently) entails
58
59* The value of `name` field gets trimmed (unless in strict mode).
60* The value of the `version` field gets cleaned by `semver.clean`. See [documentation for the semver module](https://github.com/isaacs/node-semver).
61* If `name` and/or `version` fields are missing, they are set to empty strings.
62* If `files` field is not an array, it will be removed.
63* If `bin` field is a string, then `bin` field will become an object with `name` set to the value of the `name` field, and `bin` set to the original string value.
64* If `man` field is a string, it will become an array with the original string as its sole member.
65* If `keywords` field is string, it is considered to be a list of keywords separated by one or more white-space characters. It gets converted to an array by splitting on `\s+`.
66* All people fields (`author`, `maintainers`, `contributors`) get converted into objects with name, email and url properties.
67* If `bundledDependencies` field (a typo) exists and `bundleDependencies` field does not, `bundledDependencies` will get renamed to `bundleDependencies`.
68* If the value of any of the dependencies fields (`dependencies`, `devDependencies`, `optionalDependencies`) is a string, it gets converted into an object with familiar `name=>value` pairs.
69* The values in `optionalDependencies` get added to `dependencies`. The `optionalDependencies` array is left untouched.
70* As of v2: Dependencies that point at known hosted git providers (currently: github, bitbucket, gitlab) will have their URLs canonicalized, but protocols will be preserved.
71* As of v2: Dependencies that use shortcuts for hosted git providers (`org/proj`, `github:org/proj`, `bitbucket:org/proj`, `gitlab:org/proj`, `gist:docid`) will have the shortcut left in place. (In the case of github, the `org/proj` form will be expanded to `github:org/proj`.) THIS MARKS A BREAKING CHANGE FROM V1, where the shorcut was previously expanded to a URL.
72* If `description` field does not exist, but `readme` field does, then (more or less) the first paragraph of text that's found in the readme is taken as value for `description`.
73* If `repository` field is a string, it will become an object with `url` set to the original string value, and `type` set to `"git"`.
74* If `repository.url` is not a valid url, but in the style of "[owner-name]/[repo-name]", `repository.url` will be set to git+https://github.com/[owner-name]/[repo-name].git
75* If `bugs` field is a string, the value of `bugs` field is changed into an object with `url` set to the original string value.
76* If `bugs` field does not exist, but `repository` field points to a repository hosted on GitHub, the value of the `bugs` field gets set to an url in the form of https://github.com/[owner-name]/[repo-name]/issues . If the repository field points to a GitHub Gist repo url, the associated http url is chosen.
77* If `bugs` field is an object, the resulting value only has email and url properties. If email and url properties are not strings, they are ignored. If no valid values for either email or url is found, bugs field will be removed.
78* If `homepage` field is not a string, it will be removed.
79* If the url in the `homepage` field does not specify a protocol, then http is assumed. For example, `myproject.org` will be changed to `http://myproject.org`.
80* If `homepage` field does not exist, but `repository` field points to a repository hosted on GitHub, the value of the `homepage` field gets set to an url in the form of https://github.com/[owner-name]/[repo-name]#readme . If the repository field points to a GitHub Gist repo url, the associated http url is chosen.
81
82### Rules for name field
83
84If `name` field is given, the value of the name field must be a string. The string may not:
85
86* start with a period.
87* contain the following characters: `/@\s+%`
88* contain any characters that would need to be encoded for use in urls.
89* resemble the word `node_modules` or `favicon.ico` (case doesn't matter).
90
91### Rules for version field
92
93If `version` field is given, the value of the version field must be a valid *semver* string, as determined by the `semver.valid` method. See [documentation for the semver module](https://github.com/isaacs/node-semver).
94
95### Rules for license field
96
97The `license` field should be a valid *SPDX license expression* or one of the special values allowed by [validate-npm-package-license](https://npmjs.com/package/validate-npm-package-license). See [documentation for the license field in package.json](https://docs.npmjs.com/files/package.json#license).
98
99## Credits
100
101This package contains code based on read-package-json written by Isaac Z. Schlueter. Used with permisson.
102
103## License
104
105normalize-package-data is released under the [BSD 2-Clause License](http://opensource.org/licenses/MIT).
106Copyright (c) 2013 Meryn Stol
107
){kind=link}