/npm-package-download-counts

Get package download counts for one or more packages.

Primary LanguageJavaScriptMIT LicenseMIT

Package Downloads

NPM version Build Status Coverage Status Dependencies

Get download counts for one or more packages.

Installation

$ npm install npm-package-download-counts

Usage

var counts = require( 'npm-package-download-counts' );

counts( options, clbk )

Get download counts for one or more packages.

var opts = {
	'packages': [
		'dstructs-matrix',
		'utils-copy',
		'unknown_package_name'
	]
};

counts( opts, clbk );

function clbk( error, data ) {
	if ( error ) {
		throw error;
	}
	console.dir( data );
	/*
		[
			{
				"package": "dstructs-matrix",
				"data": [
					["2015-12-01T00:00:00.000Z",3295],
					["2015-12-02T00:00:00.000Z",5498],
					["2015-12-03T00:00:00.000Z",4771],
					...
				]
			},
			{
				"package": "utils-copy",
				"data": [
					["2015-12-01T00:00:00.000Z",1003],
					["2015-12-02T00:00:00.000Z",809],
					["2015-12-03T00:00:00.000Z",946],
					...
				]
			},
			{
				"package": "unknown_package_name",
				"data": null
			}
		]
	*/
}

The function accepts the following options:

  • packages: array of package names (required).
  • period: query period. May be either a keyword (e.g., 'last-month', 'last-week', 'last-day') or a date range (e.g., '2015-12-01:2016-01-01'). Default: 'last-month'.

By default, the function returns daily downloads for the last month. To return daily downloads for an alternative period, set the period option.

var opts = {
	'packages': [
		'dstructs-array',
		'flow-map',
		'utils-merge2'
	],
	'period': '2015-11-01:2015-12-31'
};

counts( opts, clbk );

counts.factory( options, clbk )

Creates a reusable function.

var pkgs = [
	'dstructs-matrix',
	'compute-stdev',
	'compute-variance'
];

var get = counts.factory( {'packages':pkgs}, clbk );

get();
get();
get();
// ...

The factory method accepts the same options as counts().

Notes

  • If the module encounters an application-level error (e.g., no network connection, malformed request, etc), that error is returned immediately to the provided callback.
  • If a particular package is not present in downstream query results or simply does not exist, the package download count is null.
  • Time values are in simplified ISO format (ISO 8601).
  • A query period is not sanity checked. If counts are expected, ensure that the provided period is of the appropriate format and/or a recognized value.

Examples

var ls = require( 'npm-list-author-packages' );
var counts = require( 'npm-package-download-counts' );

// Get download counts for all author packages...
var opts = {
	'username': 'kgryte'
};

ls( opts, onList );

function onList( error, list ) {
	var opts;
	if ( error ) {
		throw error;
	}
	if ( !list.length ) {
		return;
	}
	opts = {
		'packages': list
	};
	counts( opts, onCounts );
}

function onCounts( error, data ) {
	if ( error ) {
		throw error;
	}
	console.dir( data );
}

To run the example code from the top-level application directory,

$ DEBUG=* node ./examples/index.js

CLI

Installation

To use the module as a general utility, install the module globally

$ npm install -g npm-package-download-counts

Usage

Usage: pkgcounts [options] pkg1 pkg2 ...

Options:

  -h,  --help                 Print this message.
  -V,  --version              Print the package version.
       --period period        Query period. May be either a keyword (e.g.,
                              'last-month','last-week','last-day') or a date
                              range (e.g., '2015-12-01:2016-01-01'). Default:
                              'last-month'.
       --format format        Output format: csv or json. Default: 'csv'.
       --delimiter delimiter  CSV column delimiter. Default: ','.

Notes

  • If the output format is csv,
    • if unable to resolve the download counts for all specified packages, the process will write an error message to stderr and will not generate CSV output.
    • if at least one package has downloads within the specified period, the process will null fill the CSV columns for those packages without downloads.
  • If the output format is json,
    • regardless of whether any package has downloads, the process will write newline-delimited JSON (ndjson) to stdout.
    • the counts (data) field for any package without downloads will be null.

Examples

$ DEBUG=* pkgcounts dstructs-matrix utils-copy
# => time,dstructs-matrix,utils-copy
# => 2015-12-01T00:00:00.000Z,3295,1003
# => 2015-12-02T00:00:00.000Z,5498,809
# => 2015-12-03T00:00:00.000Z,4771,946
# => ...

To output as newline-delimited JSON (ndjson), set the format option.

$ DEBUG=* pkgcounts --format=json dstructs-matrix utils-copy
# => {"dstructs-matrix":[[...],[...],...]}
# => {"utils-copy":[[...],[...],...]}

Tests

Unit

This repository uses tape for unit tests. To run the tests, execute the following command in the top-level application directory:

$ make test

All new feature development should have corresponding unit tests to validate correct functionality.

Test Coverage

This repository uses Istanbul as its code coverage tool. To generate a test coverage report, execute the following command in the top-level application directory:

$ make test-cov

Istanbul creates a ./reports/coverage directory. To access an HTML version of the report,

$ make view-cov

Browser Support

This repository uses Testling for browser testing. To run the tests in a (headless) local web browser, execute the following command in the top-level application directory:

$ make test-browsers

To view the tests in a local web browser,

$ make view-browser-tests

License

MIT license.

Copyright

Copyright © 2016. Athan Reines.