@vanillaes/esmtk 0.16.2 → 0.17.1

package/.vscode/launch.json

@@ -336,6 +336,78 @@
             "cwd": "${workspaceFolder}",
             "args": ["rm", "./test/cp2/test1.txt", "./test/cp2/*.js"],
             "console": "integratedTerminal",
+        },
+        {
+            "name": "Clean --bundle",
+            "type": "node",
+            "request": "launch",
+            "skipFiles": [
+                "<node_internals>/**"
+            ],
+            "program": "${workspaceFolder}/bin/esmtk.js",
+            "cwd": "${workspaceFolder}",
+            "args": ["clean", "--bundle"],
+            "console": "integratedTerminal",
+        },
+        {
+            "name": "Clean --bundle w/ override",
+            "type": "node",
+            "request": "launch",
+            "skipFiles": [
+                "<node_internals>/**"
+            ],
+            "program": "${workspaceFolder}/bin/esmtk.js",
+            "cwd": "${workspaceFolder}",
+            "args": ["clean", "--bundle", "**/*.js"],
+            "console": "integratedTerminal",
+        },
+        {
+            "name": "Clean --bundle w/ Error",
+            "type": "node",
+            "request": "launch",
+            "skipFiles": [
+                "<node_internals>/**"
+            ],
+            "program": "${workspaceFolder}/bin/esmtk.js",
+            "cwd": "${workspaceFolder}",
+            "args": ["clean", "--bundle", "**/*.mjs"],
+            "console": "integratedTerminal",
+        },
+        {
+            "name": "Clean --minify",
+            "type": "node",
+            "request": "launch",
+            "skipFiles": [
+                "<node_internals>/**"
+            ],
+            "program": "${workspaceFolder}/bin/esmtk.js",
+            "cwd": "${workspaceFolder}",
+            "args": ["clean", "--minify"],
+            "console": "integratedTerminal",
+        },
+        {
+            "name": "Clean --typings",
+            "type": "node",
+            "request": "launch",
+            "skipFiles": [
+                "<node_internals>/**"
+            ],
+            "program": "${workspaceFolder}/bin/esmtk.js",
+            "cwd": "${workspaceFolder}",
+            "args": ["clean", "--typings"],
+            "console": "integratedTerminal",
+        },
+        {
+            "name": "Clean All",
+            "type": "node",
+            "request": "launch",
+            "skipFiles": [
+                "<node_internals>/**"
+            ],
+            "program": "${workspaceFolder}/bin/esmtk.js",
+            "cwd": "${workspaceFolder}",
+            "args": ["clean", "--bundle", "--minify", "--typings"],
+            "console": "integratedTerminal",
         }
     ]
 }

package/README.md

@@ -22,7 +22,11 @@ Lint the source code (using StandardJS)
 ### Usage
 
 ```sh
+# lint the sources
 esmtk lint
+
+# lint the sources and attempt to automatally fix the issues
+esmtk --fix lint
 ```
 
 ## Types
@@ -31,7 +35,7 @@ Type check the JSDoc typings (using Typescript)
 
 ### Arguments
 
-`esmtk types index.js`
+`esmtk types [entry]`
 
 - `[entry]` - the entry-point for the source
 - `--strict` - enable 'strict mode' type checks
@@ -39,25 +43,15 @@ Type check the JSDoc typings (using Typescript)
 ### Usage
 
 ```sh
+# type check the sources
 esmtk types index.js
-```
-
-## Typings
-
-Generate Type Declarations (.d.ts) from JSDoc (using Typescript)
-
-### Arguments
-
-`esmtk typings index.js`
-
-- `[entry]` - the entry-point for the source
 
-### Usage
-
-```sh
-esmtk typings index.js
+# type check the sources (with 'strict mode' enabled)
+esmtk types --strict index.js
 ```
 
+**Node: Due to Typescript limitations, inline JSDoc typings will be ignored if typings (ie `*.d.ts` files) exist.**
+
 ## Bundle
 
 Bundle the source code to an ECMAScript module (using ESBuild)
@@ -73,7 +67,11 @@ Bundle the source code to an ECMAScript module (using ESBuild)
 ### Usage
 
 ```sh
+# bundle ESM source -> ESM bundle
 esmtk bundle src/sample.js bundle.js
+
+# bundle ESM source -> ESM bundle (includes Node-specific bindings)
+esmtk bundle --platform=node src/sample.js bundle.js
 ```
 
 ## Minify
