/nice-package

📦 Clean up messy package metadata from the npm registry

Primary LanguageJavaScript

nice-package ✨📦✨ Build Status

Clean up messy package metadata from the npm registry

The package data served by the npm registry is messy and confusing. The folks at npm, Inc maintain a tool called normalize-package-data which does a lot of work to clean this data up, but the resulting object is still a bit confusing.

nice-package uses normalize-package-data as a starter, then does even more package cleanup:

  • uses the doc['dist-tags'].latest as the baseline for package metadata
  • derives starsCount from the users object
  • derives a versions array from the time object
  • renames _npmUser to lastPublisher, because it's a more intuitive name.
  • renames maintainers to owners, for consistency with the CLI commands.
  • normalizes GitHub repository URLs to https format
  • moves internal bookkeeping properties like _id and _from into an other object that can easily be omitted.
  • more...

See Also

Installation

npm install nice-package --save

Usage

nice-package exports a class. To create a new package instance, call new Package(doc), where doc is a JSON package object from the npm registry:

const got = require('got')
const Package = require('nice-package')

got('https://registry.npmjs.com/express', {json: true})
  .then(function (doc) {
    var pkg = new Package(doc)
    console.log(JSON.stringify(pkg, null, 2))
  })

You can also instantiate a nice package from package.json data:

const Package = require('nice-package')
const pkg = new Package(require('node_modules/express/package.json'))

pkg.dependsOn('array-flatten')
// => true

Customizing the Package Object

You can pick specific properties to return:

const pkg = new Package(pkgData, {pick: ['name', 'description']})

// {
//   name: 'tlds',
//   description: 'List of TLDs'
// }

or you can omit properties. Sometimes you don't want the other data, the readme, etc.

const pkg = new Package(pkgData, {omit: ['other', 'readme', 'versions']})

Note: pick and omit will also accept comma-delimited strings instead of arrays. This works nicely if you're using query params from a URL as options to nice-package:

const pkg = new Package(pkgData, {omit: 'other,readme,versions'})

Convenience Methods

A nice package comes with convenience methods:

pkg.mentions(query)

  • query String

Performs a case-insensitive search against the JSON-stringified object. Returns a Boolean indicating whether the given query is present in the object.

pkg.dependsOn(pkgName)

  • pkgName String - The name of another package

Returns a Boolean indicating whether the given pkgName is listed in dependencies.

pkg.devDependsOn(pkgName)

  • pkgName String - The name of another package

Returns a Boolean indicating whether the given pkgName is listed in devDependencies.

pkg.somehowDependsOn(pkgName)

  • pkgName String - The name of another package

Returns a Boolean indicating whether the given pkgName is listed in dependencies or devDependencies.

pkg.depNames

A getter method that returns an array of the dependencies keys.

pkg.devDepNames

A getter method that returns an array of the devDependencies keys.

pkg.allDepNames

A getter method that returns an array of all the dependencies and devDependencies keys.

Validation

nice-package uses a JSON schema to validate packages.

The following properties are required:

  • name String
  • description String
  • version String

To determine if a package is valid, use the pkg.valid getter method:

pkg.valid
// => false

To see validation errors on a package, use the pkg.validationErrors getter method:

pkg.validationErrors

The result is an array of revalidator errors.

Tests

npm install
npm test

Dependencies

Dev Dependencies

  • require-dir: Helper to require() directories.
  • standard: JavaScript Standard Style
  • tap-spec: Formatted TAP output like Mocha's spec reporter
  • tape: tap-producing test harness for node and browsers

License

MIT

Credits

💛 Thanks to emilyrose for giving up the nice-package name on npm.

Generated by package-json-to-readme