@lumjs/gulp-transform

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

About this fork

This is a fork of the original gulp-transform with Teamop's replace-gulp-util pull request applied, and the version number bumped a bit. I've placed it into my @lumjs namespace to avoid any conflicts with the original package, but seeing as that package has not been updated since 2017, and there's been pull requests ignored since 2018, I think it's safe to say it's abandoned.

In a future update, I am planning to update the versions of all dependencies, but that will be a much bigger task. In addition to working around several major version upgrades, the upgrade process itself will be a major pain thanks to the unfathomable decisions of the DefinitelyTyped maintainers that caused major backwards-compatibility breakage, and has joined the list of utterly absurd open-source clusterfucks I've witnessed in the past three decades of working in the IT industry.

When I finally get this fully updated, I will bump the major version number.

Install

Install via npm:

npm install --save-dev gulp @lumjs/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('@lumjs/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('@lumjs/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.

Parameters

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("@lumjs/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.