closure-npc
v0.1.5
Published
Closure Node Package Checker, a type-checker for NodeJS programs
Downloads
88
Maintainers
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.