closure-npc

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.