grunt-piecemeal

Concatenates individual script folders and checks dependencies.

Overview

This plugin will identify all subfolders within the specified source folder and generate a file ++for each++ subfolder in the specified output folder. The contents of an output file will be the concatenation of every file matching a configurable file extension within the corresponding source subfolder. The order of inclusion in the concatenation can be controlled through the use of specific tags within the source files.

Getting Started

This plugin requires Grunt.

If you haven't used Grunt before, be sure to check out the Getting Started guide, as it explains how to create a Gruntfile as well as install and use Grunt plugins. Once you're familiar with that process, you may install this plugin with this command:

npm install grunt-piecemeal --save-dev

Once the plugin has been installed, it may be enabled inside your Gruntfile with this line of JavaScript:

grunt.loadNpmTasks('grunt-piecemeal');

The "piecemeal" task

Grunt Configuration

In your project's Gruntfile, add a section named piecemeal to the data object passed into grunt.initConfig().

grunt.initConfig({
  piecemeal: {
    options: {
      // Task-specific options go here.
    },
    your_target: {
      // Target-specific file lists and/or options go here.
    },
  },
})

Grunt Options

options.useStrict

Type: Boolean Default value: true

This value indicates whether the string 'use strict;' should be added to the head of each output file.

options.fileExtension

Type: String Default value: '.js'

This value indicates the file extension to search for when reading files for processing and the file extension to use when writing files for output.

Indicating a dependency

Load-time dependency

A load-time dependency on another file ++within the same folder++ can be created by adding a @depends tag for the file (excluding the file extension) to a block comment within the source file.

/**
 * @depends SomeFile
 */

Run-time dependency

A run-time dependency on another file can be created by adding a @references tag for the file (excluding the file extension) to a block comment within the source file.

/**
 * @references SomeFile
 */

A reference can be made to a file in another folder by prefixing the folder name to the file name.

/**
 * @references SomeFolder:SomeFile
 */

Error Conditions

The following error conditions can be detected during processing and will terminate execution with a grunt.fail.fatal error.

Unresolved Dependency

If an @depends declaration cannot resolve the referenced file within the current folder the following error is produced:

Fatal error: Unresolved dependency 'missing' for item 'f' in library 'lib_b'.

Unresolved Reference

If an @references declaration cannot resolve the referenced file within the specified folder (or the current folder if one is not specified) the following error is produced:

Fatal error: Unresolved reference to item 'missing' in library 'lib_a' for item 'g' in library 'lib_c'.

Cyclic Dependency

From Wikipedia,

'a circular dependency is a relation between two or more modules which either directly or indirectly depend on each other to function properly'

For example, if item 'a' declared a dependence on item 'b' which in turn declared a dependence on item 'a' then this would be a cyclic dependency and there is no way to reliably determine the ordering to satisfy this requirement

a -> b -> a

This plugin uses Topological Sorting when determining the inclusion order for the files within a folder and to detect cyclic dependencies. If a cyclic dependency is identified the following error is produced:

Fatal error: Cyclic dependency detected when evaluating item 'd' in library 'lib_a'.

Usage Example

Sample Data

The following example uses the folder structure for the standard nodeunit tests provided with this package:

test
└── standard
    ├── lib_a
    │   ├── a.js
    │   ├── b.js
    │   ├── c.js
    │   └── d.js
    ├── lib_b
    │   ├── e.js
    │   ├── f.js
    │   └── z.vbs
    └── lib_c
        ├── g.js
        └── h.js

The contents of the files within the lib_a folder are as follows:

####a.js

/**
 * @depends c
 * @references d
 * @references lib_b:e
 */

// This is file 'a' in 'lib_a'

####b.js

/**
 * @references d
 * @references lib_b:e
 */

// This is file 'b' in 'lib_a'

####c.js

/**
 * @depends b
 * @references d
 */

// This is file 'c' in 'lib_a'

####d.js

// This is file 'd' in 'lib_a'

Results

The following file structure would be generated in the specified output folder (assuming a task configuration of dest: 'tmp/default/'):

tmp
└── default
    ├── lib_a.js
    ├── lib_b.js
    └── lib_c.js

After running, the contents of the lib_a.js file is as follows (assuming the useStrict option is not overridden):

"use strict";

/**
 * @references d
 * @references lib_b:e
 */

// This is file 'b' in 'lib_a'
/**
 * @depends b
 * @references d
 */

// This is file 'c' in 'lib_a'
/**
 * @depends c
 * @references d
 * @references lib_b:e
 */

// This is file 'a' in 'lib_a'

// This is file 'd' in 'lib_a'

It can be seen that the dependency chain

a -> c -> b

has been reflected in the order of inclusion of the files.

Enhancements

As it stands, this plugin meets the particular use case that prompted its creation. However, requests for enhancement will be considered should additional functionality be desired.

Release History

• v0.1.0 (2015-03-07) Initial release

License

Copyright (c) 2015 . Licensed under the MIT license.

---

This file was created using Haroopad for Windows.