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

closure-npc

v0.1.5

Published

Closure Node Package Checker, a type-checker for NodeJS programs

Downloads

219

Readme

Closure Node Package Checker

Closure-NPC is a type-checker for NodeJS programs.

Basic Usage

Create a package.json file for your NodeJS program, and add closure-npc to your devDependencies.

{
  "name": "my-package",
  "main": "./my-package.js",
  ...
  "devDependencies": {
    "closure-npc": "*"
  }
}

Then run

npm install .
./node_modules/.bin/closure-npc .

For simple programs, this should work out-of-the-box. Closure NPC will look up the "main" script in your package.json, then follow any require('foo') calls to find all your dependencies. Once it has found all the scripts, it will type-check all of them, assuming that you are using Closure Compiler type annotations and conventions.

Closure NPC just extends Closure Compiler's type-checking to NodeJS modules. All the same caveats apply. In particular, there are many ways to write code that the compiler won't be able to check perfectly, but we believe there's value in a "best-effort" type checker.

For more on Closure Compiler's type checking, see https://developers.google.com/closure/compiler/docs/js-for-compiler.

Advanced Usage

Type-checking without package.json

To type-check arbitrary files, run

npm install closure-npc -g
closure-npc path/to/file1.js path/to/file2.js path/to/file3.js

Type substitutions

By default, closure-npc uses the same module loader algorithm as NodeJS. For example, if you have

var aws = require('aws-sdk')

it will find the aws-sdk package in node_modules, and pull that entire package into your type-checking job. That library may be large and take a long time to type-check. It might not have good type annotations, which defeats the point of pulling it in.

If you create an externDependencies in your package.json file, you can provide alternative type definitions.

{
  "name": "my-package",
  ...
  "externDependencies": {
    "aws-sdk": "./externs/aws-sdk.js"
  }
}

Closure NPC will read that file for the type definitions instead of the normal module.

Known Issues

Variable Names in Error Messages

When Closure NPC prints an error message, it will use the variable name from its internal symbol table, not the variable name in the program.

For example, if you have

/** @type {number} */
var x = true;

Closure NPC will print an error message like Type mismatch on assignment to x$module$main, which means the variable x in main.js.

We are working on a better solution for this.

Error Message Filtering

Closure NPC will print error messages for all files that it finds. You can filter errors by type with the normal Closure Compiler warnings API (https://code.google.com/p/closure-compiler/wiki/Warnings), but you cannot filter by file path. We may add a flag for this in a future version.

Dynamic require calls

Closure NPC can only recognize require calls on string literals.

require('util') // OK
require('u' + 'til') // NO!
var r = require
r('util') // NO!

If it sees anything more complicated than require("string"), it will give up.

We're not making any promises one way or the other about how this will be handled in the future. We may explicitly forbid it with a compiler error, or there may be a "blessed" way to hide module loads from the compiler.

Contributing

Closure NPC is a thin command-line wrapper around Closure Compiler, with some additional plugins for processing NodeJS plugins.

Bug reports and pull requests welcome at https://github.com/nicks/closure-compiler/.

If your bug report is not specific to NodeJS, I may redirect you to the main Closure Compiler project at http://code.google.com/p/closure-compiler/.

Author

Nick Santos supported by A Medium Corporation.

License

Copyright 2014 The Closure Compiler Authors.

Licensed under the Apache License, Version 2.0. See http://www.apache.org/licenses/LICENSE-2.0.

See the top-level README for more complete licensing information.