node-gulp-named-log/README.md

# gulp-named-log

A logging utility, primarily intended for use with Gulp or other Vinyl streams. Loosely inspired by `gulp-util`. Why you might want to use it:

* Log lines are prefixed by time, name, and optionally severity.
* Errors are displayed verbosely, in such a way that all the important details are immediately obvious.
* Supports Vinyl (Gulp) streams - simply pipe through a logstream, and every affected file will be logged.

<img src="https://i.imgur.com/iEb5seF.png">

## License

[WTFPL](http://www.wtfpl.net/txt/copying/) or [CC0](https://creativecommons.org/publicdomain/zero/1.0/), whichever you prefer. A donation and/or attribution are appreciated, but not required.

## Donate

Maintaining open-source projects takes a lot of time, and the more donations I receive, the more time I can dedicate to open-source. If this module is useful to you, consider [making a donation](http://cryto.net/~joepie91/donate.html)!

You can donate using Bitcoin, PayPal, Flattr, cash-in-mail, SEPA transfers, and pretty much anything else. Thank you!

## Contributing

Pull requests welcome. Please make sure your modifications are in line with the overall code style, and ensure that you're editing the files in `src/`, not those in `lib/`.

Build tool of choice is `gulp`; simply run `gulp` while developing, and it will watch for changes.

Be aware that by making a pull request, you agree to release your modifications under the licenses stated above.

## Usage

```javascript
var gulp = require("gulp");
var gulpBabel = require("gulp-babel");
var gulpCache = require("gulp-cached");
var gulpPlumber = require("gulp-plumber");
var gulpNamedLog = require("gulp-named-log");

// We define the different named loggers here.
var babelLogger = gulpNamedLog("babel");
var gulpLogger = gulpNamedLog("gulp");

var source = ["src/**/*.js"]

gulp.task('babel', function() {
	return gulp.src(source)
		.pipe(gulpPlumber())
		.pipe(gulpCache("babel"))
		.pipe(gulpBabel({presets: ["es2015"]}))
		.pipe(babelLogger.stream()) // This logs every file going through.
		.pipe(gulp.dest("lib/"));
});

gulp.task('watch', function () {
	gulpLogger.info("Watching for changes:", source); // This logs once.
	gulp.watch(source, ['babel']);
});

gulp.task('default', ['babel', 'watch']);

```

## API

### gulpNamedLog(name, options)

Creates a new `gulp-named-log` instace.

* __name:__ The name prefix that is used for each line that this logger logs.
* __options:__
	* __basePath:__ *Optional.* The root path of the project. This is used to display shorter paths when using the logger as a Vinyl stream - rather than showing the full path of the file, it will show the path relative to the project root.
	* __byteLimit:__ *Defaults to `20`.* When the logger is used as a Vinyl stream, this is the maximum amount of bytes that will be rendered (in hexadecimal representation) for each file line.

### logger.log(values...)

Logs each of the provided values, much like `console.log` would - but with a timestamp and logger name prefixed.

### logger.debug(values...)
### logger.info(values...)
### logger.warn(values...)
### logger.error(values...)

Like `logger.log`, but along with a timestamp and logger name, the line will also include the specified *severity*.

### logger.stream()

Returns a new Vinyl stream, that will log (and pass through) every file it receives. In a typical `gulp.watch` + `gulp-cache` setup, this will only include the files that were modified (even if the result stays the same).