Add ensureFolderExists option to FileSystem.createWriteStream

Agent-Logs-Url: https://github.com/microsoft/rushstack/sessions/199d4b3e-1f3f-44e1-9fc6-7b4a0e027c7e

Co-authored-by: iclanton <5010588+iclanton@users.noreply.github.com>

Author: Copilot

common/reviews/api/node-core-library.api.md

@@ -173,7 +173,7 @@ export class FileSystem {
     static createSymbolicLinkFolderAsync(options: IFileSystemCreateLinkOptions): Promise<void>;
     static createSymbolicLinkJunction(options: IFileSystemCreateLinkOptions): void;
     static createSymbolicLinkJunctionAsync(options: IFileSystemCreateLinkOptions): Promise<void>;
-    static createWriteStream(filePath: string): FileSystemWriteStream;
+    static createWriteStream(filePath: string, options?: IFileSystemCreateWriteStreamOptions): FileSystemWriteStream;
     static deleteFile(filePath: string, options?: IFileSystemDeleteFileOptions): void;
     static deleteFileAsync(filePath: string, options?: IFileSystemDeleteFileOptions): Promise<void>;
     static deleteFolder(folderPath: string): void;
@@ -344,6 +344,11 @@ export interface IFileSystemCreateLinkOptions {
     newLinkPath: string;
 }
 
+// @public
+export interface IFileSystemCreateWriteStreamOptions {
+    ensureFolderExists?: boolean;
+}
+
 // @public
 export interface IFileSystemDeleteFileOptions {
     throwIfNotExists?: boolean;

libraries/node-core-library/src/FileSystem.ts

@@ -276,6 +276,18 @@ export interface IFileSystemCopyFilesOptions extends IFileSystemCopyFilesAsyncOp
   filter?: FileSystemCopyFilesFilter; // narrow the type to exclude FileSystemCopyFilesAsyncFilter
 }
 
+/**
+ * The options for {@link FileSystem.createWriteStream}
+ * @public
+ */
+export interface IFileSystemCreateWriteStreamOptions {
+  /**
+   * If true, will ensure the folder is created before writing the file.
+   * @defaultValue false
+   */
+  ensureFolderExists?: boolean;
+}
+
 /**
  * The options for {@link FileSystem.deleteFile}
  * @public
@@ -1270,10 +1282,21 @@ export class FileSystem {
    * Creates a writable stream for writing to a file.
    * Behind the scenes it uses `fs.createWriteStream()`.
    *
+   * @remarks
+   * Throws an error if the folder doesn't exist, unless {@link IFileSystemCreateWriteStreamOptions.ensureFolderExists}
+   * is set to `true`.
    * @param filePath - The path to the file. The path may be absolute or relative.
+   * @param options - Optional settings that can change the behavior.
    * @returns A new writable stream for the file.
    */
-  public static createWriteStream(filePath: string): FileSystemWriteStream {
+  public static createWriteStream(
+    filePath: string,
+    options?: IFileSystemCreateWriteStreamOptions
+  ): FileSystemWriteStream {
+    if (options?.ensureFolderExists) {
+      const folderPath: string = nodeJsPath.dirname(filePath);
+      FileSystem.ensureFolder(folderPath);
+    }
     return fs.createWriteStream(filePath);
   }
 

libraries/node-core-library/src/index.ts

@@ -61,6 +61,7 @@ export {
   type IFileSystemCopyFilesAsyncOptions,
   type IFileSystemCopyFilesOptions,
   type IFileSystemCreateLinkOptions,
+  type IFileSystemCreateWriteStreamOptions,
   type IFileSystemDeleteFileOptions,
   type IFileSystemMoveOptions,
   type IFileSystemReadFileOptions,