npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

@offliner/npm-downloadtracker

v2.0.0

Published

Package tarball data store manager for the npm-two-stage project

Downloads

3

Readme

@offliner/npm-downloadtracker

Package tarball data store manager for the npm-two-stage project

Overview

The purposes of this module are:

  • to associate critical installation-related data with downloaded package tarballs
  • to help the package downloader avoid redundant downloads
  • to provide information to the offliner module for installation of downloaded packages
  • to provide a means to validate the information mapped in a dltracker.json file with respect to the download directory that contains it

Where package tarball filenames (and Git repo identifiers) are of concern, this module is meant to be used in tandem with the module @offliner/npm-package-filename.

Install

npm install @offliner/npm-downloadtracker

Usage Examples

const dltFactory = require('@offliner/npm-downloadtracker')

// ...

dltFactory.create('path/to/put/tarballs').then(tracker => {
  if (!tracker.contains('semver', packageName, spec))
    doSomethingWith(tracker)
})

// ...

const inData = {
  name: packageName,
  version: packageVer,
  filename: uniqueFilename,
  // whatever else is useful...
}
tracker.add('semver', inData).then(() => {
  goToNextAction()
})

tracker.contains('semver', pkgName, pkgVer) // --> true

// ...

const outData = tracker.getData('semver', pkgName, pkgVer)
/* -->
  outData contains everything in inData, with the additional field 'type'
*/

// ...

tracker.serialize().then(() => {
  finishUp()
}

Main Module API

dltFactory.typeMap

A hash of npm-package-arg package types to npm-package-dl-tracker package types.

dltFactory.typeMap['version']   // --> 'semver'
dltFactory.typeMap['tag']       // --> 'tag'
dltFactory.typeMap['git']       // --> 'git'
dltFactory.typeMap['remote']    // --> 'url'
dltFactory.typeMap['directory'] // --> undefined
dltFactory.typeMap['file']      // --> undefined

A value from this mapping is to be used as the first argument to instance methods add(), contains(), and getData().

Only the ones that are meaningful in this context are defined.

dltFactory.create(where[, options])Promise<trackerInstance>

Factory function to create a tracker instance.

  • where {string || undefined || null} Path to put/find tarballs

    If no argument or empty value is given, the current directory will be used.

  • options {object || undefined || null} Optional

    • log {object} Optional

    If log option present, must have these methods: error, warn, info, verbose

Instance API

tracker.path

{string} The absolute path adopted by this instance for location of tarballs

tracker.add(type, data)Promise<empty>

  • type {string} One of the values from dltFactory.typeMap (see above)

  • data {object} Contains fields to associate with a given tarball. Arbitrary extra fields may be included with required fields.

    For type 'semver', required fields are:

    • name {string}
    • version {string}
    • filename {string} The name of the tarball file

    For type 'tag', required fields are same as for 'semver' with one more:

    • spec {string} The tag

    For type 'git', required fields are:

    • repo {string} A unique identifier for a git repository
    • commit {string} The git hash that identifies a commit in the given repository
    • filename {string} The name of the tarball file

    If a field called refs is included in data of type 'git', it must be an Array of strings; the strings will be interpreted as tags, and each will be treated as an alias for the commit.

    For type 'url', required fields are:

    • spec {string} A remote URL
    • filename {string} The name of the tarball file

tracker.contains(type, name, spec)

Synchronous

  • type {string} One of the values from dltFactory.typeMap (see above)

  • name {string}

    For type 'semver' or 'tag', must be the package name

    For type 'git', must be the git repo identifier (see tracker.add() above)

    For type 'url', must be empty ('' || null || undefined)

  • spec {string}

    For type 'semver', must be the package version

    For type 'tag', must be the version tag

    For type 'git', can be...

    • a git commit hash
    • a git tag
    • a valid Semver 2.0 expression prefixed by 'semver:'
    • empty string or '*', which will match if there is a 'master' or 'main' tag or only one commit present for the named repo

    For type 'url', must be a remote URL

  • Returns: {boolean} Whether the identified package has been added

Caveat: For type 'tag', if the value of spec is 'latest' or '', the call will tell if any version of the named package has been added.

tracker.getData(type, name, spec)

Synchronous

Same argument requirements as for contains().

  • Returns: {object || null}

    If the identified package was previously added, this will contain the same data passed to tracker.add(), with the additional field type. If type 'git', and a tag or a 'semver:'-prefixed expression is given, then a spec field with that value will be included.

Caveat: For type 'tag', if the value of spec is 'latest' or '', the call will return the data of the highest version added, which is not necessarily the current latest version.

tracker.serialize()Promise<boolean>

If tracker.add() has previously been called successfully since instantiation/last call to serialize(), writes the modified state to a file named dltracker.json in the adopted directory (tracker.path), and resolves to true. Otherwise, does nothing, and resolves to false.

tracker.audit()Promise<Array>

Runs checks on the items in the current data, including the condition of each file. Resolves to an Array of objects describing problems discovered in the current tracker data, if any; otherwise an empty Array. Each element object contains the following fields:

  • data {object} The same data as returned by tracker.getData()
  • error {Error} The error encountered for the package identified by data

Submodule API: reconstruct-map.js

Primary purpose is to recreate the tracker data structure for a directory of packages that has no JSON file, though it can also be used without harm even if there is a dltracker.json file in the directory.

const reconstructMap = require('@offliner/npm-downloadtracker/reconstruct-map')

// ...

reconstructMap('path/to/tarballs').then(map => {
  handleTrackerMap(map)
})

reconstructMap(dir[, log])Promise<object>

  • dir {string} Path to find tarballs

  • log {object || undefined || null} Optional

    If given, must have these methods: error, warn, info, verbose

The resolved object contains a tree structure, in which the possible topmost fields are semver, git, and url. When any of these is present, package key values map down to the bare minimum of data for every package tarball (that has a parseable name) found in the given directory.

<object>
    |
    |------------------------------------------ 'git'
    |                                             |
    |-- 'semver'                                  |-- <repoIdentifier1>
    |       |                                     |           |
    |       |-- <packageName1>                    |           |-- <commitHashA>: <data>
    |       |         |                           |           |
    |       |         |-- <versionA>: <data>      |           ...
    |       |         |                           ...
    |       |         ...
    |       ...
    |
    |-- 'url'
    |     |
    |     |-- <URL>: <data>
    |     |  
    |     ...

License: Artistic 2.0