@userfrosting/vinyl-fs-vpath

Branch	Status
master

Vinyl source for file system with support for virtual paths. Uses globby for file discovery.

Install

npm i -D @userfrosting/vinyl-fs-vpath

Usage

IMPORTANT
This is an ES module package targeting NodeJS ^12.17.0 || >=13.2.0, refer to the NodeJS ESM docs regarding how to correctly import. ESM loaders like @babel/loader or esm likely won't work as expected.

// gulpfile.mjs
import { src } from "@userfrosting/vinyl-fs-vpath";
import { dest } from "gulp";
import terser from "gulp-terser";
import concatJs from "gulp-concat-js";

export function bundle() {
    return src(
            [ "src/**/*.js", "!src/**/*/*.test.js" ],
            [
                [ "./src/layer-1/", "./src/" ],
                [ "./src/layer-2/", "./src/" ]
            ]
        )
        .pipe(concatJs("main.js"))
        .pipe(terser())
        .pipe(dest("public/assets/"));
}

$ gulp bundle

./
+ src/
| + special.test.js
| + README.md
| + layer-1/
| | + a.js
| | + b.js
| + layer-2/
|   + a.js
|   + c.js
|   + c.test.js
+ public/assets/
  + a.js (from src/layer-2)
  + b.js (from src/layer-1)
  + c.js (from src/layer-2)

Why no dest?

Applying virtual path logic requires knowledge, without it there is no way to perform the operation in a deterministic manner. src does this by finding all the files and then performing the virtual path logic against the complete set, such an approach however does map translate to dest well. Memory pressure is a significant concern (that has no easy workaround) and perhaps more importantly it hurts the efficiency of the overall pipeline by introducing back-pressure (tasks later in the pipeline remain idle, reducing opportunity for asynchronous operations to be run).

I can see a need for mid-stream or end-of-stream virtual path operations in more specialized scenarios, so if its needed file an issue. Much of the logic already exists in @userfrosting/gulp-bundle-assets@^3, so it would not be a significant undertaking. The scope would most likely be limited to mid-stream operations to avoid duplicating the functionality of gulp.dest which can just be chained immediately after.

API

API documentation is regenerated for every release using API Extractor and API Documenter. The results reside in docs/api.

Release process

Generally speaking, all releases should first traverse through alpha, beta, and rc (release candidate) to catch missed bugs and gather feedback as appropriate. Aside from this however, there are a few steps that MUST always be done.

1. Make sure CHANGELOG.md is up to date.
2. Update version via npm like npm version 3.0.0 or npm version patch.
3. npm publish.
4. Create release on GitHub from tag made by npm version.

License

MIT