Repository files navigation

normalize-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.

normalize-package-data is used byread-package-json to normalize the data it reads from a package.json file. In turn, read-package-json is used bynpm and various npm-related tools.

npm install normalize-package-data

Basic usage is really simple. You call the function that normalize-package-data exports. Let's call itnormalizeData.

normalizeData=require('normalize-package-data')packageData=require("./package.json")normalizeData(packageData)// packageData is now normalized

You may activate strict validation by passing true as the second argument.

normalizeData=require('normalize-package-data')packageData=require("./package.json")normalizeData(packageData,true)// packageData is now normalized

If 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.

Optionally, you may pass a "warning" function. It gets called whenever thenormalizeData function encounters something that doesn't look right. It indicates less than perfect input data.

normalizeData=require('normalize-package-data')packageData=require("./package.json")warnFn=function(msg){console.error(msg)}normalizeData(packageData,warnFn)// packageData is now normalized. Any number of warnings may have been logged.

You may combine strict validation with warnings by passingtrue as the second argument, andwarnFn as third.

Whenprivate field is set totrue, warnings will be suppressed.

If the supplied data has an invalid name or version field,normalizeData will throw an error. Depending on where you callnormalizeData, you may want to catch these errors so can pass them to a callback.

• The value ofname field gets trimmed (unless in strict mode).
• The value of theversion field gets cleaned bysemver.clean. Seedocumentation for the semver module.
• Ifname and/orversion fields are missing, they are set to empty strings.
• Iffiles field is not an array, it will be removed.
• Ifbin field is a string, thenbin field will become an object withname set to the value of thename field, andbin set to the original string value.
• Ifman field is a string, it will become an array with the original string as its sole member.
• Ifkeywords 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+.
• All people fields (author,maintainers,contributors) get converted into objects with name, email and url properties.
• IfbundledDependencies field (a typo) exists andbundleDependencies field does not,bundledDependencies will get renamed tobundleDependencies.
• If the value of any of the dependencies fields (dependencies,devDependencies,optionalDependencies) is a string, it gets converted into an object with familiarname=>value pairs.
• The values inoptionalDependencies get added todependencies. TheoptionalDependencies array is left untouched.
• 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.
• 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, theorg/proj form will be expanded togithub:org/proj.) THIS MARKS A BREAKING CHANGE FROM V1, where the shortcut was previously expanded to a URL.
• Ifdescription field does not exist, butreadme field does, then (more or less) the first paragraph of text that's found in the readme is taken as value fordescription.
• Ifrepository field is a string, it will become an object withurl set to the original string value, andtype set to"git".
• Ifrepository.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
• Ifbugs field is a string, the value ofbugs field is changed into an object withurl set to the original string value.
• Ifbugs field does not exist, butrepository field points to a repository hosted on GitHub, the value of thebugs field gets set to an url in the form ofhttps://github.com/[owner-name]/[repo-name]/issues . If the repository field points to a GitHub Gist repo url, the associated http url is chosen.
• Ifbugs 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.
• Ifhomepage field is not a string, it will be removed.
• If the url in thehomepage field does not specify a protocol, then http is assumed. For example,myproject.org will be changed tohttp://myproject.org.
• Ifhomepage field does not exist, butrepository field points to a repository hosted on GitHub, the value of thehomepage field gets set to an url in the form ofhttps://github.com/[owner-name]/[repo-name]#readme . If the repository field points to a GitHub Gist repo url, the associated http url is chosen.

Ifname field is given, the value of the name field must be a string. The string may not:

• start with a period.
• contain the following characters:/@\s+%
• contain any characters that would need to be encoded for use in urls.
• resemble the wordnode_modules orfavicon.ico (case doesn't matter).

Ifversion field is given, the value of the version field must be a validsemver string, as determined by thesemver.valid method. Seedocumentation for the semver module.

Thelicense/licence field should be a validSPDX license expression or one of the special values allowed byvalidate-npm-package-license. Seedocumentation for the license field in package.json.

This package contains code based on read-package-json written by Isaac Z. Schlueter. Used with permission.

normalize-package-data is released under theBSD 2-Clause License.Copyright (c) 2013 Meryn Stol