spi

spiff

Promise-aware file-system adapter and transmogrifier.

Showing:

Popularity

Downloads/wk

2

GitHub Stars

9

Maintenance

Last Commit

4yrs ago

Contributors

2

Package

Dependencies

5

License

MIT

Type Definitions

Tree-Shakeable

No?

Categories

Readme

spiff

NPM version Downloads Build Status Coverage Status Tip

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

Rate & Review

Great Documentation0
Easy to Use0
Performant0
Highly Customizable0
Bleeding Edge0
Responsive Maintainers0
Poor Documentation0
Hard to Use0
Slow0
Buggy0
Abandoned0
Unwelcoming Community0
100
No reviews found
Be the first to rate

Alternatives

No alternatives found

Tutorials

No tutorials found
Add a tutorial