@@ -92,7 +90,14 @@ Bundle and Minify the source code to an ECMAScript module (using ESBuild)
 ### Usage
 
 ```sh
+# bundle ESM source -> minified ESM bundle
 esmtk minify src/sample.js bundle.min.js
+
+# bundle ESM source -> minified ESM bundle (includes Node-specific bindings)
+esmtk minify --platform=node src/sample.js bundle.min.js
+
+# bundle ESM source -> minified ESM bundle (output a sourcemap)
+esmtk minify --sourcemap src/sample.js bundle.min.js
 ```
 
 ## CommonJS
@@ -110,9 +115,55 @@ Bundle the source code to a CommonJS module (using ESBuild)
 ### Usage
 
 ```sh
+# bundle ESM source -> CommonJS bundle
 esmtk commonjs src/sample.js bundle.cjs
+
+# bundle ESM source -> CommonJS bundle (includes Node-specific bindings)
+esmtk commonjs --platform=node src/sample.js bundle.cjs
+```
+
+## Typings
+
+Generate Type Declarations (.d.ts) from JSDoc (using Typescript)
+
+### Arguments
+
+`esmtk typings [entry]`
+
+- `[entry]` - the entry-point for the source
+
+### Usage
+
+```sh
+# generate .d.ts files for all linked source files
+esmtk typings index.js
+```
+
+## Clean
+
+Clean up build artifacts
+
+### Arguments
+
+`esmtk clean [root]`
+
+- `[root]` - the root directory to perform the cleanup (default: `process.cwd()`)
+- `--bundle` - Clean bundled build artifacts (default: `*.esm.js`)
+- `--minify` - Clean minified build artifacts (default: `*.min.js`)
+- `--typings` - Clean typing artifacts (default: `*.d.ts`)
+
+### Usage
+
+```sh
+# clean all build artifacts
+esmtk clean --bundle --minify --typings
+
+# override default extension
+esmtk clean --bundle *.mjs
 ```
 
+**Node: The `clean` command automatically ignores the contents of `node_modules/`**
+
 ## Copy
 
 Copy is a cross-platform clone of the `cp` command in Linux
@@ -121,17 +172,26 @@ Copy is a cross-platform clone of the `cp` command in Linux
 
 `esmtk cp [-r] [source...] [destination]`
 
-- `[source...]` - the source file(s)/glob(s)
+- `[source(s)...]` - the source file(s)/glob(s)
 - `[destination]` - the destination file/directory
 - `-r, --recursive` - copy files/directories recursively
 
 ### Usage
 
 ```sh
+# copy one file
 esmtk cp file1.txt dest/file1.txt
+
+# copy multiple files
 esmtk cp file1.txt file2.txt file3.txt dest/
+
+# copy files that match a glob
 esmtk cp *.txt dest/
+
+# copy files that match multiple globs
 esmtk cp *.txt *.js *.ts dest/
+
+# recursively copy files from one directory to another
 esmtk cp -r src/ dest/
 ```
 
@@ -149,9 +209,18 @@ Remove is a cross-platform clone of the `rm` command in Linux
 ### Usage
 
 ```sh
+# remove one file
 esmtk rm file1.txt
+
+# remove multiple files
 esmtk rm file1.txt file3.txt file3.txt
+
+# remove files that match a glob
 esmtk rm *.txt
+
+# remove files that match miltiple globs
 esmtk rm *.txt *.js *.ts
+
+# recursively remove a 
 esmtk rm -r src/
 ```

package/bin/commands/clean.js

@@ -0,0 +1,32 @@
+import { removeMultipleAsync } from '../../src/rm.js'
+import { fileExists, match } from '../../src/util.js'
+
+/**
+ * Clean build artifcats using sensible defaults
+ * @param {string} root the root directory
+ * @param {any} options clean options
+ */
+export async function clean (root, options) {
+  const exists = await fileExists(root)
+  if (!exists) {
+    console.error(`clean: ${root} No such file or directory`)
+    process.exit(1)
+  }
+
+  if (options?.bundle) {
+    await cleanOne(root, options.bundle, options)
+  }
+
+  if (options?.minify) {
+    await cleanOne(root, options.minify, options)
+  }
+
+  if (options?.typings) {
+    await cleanOne(root, options.typings, options)
+  }
+}
+
+async function cleanOne (root, glob, options) {
+  const files = await match(glob, root, 'node_modules/**')
+  await removeMultipleAsync(files, options?.force)
+}

