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

Comparing version 4.0.2 to 4.1.0

dist/tsdoc-metadata.json

@@ -8,5 +8,5 @@ // This file is read by tools that parse documentation comments conforming to the TSDoc standard.
       "packageName": "@microsoft/api-extractor",
-      "packageVersion": "7.39.1"
+      "packageVersion": "7.41.0"
     }
   ]
 }

lib/FileSystem.d.ts

@@ -35,6 +35,6 @@ /// <reference types="node" />
 /**
- * The options for {@link FileSystem.writeFile}
+ * The options for {@link FileSystem.writeBuffersToFile}
  * @public
  */
-export interface IFileSystemWriteFileOptions {
+export interface IFileSystemWriteBinaryFileOptions {
     /**
@@ -45,2 +45,8 @@ * If true, will ensure the folder is created before writing the file.
     ensureFolderExists?: boolean;
+}
+/**
+ * The options for {@link FileSystem.writeFile}
+ * @public
+ */
+export interface IFileSystemWriteFileOptions extends IFileSystemWriteBinaryFileOptions {
     /**
@@ -435,2 +441,16 @@ * If specified, will normalize line endings to the specified style of newline.
     /**
+     * Writes the contents of multiple Uint8Arrays to a file on disk, overwriting the file if it already exists.
+     * Behind the scenes it uses `fs.writevSync()`.
+     *
+     * This API is useful for writing large files efficiently, especially if the input is being concatenated from
+     * multiple sources.
+     *
+     * @remarks
+     * Throws an error if the folder doesn't exist, unless ensureFolder=true.
+     * @param filePath - The absolute or relative path of the file.
+     * @param contents - The content that should be written to the file.
+     * @param options - Optional settings that can change the behavior.
+     */
+    static writeBuffersToFile(filePath: string, contents: ReadonlyArray<Uint8Array>, options?: IFileSystemWriteBinaryFileOptions): void;
+    /**
      * An async version of {@link FileSystem.writeFile}.
@@ -440,2 +460,6 @@ */
     /**
+     * An async version of {@link FileSystem.writeBuffersToFile}.
+     */
+    static writeBuffersToFileAsync(filePath: string, contents: ReadonlyArray<Uint8Array>, options?: IFileSystemWriteBinaryFileOptions): Promise<void>;
+    /**
      * Writes a text string to a file on disk, appending to the file if it already exists.
@@ -442,0 +466,0 @@ * Behind the scenes it uses `fs.appendFileSync()`.

lib/FileSystem.js

@@ -470,2 +470,59 @@ "use strict";
     /**
+     * Writes the contents of multiple Uint8Arrays to a file on disk, overwriting the file if it already exists.
+     * Behind the scenes it uses `fs.writevSync()`.
+     *
+     * This API is useful for writing large files efficiently, especially if the input is being concatenated from
+     * multiple sources.
+     *
+     * @remarks
+     * Throws an error if the folder doesn't exist, unless ensureFolder=true.
+     * @param filePath - The absolute or relative path of the file.
+     * @param contents - The content that should be written to the file.
+     * @param options - Optional settings that can change the behavior.
+     */
+    static writeBuffersToFile(filePath, contents, options) {
+        FileSystem._wrapException(() => {
+            // Need a mutable copy of the iterable to handle incomplete writes,
+            // since writev() doesn't take an argument for where to start writing.
+            const toCopy = [...contents];
+            let fd;
+            try {
+                fd = fsx.openSync(filePath, 'w');
+            }
+            catch (error) {
+                if (!(options === null || options === void 0 ? void 0 : options.ensureFolderExists) || !FileSystem.isNotExistError(error)) {
+                    throw error;
+                }
+                const folderPath = nodeJsPath.dirname(filePath);
+                FileSystem.ensureFolder(folderPath);
+                fd = fsx.openSync(filePath, 'w');
+            }
+            try {
+                // In practice this loop will have exactly 1 iteration, but the spec allows
+                // for a writev call to write fewer bytes than requested
+                while (toCopy.length) {
+                    let bytesWritten = fsx.writevSync(fd, toCopy);
+                    let buffersWritten = 0;
+                    while (buffersWritten < toCopy.length) {
+                        const bytesInCurrentBuffer = toCopy[buffersWritten].byteLength;
+                        if (bytesWritten < bytesInCurrentBuffer) {
+                            // This buffer was partially written.
+                            toCopy[buffersWritten] = toCopy[buffersWritten].subarray(bytesWritten);
+                            break;
+                        }
+                        bytesWritten -= bytesInCurrentBuffer;
+                        buffersWritten++;
+                    }
+                    if (buffersWritten > 0) {
+                        // Avoid cost of shifting the array more than needed.
+                        toCopy.splice(0, buffersWritten);
+                    }
+                }
+            }
+            finally {
+                fsx.closeSync(fd);
+            }
+        });
+    }
+    /**
      * An async version of {@link FileSystem.writeFile}.
@@ -498,2 +555,49 @@ */
     /**
+     * An async version of {@link FileSystem.writeBuffersToFile}.
+     */
+    static async writeBuffersToFileAsync(filePath, contents, options) {
+        await FileSystem._wrapExceptionAsync(async () => {
+            // Need a mutable copy of the iterable to handle incomplete writes,
+            // since writev() doesn't take an argument for where to start writing.
+            const toCopy = [...contents];
+            let handle;
+            try {
+                handle = await fs.promises.open(filePath, 'w');
+            }
+            catch (error) {
+                if (!(options === null || options === void 0 ? void 0 : options.ensureFolderExists) || !FileSystem.isNotExistError(error)) {
+                    throw error;
+                }
+                const folderPath = nodeJsPath.dirname(filePath);
+                await FileSystem.ensureFolderAsync(folderPath);
+                handle = await fs.promises.open(filePath, 'w');
+            }
+            try {
+                // In practice this loop will have exactly 1 iteration, but the spec allows
+                // for a writev call to write fewer bytes than requested
+                while (toCopy.length) {
+                    let bytesWritten = (await handle.writev(toCopy)).bytesWritten;
+                    let buffersWritten = 0;
+                    while (buffersWritten < toCopy.length) {
+                        const bytesInCurrentBuffer = toCopy[buffersWritten].byteLength;
+                        if (bytesWritten < bytesInCurrentBuffer) {
+                            // This buffer was partially written.
+                            toCopy[buffersWritten] = toCopy[buffersWritten].subarray(bytesWritten);
+                            break;
+                        }
+                        bytesWritten -= bytesInCurrentBuffer;
+                        buffersWritten++;
+                    }
+                    if (buffersWritten > 0) {
+                        // Avoid cost of shifting the array more than needed.
+                        toCopy.splice(0, buffersWritten);
+                    }
+                }
+            }
+            finally {
+                await handle.close();
+            }
+        });
+    }
+    /**
      * Writes a text string to a file on disk, appending to the file if it already exists.
@@ -500,0 +604,0 @@ * Behind the scenes it uses `fs.appendFileSync()`.

lib/index.d.ts

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

package.json

 {
   "name": "@rushstack/node-core-library",
-  "version": "4.0.2",
+  "version": "4.1.0",
   "description": "Core libraries that every NodeJS toolchain project should use",
@@ -22,4 +22,4 @@ "main": "lib/index.js",
   "devDependencies": {
-    "@rushstack/heft": "0.64.0",
-    "@rushstack/heft-node-rig": "2.4.0",
+    "@rushstack/heft": "0.65.5",
+    "@rushstack/heft-node-rig": "2.4.18",
     "@types/fs-extra": "7.0.0",
@@ -26,0 +26,0 @@ "@types/heft-jest": "1.0.1",

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

1028431

increased by1.5%

Lines of code

13347

increased by1.15%

No dependency changes