gulp-transform

A Gulp plugin for applying custom transformations to the contents of files.

Install

Install via npm:

npm install --save-dev gulp gulp-transform

Usage

Synchronous usage

This example adds a timestamp to the beginning of each source file. The comment format is inferred from the file extension. Files with unrecognized extensions are not modified.

gulpfile.js

const gulp = require('gulp');
const transform = require('gulp-transform');
const path = require('path');
 
const TIMESTAMP = Date();
 
gulp.task('timestamp', () => {
  return gulp.src('src/**/*')
    .pipe(transform('utf8', timestamp))
    .pipe(gulp.dest('out'));
});
 
function timestamp(content, file) {
  switch (path.extname(file.path)) {
    case '.js':
    case '.ts':
      return `// ${TIMESTAMP}\n\n${content}`;
    case '.coffee':
      return `# ${TIMESTAMP}\n\n${content}`;
    default:
      return content;
  }
}

src/hello.js

console.log('Hello, world.');

out/hello.js

// Thu Jul 27 2017 15:56:14 GMT-0700 (PDT)
 
console.log('Hello, world.');

Asynchronous usage

This example uses xml2js to convert XML to JSON. The callback returns a Promise since the operation is asynchronous.

gulpfile.js

const gulp = require('gulp');
const transform = require('gulp-transform');
const rename = require('gulp-rename');
const xml2js = require('xml2js');
 
gulp.task('xml-to-json', () => {
  return gulp.src('src/**/*.xml')
    .pipe(transform('utf8', xmlToJson))
    .pipe(rename({ extname: '.json' }))
    .pipe(gulp.dest('out'));
});
 
function xmlToJson(content) {
  return new Promise((resolve, reject) => {
    xml2js.parseString(content, (error, data) => {
      if (error) {
        reject(error);
      } else {
        resolve(JSON.stringify(data, null, 2));
      }
    });
  });
}

src/cities.xml

<cities>
  <city>Amsterdam</city>
  <city>Rotterdam</city>
  <city>The Hague</city>
</cities>

out/cities.json

{
  "cities": {
    "city": [
      "Amsterdam",
      "Rotterdam",
      "The Hague"
    ]
  }
}

API

transform([options], callback)

Creates a stream that transforms the contents of File objects. Files in both streaming and buffer mode are accepted.

To transform contents as a string, a character encoding must be specified; otherwise, contents will be passed to the callback as a Buffer.

The contents of each File are replaced with the return value of the callback. Or, to perform an asynchronous transformation, a Promise may be returned.

Parameter	Type	Description
[options]	object string null	An optional options object or a value indicating an encoding. If passed as an object, the following properties are are accepted as options: encoding - string | null - An encoding supported by Node.js or null to indicate no encoding. Defaults to null. thisArg - any - The value of this within callback. Defaults to undefined. If passed as a string or null, it is interpreted as the encoding option. If no encoding is given, callback is called with a Buffer object containing the contents of the file. Otherwise, it is called with a string created with buffer.toString(encoding).
callback	function	A function that transforms the contents of each file. It is invoked with two arguments: contents - Buffer | string - The contents of the file. If no encoding is given, contents will be a Buffer; otherwise, it will be a string. file - File - The File object whose contents are being transformed. Use this to access metadata about the file, e.g., its filename. The contents of the file are replaced with the return value of the callback. For asynchronous transformations, a Promise may be returned. The return or completion value must have the same type as contents. The value of this within the callback may be set with the thisArg option; otherwise, this will be undefined.

TypeScript

TypeScript declarations are included in the package.

npm i -D typescript ts-node gulp @types/gulp gulp-transform

gulpfile.ts

import gulp = require("gulp");
import transform = require("gulp-transform");
 
gulp.task("build", () => {
  gulp.src("src/**/*")
    .pipe(transform("utf8", () => { /* transform contents */ }))
    .pipe(gulp.dest("out"));
});

License

Copyright © 2016–2017 Akim McMath. Licensed under the MIT License.