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

ncjsm

v4.3.2

Published

CJS (Node.js) style modules resolver

Downloads

3,561,813

Readme

Build status Tests coverage npm version

ncjsm

(Node.js) CJS modules resolver

Environment agnostic (Node.js) CJS modules resolver.
It implements a strict version of Node.js modules resolution logic, differences are as follows:

  • Loading from global folders is not supported
  • Only Unix path separators (/) are supported in require's path arguments (Background: even though Node.js internally seems to follow Windows path separator in Windows environment, it won't work in *nix environments, and even in Window env it's not reliable so by all means should be avoided)
  • There's no awareness of node.js core modules e.g. resolve(dir, 'fs') will naturally result with null

Installation

$ npm install ncjsm

API

getResolver(extensions, confirmFile, resolvePackageMain)

For provided configuration, returns a CJS modules resolver:

  • extensions - List of supported file extensions in order of singificance, e.g. for Node.js it would be ['.js', '.json', '.node']
  • confirmFile - a confirmFile(filepath) function. Confirms whether there's a module at provided (not normalized, absolute) file path. Returns promise-like object which resolves with either normalized full path of a module or null (if there's no module for given path).
    Although result is expected to be a promise-like object, resolution can be synchronous.
  • resolvePackageMain - a resolvePackageMain(dirpath) function. Returns value of package.json's main property for given path. Returns promise-like object which resolves with either resolved value, or null, when either package.json file was not found, or it didn't have main property.
    Same as with confirmFile resolution can be synchronous.

resolve(dir, path)

Node.js resolver

Asynchronously resolves module path against provided directory path. Returns promise. If module is found, then promise resolves with an object, containing two properties:

  • targetPath - A path at which module was resolved
  • realPath - Real path of resolved module (if targetPath involves symlinks then realPath will be different)

If no matching module was found, promise is rejected with MODULE_NOT_FOUND error (unless silent: true is passed with options (passed as third argument), then it resolves with null)

const resolve = require("ncjsm/resolve");

// Asynchronously resolve path for 'foo' module against current path
resolve(__dirname, "foo").then(
  function (pathData) {
    // 'foo' module found at fooModulePath
  },
  function (error) {
    if (error.code === "MODULE_NOT_FOUND") {
      // 'foo' module doesn't exist
    }
  }
);

// `silent` option, prevents module not found rejections:
resolve(__dirname, "foo", { silent: true }).then(function (pathData) {
  if (pathData) {
    // 'foo' module found at fooModulePath
  } else {
    // 'foo' module doesn't exist
  }
});

resolveSync(dir, path)

Node.js resolver

Synchronously resolves module path against provided directory path. Otherwise works same as resolve

const resolveSync = require("ncjsm/resolve/sync");

// Synchronously resolve path for 'foo' module against current path
let fooModulePathData;
try {
  fooModulePathData = resolveSync(__dirname, "foo");
  // 'foo' module found at fooModulePath
} catch (error) {
  if (error.code === "MODULE_NOT_FOUND") {
    // 'foo' module doesn't exist
  }
}

fooModulePathData = resolveSync(__dirname, "foo", { silent: true });
if (fooModulePathData) {
  // 'foo' module found
} else {
  // 'foo' module doesn't exist
}

requireUnached([moduleIds, ]callback)

Create temporary environment where require of specific modules will not resolved the eventually cached verions

var requireUncached = require("ncjsm/require-uncached");

const firstCopyOfModule1 = require("./module1");

var secondCopyOfModule2 = requireUnached([require.resolve("./module1")], function () {
  return require("./module1");
});

console.log(firstCopyOfModule1 === secondCopyOfModule2); // false

Alternatively we may resolve callback in completely cleared require cache, for that moduleIds argument should be skipped

var requireUncached = require("ncjsm/require-uncached");

const firstCopyOfModule1 = require("./module1");

var secondCopyOfModule2 = requireUnached(function () { return require("./module1"); });

console.log(firstCopyOfModule1 === secondCopyOfModule2); // false

isPackageRoot(dirPath)

Whether provided path is a root of a package

var isPackageRoot = require("ncjsm/is-package-root");

isPackageRoot(dirPath).done(function (isRoot) {
  if (isRoot) {
    // Provided path is package root
  }
});

resolvePackageRoot(dirPath)

Resolve package root path for provided path. It is about resolution of first upper package root

var resolvePackageRoot = require("ncjsm/resolve-package-root");

resolvePackageRoot(dirPath).done(function (root) {
  if (!root) {
    // Provided path is not located in any package
  }
});

resolveProjectRoot(dirPath)

Resolve project root path for provided path. It is about resolution of topmost package root for given path

var resolveProjectRoot = require("ncjsm/resolve-project-root");

resolveProjectRoot(dirPath).done(function (root) {
  if (!root) {
    // Provided path is not located in any project
  }
});

getDependecies(modulePath, options = { ... })

Resolve all module dependencies. Returns promise that resolves with an array of paths, that includes path to input module and paths to all its dependencies (it includes deep dependencies, so also dependencies of the dependencies).

Paths to native Node.js modules are ignored.

var getDependencies = require("ncjsm/get-dependencies");

getDependencies(modulePath).done(function (deps) {
  console.log(deps); // e.g. [pathToModulePath, pathToDep1, pathToDep2, ...pathToDepn]
});
Supported options
ignoreMissing: false

If file for given module cannot be found then error is thrown. Set this to true to simply ignore not found modules

ignoreExternal: false

By default all paths to all required modules are resolved. Resolution scope may be narrowed only to modules from same package (referenced via relative path), by settung this option to true

Tests Build Status

$ npm test