spiff

Promise-based file-system adapter and transmogrifier.

Install

$ npm install --save spiff

Usage

The simplest usage of spiff copies files from one location to another.

import { read, write } from 'spiff';
 
read('src/styles/**/*.css')
    .map(write('dest/styles'));

That's all well and good, but it's not very interesting. Let's change the files.

import { read, write } from 'spiff';
 
read('src/styles/**/*.css')
 
    // Replace all whitespace with a single space.
    .map(cssFile => {
        cssFile.contents = cssFile.contents.replace(/\s+/, ' ');
 
        return cssFile;
    })
 
    .map(write('dest/styles'));

That did the trick. But look at all that code just to change one property. We can do better.

import { read, write } from 'spiff';
 
read('src/styles/**/*.css')
 
    // Replace all whitespace with a single space.
    .mapProp('contents', x => x.replace(/\s+/, ' '))
 
    .map(write('dest/styles'));

Now we're talking! But we're spitting out each file individually. Let's bundle them.

import { file, read, write } from 'spiff';
 
read('src/styles/**/*.css')
 
    // Replace all whitespace with a single space.
    .mapProp('contents', x => x.replace(/\s+/, ' '))
 
    // Concatenate multiple files into one.
    .reduce(
        // Add each css file to the bundle.
        (bundle, cssFile) => {
            bundle.contents += cssFile.contents;
 
            return bundle;
        },
        // Start with a new empty file.
        file('bundle.css')
    )
 
    .map(write('dest/styles'));

async/await

The find and read functions return special type of Promise object called a ListPromise. These lists provide a means of iterating through items with maximum concurrency, but are ultimately just Promises. Therefore, you can await the results.

async function bundleAssets() {
    await read('src/scripts/**/*.js')
        .map(write('dest/scripts'));
 
    await read('src/styles/**/*.css')
        .map(write('dest/styles'));
}

See the ListPromise documentation for more information on the available iteration methods.

API

file([options, [contents]]) : VinylRW

• options Object
  • cwd String (default: process.cwd()) Current working directory.
  • base String (default: cwd) Base path from which to derive relative paths.
  • path String File path.
• contents {String|Buffer|Stream} - (default: null) File contents.

Creates a new VinylRW file.

file('README.md', '# TODO');

find(glob, [options]) : ListPromise<VinylRW>

• glob String|Array<String>
• options Object Options for globby.

Finds files matching a glob pattern and provides them as a Promise-aware list of VinylRW objects. Does not read file contents into memory.

find('src/images/**/*.{jpg,png}')
    .map(x => x.path)
    .map(console.log);

read(glob, [options]) : ListPromise<VinylRW>

• glob String|Array<String>
• options Null|String|Object If null or a string, value is used as the encoding when reading. If an object, options for globby and fs.readFile.
  • encoding {String} (default: 'utf8') File encoding. Set to null to use Buffers instead of Strings.

Finds files matching a glob pattern and provides them as a Promise-aware list of VinylRW objects that can be mapped, filtered, reduced, and sorted. Reads file contents into memory.

// text files
read('src/styles/**/*.css')
    .map(write('dest/styles'));
 
// special encoding
read('src/data/**/*.csv', 'ucs2')
    .map(write('dest/data'));
 
// binary files
read('src/images/**/*.png', null)
    .map(write('dest/images'));

remove(glob) : Promise

• glob String|Array<String>

Permanently deletes files and directories.

remove('dest/**/*.tmp');

write([dir, [options]]) : Function

• dir String (default: file.base) Optional alternate directory in which to write a file. By default, files will be saved to their current .path value.
• options Object Options for fs.writeFile.

Returns a callback that accepts a VinylRW file and writes it to the file system, optionally in a different location.

callback(fileObj) : VinylRW

• fileObj VinylRW The VinylRW file to be written.

Writes a file to the file system based on the file's path property. Returns the file so that you may continue iterating after writing.

read('src/styles/**/*.css')
    .map(write('dest/styles'));

Contribute

Standards for this project, including tests, code coverage, and semantics are enforced with a build tool. Pull requests must include passing tests with 100% code coverage and no linting errors.

Test

$ npm test

© Shannon Moeller me@shannonmoeller.com (http://shannonmoeller.com)

Licensed under MIT