package/bin/commands/cp.js

@@ -1,5 +1,5 @@
 import { copyAsync, copyMultipleAsync, copyRecursiveAsync } from '../../src/cp.js'
-import { expandSource } from '../../src/index.js'
+import { expand } from '../../src/index.js'
 
 /**
  * POSIX cp Implemented in Node
@@ -25,14 +25,14 @@ export async function cp (paths, options) {
     }
 
     if (source.includes('*')) {
-      const sources = await expandSource(source)
+      const sources = await expand(source)
       await copyMultipleAsync(sources, target, options?.force)
     }
   }
 
   if (paths.length > 2) {
     let sources = paths.slice(0, -1)
-    sources = await await Promise.all(sources.map(source => expandSource(source)))
+    sources = await await Promise.all(sources.map(source => expand(source)))
     sources = sources.flat()
     const target = paths.slice(-1)[0]
 

package/bin/commands/index.js

@@ -1,4 +1,5 @@
 export { bundle } from './bundle.js'
+export { clean } from './clean.js'
 export { commonjs } from './commonjs.js'
 export { cp } from './cp.js'
 export { lint } from './lint.js'

package/bin/commands/rm.js

@@ -1,5 +1,5 @@
 import { removeAsync, removeMultipleAsync, removeRecursiveAsync } from '../../src/rm.js'
-import { expandSource } from '../../src/util.js'
+import { expand } from '../../src/util.js'
 
 /**
  * POSIX rm Implemented in Node
@@ -20,13 +20,13 @@ export async function rm (paths, options) {
 
     if (paths[0].includes('*')) {
       const glob = paths[0]
-      const files = await expandSource(glob)
+      const files = await expand(glob)
       await removeMultipleAsync(files, options?.force)
     }
   }
 
   if (paths.length > 1) {
-    let files = await await Promise.all(paths.map(path => expandSource(path)))
+    let files = await await Promise.all(paths.map(path => expand(path)))
     files = files.flat()
 
     await removeMultipleAsync(files, options?.force)

package/bin/esmtk.js

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { bundle, cp, commonjs, lint, minify, rm, types, typings } from './commands/index.js'
+import { bundle, clean, cp, commonjs, lint, minify, rm, types, typings } from './commands/index.js'
 import { Command } from 'commander'
 import { createRequire } from 'module'
 const program = new Command()
@@ -51,6 +51,29 @@ program.command('minify <input> <output>')
     minify(input, output, options)
   })
 
+program.command('clean')
+  .description('Clean build artificts')
+  .argument('[root]', 'The root directory to perform operations from (default cwd)', process.cwd())
+  .option('--bundle [bundle]', 'Clean bundled build artifacts (default: *.esm.js)')
+  .option('--minify [minify]', 'Clean minified build artifacts (default: *.min.js)')
+  .option('--typings [typings]', 'Clean typing artifacts (default: *.d.ts)')
+  // .option('-f, --force', 'Do not prompt before overwriting', false)
+  .action((root, options) => {
+    // set --bundle default
+    if (options?.bundle && typeof (options.bundle) === 'boolean') {
+      options.bundle = '**/*.esm.js'
+    }
+    // set --minify default
+    if (options?.minify && typeof (options.minify) === 'boolean') {
+      options.minify = '**/*.min.js'
+    }
+    // set --typings default
+    if (options?.typings && typeof (options.typings) === 'boolean') {
+      options.typings = '**/*.d.ts'
+    }
+    clean(root, options)
+  })
+
 program.command('cp')
   .usage(`[-r] source target
 
@@ -63,6 +86,7 @@ program.command('cp')
   .description('Copy files and directories')
   .argument('[paths...]')
   .option('-r, --recursive', 'Copy directories recursively', false)
+  // .option('-f, --force', 'Do not prompt before overwriting', false)
   .action((paths, options) => {
     cp(paths, options)
   })
@@ -78,7 +102,7 @@ program.command('rm')
   `)
   .description('Remove files or directories')
   .argument('[paths...]')
