feat(fs/unstable): add truncate and truncateSync (#6416)

Author: jbronder

_tools/check_docs.ts

@@ -74,6 +74,7 @@ const ENTRY_POINTS = [
   "../fs/unstable_rename.ts",
   "../fs/unstable_stat.ts",
   "../fs/unstable_symlink.ts",
+  "../fs/unstable_truncate.ts",
   "../fs/unstable_types.ts",
   "../html/mod.ts",
   "../html/unstable_is_valid_custom_element_name.ts",

_tools/node_test_runner/run_test.mjs

@@ -59,6 +59,7 @@ import "../../fs/unstable_real_path_test.ts";
 import "../../fs/unstable_rename_test.ts";
 import "../../fs/unstable_stat_test.ts";
 import "../../fs/unstable_symlink_test.ts";
+import "../../fs/unstable_truncate_test.ts";
 import "../../fs/unstable_lstat_test.ts";
 import "../../fs/unstable_chmod_test.ts";
 

fs/deno.json

@@ -25,6 +25,7 @@
     "./unstable-rename": "./unstable_rename.ts",
     "./unstable-stat": "./unstable_stat.ts",
     "./unstable-symlink": "./unstable_symlink.ts",
+    "./unstable-truncate": "./unstable_truncate.ts",
     "./unstable-types": "./unstable_types.ts",
     "./walk": "./walk.ts"
   }

fs/unstable_truncate.ts

@@ -0,0 +1,91 @@
+// Copyright 2018-2025 the Deno authors. MIT license.
+
+import { getNodeFs, isDeno } from "./_utils.ts";
+import { mapError } from "./_map_error.ts";
+
+/**
+ * Truncates (or extends) the specified file, to reach the specified `len`. If
+ * `len` is not specified then the entire file contents are truncated.
+ *
+ * Requires `allow-write` permission.
+ *
+ * @example Truncate file to 0 bytes
+ * ```ts ignore
+ * import { truncate } from "@std/fs/unstable-truncate";
+ * await truncate("my_file.txt");
+ * ```
+ *
+ * @example Truncate part of a file
+ * ```ts ignore
+ * import { makeTempFile } from "@std/fs/unstable-make-temp-file";
+ * import { readFile } from "@std/fs/unstable-read-file";
+ * import { truncate } from "@std/fs/unstable-truncate";
+ * import { writeTextFile } from "@std/fs/unstable-write-text-file";
+ *
+ * const file = await makeTempFile();
+ * await writeTextFile(file, "Hello World");
+ * await truncate(file, 7);
+ * const data = await readFile(file);
+ * console.log(new TextDecoder().decode(data));  // "Hello W"
+ * ```
+ *
+ * @tags allow-write
+ *
+ * @param name The name/path to the file.
+ * @param len An optional value that sets the new size of the file. Omitting this argument sets the file size to 0 bytes.
+ */
+export async function truncate(name: string, len?: number): Promise<void> {
+  if (isDeno) {
+    await Deno.truncate(name, len);
+  } else {
+    try {
+      await getNodeFs().promises.truncate(name, len);
+    } catch (error) {
+      throw mapError(error);
+    }
+  }
+}
+
+/**
+ * Synchronously truncates (or extends) the specified file, to reach the
+ * specified `len`. If `len` is not specified then the entire file contents are
+ * truncated.
+ *
+ * Requires `allow-write` permission.
+ *
+ * @example Truncate file to 0 bytes
+ * ```ts ignore
+ * import { truncateSync } from "@std/fs/unstable-truncate";
+ * truncateSync("my_file.txt");
+ * ```
+ *
+ * @example Truncate part of a file
+ * ```ts ignore
+ * import { makeTempFileSync } from "@std/fs/unstable-make-temp-file";
+ * import { readFileSync } from "@std/fs/unstable-read-file";
+ * import { truncateSync } from "@std/fs/unstable-truncate";
+ * import { writeFileSync } from "@std/fs/unstable-write-file";
+ *
+ * const file = makeTempFileSync();
+ * writeFileSync(file, new TextEncoder().encode("Hello World"));
+ * truncateSync(file, 7);
+ * const data = readFileSync(file);
+ * console.log(new TextDecoder().decode(data));
+ * ```
+ *
+ * @tags allow-write
+ *
+ * @param name The name/path to the file.
+ * @param len An optional value that sets the new size of the file. Omitting this argument sets the file size to 0 bytes.
+ */
+export function truncateSync(name: string, len?: number): void {
+  if (isDeno) {
+    Deno.truncateSync(name, len);
+  } else {
+    try {
+      getNodeFs().truncateSync(name, len);
+    } catch (error) {
+      throw mapError(error);
+    }
+  }
+}

fs/unstable_truncate_test.ts

@@ -0,0 +1,93 @@
+// Copyright 2018-2025 the Deno authors. MIT license.
+
+import { assertEquals, assertRejects, assertThrows } from "@std/assert";
+import { truncate, truncateSync } from "./unstable_truncate.ts";
+import { NotFound } from "./unstable_errors.js";
+import { mkdtemp, readFile, rm, writeFile } from "node:fs/promises";
+import { mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { tmpdir } from "node:os";
+
+Deno.test("truncate() succeeds in truncating file sizes", async () => {
+  const tempDataDir = await mkdtemp(resolve(tmpdir(), "truncate_"));
+  const testFile = join(tempDataDir, "truncFile.txt");
+  await writeFile(testFile, "Hello, Standard Library");
+
+  await truncate(testFile, 30);
+  assertEquals((await readFile(testFile)).length, 30);
+  await truncate(testFile, 10);
+  assertEquals((await readFile(testFile)).length, 10);
+  await truncate(testFile, -5);
+  assertEquals((await readFile(testFile)).length, 0);
+
+  await rm(tempDataDir, { recursive: true, force: true });
+});
+
+Deno.test("truncate() truncates the file to zero when 'len' is not provided", async () => {
+  const tempDataDir = await mkdtemp(resolve(tmpdir(), "truncate_"));
+  const testFile = join(tempDataDir, "truncFile.txt");
+  await writeFile(testFile, "Hello, Standard Library");
+
+  await truncate(testFile);
+  assertEquals((await readFile(testFile)).length, 0);
+
+  await rm(tempDataDir, { recursive: true, force: true });
+});
+
+Deno.test("truncate() rejects with Error when passing a non-regular file", async () => {
+  const tempDataDir = await mkdtemp(resolve(tmpdir(), "truncate_"));
+
+  await assertRejects(async () => {
+    await truncate(tempDataDir);
+  }, Error);
+
+  await rm(tempDataDir, { recursive: true, force: true });
+});
+
+Deno.test("truncate() rejects with NotFound with a non-existent file", async () => {
+  await assertRejects(async () => {
+    await truncate("non-existent-file.txt");
+  }, NotFound);
+});
+
+Deno.test("truncateSync() succeeds in truncating file sizes", () => {
+  const tempDataDir = mkdtempSync(resolve(tmpdir(), "truncateSync_"));
+  const testFile = join(tempDataDir, "truncFile.txt");
+  writeFileSync(testFile, "Hello, Standard Library");
+
+  truncateSync(testFile, 30);
+  assertEquals((readFileSync(testFile)).length, 30);
+  truncateSync(testFile, 10);
+  assertEquals((readFileSync(testFile)).length, 10);
+  truncateSync(testFile, -5);
+  assertEquals((readFileSync(testFile)).length, 0);
+
+  rmSync(tempDataDir, { recursive: true, force: true });
+});
+
+Deno.test("truncateSync() truncates the file to zero when 'len' is not provided", () => {
+  const tempDataDir = mkdtempSync(resolve(tmpdir(), "truncateSync_"));
+  const testFile = join(tempDataDir, "truncFile.txt");
+  writeFileSync(testFile, "Hello, Standard Library");
+
+  truncateSync(testFile);
+  assertEquals((readFileSync(testFile)).length, 0);
+
+  rmSync(tempDataDir, { recursive: true, force: true });
+});
+
+Deno.test("truncateSync() throws with Error with a non-regular file", () => {
+  const tempDataDir = mkdtempSync(resolve(tmpdir(), "truncateSync_"));
+
+  assertThrows(() => {
+    truncateSync(tempDataDir);
+  }, Error);
+
+  rmSync(tempDataDir, { recursive: true, force: true });
+});
+
+Deno.test("truncateSync() throws with NotFound with a non-existent file", () => {
+  assertThrows(() => {
+    truncateSync("non-existent-file.txt");
+  }, NotFound);
+});