@rushstack/node-core-library - npm Package Compare versions

Comparing version 3.23.1 to 3.24.0

CHANGELOG.json

@@ -5,2 +5,14 @@ {
     {
+      "version": "3.24.0",
+      "tag": "@rushstack/node-core-library_v3.24.0",
+      "date": "Sat, 30 May 2020 02:59:54 GMT",
+      "comments": {
+        "minor": [
+          {
+            "comment": "Add a FileSystem.copyFiles() API for recursively copying folders, and clarify that FileSystem.copyFile() only copies a single file"
+          }
+        ]
+      }
+    },
+    {
       "version": "3.23.1",
@@ -7,0 +19,0 @@ "tag": "@rushstack/node-core-library_v3.23.1",

CHANGELOG.md

 # Change Log - @rushstack/node-core-library
 
-This log was last generated on Thu, 28 May 2020 05:59:02 GMT and should not be manually modified.
+This log was last generated on Sat, 30 May 2020 02:59:54 GMT and should not be manually modified.
 
+## 3.24.0
+Sat, 30 May 2020 02:59:54 GMT
+
+### Minor changes
+
+- Add a FileSystem.copyFiles() API for recursively copying folders, and clarify that FileSystem.copyFile() only copies a single file
+
 ## 3.23.1
@@ -6,0 +13,0 @@ Thu, 28 May 2020 05:59:02 GMT

lib/FileSystem.d.ts

@@ -14,3 +14,3 @@ /// <reference types="node" />
 /**
- * The options for FileSystem.readFolder()
+ * The options for {@link FileSystem.readFolder}
  * @public
@@ -26,3 +26,3 @@ */
 /**
- * The options for FileSystem.writeFile()
+ * The options for {@link FileSystem.writeFile}
  * @public
@@ -48,3 +48,3 @@ */
 /**
- * The options for FileSystem.readFile()
+ * The options for {@link FileSystem.readFile}
  * @public
@@ -65,3 +65,3 @@ */
 /**
- * The options for FileSystem.move()
+ * The options for {@link FileSystem.move}
  * @public
@@ -92,3 +92,3 @@ */
 /**
- * The options for FileSystem.copyFile()
+ * The options for {@link FileSystem.copyFile}
  * @public
@@ -107,6 +107,83 @@ */
     destinationPath: string;
+    /**
+     * Specifies what to do if the target object already exists.
+     * @defaultValue {@link AlreadyExistsBehavior.Overwrite}
+     */
+    alreadyExistsBehavior?: AlreadyExistsBehavior;
 }
 /**
- * The options for FileSystem.deleteFile()
+ * Specifies the behavior of {@link FileSystem.copyFiles} in a situation where the target object
+ * already exists.
  * @public
+ */
+export declare const enum AlreadyExistsBehavior {
+    /**
+     * If the destination object exists, overwrite it.
+     * This is the default behavior for {@link FileSystem.copyFiles}.
+     */
+    Overwrite = "overwrite",
+    /**
+     * If the destination object exists, report an error.
+     */
+    Error = "error",
+    /**
+     * If the destination object exists, skip it and continue the operation.
+     */
+    Ignore = "ignore"
+}
+/**
+ * Callback function type for {@link IFileSystemCopyFilesAsyncOptions.filter}
+ * @public
+ */
+export declare type FileSystemCopyFilesAsyncFilter = (sourcePath: string, destinationPath: string) => Promise<boolean>;
+/**
+ * Callback function type for {@link IFileSystemCopyFilesOptions.filter}
+ * @public
+ */
+export declare type FileSystemCopyFilesFilter = (sourcePath: string, destinationPath: string) => boolean;
+/**
+ * The options for {@link FileSystem.copyFilesAsync}
+ * @public
+ */
+export interface IFileSystemCopyFilesAsyncOptions {
+    /**
+     * The starting path of the file or folder to be copied.
+     * The path may be absolute or relative.
+     */
+    sourcePath: string;
+    /**
+     * The path that the files will be copied to.
+     * The path may be absolute or relative.
+     */
+    destinationPath: string;
+    /**
+     * If true, then when copying symlinks, copy the target object instead of copying the link.
+     */
+    dereferenceSymlinks?: boolean;
+    /**
+     * Specifies what to do if the target object already exists.
+     */
+    alreadyExistsBehavior?: AlreadyExistsBehavior;
+    /**
+     * If true, then the target object will be assigned "last modification" and "last access" timestamps
+     * that are the same as the source.  Otherwise, the OS default timestamps are assigned.
+     */
+    preserveTimestamps?: boolean;
+    /**
+     * A callback that will be invoked for each path that is copied.  The callback can return `false`
+     * to cause the object to be excluded from the operation.
+     */
+    filter?: FileSystemCopyFilesAsyncFilter | FileSystemCopyFilesFilter;
+}
+/**
+ * The options for {@link FileSystem.copyFiles}
+ * @public
+ */
+export interface IFileSystemCopyFilesOptions extends IFileSystemCopyFilesAsyncOptions {
+    /**  {@inheritdoc IFileSystemCopyFilesAsyncOptions.filter} */
+    filter?: FileSystemCopyFilesFilter;
+}
+/**
+ * The options for {@link FileSystem.deleteFile}
+ * @public
 */
@@ -121,3 +198,3 @@ export interface IFileSystemDeleteFileOptions {
 /**
- * The parameters for `updateTimes()`.
+ * The options for {@link FileSystem.updateTimes}
  * Both times must be specified.
@@ -137,4 +214,4 @@ * @public
 /**
- * The options for `FileSystem.createSymbolicLinkJunction()`, `createSymbolicLinkFile()`,
- * `createSymbolicLinkFolder()`,  and `createHardLink()`.
+ * The options for {@link FileSystem.createSymbolicLinkJunction}, {@link FileSystem.createSymbolicLinkFile},
+ * {@link FileSystem.createSymbolicLinkFolder}, and {@link FileSystem.createHardLink}.
  *
@@ -346,5 +423,10 @@ * @public
     /**
-     * Copies a file from one location to another.
+     * Copies a single file from one location to another.
      * By default, destinationPath is overwritten if it already exists.
-     * Behind the scenes it uses `fs.copyFileSync()`.
+     *
+     * @remarks
+     * The `copyFile()` API cannot be used to copy folders.  It copies at most one file.
+     * Use {@link FileSystem.copyFiles} if you need to recursively copy a tree of folders.
+     *
+     * The implementation is based on `copySync()` from the `fs-extra` package.
      */
@@ -357,2 +439,17 @@ static copyFile(options: IFileSystemCopyFileOptions): void;
     /**
+     * Copies a file or folder from one location to another, recursively copying any folder contents.
+     * By default, destinationPath is overwritten if it already exists.
+     *
+     * @remarks
+     * If you only intend to copy a single file, it is recommended to use {@link FileSystem.copyFile}
+     * instead to more clearly communicate the intended operation.
+     *
+     * The implementation is based on `copySync()` from the `fs-extra` package.
+     */
+    static copyFiles(options: IFileSystemCopyFilesOptions): void;
+    /**
+     * An async version of {@link FileSystem.copyFiles}.
+     */
+    static copyFilesAsync(options: IFileSystemCopyFilesOptions): Promise<void>;
+    /**
      * Deletes a file. Can optionally throw if the file doesn't exist.
@@ -359,0 +456,0 @@ * Behind the scenes it uses `fs.unlinkSync()`.

lib/FileSystem.js

@@ -34,2 +34,8 @@ "use strict";
 };
+const COPY_FILE_DEFAULT_OPTIONS = {
+    alreadyExistsBehavior: "overwrite" /* Overwrite */
+};
+const COPY_FILES_DEFAULT_OPTIONS = {
+    alreadyExistsBehavior: "overwrite" /* Overwrite */
+};
 const DELETE_FILE_DEFAULT_OPTIONS = {
@@ -522,9 +528,22 @@ throwIfNotExists: false
     /**
-     * Copies a file from one location to another.
+     * Copies a single file from one location to another.
      * By default, destinationPath is overwritten if it already exists.
-     * Behind the scenes it uses `fs.copyFileSync()`.
+     *
+     * @remarks
+     * The `copyFile()` API cannot be used to copy folders.  It copies at most one file.
+     * Use {@link FileSystem.copyFiles} if you need to recursively copy a tree of folders.
+     *
+     * The implementation is based on `copySync()` from the `fs-extra` package.
      */
     static copyFile(options) {
+        options = Object.assign({}, COPY_FILE_DEFAULT_OPTIONS, options);
+        if (FileSystem.getStatistics(options.sourcePath).isDirectory()) {
+            throw new Error('The specified path refers to a folder; this operation expects a file object:\n'
+                + options.sourcePath);
+        }
         FileSystem._wrapException(() => {
-            fsx.copySync(options.sourcePath, options.destinationPath);
+            fsx.copySync(options.sourcePath, options.destinationPath, {
+                errorOnExist: options.alreadyExistsBehavior === "error" /* Error */,
+                overwrite: options.alreadyExistsBehavior === "overwrite" /* Overwrite */
+            });
         });
@@ -537,4 +556,12 @@ }
         return __awaiter(this, void 0, void 0, function* () {
+            options = Object.assign({}, COPY_FILE_DEFAULT_OPTIONS, options);
+            if (FileSystem.getStatistics(options.sourcePath).isDirectory()) {
+                throw new Error('The specified path refers to a folder; this operation expects a file object:\n'
+                    + options.sourcePath);
+            }
             yield FileSystem._wrapExceptionAsync(() => {
-                return fsx.copy(options.sourcePath, options.destinationPath);
+                return fsx.copy(options.sourcePath, options.destinationPath, {
+                    errorOnExist: options.alreadyExistsBehavior === "error" /* Error */,
+                    overwrite: options.alreadyExistsBehavior === "overwrite" /* Overwrite */
+                });
             });
@@ -544,2 +571,41 @@ });
     /**
+     * Copies a file or folder from one location to another, recursively copying any folder contents.
+     * By default, destinationPath is overwritten if it already exists.
+     *
+     * @remarks
+     * If you only intend to copy a single file, it is recommended to use {@link FileSystem.copyFile}
+     * instead to more clearly communicate the intended operation.
+     *
+     * The implementation is based on `copySync()` from the `fs-extra` package.
+     */
+    static copyFiles(options) {
+        options = Object.assign({}, COPY_FILES_DEFAULT_OPTIONS, options);
+        FileSystem._wrapException(() => {
+            fsx.copySync(options.sourcePath, options.destinationPath, {
+                dereference: !!options.dereferenceSymlinks,
+                errorOnExist: options.alreadyExistsBehavior === "error" /* Error */,
+                overwrite: options.alreadyExistsBehavior === "overwrite" /* Overwrite */,
+                preserveTimestamps: !!options.preserveTimestamps,
+                filter: options.filter
+            });
+        });
+    }
+    /**
+     * An async version of {@link FileSystem.copyFiles}.
+     */
+    static copyFilesAsync(options) {
+        return __awaiter(this, void 0, void 0, function* () {
+            options = Object.assign({}, COPY_FILES_DEFAULT_OPTIONS, options);
+            yield FileSystem._wrapExceptionAsync(() => __awaiter(this, void 0, void 0, function* () {
+                fsx.copySync(options.sourcePath, options.destinationPath, {
+                    dereference: !!options.dereferenceSymlinks,
+                    errorOnExist: options.alreadyExistsBehavior === "error" /* Error */,
+                    overwrite: options.alreadyExistsBehavior === "overwrite" /* Overwrite */,
+                    preserveTimestamps: !!options.preserveTimestamps,
+                    filter: options.filter
+                });
+            }));
+        });
+    }
+    /**
      * Deletes a file. Can optionally throw if the file doesn't exist.
@@ -546,0 +612,0 @@ * Behind the scenes it uses `fs.unlinkSync()`.

lib/index.d.ts

@@ -21,3 +21,3 @@ /**
 export { Sort } from './Sort';
-export { FileSystem, FileSystemStats, IFileSystemReadFolderOptions, IFileSystemWriteFileOptions, IFileSystemReadFileOptions, IFileSystemMoveOptions, IFileSystemCopyFileOptions, IFileSystemDeleteFileOptions, IFileSystemUpdateTimeParameters, IFileSystemCreateLinkOptions } from './FileSystem';
+export { AlreadyExistsBehavior, FileSystem, FileSystemStats, IFileSystemReadFolderOptions, IFileSystemWriteFileOptions, IFileSystemReadFileOptions, IFileSystemMoveOptions, IFileSystemCopyFileOptions, IFileSystemDeleteFileOptions, IFileSystemUpdateTimeParameters, IFileSystemCreateLinkOptions, IFileSystemCopyFilesAsyncOptions, IFileSystemCopyFilesOptions, FileSystemCopyFilesAsyncFilter, FileSystemCopyFilesFilter, } from './FileSystem';
 export { FileWriter, IFileWriterFlags } from './FileWriter';
@@ -24,0 +24,0 @@ export { LegacyAdapters, LegacyCallback } from './LegacyAdapters';

package.json

 {
 	"name": "@rushstack/node-core-library",
-	"version": "3.23.1",
+	"version": "3.24.0",
 	"description": "Core libraries that every NodeJS toolchain project should use",
@@ -5,0 +5,0 @@ "main": "lib/index.js",

New alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Fixed alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Improved metrics

Total package byte prevSize

720524

increased by2.95%

Lines of code

9847

increased by2.84%

No dependency changes