@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

Name Type Description

Name	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`.

[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("@lumjs/gulp-transform");

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