# normalize-pkg [![NPM version](https://img.shields.io/npm/v/normalize-pkg.svg?style=flat)](https://www.npmjs.com/package/normalize-pkg) [![NPM downloads](https://img.shields.io/npm/dm/normalize-pkg.svg?style=flat)](https://npmjs.org/package/normalize-pkg) [![Linux Build Status](https://img.shields.io/travis/jonschlinkert/normalize-pkg.svg?style=flat&label=Travis)](https://travis-ci.org/jonschlinkert/normalize-pkg) > Normalize values in package.json using the map-schema library. ## Table of Contents - [Install](#install) - [Install](#install-1) - [Usage](#usage) - [Features](#features) - [Schema](#schema) - [Defaults](#defaults) - [API](#api) - [Options](#options) * [options.knownOnly](#optionsknownonly) * [options.pick](#optionspick) * [options.omit](#optionsomit) * [options.fields](#optionsfields) * [options.extend](#optionsextend) - [About](#about) * [Related projects](#related-projects) * [Contributing](#contributing) * [Contributors](#contributors) * [Release history](#release-history) * [Building docs](#building-docs) * [Running tests](#running-tests) * [Author](#author) * [License](#license) _(TOC generated by [verb](https://github.com/verbose/verb) using [markdown-toc](https://github.com/jonschlinkert/markdown-toc))_ ## Install Install with [npm](https://www.npmjs.com/): ```sh $ npm install --save normalize-pkg ``` ## Install Install with [bower](http://bower.io/) ```sh $ bower install normalize-pkg --save ``` ## Usage ```js var config = require('./')(); var pkg = config.normalize(require('./package')); ``` ## Features Normalizes most package.json fields, and: * converts `repository` objects to a string * stringifies `author` object * stringifies each "person" object in `maintainers`, `contributors` and `collaborators` * converts `licenses` arrays and objects to a `license` string * removes files that don't exist from `bin`, `main` and the `files` array * adds `cli.js` to `bin` if it exists * creates `keywords` array from `name` if not defined See the [schema](lib/schema.js), [normalizers](lib/normalizers), and [unit tests](test) for more examples. ## Schema Values are normalized using a [schema](lib/schema.js) that is passed to [map-schema](https://github.com/jonschlinkert/map-schema). * only properties that have a corresponding field on the schema will be normalized. * any properties that do not have a corresponding field are returned unmodified. See the [.field docs](#field) to learn how to add or overwrite a field on the schema. ## Defaults A `default` value may optionally be defined when a `.field` is registered. When `.normalize` is run and a property that is required or recommended by npm is missing, `normalize-pkg` attempts to create the field if valid data can be found in the repository. built-in fields have a default value: * `version`: `'0.1.0'` * `license`: `'MIT'` * `engines`: `{node: '>= 0.10.0'}` For example: * `name`: the [project-name](https://github.com/jonschlinkert/project-name) library is used to fill in the name * `bin`: if empty, populated with `cli.js` or `bin` if either exists on the file system **Example** The following: ```js var config = require('./')(); // no package.json is passed, just an empty object var pkg = config.normalize({}); console.log(pkg); ``` **Results** Since an empty object was passed, `normalize-pkg` was smart enough to fill in missing fields looking for info in the project. In this case, specifically from parsing `.git` config and using any defaults defined on the schema. ```js { name: 'normalize-pkg', version: '0.1.0', homepage: 'https://github.com/jonschlinkert/normalize-pkg', repository: 'jonschlinkert/normalize-pkg', license: 'MIT', files: [ 'index.js' ], main: 'index.js', engines: { node: '>= 0.10.0' } } ``` ## API ### [NormalizePkg](index.js#L26) Create an instance of `NormalizePkg` with the given `options`. **Example** ```js var config = new NormalizePkg(); var pkg = config.normalize({ author: { name: 'Jon Schlinkert', url: 'https://github.com/jonschlinkert' } }); console.log(pkg); //=> {author: 'Jon Schlinkert (https://github.com/jonschlinkert)'} ``` **Params** * `options` **{Object}** ### [.field](index.js#L76) Add a field to the schema, or overwrite or extend an existing field. The last argument is an `options` object that supports the following properties: * `normalize` **{Function}**: function to be called on the value when the `.normalize` method is called * `default` **{any}**: default value to be used when the package.json property is undefined. * `required` **{Boolean}**: define `true` if the property is required **Example** ```js var config = new NormalizePkg(); config.field('foo', 'string', { default: 'bar' }); var pkg = config.normalize({}); console.log(pkg); //=> {foo: 'bar'} ``` **Params** * `name` **{String}**: Field name (required) * `type` **{String|Array}**: One or more native javascript types allowed for the property value (required) * `options` **{Object}** * `returns` **{Object}**: Returns the instance ### [.normalize](index.js#L102) Iterate over `pkg` properties and normalize values that have corresponding [fields](#field) registered on the schema. **Example** ```js var config = new NormalizePkg(); var pkg = config.normalize(require('./package.json')); ``` **Params** * `pkg` **{Object}**: The `package.json` object to normalize * `options` **{Object}** * `returns` **{Object}**: Returns a normalized package.json object. ## Options ### options.knownOnly **Type**: `boolean` **Default**: `undefined` Omit properties from package.json that do not have a field registered on the schema. ```js var Config = require('normalize-pkg'); var config = new Config({knownOnly: true}); var pkg = config.normalize({name: 'my-project', foo: 'bar'}); console.log(pkg); //=> {name: 'my-project'} ``` ### options.pick **Type**: `array` **Default**: `undefined` Filter the resulting object to contain only the specified keys. ### options.omit **Type**: `array` **Default**: `undefined` Remove the specified keys from the resulting object. ### options.fields Pass a `fields` object on the options to customize any fields on the schema (also see [options.extend](#options-extend)): ```js var pkg = config.normalize(require('./package'), { extend: true, fields: { name: { normalize: function() { return 'bar' } } } }); console.log(pkg.name); //=> 'bar' ``` ### options.extend **Type**: `boolean` **Default**: `undefined` Used with [options.field](#options-field), pass `true` if you want to extend a field that is already defined on the schema. ```js var pkg = config.normalize(require('./package'), { extend: true, fields: { name: { normalize: function() { return 'bar' } } } }); console.log(pkg.name); //=> 'bar' ``` ## About ### Related projects [update](https://www.npmjs.com/package/update): Be scalable! Update is a new, open source developer framework and CLI for automating updates… [more](https://github.com/update/update) | [homepage](https://github.com/update/update "Be scalable! Update is a new, open source developer framework and CLI for automating updates of any kind in code projects.") ### Contributing Pull requests and stars are always welcome. For bugs and feature requests, [please create an issue](../../issues/new). ### Contributors | **Commits** | **Contributor**
| | --- | --- | | 143 | [jonschlinkert](https://github.com/jonschlinkert) | | 12 | [doowb](https://github.com/doowb) | | 2 | [pdehaan](https://github.com/pdehaan) | ### Building docs _(This document was generated by [verb-generate-readme](https://github.com/verbose/verb-generate-readme) (a [verb](https://github.com/verbose/verb) generator), please don't edit the readme directly. Any changes to the readme must be made in [.verb.md](.verb.md).)_ To generate the readme and API documentation with [verb](https://github.com/verbose/verb): ```sh $ npm install -g verb verb-generate-readme && verb ``` ### Running tests Install dev dependencies: ```sh $ npm install -d && npm test ``` ### Author **Jon Schlinkert** * [github/jonschlinkert](https://github.com/jonschlinkert) * [twitter/jonschlinkert](http://twitter.com/jonschlinkert) ### License Copyright © 2016, [Jon Schlinkert](https://github.com/jonschlinkert). Released under the [MIT license](LICENSE). *** _This file was generated by [verb-generate-readme](https://github.com/verbose/verb-generate-readme), v0.2.0, on October 29, 2016._