Neo's Playing Morpheus

    npm-registry

    0.1.13 • Public • Published

    npm-registry

    To keep myself sane while working with The npm Registry I decided to write my own library to deal with all the incomplete, inconsistent and horrible data structures that are available in The npm Registry. NoSQL is nice and all, but that doesn't mean you should leave your data unmaintained. This library is never meant as a full replacement of the npm-registry-client which the npm bin file is using. Unless those API's and methods are so poorly implemented or designed that I get a mental breakdown, then yes, this will become a full and usable replacement of the above said module.

    This module is written with high availability in mind. The main reason behind this is that npm Inc. has added a lot of moving parts on top of the registry which frequently breaks. In order to combat this I've implemented automatic downgrading to multiple registries. If all other supplied registries fail to work an automatic exponential randomized back off algorithm kicks in place and retries the query once more. This functionality is all provided by the awesome mana package which provides core functionality for writing sane api-clients.

    Installation

    npm install --save npm-registry
    

    And that is all you need to type in your terminal in order to prevent becoming terminal. The --save tells npm to automatically add the package and latest version to your package.json.

    Getting started

    Now that you've installed the npm-registry module you can require and initialize it using:

    'use strict';
     
    var Registry = require('npm-registry');
     
    var npm = new Registry({ options });

    As seen in the example above, the Registry constructor allows an Object with options to customize the npm registry client. The following options are supported:

    • registry The URL of the npm registry. Defaults to Nodejitsu's mirror.
    • stats URL of the download stats service. Defaults to npm's API server.
    • mirrors Array of mirrors to use when a registry is down.
    • maxdelay Maximum delay for exponential back off.
    • mindelay Minimum delay for exponential back off.
    • githulk Reference to a pre-configured GitHulk instance.
    • retries The amount of retries we should do before giving up.
    • factor Exponential backoff factor.
    • authorization Optional authorization header for authorized requests.
    • user,password Optional user/password for authorized requests.

    The fully configured npm registry client can then be used to access the various of API endpoints using:

    //
    // npm.<endpoint>.<method>(<arg>, <callback>);
    //
    npm.packages.get('npm-registry', function (err, data) {
      ..
    });

    The following endpoints are available:

    Packages

    The .packages endpoints allows you to retrieve detailed information about npm packages. The following methods are implemented:

    npm.packages.get

    Get information from the npm package. If the name contains an @ char we assume that the user wants to get a specific version instead.

    Example: primus@0.1.1 would retrieve primus version 0.1.1

    npm.packages.get('primus', function (err, data) {
     
    });

    npm.packages.details

    Retrieve additional details for the package information. This a lot slower than a simple .get but much more detailed and accurate as it uses custom parsers for accurate licensing information. Which could require a fair amount of npm and github lookups.

    npm.packages.details('memcached', function (err, data) {
     
    });

    npm.packages.depended

    Get all packages that are depended upon a given package name.

    npm.packages.depended('eventemitter3', function (err, depended) {
     
    });

    npm.packages.starred

    Find out which users have starred the given package.

    npm.packages.starred('npm-registry', function (err, starred) {
     
    });

    npm.packages.keyword

    Find all packages that matches the giving keywords.

    npm.packages.keyword('primus');

    npm.packages.releases

    Retrieve all release specific information for the given package name. Please note that this uses the npm.packages.details call under the hood to provide more detailed information but it will therefor also take longer.

    npm.packages.releases('bigpipe', function (err, releases) {
     
    });

    npm.packages.release

    Get a specific release of a package. Please note that this uses the npm.packages.details call under the hood to provide more detailed information but it will therefor also take longer.

    npm.packages.release('npm-registry', '0.0.2', function (err, release) {
     
    });

    npm.packages.range

    Get a release that is satisfying a given semver range. Please note that this uses the npm.packages.details call under the hood to provide more detailed information but it will therefor also take longer.

    npm.packages.release('npm-registry', '^0.1.2', function (err, release) {
     
    });

    Users

    The .users endpoint allows you to retrieve detailed information about a given npm account. The following methods are implemented:

    npm.users.add

    Add a user as maintainer of a package.

    npm.users.add('foobar', 'npm-registry', function (err) {
     
    });

    npm.users.create

    Create a new npm account.

    npm.users.create('foobar', 'foo@bar.com', 'secretpassword', function (err) {
     
    });

    npm.users.update

    Update the users.

    npm.users.update('foobar', {
      twitter: 'foobar',
      email: 'foo@foobar.bar'
    }, function (err) {
     
    });

    npm.users.list

    List all packages that the user maintains.

    npm.users.list('foobar', function (err, modules) {
     
    });

    npm.users.starred

    Get all packages that the user has starred.

    npm.users.starred('foobar', function (err, modules) {
      
    });

    npm.users.get

    Get profile information for a given user.

    npm.users.get('foobar', function (err) {
     
    });

    npm.users.sync

    Sync ownership of npm modules with another account. This is useful if you have one base owner of modules like a corporate account and you want to on-board a new user.

    npm.users.sync('source-account', 'foobar', function (err) {
     
    });

    Downloads

    The .downloads endpoint allows you to retrieve download stats for a given package. The following methods are implemented:

    npm.downloads.totals

    Get the total amount of downloads for a given period. If no package name has been supplied the total of all packages will be returned. The following date ranges are accepted by the stats server.

    • All packages, last day:
    • last day: last-day
    • specific date: 2014-02-01
    • last week: `last-week
    • range of date (30 days max): 2014-02-01:2014-02-08
    • last month: last-monthA
    • specific month: 2014-01-01:2014-01-31
    npm.downloads.totals('last-week', 'npm-registry', function (err, stats) {
     
    });

    npm.downloads.range

    Same as above, but it doesn't get the total/summary of the downloads but an array with the downloads per day. The same date ranges are allowed and if no package name is supplied, all packages is assumed.

    npm.downloads.range('last-week', 'npm-registry', function (err, stats) {
     
    });

    Normalization

    As the internal data structure is do damn awkward and unmaintained in npm we need to normalize the data structures before we can even try to use it. While this normalization is part automatically done for you internally there might be use cases where you want to manually normalize a given dataset. The normalize module can be required directly using:

    var normalize = require('npm-registry/normalize');

    The normalize variable now contains two different functions, users and packages. As you might have guessed, these functions normalize different data structures. The function accepts a simple single argument which is the data object that you receive from the npm registry endpoints.

    data = normalize.packages(data);

    License

    MIT

    Install

    npm i npm-registry

    DownloadsWeekly Downloads

    9,174

    Version

    0.1.13

    License

    MIT

    Last publish

    Collaborators

    • jcrugzz
    • swaagie
    • indexzero
    • v1
    • 3rdeden