gulp-transform - npm Package Compare versions

Comparing version 1.0.2 to 1.0.3

index.js

@@ -11,8 +11,8 @@ 'use strict';
 module.exports = function gulpTransform(transformFn, options) {
-  if (!transformFn) {
-    err('transformFn must be defined.');
-  } else if (typeof transformFn !== 'function') {
-    err('transformFn must be a function.');
-  } else if (options && !/^(?:function|object)$/.test(typeof options)) {
-    err('options must be an object or undefined.');
+  if (isNone(transformFn)) {
+    throwPluginError('transformFn must be defined.');
+  } else if (!isFunction(transformFn)) {
+    throwPluginError('transformFn must be a function.');
+  } else if (!isNone(options) && !isObject(options)) {
+    throwPluginError('options must be an object if defined.');
   } else {
@@ -86,6 +86,6 @@ return new PluginStream(transformFn, options);
     return contents;
-  } else if (typeof contents === 'string' || contents instanceof String) {
+  } else if (isString(contents)) {
     return new Buffer(contents);
   } else {
-    err('transformFn must return a string or a buffer.');
+    throwPluginError('transformFn must return a string or a buffer.');
   }
@@ -96,5 +96,23 @@ }
 
-// Throws Gulp PluginError with message.
-function err(message) {
+function throwPluginError(message) {
   throw new PluginError('gulp-transform', message);
 }
+
+
+
+function isNone(value) {
+  return value === undefined || value === null;
+}
+
+function isFunction(value) {
+  return typeof value === 'function';
+}
+
+function isObject(value) {
+  var type = typeof value;
+  return type === 'object' || type === 'function';
+}
+
+function isString(value) {
+  return typeof value === 'string' || value instanceof String;
+}

package.json

 {
   "name": "gulp-transform",
-  "version": "1.0.2",
+  "version": "1.0.3",
   "description": "Gulp plugin for performing arbitrary transformations on the contents of files.",
@@ -43,6 +43,9 @@ "main": "index.js",
     "chai": "^3.4.1",
+    "cheerio": "^0.19.0",
     "coveralls": "^2.11.6",
     "event-stream": "^3.3.2",
+    "gulp": "^3.9.0",
     "istanbul": "^0.4.1",
     "mocha": "^2.3.4",
+    "rimraf": "^2.5.1",
     "sinon": "^1.17.2",
@@ -49,0 +52,0 @@ "sinon-chai": "^2.8.0"

README.md

@@ -11,5 +11,11 @@ # gulp-transform
 [Gulp][Gulp link] plugin for applying arbitrary transformations to
-the contents of files. Useful for incorporating non-gulp functions and modules
-into your pipeline. Files may be in streaming mode or buffer mode.
+the contents of files.
 
+* **Simple**. Just pass a callback function that takes the current file
+contents and returns the desired contents.
+* **Flexible**. Receive file contents as a Buffer or a string. Compatible with
+pipelines in both buffer mode and streaming mode.
+* **Economical**. Reduce the need for gulp-specific plugins by pairing
+gulp-transform with ordinary node packages and functions.
+
 ## Install
@@ -23,8 +29,10 @@
 
-## Example
+## Examples
 
-Source file (caesar.txt):
+#### Simple transformation
 
+Source file:
+
 ```
-I am constant as the northern star...
+I am constant as the northern star.
 ```
@@ -38,11 +46,8 @@
 
-// Repeat contents three times and prepend filename.
-function transformFn(contents, file) {
-  return [file.path, contents, contents, contents].join('\n');
-}
-
-gulp.task('silly-task', function() {
-  return gulp.src('/path/to/src/**/*.txt')
-    .pipe(transform(transformFn)) // Apply transform.
-    .pipe(gulp.dest('/path/to/dest'));
+gulp.task('quadruple', function() {
+  return gulp.src('src/*.txt')
+    .pipe(transform(function(contents) {
+      return Array(4).fill(contents).join('\n');
+    }))
+    .pipe(gulp.dest('dest'));
 });
@@ -54,88 +59,70 @@ ```
 ```
-/path/to/src/caesar.txt
-I am constant as the northern star...
-I am constant as the northern star...
-I am constant as the northern star...
+I am constant as the northern star.
+I am constant as the northern star.
+I am constant as the northern star.
+I am constant as the northern star.
 ```
 
+#### Pairing with non-gulp packages
+
+We can pair gulp-transform with vanilla node packages to reduce dependence on
+gulp-specific plugins. In this example, we use gulp-transform with
+[cheerio][Cheerio link] to add a `role="main"` attribute to our `<main>` tags,
+thus ensuring accessibility in older versions of Internet Explorer.
+
+```js
+const gulp = require('gulp');
+const transform = require('gulp-transform');
+const cheerio = require('cheerio');
+
+
+function transformFn(contents) {
+  var $ = cheerio.load(contents);
+  $('main').attr('role', 'main');
+  return $.html();
+}
+
+gulp.task('cheerio', function() {
+  return gulp.src('src/**/*.html')
+    .pipe(transform(transformFn, {encoding: 'utf8'}))
+    .pipe(gulp.dest('dest'));
+});
+```
+
 ## API
 
-The package exports a single plugin function that takes a callback and an
-optional options object. The callback is invoked once per file. The
-contents of the file are passed to the callback and replaced by the return
-value.
+#### `transform(transformFn, [options])`
 
-##### Usage
+##### transformFn `function`
 
-##### `transform(transformFn, [options])`
+The callback responsible for the transformation. The return value must be a
+string or a Buffer, which will replace the file's contents. The callback
+is invoked once per file with the following arguments:
 
-<table>
-  <thead>
-    <tr>
-      <th>
-        Param
-      </th>
-      <th align="center">
-        Type
-      </th>
-      <th>
-        Details
-      </th>
-    </tr>
-  </thead>
-  <tbody>
-    <tr>
-      <td>
-        transformFn
-      </td>
-      <td align="center">
-        <code>Function</code>
-      </td>
-      <td>
-        Function that transforms the contents of each file. Invoked with the
-        following arguments:
-        <ul>
-          <li>
-            <strong>contents</strong> (<code>Buffer</code>|<code>String</code>) The contents of
-            the file. Will be a Buffer unless otherwise specified.
-          </li>
-          <li>
-            <strong>file</strong> (<code>File</code>)
-            The <a href="https://github.com/gulpjs/vinyl">vinyl file</a> object
-            whose contents are to be transformed. Useful for getting metadata
-            about the file, such as its name or path.
-          </li>
-        </ul>
-        The return value will replace the file's contents and must be either
-        a String or a Buffer.
-      </td>
-    </tr>
-    <tr>
-      <td>
-        options<br>(optional)
-      </td>
-      <td align="center">
-        <code>Object</code>
-      </td>
-      <td>
-        Options to modify the behavior of the plugin.
-        <ul>
-          <li>
-            <strong>encoding</strong> (<code>String</code>) Casts contents to
-            a string with the specified
-            <a href="https://nodejs.org/docs/latest/api/buffer.html#buffer_buffers_and_character_encodings">encoding</a>
-            before it is passed to transformFn. If no encoding is specified,
-            contents will be passed as a Buffer.
-          </li>
-          <li>
-            <strong>thisArg</strong> (<code>&#42;</code>) Determines the value of
-            <code>this</code> within transformFn. Defaults to
-            <code>undefined</code>.
-          </li>
-        </ul>
-      </td>
-    </tr>
-  </tbody>
-</table>
+* **contents** `Buffer` | `string` <br>
+The initial contents of the file. Contents are passed as a Buffer unless the
+`encoding` option is set, in which case they are passed as a string.
+Contents are normalized to ensure a consistent API regardless of whether
+files are in streaming or buffer mode.
 
+* **file** `File` <br>
+The [Vinyl file][Vinyl link] object to which the contents belong. Useful for
+getting metadata about the file, such as its path. Making changes to
+`file.contents` is not recommended, however, as these contents are not
+normalized and will in any case be replaced by the return value of the callback.
+
+##### options `object` (optional)
+
+An object for configuring the behavior of the plugin. The following keys are
+accepted as options:
+
+* **encoding** `string` <br>
+Casts contents to a string with the specified
+[encoding][Encoding link] before it is passed to transformFn. If no encoding is
+specified, contents will be passed as a Buffer.
+
+* **thisArg** `*` <br>
+Determines the value of `this` within transformFn. If omitted,
+`this` will be undefined.
+
 ## License
@@ -156,1 +143,4 @@
 [Dependencies link]: https://gemnasium.com/akim-mcmath/gulp-transform
+[Cheerio link]: https://www.npmjs.com/package/cheerio
+[Vinyl link]: https://github.com/gulpjs/vinyl
+[Encoding link]: https://nodejs.org/docs/latest/api/buffer.html#buffer_buffers_and_character_encodings

No alert changes

Improved metrics

Total package byte prevSize

9817

increased by6.33%

Lines of code

84

increased by16.67%

Worsened metrics

Dev dependency count

10

increased by42.86%

Number of lines in readme file

142

decreased by-6.58%

No dependency changes