Native ES modules (#249)

* Refactor for native es module release * Don't test out-of-support NodeJS 13 * Test logging improvements * Expunged fragile mock-fs, and stray dependency glob-escape * Version bumps
userfrosting · Feb 13, 2021 · 5fc9ccd · 5fc9ccd
1 parent df908e5
commit 5fc9ccd
Show file tree

Hide file tree

Showing 17 changed files with 372 additions and 1,002 deletions.
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
@@ -1,61 +1,25 @@
-{
-    "name": "Continuous Integration",
-    "on": {
-        # Every push
-        "push": {},
-        "schedule": [
-            {
-                # Every Monday and Thursday at 12PM UTC
-                "cron": "0 12 * * 1,4"
-            }
-        ]
-    },
-    "jobs": {
-        "test": {
-            "strategy": {
-                "matrix": {
-                    "os": [
-                        "ubuntu-latest",
-                        "macos-latest",
-                        "windows-latest"
-                    ],
-                    "node-version": [
-                        "10.x",
-                        "12.x",
-                        "14.x",
-                        "15.x",
-                    ]
-                }
-            },
-            "runs-on": "${{ matrix.os }}",
-            "steps": [
-                {
-                    "name": "Checkout",
-                    "uses": "actions/checkout@v1"
-                },
-                {
-                    "name": "Setup node",
-                    "uses": "actions/setup-node@v1",
-                    "with": {
-                        "node-version": "${{ matrix.node-version }}"
-                    }
-                },
-                {
-                    "name": "Install dependencies",
-                    "run": "npm ci"
-                },
-                {
-                    "name": "Run tests",
-                    "run": "./node_modules/.bin/nyc --reporter=lcovonly npm test"
-                },
-                {
-                    "name": "Push coverage to Codecov",
-                    "uses": "codecov/codecov-action@v1",
-                    "with": {
-                        "token": "${{ secrets.CODECOV_UPLOAD_TOKEN }}"
-                    }
-                }
-            ]
-        }
-    }
-}
+name: Continuous Integration
+on:
+    # Every push
+    push:
+    schedule:
+        # Every Monday and Thursday at 12PM UTC
+        - cron: '0 12 * * 1,4'
+
+jobs:
+    test:
+        strategy:
+            matrix:
+                platform: [ ubuntu-latest, macos-latest, windows-latest ]
+                node-version: [ ^12.17.0, ^14.0.0, ^15.0.0 ]
+        runs-on: ${{ matrix.platform }}
+        steps:
+        - uses: actions/checkout@v2
+        - uses: actions/setup-node@v1
+          with:
+            node-version: ${{ matrix.node-version }}
+        - run: npm ci
+        - run: npm test
+        - uses: codecov/codecov-action@v1
+          with:
+            token: ${{ secrets.CODECOV_UPLOAD_TOKEN }}
diff --git a/.gitignore b/.gitignore
@@ -1,6 +1,5 @@
 node_modules/
 npm-debug.log
 dist/
-.nyc_output
 coverage
 temp
diff --git a/.npmignore b/.npmignore
@@ -13,3 +13,5 @@ temp/
 test-data/
 tsconfig.json
 .github
+.dependabot
+.vscode
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -7,12 +7,16 @@ and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.
 
 ## [Unreleased]
 
+### Changed
+- Removed `esm` loader in favour of native ESM support.
+- Raised minimum NodeJS version from 10 to 12.17.0.
+
 ## [2.0.0] - 2020-10-25
 
 ### Changed
-* `since` configuration option. Use [vinyl-filter-since](https://www.npmjs.com/package/vinyl-filter-since) if functionality is needed. This may be restored in a future release.
-* `removeBOM` configuration option. Use [gulp-stripbom](https://www.npmjs.com/package/gulp-stripbom) if functionality is needed. This may be restored in a future release.
-* `sourcemaps` configuration option. Use [gulp-sourcemaps](https://www.npmjs.com/package/gulp-sourcemaps) if functionality is needed. This may be restored in a future release.
+- `since` configuration option. Use [vinyl-filter-since](https://www.npmjs.com/package/vinyl-filter-since) if functionality is needed. This may be restored in a future release.
+- `removeBOM` configuration option. Use [gulp-stripbom](https://www.npmjs.com/package/gulp-stripbom) if functionality is needed. This may be restored in a future release.
+- `sourcemaps` configuration option. Use [gulp-sourcemaps](https://www.npmjs.com/package/gulp-sourcemaps) if functionality is needed. This may be restored in a future release.
 
 ### Fixed
 * File names containing glob syntax failing to be read correctly due to unescaped glob syntax being processed by `vinyl-fs` internally. [#79](https://github.com/userfrosting/vinyl-fs-vpath/issues/79)

diff --git a/LICENSE b/LICENSE
@@ -1,6 +1,6 @@
 The MIT License (MIT)
 
-Copyright (c) 2019 - 2020 David Jordan Myles Mele
+Copyright (c) 2019 - 2021 David Jordan Myles Mele
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

diff --git a/README.md b/README.md
@@ -14,8 +14,12 @@ npm i -D @userfrosting/vinyl-fs-vpath
 
 ## Usage
 
+> **IMPORTANT**<br/>
+> This is an ES module package targeting NodeJS `^12.17.0 || >=13.2.0`, refer to the [NodeJS ESM docs](https://nodejs.org/api/esm.html) regarding how to correctly import.
+> ESM loaders like `@babel/loader` or `esm` likely won't work as expected.
+
 ```js
-// gulpfile.esm.js
+// gulpfile.mjs
 import { src } from "@userfrosting/vinyl-fs-vpath";
 import { dest } from "gulp";
 import terser from "gulp-terser";
@@ -59,9 +63,9 @@ $ gulp bundle
 
 ## Why no `dest`?
 
-This package was originally created to address a pain point that adding support for `dest` would inherit, backpressure and memory pressure. Backpressure occurs in a stream when a single part of the pipeline collects chunks but emits little to nothing for later pipeline parts, thus reducing effiency overall. The override logic with virtual paths needs to hold onto most of the files to decide what files should be discarded, which means memory requirements will steadily increase proportionally with the number of files in the pipeline. Some optimisations can be made, however they have little impact in most cases.
+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 backpressure (tasks later in the pipeline remain idle, reducing opportunity for asynchronous operations to be run).
 
-Much of the source does already exist in `@userfrosting/gulp-bundle-assets@^3`, so its introduction wouldn't be tremendously difficult. If it is something you might find useful just ask.
+I can see a need for mid-stream or end-of-stream virtual path operations in more specialised 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
 

diff --git a/docs/api/vinyl-fs-vpath.iconfig.md b/docs/api/vinyl-fs-vpath.iconfig.md
@@ -15,9 +15,9 @@ export interface IConfig
 
 |  Property | Type | Description |
 |  --- | --- | --- |
-|  [base](./vinyl-fs-vpath.iconfig.base.md) | string | Specifies the folder relative to the cwd This is used to determine the file names when saving in .dest() Default: cwd |
-|  [cwd](./vinyl-fs-vpath.iconfig.cwd.md) | string | Current working directory. Default: process.cwd() |
+|  [base?](./vinyl-fs-vpath.iconfig.base.md) | string | <i>(Optional)</i> Specifies the folder relative to the cwd This is used to determine the file names when saving in .dest() Default: cwd |
+|  [cwd?](./vinyl-fs-vpath.iconfig.cwd.md) | string | <i>(Optional)</i> Current working directory. Default: process.cwd() |
 |  [globs](./vinyl-fs-vpath.iconfig.globs.md) | string \| string\[\] | Input file matchers. |
-|  [logger](./vinyl-fs-vpath.iconfig.logger.md) | Logger | Optional logger. Use this to debug issues and trace behaviours. Adheres to interface defined in ts-log package. |
+|  [logger?](./vinyl-fs-vpath.iconfig.logger.md) | Logger | <i>(Optional)</i> Optional logger. Use this to debug issues and trace behaviours. Adheres to interface defined in ts-log package. |
 |  [pathMappings](./vinyl-fs-vpath.iconfig.pathmappings.md) | [IPathMapper](./vinyl-fs-vpath.ipathmapper.md)<!-- -->\[\] | Virtual path mappings. Collision resolution uses the last mapping to select the file. Internally mapping occurs on absolute path strings, conversion and normalisation is performed automatically. Resolution is \*not\* recursive. |