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 🙏

© 2020 – Pkg Stats / Ryan Hefner

trace-deps

v0.3.5

Published

A dependency tracing tool.

Downloads

24,391

Readme

trace-deps 🔬

npm version Travis Status AppVeyor Status Coverage Status

A dependency tracing tool for Node.js source files.

Overview

trace-deps can parse CommonJS / ESM source files, inspect dependency statements, and produce a list of absolute file paths on-disk for all inferred dependencies. The library currently works with files ending in .js, .mjs file extensions that contain the following dependency statements:

  • require("<string>"): CommonJS require.
  • require.resolve("<string>"): CommonJS require resolution (returns path to dependency instead of loaded code).
  • import "<string>", import <var> | { <var> } | * as <var> from "<string>": ECMAScript Module static import.
  • export <var> | { <var> } | * as <var> from "<string>": ECMAScript Module static re-export.
  • import("<string>"): ECMAScript Module dynamic import.

API

traceFile({ srcPath, ignores })

Trace and return on-disk locations of all file dependencies from a source file.

Parameters:

  • srcPath (string): source file path to trace
  • ignores (Array<string>): list of package prefixes to ignore tracing entirely
  • allowMissing (Object.<string, Array<string>): Mapping of package prefixes to permitted missing module prefixes.
  • bailOnMissing (boolean): Throw error if missing static import. (Default: true). If false, misses are added to misses object.
  • extraImports (Object.<string, Array<string>): Mapping of files to additional imports to trace.
    • The key is path (either Posix or native OS paths are accepted) in the form of either:
      1. an absolute path to a source file (e.g., /PATH/TO/src/foo.js), or;
      2. a relative path to a file from a package in node_modules starting at the package name (e.g. lodash/index.js).
    • The value is an array of additional import specifiers that are resolved and further traced. The additional imports are anything that could be validly passed to a require() or import call (e.g., ./relative/path/to/source-file.js, a-pkg, a-pkg/with/nested/path.js).
      • Paths should be specified as you would in a Node.js require() which is to say Posix / form.

Returns:

  • (Promise<Object>): Dependencies and other information.
    • dependencies (Array<string>): list of absolute paths to on-disk dependencies
    • misses (Object.<string, Array<Object>): Mapping of file absolute paths on disk to an array of imports that trace-deps was not able to resolve (dynamic requires, etc.). The object contained in the value array is structured as follows:
      • src (string): The source code snippet of the import in question (e.g., "require(A_VAR)")
      • start, end (number): The starting / ending character indexes in the source code string corresponding to the source file.
      • loc (Object): Line / column information for the code string at issue taking the form:
        {
          start: { line: Number, column: Number},
          end:   { line: Number, column: Number}
        }
      • type (string): One of the following:
        • dynamic: A dynamic import that trace-deps cannot resolve.
        • static: A resolved dependency that was not found.
        • extra: A user-provided extraImports static value that was not found.
      • dep (string) (optional): The dependency value if statically inferred.

traceFiles({ srcPaths, ignores })

Trace and return on-disk locations of all file dependencies from source files.

Parameters:

  • srcPaths (Array<string>): source file paths to trace
  • ignores (Array<string>): list of package prefixes to ignore
  • allowMissing (Object.<string, Array<string>): Mapping of package prefixes to permitted missing module prefixes.
  • bailOnMissing (boolean): Throw error if missing static import.
  • extraImports (Object.<string, Array<string>): Mapping of files to additional imports to trace.

Returns:

  • (Promise<Object>): Dependencies and other information. See traceFile() for object shape.

CLI

trace-deps also provides a handy CLI for checking all dependencies and misses imported.

$ trace-deps -h
Usage: trace-deps <action> [options]

Actions: (<action>)
  trace                     Trace dependencies and misses for a file

Options:
  --input, -i   (trace)     Starting file to trace              [string]
  --output, -o  (trace)     Output format (text, json)          [string] [default: text]
  --help, -h                Show help                           [boolean]
  --version, -v             Show version number                 [boolean]

Examples:
  trace-deps trace --input ./path/to/file.js     Trace a source file

Notes

  • Only parses Node.js JavaScript: trace-deps presently will only Node.js-compatible JavaScript in CommonJS or ESM formats. It will not correctly parse things like TypeScript, JSX, ReasonML, non-JavaScript, etc.

  • Only handles single string dependencies: require, require.resolve, and dynamic import() support calls with variables or other expressions like require(aVar), import(process.env.VAL + "more-stuff"). This library presently only supports calls with a single string and nothing else. We have a tracking ticket to consider expanding support for things like partial evaluation.

  • Includes package.json files used in resolution: As this is a Node.js-focused library, to follow the Node.js module resolution algorithm which notably uses intermediate encountered package.json files to determine how to resolve modules. This means that we include a lot of package.json files that seemingly aren't directly imported (such as a const pkg = require("mod/package.json")) because they are needed for the list of all traced files to together resolve correctly if all on disk together.

  • Using the allowMissing option: The allowMissing function field helps in situations where you want to allow certain dependencies to have known missing sub-dependencies, often seen in patterns like: try { require("optional-dep"); } catch (e) {}. If the sub-dependency is found, then it will be returned just like any normal one. If not, the module not found error is just swallowed and normal processing resumes.

    To configure the parameter, create an object of key package-prefix with a value of an array of other package prefixes to skip over not found errors:

    traceFile({
      srcPath,
      allowMissing: {
        "ws": [
          // See, e.g.: https://github.com/websockets/ws/blob/08c6c8ba70404818f7f4bc23eb5fd0bf9c94c039/lib/buffer-util.js#L121-L122
          "bufferutil",
          // See, e.g.: https://github.com/websockets/ws/blob/b6430fea423d88926847a47d4ecfc36e52dc1164/lib/validation.js#L3-L10
          "utf-8-validate"
        ]
      }
    })
  • ignores vs. allowMissing: The ignores option completely skips a dependency from being further traversed irrespective of whether or not a matching dependency exists on disk. The allowMissing option will include and further traverse dependencies that are present on disk if found and suppress any errors for matches that are missing.