expand-pkg

expand-pkg

Parse string values in package.json into objects.

You might also be interested in normalize-pkg.

Install

Install with npm:

$ npm install expand-pkg --save

Usage

var Config = require('./');
var config = new Config();
console.log(config.expand(require('./package')));

Schema

Values are parsed using a schema that is passed to map-schema (builds on the schema from normalize-pkg as a starting point):

• only properties that have a corresponding field on the schema will be parsed.
• any properties that do not have a corresponding field are returned unmodified.

See the .field docs 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 .expand is run and a property that is required or recommended by npm is missing, expand-pkg attempts to create the field if valid data can be found in the repository.

The following fields are the only built-in fields with default values:

• version: '0.1.0'
• license: 'MIT'
• engines: {node: '>= 0.10.0'}

API

Config

Create an instance of Config with the given options.

Params

• options {Object}

Example

var config = new Config();
var pkg = config.expand({
  author: 'Jon Schlinkert (https://github.com/jonschlinkert)'
});
console.log(pkg);
//=> {name: 'Jon Schlinkert', url: 'https://github.com/jonschlinkert'}

.field

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 given package.json value when the .expand 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

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

Example

var config = new Config();

config.field('foo', 'string', {
  default: 'bar'
});

var pkg = config.expand({});
console.log(pkg);
//=> {foo:  'bar'}

.expand

Iterate over pkg properties and expand values that have corresponding fields registered on the schema.

Params

• pkg {Object}: The package.json object to expand
• options {Object}
• returns {Object}: Returns an expanded package.json object.

Example

var config = new Config();
var pkg = config.expand(require('./package.json'));

Options

options.knownOnly

Type

: boolean

Default: undefined

Omit properties from package.json that do not have a field registered on the schema.

var Config = require('expand-pkg');
var config = new Config({knownOnly: true});

console.log(config.expand({author: 'Brian Woodward', foo: 'bar'}));
//=> {author: {name: 'Brian Woodward'}}

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):

var pkg = config.expand(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, pass true if you want to extend a field that is already defined on the schema.

var pkg = config.expand(require('./package'), {
  extend: true,
  fields: {
    name: {
      normalize: function() {
        return 'bar'
      }
    }
  }
});

console.log(pkg.name);
//=> 'bar'

Related projects

You might also be interested in these projects:

• normalize-pkg: Normalize values in package.json using the map-schema library. | homepage
• repo-utils: Utils for normalizing and formatting repo data. | homepage
• sync-pkg: CLI to sync only basic properties from package.json to bower.json. | homepage

Contributing

Pull requests and stars are always welcome. For bugs and feature requests, please create an issue.

Building docs

Generate readme and API documentation with verb:

$ npm install verb && npm run docs

Or, if verb is installed globally:

$ verb

Running tests

Install dev dependencies:

$ npm install -d && npm test

Author

Jon Schlinkert

• github/jonschlinkert
• twitter/jonschlinkert

License

Copyright © 2016, Jon Schlinkert. Released under the MIT license.

---

This file was generated by verb, v, on March 29, 2016.