-  .option('-f, --force', 'Do not prompt before overwriting', false)
+  // .option('-f, --force', 'Do not prompt before overwriting', false)
   .option('-r, --recursive', 'Remove directories recursively', false)
   .action((paths, options) => {
     rm(paths, options)

package/package.json

@@ -1,13 +1,19 @@
 {
   "name": "@vanillaes/esmtk",
-  "version": "0.16.2",
+  "version": "0.17.1",
   "description": "ES Module Toolkit",
   "keywords": [
+    "ecmascript",
     "esm",
     "esmodules",
-    "nodejs",
     "cli",
-    "developer-tools"
+    "developer-tools",
+    "jsdoc",
+    "fs",
+    "cp",
+    "copy",
+    "rm",
+    "remove"
   ],
   "repository": "https://github.com/vanillaes/esmtk",
   "author": "Evan Plaice <evanplaice@gmail.com> (https://evanplaice.com/)",
@@ -33,7 +39,10 @@
   "scripts": {
     "lint": "./bin/esmtk.js lint",
     "types": "./bin/esmtk.js types src/index.js",
+    "bundle": "./bin/esmtk.js bundle --platform=node src/index.js src/index.esm.js",
+    "minify": "./bin/esmtk.js minify --platform=node src/index.js src/index.min.js",
     "typings": "./bin/esmtk.js typings src/index.js",
+    "clean": "./bin/esmtk.js clean --bundle --minify --typings",
     "preversion": "npm run lint && npm run types",
     "postversion": "git push --follow-tags"
   },

package/src/index.d.ts

@@ -1,3 +1,3 @@
 export { copyAsync, copyRecursiveAsync } from "./cp.js";
 export { removeAsync, removeMultipleAsync, removeRecursiveAsync } from "./rm.js";
-export { expandSource, fileExists, installed, match, which } from "./util.js";
+export { expand, fileExists, installed, match, which } from "./util.js";

package/src/index.js

@@ -1,3 +1,3 @@
 export { copyAsync, copyRecursiveAsync } from './cp.js'
 export { removeAsync, removeMultipleAsync, removeRecursiveAsync } from './rm.js'
-export { expandSource, fileExists, installed, match, which } from './util.js'
+export { expand, fileExists, installed, match, which } from './util.js'

package/src/util.d.ts

@@ -1,10 +1,10 @@
 /**
- * Expand source file/glob into a list of paths
+ * Expand file/glob into a list of paths
  *
  * @param {*} source the source file/glob
  * @returns {Promise<string[]>} an array of paths
  */
-export function expandSource(source: any): Promise<string[]>;
+export function expand(source: any): Promise<string[]>;
 /**
  * Check if a file/folder exists
  * @param {string} path the path to the file/folder
@@ -20,9 +20,11 @@ export function installed(pkg: string): Promise<boolean>;
 /**
  * Description
  * @param {string} pattern glob pattern(s) to match
+ * @param {string} root root path where the matcher runs from
+ * @param {string} ignore glob of pattern(s) to ignore
  * @returns {Promise<string[]>} an array of paths
  */
-export function match(pattern: string): Promise<string[]>;
+export function match(pattern: string, root?: string, ignore?: string): Promise<string[]>;
 /**
  * Check to see if an application is installed globally
  * @param {string} program the name of the application

package/src/util.js

@@ -5,24 +5,24 @@ import { promisify } from 'node:util'
 const execAsync = promisify(exec)
 
 /**
- * Expand source file/glob into a list of paths
+ * Expand file/glob into a list of paths
  *
  * @param {*} source the source file/glob
  * @returns {Promise<string[]>} an array of paths
  */
-export async function expandSource (source) {
+export async function expand (source) {
   const isGlob = source.includes('*')
   if (isGlob) {
     const paths = await match(source)
     if (paths.length === 0) {
-      console.error(`cp: ${source} no matches found`)
+      console.error(`${source} no matches found`)
       process.exit(1)
     }
     return paths
   } else {
     const exists = await fileExists(source)
     if (!exists) {
-      console.error(`cp: ${source} No such file or directory`)
+      console.error(`${source} No such file or directory`)
       process.exit(1)
     }
     return [source]
@@ -60,10 +60,13 @@ export async function installed (pkg) {
 /**
  * Description
  * @param {string} pattern glob pattern(s) to match
+ * @param {string} root root path where the matcher runs from
+ * @param {string} ignore glob of pattern(s) to ignore
  * @returns {Promise<string[]>} an array of paths
  */
-export async function match (pattern) {
-  return await Array.fromAsync(glob(pattern))
+export async function match (pattern, root = process.cwd(), ignore = '') {
+  const ignores = ignore.includes(',') ? [ignore] : ignore.split(',')
+  return await Array.fromAsync(glob(pattern, { cwd: root, exclude: ignores }))
 }
 
 /**