nclosure

nclosure: Server Side Google Closure Tools in Node.js

Overview

The Google Closure Tools are a powerful set of utilities that aim to make large scale JavaScript development more manageable. This project brings the power of the closure tools to the node platform. The closure tools gives developers the utilities required to improve code design and maintainability by providing support for:

• Enhanced Modularisation (Both logically and physically)
• Better Encapsulation
• Type Safety
• Interfaces and Mixins
• Rich Documentation
• A Huge Library of Production Ready Utilities, including:
  • Collections / Arrays
  • Testing / Mocking
  • Async Development
  • Encryption
  • Date / Date Range Support
  • Events
  • Internationalisation
  • Locale
  • Math
  • String
  • Structs
  • More...

Installation (core)

• Install nclosure. By getting the source (NPM install comming soon):

    	git clone git://github.com/gatapia/nclosure.git
    	cd nclosure
    	npm link
  

Closure Library

For full details on utilities provided in the closure library refer to the official docs. To use any utility provided in the closure library just:

1. Include nclosure in your application by require(ing) it and initialising it.

    require('nclosure').nclosure();
   

2. goog.require any namespace from the Closure library.

    goog.require('goog.structs.Trie');
   

3. That's it, use the imported namespaces anywhere in your file.

    var trie = new goog.structs.Trie();
   

Closure Compiler

Using the Closure Compiler requires a small investment in learning but once you have worked your way through the docs you can take advantage of the compiler's support for:

• Enhanced Code Documentation
• Type Safety
• Encapsulation
• Modularisation
• Enhanced Inheritance and Interfaces
• Scalability

Once your source code is annotated and ready for compilation just run the following command:

	nccompile source.js

The nccompile command accepts various arguments:

• -c: Create [C]ompile file - Produces a compiled .min.js file
• -d: Create [D]ependencies- Creates a deps.js file that can be used as an additionalDeps in an external project.

JSDoc Documentation

To run nclosure's documentation tool simply run:

ncdoc <directory or source file>

For full documentation details please read the official jsdoc-toolkit docs.

Closure Testing

nclosure supports testing using Closure's 'goog.testing.jsunit' test tools. To set up a unit test simply create a test file like:

#!/usr/local/bin/node
require('nclosure').nclosure();

goog.require('goog.testing.jsunit');
// Import the code you are testing
goog.require('nclosure.examples.simple.Example');

goog.provide('nclosure.examples.simple.tests.syncTests');

// Any testXXX function are auto-discovered and run
var testFunction1 = function() {
  assertNotEquals(typeof(example_), 'undefined');
};

function testFunction2() {
  assertTrue(false);
}

If the tests are not in the same directory as your code you will have to ensure that the deps.js file of the code you are testing is declared in the closure.json file of the tests directory or passed in to the call to goog(); like:

require('nclosure').goog({additionalDeps:['/pathToDeps/deps.js']});

To run a single test just execute:

./testSourceFile.js <optionalTestName>

To run all tests in a single directory run the following command:

  nctest <dirname>

Closure Linter

For detailed code style checking you can also use nclosure's linter support. To use linter you will need to download and install Closure Linter.

Closure Linter checks your code against Google's own JavaScript Style Guide which is a mature and highly scalable framework for developing JavaScript code.

To install Closure Linter read the following page.

Once installed simply run the following command to linter your code.

	ncstyle <directory>

Advanced Configuration

nclosure can be configured in several ways. The easiest is to modify the bin/closure.json file with your global settings. Settings here can be extended by placing a closure.json file in your source directory. You can also place a closure.json in the directory running node.

Finally, nclosure can also be configured by passing an optional options object to the require('nclosure').goog(opts); call.

All configuration files and configuration objects take the following format:

    {
      closureBasePath: Location of the closure-library/closure/goog/
          directory
      additionalDeps: Any additional dependency files required to run your
          code.  These files generally point to other closure libraries.
          Note these deps files must have paths relative to this setting
          file or be absolute.
      compiler_jar: Path to the compiler jar you want to use.  This defaults
        to the included compiler.jar file so only change this if you want
        to use a custom compiler.
      additionalCompileOptions: Additional compiler options,
        e.g.: "['--jscomp_warning=newWarningType']"
      additionalCompileRoots: These are directories containing source code
        that needs to be included in the compilation.  If this is not
        included then additionalDeps is used to try to guess any additional
        roots required (assumes that the deps.js file is in the root folder
        of the source directory).
      jsdocToolkitDir: The location of jsdoc-toolkit.  This is only required
        if you want to use jsdoc-toolkit to document your source code.
      additionalJSDocToolkitOptions: Additional jsdoc-toolkit options,
        e.g.: "['-D="noGlobal:true"']"
      additionalLinterOptions: Additional gjslint and fixjsstyle options,
        e.g.: "['--summary=true']"
      nodeDir: The location of the node source code.  This is only required
        if you are contributing to the nclosure project or would like to
        update your node-extern files.
    }

Note: All paths can be absolute or relative to the location of the current settings file.

Acknoledgements

My sincerest appreciation to Google for open sourcing this awesome toolset. Thanks to the jsdoc-toolkit guys (Michael Mathews + co) and to Wouter Bos for his awesome jsdoc-toolkit template. Thanks also to Aaron Wirtz for his node-jsdoc-toolkit project. Huge thanks also goes to Hendrik Schnepel whose awesome nclosure project got me started with this project.

License

Copyright 2011 Guido Tapia ([e-mail])

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.