Ninja Parading Musically

    @eklingen/vinyl-stream-gears

    4.0.2 • Public • Published

    Vinyl-stream gears

    Tiny Vinyl-stream utilities -aka Gulp plugins- for tiny stream operations. No dependencies. These are not full-featured wrappers for other libraries. Most of these functions only work on Vinyl Buffer objects. They have only been tested on Vinyl Buffer objects. Optional argument objects are not sanitized.

    Installation

    yarn install. Or npm install. Or just copy the files to your own project.

    Usage

    You can import only what you need.

    const { append, prepend } = require('@eklingen/vinyl-stream-gears')

    Append

    Append text to the end of a file.

    const { append } = require('@eklingen/vinyl-stream-gears')
    stream.pipe(append('Merry Christmas'))

    Apply

    Apply a callback function to the file in the stream. Useful for inspecting properties, for example. This is internally also used by the tests. Don't forget to check for .isBuffer() or .contents etc!

    const { apply } = require('@eklingen/vinyl-stream-gears')
    stream.pipe(apply(file => {
      // do something with file
    }))

    (since v2.0.0) This used to have a flush callback as well, but as it turns out, the flush event is inconsistently handled in Node. It's best to use stream.Finished or an end handler.


    Changed

    Leaves only changed files in the stream, as compared to a destination directory. Useful to prevent unnecessary writes.

    const { changed } = require('@eklingen/vinyl-stream-gears')
    stream.pipe(changed('path/to/destination'))

    You can choose between comparing either the file contents (default) via the option method: 'contents' or the file's modified timestamp via the option method: 'mtime'. The last one is less reliable in combination with source control.

    stream.pipe(changed('path/to/destination', { method: 'mtime' })) // Compare via modified timestamp

    If you don't care about the file contents, just that it is physically present, you could set the option method: 'exists'.

    stream.pipe(changed('path/to/destination', { method: 'exists '})) // Skips if a file with the same name already exists

    When comparing file contents, keep in mind that anything that is added later in the stream will show up as a difference. If a sourcemap comment is added later in the stream, this shows up as a difference. Use the option injectSourceMapComment: true to append a sourcemap comment to the file contents when comparing. Appending it to a the file itself could cause some tools to output it twice.

    stream.pipe(changed('path/to/destination', { injectSourceMapComment: true })) // Pretends the source file has a sourcemap comment added for comparison

    Changed in place

    Leaves only changed files in the stream, as compared to a destination directory. It also saves a cache file .cache-file to disk in the destination folder, with the filenames and their resulting value. It will add new files to the cache and remove non-existing files the next time around. Useful if you want to write changes back to the source directory, to prevent an infinite loop and unnecessary writes. When compressing images, for example. Don't forget to call .remember() in the finish event of the stream.

    const { changedInPlace } = require('@eklingen/vinyl-stream-gears')
    stream.pipe(changedInPlace.filter('path/to/destination'))
    ...
    stream.on('finish', () => changedInPlace.remember('path/to/destination')) // Save cache file
    return stream

    You can choose between comparing either the SHA1 hash of the file contents (default) via the option method: 'hash' or the file's modified timestamp via the option method: 'mtime'. The last one is less reliable in combination with source control.

    stream.pipe(changedInPlace.filter('path/to/destination', { method: 'mtime' })) // Compare via modified timestamp

    Filesize

    Report the size of the file passing through the stream.

    const { filesize } = require('@eklingen/vinyl-stream-gears')
    stream.pipe(filesize())

    By default, both the raw and the gzipped size is shown. Disable the latter via the option showGzip: false.

    stream.pipe(filesize({ showGzip: false }))

    Filesize diff

    Reports the size difference of the file passing through the stream after operations have been performed.

    const { filesizeDiff } = require('@eklingen/vinyl-stream-gears')
    stream.pipe(filesizeDiff.start())
    ...
    stream.pipe(filesizeDiff.report())

    You can choose to report only the files that have been changed in size (default) via the option reportOnlyChanged: true or report all the files via the option reportOnlyChanged: false.

    stream.pipe(filesizeDiff.report({ reportOnlyChanged: false }))

    You can also use this to filter out files from the stream that have not decreased in size. Useful when compressing images. You can give the change a bit of slack (default is 100) via the option slack: <Number>. This number is the amount of bytes it should ignore. This is useful if you don't want to write images to disk that have only decreased a couple of bytes.

    stream.pipe(filesizeDiff.start())
    ...
    stream.pipe(filesizeDiff.filter({ slack: 100 }))
    ...
    stream.pipe(filesizeDiff.report())

    Filter

    Filter files from the stream by property. Useful if you want to remove certain files from the stream.

    const { filter } = require('@eklingen/vinyl-stream-gears')
    stream.pipe(filter([ file => path.extname(file.relative) === '.map', ... ]))

    Log

    Reports the file in the stream to the console.

    const { log } = require('@eklingen/vinyl-stream-gears')
    stream.pipe(log())

    You can use the option showContents: true to show the contents. This can be helpful when verifying if a plugin is behaving itself.

    stream.pipe(log({ showContents> true }))

    Passthrough

    Does nothing. Wrapper around PassThrough. Can be used for tertiary if else statements within streams.

    const { passthrough } = require('@eklingen/vinyl-stream-gears')
    stream.pipe(debug ? doStuff() : passthrough())

    Prepend

    Prepend text to the beginning of a file.

    const { prepend } = require('@eklingen/vinyl-stream-gears')
    stream.pipe(prepend('Greetings!'))

    Rename

    Rename files in the stream. Also renames sourcemaps, if the file has a .sourceMap property. Possible properties in the mutation object are: filename, extname and dirname.

    const { rename } = require('@eklingen/vinyl-stream-gears')
    stream.pipe(rename(filename => ({ extname: 'css' })))

    Replace

    Performs a content replacement on the file in the stream. Can take an array of replacements, in the format [ { replace: (string or regex), value: (string) }, ... ]. These replacements are run in the order they are given.

    const { replace } = require('@eklingen/vinyl-stream-gears')
    stream.pipe(replace([
      { replace: '80s', value: '90s' },
      { replace: /(complicated|regex)/g, value: '' }
    ]))

    Run

    Run a shell command. This one is relatively untested.

    const { run } = require('@eklingen/vinyl-stream-gears')
    stream.pipe(run('ls -ll'))

    In this use, it just executes the command. You can also pass options. These are the defaults:

    options = {
      env: process.env,
      cwd: process.cwd(),
      input: false, // STDIO input
      quiet: false, // Don't report anything
      stdio: ['pipe', 'pipe', 'pipe'],
      windowsHide: true // hide console on Windows
    }

    Giving a string to input should pass that to STDIO. But again, this is relatively untested.


    Copyright (c) 2019 Elco Klingen. MIT License.

    Install

    npm i @eklingen/vinyl-stream-gears

    DownloadsWeekly Downloads

    89

    Version

    4.0.2

    License

    MIT

    Unpacked Size

    26.1 kB

    Total Files

    20

    Last publish

    Collaborators

    • eklingen