Expand FileSystem.createWriteStream.

Author: iclanton

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

@@ -174,6 +174,7 @@ export class FileSystem {
     static createSymbolicLinkJunction(options: IFileSystemCreateLinkOptions): void;
     static createSymbolicLinkJunctionAsync(options: IFileSystemCreateLinkOptions): Promise<void>;
     static createWriteStream(filePath: string, options?: IFileSystemCreateWriteStreamOptions): FileSystemWriteStream;
+    static createWriteStreamAsync(filePath: string, options?: IFileSystemCreateWriteStreamOptions): Promise<FileSystemWriteStream>;
     static deleteFile(filePath: string, options?: IFileSystemDeleteFileOptions): void;
     static deleteFileAsync(filePath: string, options?: IFileSystemDeleteFileOptions): Promise<void>;
     static deleteFolder(folderPath: string): void;
@@ -345,8 +346,7 @@ export interface IFileSystemCreateLinkOptions {
 }
 
 // @public
-export interface IFileSystemCreateWriteStreamOptions {
-    ensureFolderExists?: boolean;
+export interface IFileSystemCreateWriteStreamOptions extends IFileSystemWriteFileOptionsBase {
 }
 
 // @public
@@ -355,9 +355,8 @@ export interface IFileSystemDeleteFileOptions {
 }
 
 // @public
-export interface IFileSystemMoveOptions {
+export interface IFileSystemMoveOptions extends IFileSystemWriteFileOptionsBase {
     destinationPath: string;
-    ensureFolderExists?: boolean;
     overwrite?: boolean;
     sourcePath: string;
 }
@@ -380,8 +379,7 @@ export interface IFileSystemUpdateTimeParameters {
 }
 
 // @public
-export interface IFileSystemWriteBinaryFileOptions {
-    ensureFolderExists?: boolean;
+export interface IFileSystemWriteBinaryFileOptions extends IFileSystemWriteFileOptionsBase {
 }
 
 // @public
@@ -390,6 +388,11 @@ export interface IFileSystemWriteFileOptions extends IFileSystemWriteBinaryFileO
     encoding?: Encoding;
 }
 
+// @public (undocumented)
+export interface IFileSystemWriteFileOptionsBase {
+    ensureFolderExists?: boolean;
+}
+
 // @public
 export interface IFileWriterFlags {
     append?: boolean;

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

@@ -62,17 +62,22 @@ export interface IFileSystemReadFolderOptions {
 }
 
 /**
- * The options for {@link FileSystem.writeBuffersToFile}
  * @public
  */
-export interface IFileSystemWriteBinaryFileOptions {
+export interface IFileSystemWriteFileOptionsBase {
   /**
    * If true, will ensure the folder is created before writing the file.
    * @defaultValue false
    */
   ensureFolderExists?: boolean;
 }
 
+/**
+ * The options for {@link FileSystem.writeBuffersToFile}
+ * @public
+ */
+export interface IFileSystemWriteBinaryFileOptions extends IFileSystemWriteFileOptionsBase {}
+
 /**
  * The options for {@link FileSystem.writeFile}
  * @public
@@ -113,7 +118,7 @@ export interface IFileSystemReadFileOptions {
  * The options for {@link FileSystem.move}
  * @public
  */
-export interface IFileSystemMoveOptions {
+export interface IFileSystemMoveOptions extends IFileSystemWriteFileOptionsBase {
   /**
    * The path of the existing object to be moved.
    * The path may be absolute or relative.
@@ -131,12 +136,6 @@ export interface IFileSystemMoveOptions {
    * @defaultValue true
    */
   overwrite?: boolean;
-
-  /**
-   * If true, will ensure the folder is created before writing the file.
-   * @defaultValue false
-   */
-  ensureFolderExists?: boolean;
 }
 
 /**
@@ -280,13 +279,7 @@ export interface IFileSystemCopyFilesOptions extends IFileSystemCopyFilesAsyncOp
  * 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;
-}
+export interface IFileSystemCreateWriteStreamOptions extends IFileSystemWriteFileOptionsBase {}
 
 /**
  * The options for {@link FileSystem.deleteFile}
@@ -780,10 +773,11 @@ export class FileSystem {
    * Writes a text string to a file on disk, overwriting the file if it already exists.
    * Behind the scenes it uses `fs.writeFileSync()`.
    * @remarks
-   * Throws an error if the folder doesn't exist, unless ensureFolder=true.
+   * Throws an error if the folder doesn't exist, unless {@link IFileSystemWriteFileOptionsBase.ensureFolderExists}
+   * is set to `true`.
    * @param filePath - The absolute or relative path of the file.
    * @param contents - The text that should be written to the file.
-   * @param options - Optional settings that can change the behavior. Type: `IWriteFileOptions`
+   * @param options - Optional settings that can change the behavior.
    */
   public static writeFile(
     filePath: string,
@@ -826,7 +820,8 @@ export class FileSystem {
    * multiple sources.
    *
    * @remarks
-   * Throws an error if the folder doesn't exist, unless ensureFolder=true.
+   * Throws an error if the folder doesn't exist, unless {@link IFileSystemWriteFileOptionsBase.ensureFolderExists}
+   * is set to `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.
@@ -986,10 +981,11 @@ export class FileSystem {
    * Writes a text string to a file on disk, appending to the file if it already exists.
    * Behind the scenes it uses `fs.appendFileSync()`.
    * @remarks
-   * Throws an error if the folder doesn't exist, unless ensureFolder=true.
+   * Throws an error if the folder doesn't exist, unless {@link IFileSystemWriteFileOptionsBase.ensureFolderExists}
+   * is set to `true`.
    * @param filePath - The absolute or relative path of the file.
    * @param contents - The text that should be written to the file.
-   * @param options - Optional settings that can change the behavior. Type: `IWriteFileOptions`
+   * @param options - Optional settings that can change the behavior.
    */
   public static appendToFile(
     filePath: string,
@@ -1283,7 +1279,7 @@ export class FileSystem {
    * Behind the scenes it uses `fs.createWriteStream()`.
    *
    * @remarks
-   * Throws an error if the folder doesn't exist, unless {@link IFileSystemCreateWriteStreamOptions.ensureFolderExists}
+   * Throws an error if the folder doesn't exist, unless {@link IFileSystemWriteFileOptionsBase.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.
@@ -1297,6 +1293,22 @@ export class FileSystem {
       const folderPath: string = nodeJsPath.dirname(filePath);
       FileSystem.ensureFolder(folderPath);
     }
+
+    return fs.createWriteStream(filePath);
+  }
+
+  /**
+   * An async version of {@link FileSystem.createWriteStream}.
+   */
+  public static async createWriteStreamAsync(
+    filePath: string,
+    options?: IFileSystemCreateWriteStreamOptions
+  ): Promise<FileSystemWriteStream> {
+    if (options?.ensureFolderExists) {
+      const folderPath: string = nodeJsPath.dirname(filePath);
+      await FileSystem.ensureFolderAsync(folderPath);
+    }
+
     return fs.createWriteStream(filePath);
   }
 

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

@@ -50,6 +50,7 @@ export { type IFileErrorOptions, type IFileErrorFormattingOptions, FileError } f
 export {
   AlreadyExistsBehavior,
   FileSystem,
+  type IFileSystemWriteFileOptionsBase,
   type FileSystemCopyFilesAsyncFilter,
   type FileSystemCopyFilesFilter,
   type FileSystemReadStream,