├── .editorconfig
├── .gitignore
├── .travis.yml
├── CHANGELOG.md
├── CONTRIBUTING.md
├── IMPLEMENTATION-EXAMPLE.md
├── IMPLEMENTATIONS.md
├── LICENSE
├── README.md
├── index.js
├── package.json
└── test
    └── main.js


/.editorconfig:
--------------------------------------------------------------------------------
1 | root = true
2 | 
3 | [*]
4 | charset = utf-8
5 | indent_style = tab
6 | end_of_line = lf
7 | trim_trailing_whitespace = true
8 | insert_final_newline = true
9 | 


--------------------------------------------------------------------------------
/.gitignore:
--------------------------------------------------------------------------------
1 | coverage/
2 | node_modules/
3 | npm-debug.log
4 | *.sublime-*
5 | .idea/
6 | 


--------------------------------------------------------------------------------
/.travis.yml:
--------------------------------------------------------------------------------
 1 | language: node_js
 2 | node_js:
 3 |   - "0.10"
 4 |   - "0.12"
 5 |   - "4"
 6 |   - "5"
 7 |   - "6"
 8 | script: "npm run test-travis"
 9 | after_script: "npm i coveralls@2 && cat coverage/lcov.info | coveralls"
10 | 


--------------------------------------------------------------------------------
/CHANGELOG.md:
--------------------------------------------------------------------------------
 1 | # Changelog
 2 | 
 3 | ## 1.0.0 The Promised Hashing
 4 | 
 5 | ### Breaking changes
 6 | 
 7 | - The `config` method has been removed, you can now pass a configuration options object in the `bust()` call. See the [docs](https://github.com/UltCombo/gulp-buster/#syntax) for details.
 8 | - Removed the undocumented experimental `mode` option, use the new `transform` option instead.
 9 | - Removed the undocumented `hashes` method.
10 | 
11 | ### Patch releases
12 | 
13 | - **1.0.1**: Fixed a bug in the crypto hashing logic that would give wrong hash results sometimes, mainly when hashing binary files. Also added official support for Node.js versions 0.12, 4, 5 and 6! (in addition to version 0.10 which was already supported)
14 | - **1.0.2**: Updated dependencies and cleaned up the code style.
15 | 
16 | ### New features
17 | 
18 | - Configuration options: added new `formatter` and `transform` options, added support for `algo` as a function and negative `length`. See the [docs](https://github.com/UltCombo/gulp-buster/#parameters) for details.
19 | - All of the configuration options which accept a function can be run asynchronously by returning a promise.
20 | - Added type validation for configuration options.
21 | 
22 | ## 0.2.0 Multidimensional Configurable Hashing Abyss
23 | 
24 | - `fileName` parameter is now optional and defaults to `busters.json`.
25 | - Allow multiple different output files in the same script (hashes are grouped by output filename).
26 | - Added `.config()` method to allow customizing the hashing algorithm, hash length and default output filename.
27 | 
28 | ### Patch releases
29 | 
30 | - **0.2.1**: Readme: Fixed miscellaneous typos, including config sample.
31 | - **0.2.2**: Fixed crash when piping an empty buffer stream into gulp-buster. Many documentation improvements: added cache busting explanation, improved syntax and architecture documentation, added 3rd-party implementations listing and contributing guide.
32 | 
33 | ## 0.1.0 Bustering Gulpness
34 | 
35 | - Initial release.
36 | 


--------------------------------------------------------------------------------
/CONTRIBUTING.md:
--------------------------------------------------------------------------------
1 | See [Ult Foundation Contributor's Guide](https://github.com/UltFoundation/Ultiomatic.js/blob/master/CONTRIBUTING.md).
2 | 


--------------------------------------------------------------------------------
/IMPLEMENTATION-EXAMPLE.md:
--------------------------------------------------------------------------------
 1 | # Implementation examples
 2 | 
 3 | These examples explain the basic logic necessary to implement gulp-buster into your application.
 4 | 
 5 | ## Node.js + Jade
 6 | 
 7 | **asset-loader.js**
 8 | ```js
 9 | var busters = require('path/to/busters.json');
10 | module.exports = function(path) {
11 | 	return path + (busters[path] ? '?' + busters[path] : '');
12 | };
13 | ```
14 | 
15 | Then when outputting cache-busted file paths, simply call the asset loader passing the (relative to project root) file path. Example with Express and Jade:
16 | 
17 | ```jade
18 | script(src=fooSrc)
19 | ```
20 | 
21 | ```js
22 | var asset = require('./asset-loader.js');
23 | res.render('view', { fooSrc: '/' + asset('js/min/foo.min.js') }, function(err, html) {
24 | 	// ...
25 | });
26 | ```
27 | 
28 | As you can see, the gulp-buster `busters.json`'s paths are relative to project root without the leading slash, so we manually prepend a `/` to the cache-busted URL. This works nicely if your project root corresponds to the web server root. Otherwise, you will have to prepend the correct base URL. The optimal way would be to dynamically retrieve your app's base URL, specially as the project path relative to the web server root may differ between production and local development environments (e.g. it is a common scenario to have the project run at `/` in the production server and at `/myProject/` in local development).
29 | 
30 | ## Client-side
31 | 
32 | There are many ways to implement this in the front-end as well. If your project uses an AMD loader such as Require.js, you can map the modules to their cache-busted URLs in the config. Even without any loader, it is possible to `document.write` the scripts as follows:
33 | 
34 | ```js
35 | ['app', 'services', 'controllers', 'filters', 'directives'].forEach(function(s) {
36 | 	document.write('<script src="/' + asset('js/' + s + '.js') + '"><\/script>');
37 | });
38 | ```
39 | 
40 | **Note:** If implementing this in the front-end, make sure to load the fresh (non-cached) `busters.json` file. That is, retrieving it through an Ajax request may return a cached version of it depending on the server configurations. Append a timestamp to the request URL's querystring to prevent caching issues. You may also output the JSON file's contents inside of a dynamic page's `<script>` tag assigning it to a variable. JSON (JavaScript Object Notation) is a subset of the JS object/array literals syntax, so this is perfectly valid as well.
41 | 
42 | ## Closing words
43 | 
44 | As the asset loader implementation is up to you, you may make it the way which better fits your application. A more robust implementation could check the file extension (js/css/png) and return the full HTML tag for it, accept string/array of strings overloading for the path argument, and also take the base path as an optional argument.
45 | 


--------------------------------------------------------------------------------
/IMPLEMENTATIONS.md:
--------------------------------------------------------------------------------
 1 | # Implementations
 2 | 
 3 | First off, if you are planning to make your own gulp-buster implementation, check the [implementation examples](https://github.com/UltCombo/gulp-buster/blob/master/IMPLEMENTATION-EXAMPLE.md) which explain the basic implementation logic and provide some tips.
 4 | 
 5 | ## Available implementations per language
 6 | 
 7 | ### PHP
 8 | 
 9 | - [BustersPhp](https://github.com/mikedfunk/BustersPhp)
10 | - [GulpBusterBundle](https://github.com/ajaxray/GulpBusterBundle) (for Symfony 2)
11 | 
12 | ## Submit your own implementation
13 | 
14 | Have you made a new implementation and would like it listed here? Just send a PR! `=]`
15 | 


--------------------------------------------------------------------------------
/LICENSE:
--------------------------------------------------------------------------------
 1 |             DO WHAT THE FUCK YOU WANT TO PUBLIC LICENSE
 2 |                     Version 2, December 2004
 3 | 
 4 |  Copyright (C) 2004 Sam Hocevar <sam@hocevar.net>
 5 | 
 6 |  Everyone is permitted to copy and distribute verbatim or modified
 7 |  copies of this license document, and changing it is allowed as long
 8 |  as the name is changed.
 9 | 
10 |             DO WHAT THE FUCK YOU WANT TO PUBLIC LICENSE
11 |    TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION
12 | 
13 |   0. You just DO WHAT THE FUCK YOU WANT TO.
14 | 
15 | 


--------------------------------------------------------------------------------
/README.md:
--------------------------------------------------------------------------------
  1 | # [gulp](https://github.com/gulpjs/gulp/)-buster
  2 | [![npm version](http://img.shields.io/npm/v/gulp-buster.svg)](https://npmjs.org/package/gulp-buster)
  3 | [![Build Status](http://img.shields.io/travis/UltCombo/gulp-buster.svg)](https://travis-ci.org/UltCombo/gulp-buster)
  4 | [![Coverage Status](https://img.shields.io/coveralls/UltCombo/gulp-buster.svg)](https://coveralls.io/r/UltCombo/gulp-buster)
  5 | [![Dependency Status](http://img.shields.io/david/UltCombo/gulp-buster.svg)](https://david-dm.org/UltCombo/gulp-buster)
  6 | [![devDependency Status](http://img.shields.io/david/dev/UltCombo/gulp-buster.svg)](https://david-dm.org/UltCombo/gulp-buster#info=devDependencies)
  7 | 
  8 | Cache buster hashes generator for gulp. Blazing fast and fully configurable.
  9 | 
 10 | ## What is cache busting?
 11 | 
 12 | It is basically a way to expire a given resource.
 13 | 
 14 | As a mean to optimize web applications, it is recommended to set assets' expiration date to a long time in the future (usually one month to one year). This way, the browser can load the cached resources from the local disk rather than over the network.
 15 | 
 16 | But of course, that also means the browser won't even attempt to load a resource from the network while it has a non-expired cached version of the given resource, even if that resource has been modified in the server. Then, how to invalidate this cached resource and force the browser to load the new version?
 17 | 
 18 | Here enters cache busting, also known as "fingerprinting", as described in [Optimize Caching - Google Developers](https://developers.google.com/speed/docs/best-practices/caching):
 19 | 
 20 | > For resources that change occasionally, you can have the browser cache the resource until it changes on the server, at which point the server tells the browser that a new version is available. You accomplish this by embedding a fingerprint of the resource in its URL (i.e. the file path). When the resource changes, so does its fingerprint, and in turn, so does its URL. As soon as the URL changes, the browser is forced to re-fetch the resource. Fingerprinting allows you to set expiry dates long into the future even for resources that change more frequently.
 21 | 
 22 | **Note:** Even if you are not explicitly setting expiration headers, browsers are allowed to and **will** cache assets such as CSS and image files. This means, without proper cache busting, your clients may get broken pages (e.g. updated markup with outdated styling and images which were automatically cached by the browser) even if your server does not send caching headers! (which it should send anyway)
 23 | 
 24 | Of course, technically, the caching issue could be worked around if every client refreshes the page, but that is not obvious to every user and, obviously, it would provide a terrible user experience and negatively affect the overall image of your product. And you don't want that, right? `;)`
 25 | 
 26 | ## Install
 27 | 
 28 | First off, [install gulp](https://github.com/gulpjs/gulp/blob/master/docs/getting-started.md).
 29 | 
 30 | Then install gulp-buster as a development dependency:
 31 | 
 32 | ```
 33 | npm install --save-dev gulp-buster
 34 | ```
 35 | 
 36 | ## How to use
 37 | 
 38 | gulp-buster can be used standalone as part of a build task, or in conjunction with [gulp-watch](https://npmjs.org/package/gulp-watch) to update the cache buster hashes as the files are modified.
 39 | 
 40 | Example with gulp-watch `^1.0.5` and gulp-ruby-sass `^0.7.1` (compile, bust and watch for changes):
 41 | 
 42 | ```js
 43 | var gulp = require('gulp'),
 44 | 	watch = require('gulp-watch'),
 45 | 	sass = require('gulp-ruby-sass'),
 46 | 	bust = require('gulp-buster');
 47 | 
 48 | gulp.task('default', function() {
 49 | 	var srcGlob = 'scss/*.scss';
 50 | 	return gulp.src(srcGlob)
 51 | 		.pipe(watch(srcGlob, function(files) {
 52 | 			return files
 53 | 				.pipe(sass())
 54 | 				.pipe(gulp.dest('css'))
 55 | 				.pipe(bust())           // pipe generated files into gulp-buster
 56 | 				.pipe(gulp.dest('.'));  // output busters.json to project root
 57 | 	}));
 58 | });
 59 | ```
 60 | 
 61 | ## Syntax
 62 | 
 63 | ```none
 64 | <through stream> bust([options])
 65 | ```
 66 | 
 67 | ### Parameters
 68 | 
 69 | - `options` (object|string, optional): the configuration options object. Passing `options` as a string is treated as `{ fileName: options }`.
 70 | 
 71 | - `options.fileName` (string, optional): the output filename. Defaults to `'busters.json'`.
 72 | 
 73 | - `options.algo` (string|function, optional): the hashing algorithm to be used. As a string, it accepts the same algorithms as [`crypto.createHash`](http://nodejs.org/api/crypto.html#crypto_crypto_createhash_algorithm). As a function, it takes a [vinyl file](https://github.com/wearefractal/vinyl) as the first argument and must return a string. Defaults to `'md5'`.
 74 | 
 75 | - `options.length` (number, optional): the maximum length of the hash. Specifying a positive `length` will return the given number of leading characters of the hash, and a negative `length` will return the given number of trailing characters. Defaults to `0`, which means no limit (actual length will then depend on the hashing algorithm used). Specifying a length larger than the hash will have no effect.
 76 | 
 77 | - `options.transform` (function, optional): allows mutating the hashes object, or even creating a completely new data structure, before passing it to the `formatter`. It takes a copy of the hashes object (a plain object in the `filePath: hash` format) as the first argument and must return a value compatible with the `formatter` option. Defaults to passing through the hashes object.
 78 | 
 79 | - `options.formatter` (function, optional): the function responsible for serializing the hashes data structure into the string content of the output file. It takes the value returned from the `transform` function as the first argument and must return a string. Defaults to `JSON.stringify`.
 80 | 
 81 | - `options.relativePath` (string, optional): the part of the path, relative to the project root, that should be omitted from the hashes object. Defaults to the project root—more specifically `process.cwd`. gulp defaults the `process.cwd` to where the gulpfile is located.
 82 | 
 83 | **Note:** all of the options which accept a function can be run asynchronously by returning a promise (or *thenable*). If the given option has a return value constraint, the constraint will still be applied to the promise's fulfillment value.
 84 | 
 85 | ## Integrating with Web applications
 86 | 
 87 | gulp-buster is language-agnostic, thus this part relies on you and your specific use case. By default, gulp-buster generates a JSON file in the following format:
 88 | 
 89 | ```js
 90 | {
 91 | 	"path/to/file/relative/to/project/root/filename.ext": "hash",
 92 | 	//other entries
 93 | }
 94 | ```
 95 | 
 96 | Integration can be easily achieved on any language which supports JSON parsing, in either back-end or front-end. See the [Implementations page](https://github.com/UltCombo/gulp-buster/blob/master/IMPLEMENTATIONS.md) for examples and existing solutions for your language of choice.
 97 | 
 98 | **Note:** The output file contents' data structure and format can be customized through the [configuration options](#parameters). This enables gulp-buster to output the cache buster hashes file in a suitable native data structure for your target language, as well as allowing to mutate the paths and hashes to suit your specific needs.
 99 | 
100 | ## Architecture
101 | 
102 | When gulp-buster is initialized, it creates an empty object which serves as a cache for the generated hashes. Generated hashes are then grouped by the `options.fileName` parameter. That means, piping two different streams into `bust('foo.json')` will merge both of those streams' files' hashes into the same output file. This approach's main pros are:
103 | 
104 | - Allows piping only modified files into gulp-buster, the other hashes are retrieved from the cache when generating the output file;
105 | - Deleted files' hashes are automatically cleaned on startup, as the hashes cache object starts empty on every startup;
106 | - Although this feature is very similar to [gulp-remember](https://github.com/ahaurw01/gulp-remember), gulp-buster's hashes cache is much more efficient. Using gulp-remember would cause all of the files that have ever went through the stream to be re-hashed whenever piping any new file, unlike gulp-buster's hashes cache which allows hashing only the files that are piped into gulp-buster.
107 | 
108 | There are close to no cons, the only notable drawback is that all the to-be-busted files must be piped into gulp-buster (preferably at startup) before it generates the output file with all hashes that you'd expect. A feature to allow inputting an already-generated hashes file was considered in order to avoid having to pipe all the to-be-busted files at startup, but that seems to bring more cons than pros -- the auto-cleanup of deleted files' hashes would no longer happen, outdated hashes could stay in the output hashes file if the to-be-busted files were edited while gulp was not running, and finally it'd also be incompatible with the `transform` and `formatter` features.
109 | 
110 | ## Changelog
111 | 
112 | [Available here.](https://github.com/UltCombo/gulp-buster/blob/master/CHANGELOG.md)
113 | 
114 | ## FAQ
115 | 
116 | **Q. Is the correct name Gulp-Buster, gulp-buster or Gulp-buster?**<br>
117 | The name is always lowercase, matching the npm package name.
118 | 


--------------------------------------------------------------------------------
/index.js:
--------------------------------------------------------------------------------
  1 | 'use strict';
  2 | 
  3 | var crypto = require('crypto');
  4 | var path = require('path');
  5 | var through = require('through');
  6 | var assign = require('object-assign');
  7 | var defaults = require('lodash.defaults');
  8 | var gutil = require('gulp-util');
  9 | var Promise = require('bluebird');
 10 | var DEFAULT_OPTIONS = {
 11 | 	fileName: 'busters.json',
 12 | 	algo: 'md5',
 13 | 	length: 0,
 14 | 	transform: Object,
 15 | 	formatter: JSON.stringify,
 16 | 	relativePath: '.',
 17 | };
 18 | var OPTION_TYPES = {
 19 | 	fileName: ['String'],
 20 | 	algo: ['String', 'Function'],
 21 | 	length: ['Number'],
 22 | 	transform: ['Function'],
 23 | 	formatter: ['Function'],
 24 | 	relativePath: ['String'],
 25 | };
 26 | var hashesStore = {}; // options.fileName: { relativePath: hash }
 27 | 
 28 | function error(msg) {
 29 | 	return new gutil.PluginError('gulp-buster', msg);
 30 | }
 31 | 
 32 | function hash(file, options) {
 33 | 	return typeof options.algo === 'function'
 34 | 		? options.algo.call(undefined, file)
 35 | 		: crypto.createHash(options.algo).update(file.contents).digest('hex');
 36 | }
 37 | 
 38 | function sliceHash(hash, options) {
 39 | 	// positive length = leading characters; negative = trailing
 40 | 	return options.length
 41 | 		? options.length > 0
 42 | 			? hash.slice(0, options.length)
 43 | 			: hash.slice(options.length)
 44 | 		: hash;
 45 | }
 46 | 
 47 | function relativePath(projectPath, relativePath, filePath) {
 48 | 	return path.relative(path.join(projectPath, relativePath), filePath).replace(/\\/g, '/');
 49 | }
 50 | 
 51 | function getType(value) {
 52 | 	return {}.toString.call(value).slice(8, -1);
 53 | }
 54 | 
 55 | function assignOptions(options) {
 56 | 	if (typeof options === 'string') options = { fileName: options };
 57 | 	options = options || {};
 58 | 
 59 | 	Object.keys(options).forEach(function(option) {
 60 | 		if (!OPTION_TYPES.hasOwnProperty(option)) throw error('Unsupported option: ' + option);
 61 | 		if (options[option] !== undefined && OPTION_TYPES[option].indexOf(getType(options[option])) === -1) throw error('`options.' + option + '` must be of type ' + OPTION_TYPES[option].join(' or '));
 62 | 	});
 63 | 
 64 | 	return defaults({}, options, DEFAULT_OPTIONS);
 65 | }
 66 | 
 67 | module.exports = exports = function(options) {
 68 | 	options = assignOptions(options);
 69 | 	var hashes = hashesStore[options.fileName] = hashesStore[options.fileName] || {},
 70 | 		hashingPromises = [];
 71 | 
 72 | 	function hashFile(file) {
 73 | 		if (file.isNull()) return; // ignore
 74 | 		if (file.isStream()) return this.emit('error', error('Streaming not supported'));
 75 | 
 76 | 		// start hashing files as soon as they are received for maximum concurrency
 77 | 		hashingPromises.push(
 78 | 			Promise.try(hash.bind(undefined, file, options)).then(function(hashed) {
 79 | 				if (typeof hashed !== 'string') throw error('Return/fulfill value of `options.algo` must be a string');
 80 | 				hashes[relativePath(file.cwd, options.relativePath, file.path)] = sliceHash(hashed, options);
 81 | 			})
 82 | 		);
 83 | 	}
 84 | 
 85 | 	function endStream() {
 86 | 		Promise.all(hashingPromises).bind(this).then(function() {
 87 | 			return options.transform.call(undefined, assign({}, hashes));
 88 | 		}).then(function(transformed) {
 89 | 			return options.formatter.call(undefined, transformed);
 90 | 		}).then(function(formatted) {
 91 | 			if (typeof formatted !== 'string') throw error('Return/fulfill value of `options.formatter` must be a string');
 92 | 
 93 | 			this.emit('data', new gutil.File({
 94 | 				path: path.join(process.cwd(), options.fileName),
 95 | 				contents: new Buffer(formatted),
 96 | 			}));
 97 | 			this.emit('end');
 98 | 		}).catch(function(err) {
 99 | 			this.emit('error', err instanceof gutil.PluginError ? err : error(err));
100 | 		});
101 | 	}
102 | 
103 | 	return through(hashFile, endStream);
104 | };
105 | 
106 | // for testing. Don't use, may be removed or changed at anytime
107 | assign(exports, {
108 | 	_Promise: Promise,
109 | 	_DEFAULT_OPTIONS: DEFAULT_OPTIONS,
110 | 	_error: error,
111 | 	_hash: hash,
112 | 	_relativePath: relativePath,
113 | 	_getType: getType,
114 | 	_assignOptions: assignOptions,
115 | 	_reset: function() {
116 | 		hashesStore = {};
117 | 	},
118 | });
119 | 


--------------------------------------------------------------------------------
/package.json:
--------------------------------------------------------------------------------
 1 | {
 2 |   "name": "gulp-buster",
 3 |   "description": "Cache buster hashes generator for gulp. Blazing fast and fully configurable.",
 4 |   "version": "1.1.0",
 5 |   "author": {
 6 |     "name": "Ult Combo",
 7 |     "email": "ultcombo@gmail.com"
 8 |   },
 9 |   "main": "./index.js",
10 |   "keywords": [
11 |     "gulpplugin",
12 |     "cachebuster",
13 |     "cache buster",
14 |     "cache",
15 |     "fingerprint",
16 |     "fingerprinting",
17 |     "revision",
18 |     "revisioning",
19 |     "workflow",
20 |     "webdev",
21 |     "web development"
22 |   ],
23 |   "repository": {
24 |     "type": "git",
25 |     "url": "https://github.com/UltCombo/gulp-buster.git"
26 |   },
27 |   "dependencies": {
28 |     "bluebird": "^3.3.5",
29 |     "gulp-util": "^3.0.7",
30 |     "lodash.defaults": "^4.0.1",
31 |     "object-assign": "^4.0.1",
32 |     "through": "^2.3.8"
33 |   },
34 |   "engines": {
35 |     "node": ">= 0.10"
36 |   },
37 |   "license": "WTFPL",
38 |   "bugs": {
39 |     "url": "https://github.com/UltCombo/gulp-buster/issues"
40 |   },
41 |   "homepage": "https://github.com/UltCombo/gulp-buster",
42 |   "devDependencies": {
43 |     "istanbul": "^0.4.3",
44 |     "mocha": "^2.4.5",
45 |     "should": "^8.3.1"
46 |   },
47 |   "scripts": {
48 |     "test": "mocha",
49 |     "test-cov": "istanbul cover node_modules/mocha/bin/_mocha -- -R dot",
50 |     "test-travis": "istanbul cover node_modules/mocha/bin/_mocha --report lcovonly"
51 |   }
52 | }
53 | 


--------------------------------------------------------------------------------
/test/main.js:
--------------------------------------------------------------------------------
  1 | 'use strict';
  2 | 
  3 | var bust = require('..');
  4 | var assign = require('object-assign');
  5 | var gutil = require('gulp-util');
  6 | require('should');
  7 | 
  8 | var fileContentStr = 'foo';
  9 | var file2ContentStr = 'bar';
 10 | var file = new gutil.File({
 11 | 	cwd: 'C:/users/ult/',
 12 | 	base: 'C:/users/ult/test',
 13 | 	path: 'C:/users/ult/test/file.js',
 14 | 	contents: new Buffer(fileContentStr),
 15 | });
 16 | var file2 = new gutil.File({
 17 | 	cwd: 'C:/users/ult/',
 18 | 	base: 'C:/users/ult/test',
 19 | 	path: 'C:/users/ult/test/file2.js',
 20 | 	contents: new Buffer(file2ContentStr),
 21 | });
 22 | var fileBinary = new gutil.File({
 23 | 	cwd: 'C:/users/ult/',
 24 | 	base: 'C:/users/ult/test',
 25 | 	path: 'C:/users/ult/test/file2.js',
 26 | 	contents: new Buffer([0x80]), // `Buffer.from` is not supported in Node 0.10
 27 | });
 28 | var fileBustPath = bust._relativePath(file.cwd, '.', file.path);
 29 | var fileBustPathRelative = bust._relativePath(file.cwd, 'test/', file.path);
 30 | var file2BustPath = bust._relativePath(file2.cwd, '.', file2.path);
 31 | var fileHash = bust._hash(file, bust._DEFAULT_OPTIONS);
 32 | var file2Hash = bust._hash(file2, bust._DEFAULT_OPTIONS);
 33 | var fileBinaryHash = bust._hash(fileBinary, bust._DEFAULT_OPTIONS);
 34 | 
 35 | var parseFile = function(file) {
 36 | 	return JSON.parse(file.contents.toString());
 37 | };
 38 | 
 39 | beforeEach(bust._reset);
 40 | 
 41 | describe('Configuration-independent internal methods', function() {
 42 | 	describe('_error()', function() {
 43 | 		it('should return an instance of PluginError', function() {
 44 | 			bust._error('err').should.be.an.instanceOf(gutil.PluginError);
 45 | 		});
 46 | 	});
 47 | 
 48 | 	describe('_relativePath()', function() {
 49 | 		it('should return a path relative to project root', function() {
 50 | 			bust._relativePath('/projectRoot/', '.', '/projectRoot/folder/file.ext').should.equal('folder/file.ext');
 51 | 		});
 52 | 	});
 53 | 
 54 | 	describe('_getType()', function() {
 55 | 		it('should return the correct type for all native values', function() {
 56 | 			bust._getType('').should.equal('String');
 57 | 			bust._getType(0).should.equal('Number');
 58 | 			bust._getType({}).should.equal('Object');
 59 | 			bust._getType([]).should.equal('Array');
 60 | 			bust._getType(null).should.equal('Null');
 61 | 			bust._getType(undefined).should.equal('Undefined');
 62 | 			bust._getType(false).should.equal('Boolean');
 63 | 			bust._getType(function() {}).should.equal('Function');
 64 | 			bust._getType(/(?:)/).should.equal('RegExp');
 65 | 			bust._getType(new Date()).should.equal('Date');
 66 | 			bust._getType(new Error()).should.equal('Error');
 67 | 		});
 68 | 	});
 69 | 
 70 | 	describe('_assignOptions()', function() {
 71 | 		it('should assign options', function() {
 72 | 			var options = { length: 10, algo: 'md5' };
 73 | 			bust._assignOptions(options).should.eql(assign({}, bust._DEFAULT_OPTIONS, options));
 74 | 		});
 75 | 
 76 | 		it('should return the default options when no options are passed', function() {
 77 | 			bust._assignOptions().should.eql(bust._DEFAULT_OPTIONS);
 78 | 		});
 79 | 
 80 | 		it('should treat `options` string as `options.fileName`', function() {
 81 | 			var fileName = 'customName.ext';
 82 | 			bust._assignOptions(fileName).fileName.should.equal(fileName);
 83 | 		});
 84 | 
 85 | 		it('should set options whose value evaluate to `undefined` to their default value', function() {
 86 | 			bust._assignOptions({ fileName: undefined }).should.eql(bust._DEFAULT_OPTIONS);
 87 | 		});
 88 | 
 89 | 		it('should not mutate the `options` argument', function() {
 90 | 			var options = {};
 91 | 			bust._assignOptions(options);
 92 | 			options.should.eql({});
 93 | 		});
 94 | 
 95 | 		it('should throw on unsupported options', function() {
 96 | 			bust._assignOptions.bind(undefined, { foo: 0 }).should.throw();
 97 | 		});
 98 | 
 99 | 		it('should throw on invalid option value', function() {
100 | 			bust._assignOptions.bind(undefined, { transform: null }).should.throw();
101 | 		});
102 | 	});
103 | });
104 | 
105 | describe('Core', function() {
106 | 	it('should bust two files into the same output file in the same stream', function(done) {
107 | 		var stream = bust();
108 | 		stream.on('data', function(newFile) {
109 | 			newFile.should.be.an.instanceOf(gutil.File);
110 | 			newFile.should.have.property('path');
111 | 			newFile.should.have.property('relative');
112 | 			newFile.should.have.property('contents');
113 | 
114 | 			newFile.relative.should.equal('busters.json');
115 | 			var expectedObj = {};
116 | 			expectedObj[fileBustPath] = fileHash;
117 | 			expectedObj[file2BustPath] = file2Hash;
118 | 
119 | 			parseFile(newFile).should.eql(expectedObj);
120 | 			Buffer.isBuffer(newFile.contents).should.be.true();
121 | 			done();
122 | 		});
123 | 		stream.write(file);
124 | 		stream.end(file2);
125 | 	});
126 | 
127 | 	it('should bust two files into different output files in different streams', function(done) {
128 | 		var stream = bust('output1.json');
129 | 		var stream2 = bust('output2.json');
130 | 		var testedOutputs = 0;
131 | 
132 | 		stream.on('data', function(newFile) {
133 | 			var obj = parseFile(newFile);
134 | 			obj.should.have.property(fileBustPath);
135 | 			obj.should.not.have.property(file2BustPath);
136 | 			if (++testedOutputs === 2) done();
137 | 		});
138 | 		stream2.on('data', function(newFile) {
139 | 			var obj = parseFile(newFile);
140 | 			obj.should.not.have.property(fileBustPath);
141 | 			obj.should.have.property(file2BustPath);
142 | 			if (++testedOutputs === 2) done();
143 | 		});
144 | 		stream.end(file);
145 | 		stream2.end(file2);
146 | 	});
147 | 
148 | 	it('should bust two files into the same output file in different streams', function(done) {
149 | 		var stream = bust('output.json');
150 | 		var stream2 = bust('output.json');
151 | 		var testedOutputs = 0;
152 | 
153 | 		function runAssertion(newFile) {
154 | 			var obj = parseFile(newFile);
155 | 			obj.should.have.property(fileBustPath);
156 | 			obj.should.have.property(file2BustPath);
157 | 			done();
158 | 		}
159 | 		function onData() {
160 | 			if (++testedOutputs === 2) runAssertion.apply(this, arguments);
161 | 		}
162 | 		stream.on('data', onData);
163 | 		stream2.on('data', onData);
164 | 		stream.end(file);
165 | 		stream2.end(file2);
166 | 	});
167 | 
168 | 	it('should return an empty hashes object file when receiving an empty buffers stream', function(done) {
169 | 		var stream = bust();
170 | 		stream.on('data', function(newFile) {
171 | 			parseFile(newFile).should.eql({});
172 | 			done();
173 | 		});
174 | 		stream.end();
175 | 	});
176 | });
177 | 
178 | describe('Configuration options', function() {
179 | 	describe('fileName', function() {
180 | 		it('should allow setting the output file name', function(done) {
181 | 			var fileName = 'customName.ext';
182 | 
183 | 			var stream = bust({ fileName: fileName });
184 | 			stream.on('data', function(newFile) {
185 | 				newFile.relative.should.equal(fileName);
186 | 				done();
187 | 			});
188 | 			stream.end(file);
189 | 		});
190 | 	});
191 | 
192 | 	describe('algo', function() {
193 | 		it('should accept a hashing algorithm name string', function(done) {
194 | 			var stream = bust({ algo: 'sha1' });
195 | 			stream.on('data', function(newFile) {
196 | 				parseFile(newFile)[fileBustPath].should.be.a.String().with.lengthOf(40);
197 | 				done();
198 | 			});
199 | 			stream.end(file);
200 | 		});
201 | 
202 | 		it('should hash binary files with algorithm name correctly', function() {
203 | 			fileBinaryHash.should.equal('8d39dd7eef115ea6975446ef4082951f');
204 | 		});
205 | 
206 | 		it('should emit an error when the hashing algorithm is not supported', function(done) {
207 | 			var stream = bust({ algo: 'UltHasher9000' });
208 | 			stream.on('error', function() {
209 | 				done();
210 | 			});
211 | 			stream.end(file);
212 | 		});
213 | 
214 | 		it('should accept a synchronous function', function(done) {
215 | 			var stream = bust({
216 | 				algo: function(file) {
217 | 					(this === undefined).should.be.true();
218 | 					return file.contents.toString();
219 | 				},
220 | 			});
221 | 			stream.on('data', function(newFile) {
222 | 				parseFile(newFile)[fileBustPath].should.equal(fileContentStr);
223 | 				done();
224 | 			});
225 | 			stream.end(file);
226 | 		});
227 | 
228 | 		it('should accept an asynchronous function', function(done) {
229 | 			var stream = bust({
230 | 				algo: function(file) {
231 | 					(this === undefined).should.be.true();
232 | 					return new bust._Promise(function(fulfill) {
233 | 						setTimeout(function() {
234 | 							fulfill(file.contents.toString());
235 | 						}, 0);
236 | 					});
237 | 				},
238 | 			});
239 | 			stream.on('data', function(newFile) {
240 | 				parseFile(newFile)[fileBustPath].should.equal(fileContentStr);
241 | 				done();
242 | 			});
243 | 			stream.end(file);
244 | 		});
245 | 
246 | 		it('should emit an error when function does not return a string or promise', function(done) {
247 | 			var stream = bust({ algo: function() {} });
248 | 			stream.on('error', function(err) {
249 | 				err.should.be.an.instanceOf(gutil.PluginError);
250 | 				done();
251 | 			});
252 | 			stream.end(file);
253 | 		});
254 | 
255 | 		it('should emit an error when promise is not fulfilled with a string', function(done) {
256 | 			var stream = bust({
257 | 				algo: function() {
258 | 					return new bust._Promise.resolve();
259 | 				},
260 | 			});
261 | 			stream.on('error', function(err) {
262 | 				err.should.be.an.instanceOf(gutil.PluginError);
263 | 				done();
264 | 			});
265 | 			stream.end(file);
266 | 		});
267 | 	});
268 | 
269 | 	describe('length', function() {
270 | 		it('should return leading characters for positive values', function(done) {
271 | 			var expectedLength = 6;
272 | 			var stream = bust({ length: expectedLength });
273 | 
274 | 			fileHash.length.should.be.greaterThan(expectedLength);
275 | 
276 | 			stream.on('data', function(newFile) {
277 | 				parseFile(newFile)[fileBustPath].should.equal(fileHash.slice(0, expectedLength));
278 | 				done();
279 | 			});
280 | 			stream.end(file);
281 | 		});
282 | 
283 | 		it('should return trailing characters for negative values', function(done) {
284 | 			var expectedLength = 6;
285 | 			var stream = bust({ length: -expectedLength });
286 | 
287 | 			fileHash.length.should.be.greaterThan(expectedLength);
288 | 
289 | 			stream.on('data', function(newFile) {
290 | 				parseFile(newFile)[fileBustPath].should.equal(fileHash.slice(-expectedLength));
291 | 				done();
292 | 			});
293 | 			stream.end(file);
294 | 		});
295 | 	});
296 | 
297 | 	describe('transform', function() {
298 | 		it('should accept a synchronous function', function(done) {
299 | 			var suffix = '_suffix';
300 | 			var options = {
301 | 				transform: function(hashes) {
302 | 					(this === undefined).should.be.true();
303 | 					return [hashes[fileBustPath] + suffix];
304 | 				},
305 | 			};
306 | 			var stream = bust(options);
307 | 			stream.on('data', function(newFile) {
308 | 				parseFile(newFile)[0].should.equal(fileHash + suffix);
309 | 				done();
310 | 			});
311 | 			stream.end(file);
312 | 		});
313 | 
314 | 		it('should accept an asynchronous function', function(done) {
315 | 			var suffix = '_suffix';
316 | 			var options = {
317 | 				transform: function(hashes) {
318 | 					(this === undefined).should.be.true();
319 | 					return new bust._Promise(function(fulfill) {
320 | 						setTimeout(function() {
321 | 							fulfill([hashes[fileBustPath] + suffix]);
322 | 						}, 0);
323 | 					});
324 | 				},
325 | 			};
326 | 			var stream = bust(options);
327 | 			stream.on('data', function(newFile) {
328 | 				parseFile(newFile)[0].should.equal(fileHash + suffix);
329 | 				done();
330 | 			});
331 | 			stream.end(file);
332 | 		});
333 | 	});
334 | 
335 | 	describe('formatter', function() {
336 | 		it('should accept a synchronous function', function(done) {
337 | 			var options = {
338 | 				formatter: function(hashes) {
339 | 					(this === undefined).should.be.true();
340 | 					return hashes[fileBustPath];
341 | 				},
342 | 			};
343 | 			var stream = bust(options);
344 | 			stream.on('data', function(newFile) {
345 | 				newFile.contents.toString().should.equal(fileHash);
346 | 				done();
347 | 			});
348 | 			stream.end(file);
349 | 		});
350 | 
351 | 		it('should accept an asynchronous function', function(done) {
352 | 			var options = {
353 | 				formatter: function(hashes) {
354 | 					(this === undefined).should.be.true();
355 | 					return new bust._Promise(function(fulfill) {
356 | 						setTimeout(function() {
357 | 							fulfill(hashes[fileBustPath]);
358 | 						}, 0);
359 | 					});
360 | 				},
361 | 			};
362 | 			var stream = bust(options);
363 | 			stream.on('data', function(newFile) {
364 | 				newFile.contents.toString().should.equal(fileHash);
365 | 				done();
366 | 			});
367 | 			stream.end(file);
368 | 		});
369 | 
370 | 		it('should emit an error when function does not return a string or promise', function(done) {
371 | 			var stream = bust({ formatter: function() {} });
372 | 			stream.on('error', function(err) {
373 | 				err.should.be.an.instanceOf(gutil.PluginError);
374 | 				done();
375 | 			});
376 | 			stream.end(file);
377 | 		});
378 | 
379 | 		it('should emit an error when promise is not fulfilled with a string', function(done) {
380 | 			var stream = bust({
381 | 				formatter: function() {
382 | 					return new bust._Promise.resolve();
383 | 				},
384 | 			});
385 | 			stream.on('error', function(err) {
386 | 				err.should.be.an.instanceOf(gutil.PluginError);
387 | 				done();
388 | 			});
389 | 			stream.end(file);
390 | 		});
391 | 	});
392 | 
393 | 	describe('relativePath', function() {
394 | 		it('should not include this path in the hashes object', function(done) {
395 | 			var options = {
396 | 				relativePath: 'test/',
397 | 			};
398 | 			var stream = bust(options);
399 | 			stream.on('data', function(newFile) {
400 | 				parseFile(newFile).should.have.property(fileBustPathRelative);
401 | 				done();
402 | 			});
403 | 			stream.end(file);
404 | 		});
405 | 
406 | 		it('should accept a leading slash', function(done) {
407 | 			var options = {
408 | 				relativePath: '/test/',
409 | 			};
410 | 			var stream = bust(options);
411 | 			stream.on('data', function(newFile) {
412 | 				parseFile(newFile).should.have.property(fileBustPathRelative);
413 | 				done();
414 | 			});
415 | 			stream.end(file);
416 | 		});
417 | 
418 | 		it('should not require a trailing slash', function(done) {
419 | 			var options = {
420 | 				relativePath: 'test',
421 | 			};
422 | 			var stream = bust(options);
423 | 			stream.on('data', function(newFile) {
424 | 				parseFile(newFile).should.have.property(fileBustPathRelative);
425 | 				done();
426 | 			});
427 | 			stream.end(file);
428 | 		});
429 | 
430 | 		it('should accept just a slash', function(done) {
431 | 			var options = {
432 | 				relativePath: '/',
433 | 			};
434 | 			var stream = bust(options);
435 | 			stream.on('data', function(newFile) {
436 | 				parseFile(newFile).should.have.property(fileBustPath);
437 | 				done();
438 | 			});
439 | 			stream.end(file);
440 | 		});
441 | 	});
442 | });
443 | 


--------------------------------------------------------------------------------