copy-file-util 0.0.2

package/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2022 Individual contributors to copy-file-util
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,77 @@
+# copy-file-util
+<img src=https://centerkey.com/graphics/center-key-logo.svg align=right width=200 alt=logo>
+
+_A file copy and rename cli tool designed for use in npm scripts_
+
+[![License:MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://github.com/center-key/copy-file-util/blob/main/LICENSE.txt)
+[![npm](https://img.shields.io/npm/v/copy-file-util.svg)](https://www.npmjs.com/package/copy-file-util)
+[![Vulnerabilities](https://snyk.io/test/github/center-key/copy-file-util/badge.svg)](https://snyk.io/test/github/center-key/copy-file-util)
+[![Build](https://github.com/center-key/copy-file-util/workflows/build/badge.svg)](https://github.com/center-key/copy-file-util/actions/workflows/run-spec-on-push.yaml)
+
+**copy-file-util** copies a folder and its subfolders.
+
+## A) Setup
+
+Install package for node:
+```shell
+$ npm install --save-dev copy-file-util
+```
+
+## B) Usage
+
+### 1. npm scripts
+Call `copy-file` from the `"scripts"` section of your **package.json** file.
+
+The **first** parameter is the *source* file.
+The **second** parameter is the *target* file or folder (use the `--fodler` flag).
+
+Example **package.json** script:
+```json
+   "scripts": {
+      "pub-license": "copy-file src/LICENSE doc/license.txt",
+      "backup-license": "copy-file src/LICENSE --folder backup",
+   },
+```
+
+Try out the script with the command: `npm run pub-license`
+
+### 2. Global
+You can install **copy-file-util** globally and then run it anywhere directly from the terminal.
+
+Example terminal commands:
+```shell
+$ npm install --global copy-file-util
+$ copy-file src/web/api.html docs/api-manual.html
+```
+
+### 3. ESM and TypeScript Code
+Even though **copy-file-util** is primarily intended for build scripts, the package can easily be used in ESM and TypeScript projects.
+
+``` typescript
+import { copyFile } from 'copy-file-util';
+const result = copyFile.cp('src/web/api.html' { targetFile: 'docs/api-manual.html' });
+console.log('Execution time:', result.duration, 'ms');
+```
+
+See the **TypeScript Declaration File** file [copy-file.d.ts](dist/copy-file.d.ts) in the **dist** folder for documentation.
+
+## C) CLI Flags
+
+| Flag       | Description                       | Values | Default |
+| ---------- | --------------------------------- | ------ | ------- |
+| `--folder` | Indicates the target is a folder. | N/A    | N/A     |
+| `--quiet`  | Suppress informational messages.  | N/A    | N/A     |
+
+### Examples
+   - `copy-file app.js app.mjs --quite` &nbsp; Displays no output.
+   - `copy-file app.js --folder dist` &nbsp; Copies **app.js** into the **dist** folder.
+
+<br>
+
+---
+**Build Tools**
+   - 🎋 [add-dist-header](https://github.com/center-key/add-dist-header):&nbsp; _Adds a header comment to a file and saves it to your distribution folder_
+   - 📄 [copy-file-util](https://github.com/center-key/copy-file-util):&nbsp; _A file copy and rename cli tool designed for use in npm scripts_
+   - 📂 [copy-folder-cli](https://github.com/center-key/copy-folder-cli):&nbsp; _A recursive directory file copy utility designed for use in npm scripts_
+
+[MIT License](LICENSE.txt)

package/bin/cli.js

@@ -0,0 +1,62 @@
+#!/usr/bin/env node
+////////////////////
+// copy-file-util //
+// MIT License    //
+////////////////////
+
+// Usage in package.json:
+//    "scripts": {
+//       "pub-license": "copy-file src/LICENSE doc/license.txt"
+//    },
+//
+// Usage from command line:
+//    $ npm install --global copy-file-util
+//    $ copy-file src/LICENSE doc/license.txt
+//
+// Contributors to this project:
+//    $ cd copy-file-util
+//    $ npm install
+//    $ npm test
+//    $ node bin/cli.js spec/fixtures/source/mock.txt --folder spec/fixtures/target/to-folder
+
+// Imports
+import { copyFile } from '../dist/copy-file.js';
+import chalk        from 'chalk';
+import log          from 'fancy-log';
+
+// Parameters
+const validFlags = ['folder', 'quiet'];
+const args =       process.argv.slice(2);
+const flags =      args.filter(arg => /^--/.test(arg));
+const flagMap =    Object.fromEntries(flags.map(flag => flag.replace(/^--/, '').split('=')));
+const params =     args.filter(arg => !/^--/.test(arg));
+const source =     params[0];
+const target =     params[1];
+
+// Reporting
+const printReport = (result) => {
+   const name =   chalk.gray('copy-file-util');
+   const origin = chalk.blue.bold(result.origin);
+   const dest =   chalk.magenta(result.dest);
+   const arrow =  chalk.gray.bold(' ⟹  ');  //extra space for alignment
+   const info =   chalk.white(`(${result.duration}ms)`);
+   log(name, origin, arrow, dest, info);
+   };
+
+// Copy File
+const exit =        (message) => (console.error('[copy-file]', message), process.exit(1));
+const invalidFlag = Object.keys(flagMap).find(key => !validFlags.includes(key));
+const mode =        { folder: 'folder' in flagMap, quiet: 'quiet' in flagMap };
+const error =
+   invalidFlag ?            'Invalid flag: ' + invalidFlag :
+   params.length > 2 ?      'Extraneous parameter: ' + params[2] :
+   !source ?                'Missing source file.' :
+   !target && mode.folder ? 'Missing target folder.' :
+   !target ?                'Missing target file.' :
+   null;
+if (error)
+   exit(error);
+const options = mode.folder ? { targetFolder: target } : { targetFile: target };
+const result = copyFile.cp(source, options);
+if (!mode.quiet)
+   printReport(result);

package/dist/copy-file.d.ts

@@ -0,0 +1,16 @@
+//! copy-file-util v0.0.2 ~~ https://github.com/center-key/copy-file-util ~~ MIT License
+
+export declare type Options = {
+    targetFile?: string;
+    targetFolder?: string;
+    fileExtension?: string;
+};
+export declare type Result = {
+    origin: string;
+    dest: string;
+    duration: number;
+};
+declare const copyFile: {
+    cp(sourceFile: string, options: Options): Result;
+};
+export { copyFile };

package/dist/copy-file.js

@@ -0,0 +1,45 @@
+//! copy-file-util v0.0.2 ~~ https://github.com/center-key/copy-file-util ~~ MIT License
+
+import fs from 'fs-extra';
+import path from 'path';
+import slash from 'slash';
+const copyFile = {
+    cp(sourceFile, options) {
+        var _a;
+        const defaults = {
+            targetFile: null,
+            targetFolder: null,
+            fileExtension: null,
+        };
+        const settings = Object.assign(Object.assign({}, defaults), options);
+        const startTime = Date.now();
+        const missingTarget = !settings.targetFile && !settings.targetFolder;
+        const ambiguousTarget = !!settings.targetFile && !!settings.targetFolder;
+        const normalize = (folder) => !folder ? '' : slash(path.normalize(folder)).replace(/\/$/, '');
+        const source = normalize(sourceFile);
+        const sourceExists = fs.pathExistsSync(source);
+        const sourceIsFile = sourceExists && fs.statSync(source).isFile();
+        const targetFolder = normalize(settings.targetFile ? path.dirname(settings.targetFile) : settings.targetFolder);
+        const target = normalize((_a = settings.targetFile) !== null && _a !== void 0 ? _a : settings.targetFolder + '/' + path.basename(source));
+        if (targetFolder)
+            fs.ensureDirSync(targetFolder);
+        const badTargetFolder = !fs.pathExistsSync(targetFolder);
+        const errorMessage = settings.fileExtension ? 'Option "fileExtension" not yet implemented.' :
+            !sourceFile ? 'Must specify the source file.' :
+                !sourceExists ? 'Source file does not exist: ' + source :
+                    !sourceIsFile ? 'Source is not a file: ' + source :
+                        missingTarget ? 'Must specify a target file or folder.' :
+                            ambiguousTarget ? 'Target cannot be both a file and a folder.' :
+                                badTargetFolder ? 'Target folder cannot be written to: ' + targetFolder :
+                                    null;
+        if (errorMessage)
+            throw Error('[copy-file-util] ' + errorMessage);
+        fs.copySync(source, target);
+        return {
+            origin: source,
+            dest: target,
+            duration: Date.now() - startTime,
+        };
+    },
+};
+export { copyFile };

package/dist/copy-file.umd.cjs

@@ -0,0 +1,61 @@
+//! copy-file-util v0.0.2 ~~ https://github.com/center-key/copy-file-util ~~ MIT License
+
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+(function (factory) {
+    if (typeof module === "object" && typeof module.exports === "object") {
+        var v = factory(require, exports);
+        if (v !== undefined) module.exports = v;
+    }
+    else if (typeof define === "function" && define.amd) {
+        define(["require", "exports", "fs-extra", "path", "slash"], factory);
+    }
+})(function (require, exports) {
+    "use strict";
+    Object.defineProperty(exports, "__esModule", { value: true });
+    exports.copyFile = void 0;
+    const fs_extra_1 = __importDefault(require("fs-extra"));
+    const path_1 = __importDefault(require("path"));
+    const slash_1 = __importDefault(require("slash"));
+    const copyFile = {
+        cp(sourceFile, options) {
+            var _a;
+            const defaults = {
+                targetFile: null,
+                targetFolder: null,
+                fileExtension: null,
+            };
+            const settings = Object.assign(Object.assign({}, defaults), options);
+            const startTime = Date.now();
+            const missingTarget = !settings.targetFile && !settings.targetFolder;
+            const ambiguousTarget = !!settings.targetFile && !!settings.targetFolder;
+            const normalize = (folder) => !folder ? '' : (0, slash_1.default)(path_1.default.normalize(folder)).replace(/\/$/, '');
+            const source = normalize(sourceFile);
+            const sourceExists = fs_extra_1.default.pathExistsSync(source);
+            const sourceIsFile = sourceExists && fs_extra_1.default.statSync(source).isFile();
+            const targetFolder = normalize(settings.targetFile ? path_1.default.dirname(settings.targetFile) : settings.targetFolder);
+            const target = normalize((_a = settings.targetFile) !== null && _a !== void 0 ? _a : settings.targetFolder + '/' + path_1.default.basename(source));
+            if (targetFolder)
+                fs_extra_1.default.ensureDirSync(targetFolder);
+            const badTargetFolder = !fs_extra_1.default.pathExistsSync(targetFolder);
+            const errorMessage = settings.fileExtension ? 'Option "fileExtension" not yet implemented.' :
+                !sourceFile ? 'Must specify the source file.' :
+                    !sourceExists ? 'Source file does not exist: ' + source :
+                        !sourceIsFile ? 'Source is not a file: ' + source :
+                            missingTarget ? 'Must specify a target file or folder.' :
+                                ambiguousTarget ? 'Target cannot be both a file and a folder.' :
+                                    badTargetFolder ? 'Target folder cannot be written to: ' + targetFolder :
+                                        null;
+            if (errorMessage)
+                throw Error('[copy-file-util] ' + errorMessage);
+            fs_extra_1.default.copySync(source, target);
+            return {
+                origin: source,
+                dest: target,
+                duration: Date.now() - startTime,
+            };
+        },
+    };
+    exports.copyFile = copyFile;
+});

package/package.json

@@ -0,0 +1,99 @@
+{
+   "name": "copy-file-util",
+   "version": "0.0.2",
+   "description": "A file copy and rename cli tool designed for use in npm scripts (written in functional TypeScript)",
+   "license": "MIT",
+   "type": "module",
+   "module": "dist/copy-file.js",
+   "main": "dist/copy-file.umd.cjs",
+   "types": "dist/copy-file.d.ts",
+   "files": [
+      "dist"
+   ],
+   "exports": {
+      ".": {
+         "import": "./dist/copy-file.js",
+         "require": "./dist/copy-file.umd.cjs"
+      },
+      "./": "./dist/"
+   },
+   "bin": {
+      "copy-file": "bin/cli.js"
+   },
+   "repository": "github:center-key/copy-file-util",
+   "homepage": "https://github.com/center-key/copy-file-util",
+   "bugs": "https://github.com/center-key/copy-file-util/issues",
+   "docs": "https://github.com/center-key/copy-file-util#readme",
+   "author": "Center Key (https://centerkey.com)",
+   "keywords": [
+      "cli",
+      "copy",
+      "cp",
+      "file",
+      "rename",
+      "scripts"
+   ],
+   "jshintConfig": {
+      "esversion": 11,
+      "strict": "implied",
+      "eqeqeq": true,
+      "undef": true,
+      "unused": true,
+      "varstmt": true,
+      "node": true,
+      "mocha": true
+   },
+   "eslintConfig": {
+      "ignorePatterns": [
+         "build",
+         "dist",
+         "node_modules"
+      ],
+      "root": true,
+      "parser": "@typescript-eslint/parser",
+      "plugins": [
+         "@typescript-eslint"
+      ],
+      "extends": [
+         "eslint:recommended",
+         "plugin:@typescript-eslint/recommended"
+      ],
+      "rules": {
+         "@typescript-eslint/no-non-null-assertion": "off"
+      }
+   },
+   "scripts": {
+      "step:01": "rimraf build dist spec/fixtures/target **/.DS_Store",
+      "step:02": "jshint . --exclude-path .gitignore",
+      "step:03": "eslint --max-warnings 0 . --ext .ts",
+      "step:04": "tsc",
+      "step:05": "tsc --module UMD --outDir build/umd",
+      "step:06": "cpy build/umd/copy-file.js build --rename=copy-file.umd.cjs --flat=true",
+      "step:07": "cpy build/copy-file.* dist --flat=true",
+      "step:08": "add-dist-header build dist",
+      "pretest": "npm-run-all step:*",
+      "test": "mocha spec/*.spec.js"
+   },
+   "dependencies": {
+      "chalk": "~5.0",
+      "fancy-log": "~2.0",
+      "fs-extra": "~10.1",
+      "slash": "~4.0"
+   },
+   "devDependencies": {
+      "@types/fancy-log": "~2.0",
+      "@types/fs-extra": "~9.0",
+      "@types/node": "~18.7",
+      "@typescript-eslint/eslint-plugin": "~5.38",
+      "@typescript-eslint/parser": "~5.38",
+      "add-dist-header": "~0.2",
+      "assert-deep-strict-equal": "~1.0",
+      "cpy-cli": "~4.2",
+      "eslint": "~8.23",
+      "jshint": "~2.13",
+      "mocha": "~10.0",
+      "npm-run-all2": "~6.0",
+      "rimraf": "~3.0",
+      "typescript": "~4.8"
+   }
+}