feat(fs/unstable): add writeTextFile and writeTextFileSync (denoland#6463)

Author: jbronder

_tools/check_docs.ts

@@ -82,6 +82,8 @@ const ENTRY_POINTS = [
   "../fs/unstable_types.ts",
   "../fs/unstable_umask.ts",
   "../fs/unstable_utime.ts",
+  "../fs/unstable_write_file.ts",
+  "../fs/unstable_write_text_file.ts",
   "../html/mod.ts",
   "../html/unstable_is_valid_custom_element_name.ts",
   "../http/mod.ts",

_tools/node_test_runner/run_test.mjs

@@ -63,6 +63,7 @@ import "../../fs/unstable_stat_test.ts";
 import "../../fs/unstable_symlink_test.ts";
 import "../../fs/unstable_truncate_test.ts";
 import "../../fs/unstable_write_file_test.ts";
+import "../../fs/unstable_write_text_file_test.ts";
 import "../../fs/unstable_lstat_test.ts";
 import "../../fs/unstable_chmod_test.ts";
 import "../../fs/unstable_umask_test.ts";

fs/deno.json

@@ -33,6 +33,7 @@
     "./unstable-types": "./unstable_types.ts",
     "./unstable-umask": "./unstable_umask.ts",
     "./unstable-write-file": "./unstable_write_file.ts",
+    "./unstable-write-text-file": "./unstable_write_text_file.ts",
     "./walk": "./walk.ts"
   }
 }

fs/unstable_write_text_file.ts

@@ -0,0 +1,103 @@
+// Copyright 2018-2025 the Deno authors. MIT license.
+
+import { getNodeFs, isDeno } from "./_utils.ts";
+import { getWriteFsFlag } from "./_get_fs_flag.ts";
+import { mapError } from "./_map_error.ts";
+import type { WriteFileOptions } from "./unstable_types.ts";
+
+/**
+ * Write string `data` to the given `path`, by default creating a new file if
+ * needed, else overwriting.
+ *
+ * Requires `allow-write` permission, and `allow-read` if `options.create` is
+ * `false`.
+ *
+ * @example Usage
+ * ```ts ignore
+ * import { writeTextFile } from "@std/fs/unstable-write-text-file";
+ * await writeTextFile("hello1.txt", "Hello world\n");  // overwrite "hello1.txt" or create it
+ * ```
+ *
+ * @tags allow-read, allow-write
+ *
+ * @param path The path of the file that `data` is written to.
+ * @param data A UTF-8 string or a stream of UTF-8 strings.
+ * @param options Options for writing files. See {@linkcode WriteFileOptions}.
+ */
+export async function writeTextFile(
+  path: string | URL,
+  data: string | ReadableStream<string>,
+  options?: WriteFileOptions,
+): Promise<void> {
+  if (isDeno) {
+    await Deno.writeTextFile(path, data, { ...options });
+  } else {
+    const {
+      append = false,
+      create = true,
+      createNew = false,
+      mode,
+      signal,
+    } = options ?? {};
+
+    const flag = getWriteFsFlag({ append, create, createNew });
+    try {
+      await getNodeFs().promises.writeFile(path, data, {
+        encoding: "utf-8",
+        flag,
+        signal,
+      });
+      if (mode != null) {
+        await getNodeFs().promises.chmod(path, mode);
+      }
+    } catch (error) {
+      throw mapError(error);
+    }
+  }
+}
+
+/**
+ * Synchronously write string `data` to the given `path`, by default creating
+ * a new file if needed, else overwriting.
+ *
+ * Requires `allow-write` permission, and `allow-read` if `options.create` is
+ * `false`.
+ *
+ * @example Usage
+ * ```ts ignore
+ * import { writeTextFileSync } from "@std/fs/unstable-write-text-file";
+ * writeTextFileSync("hello1.txt", "Hello world\n");  // overwrite "hello1.txt" or create it
+ * ```
+ *
+ * @tags allow-read, allow-write
+ *
+ * @param path The path of the file that `data` is written to.
+ * @param data A UTF-8 string.
+ * @param options Options for writing files. See {@linkcode WriteFileOptions}.
+ */
+export function writeTextFileSync(
+  path: string | URL,
+  data: string,
+  options?: WriteFileOptions,
+): void {
+  if (isDeno) {
+    Deno.writeTextFileSync(path, data, { ...options });
+  } else {
+    const {
+      append = false,
+      create = true,
+      createNew = false,
+      mode,
+    } = options ?? {};
+
+    const flag = getWriteFsFlag({ append, create, createNew });
+    try {
+      getNodeFs().writeFileSync(path, data, { encoding: "utf-8", flag });
+      if (mode != null) {
+        getNodeFs().chmodSync(path, mode);
+      }
+    } catch (error) {
+      throw mapError(error);
+    }
+  }
+}