Nice-package NPM

nice-package ✨📦✨

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

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

github-url-to-object: Extract user, repo, and other interesting properties from GitHub URLs
normalize-registry-metadata: clean package metadata objects you get from registry changes feeds
revalidator: A cross-browser / node.js validator powered by JSON Schema
semver: The semantic version parser used by npm.