feat(fs/unstable): add renameSync (denoland#6396)

Author: jbronder

fs/unstable_rename.ts

@@ -42,3 +42,39 @@ export async function rename(
     }
   }
 }
+
+/**
+ * Synchronously renames (moves) `oldpath` to `newpath`. Paths may be files or
+ * directories. If `newpath` already exists and is not a directory,
+ * `renameSync()` replaces it. OS-specific restrictions may apply when
+ * `oldpath` and `newpath` are in different directories.
+ *
+ * On Unix-like OSes, this operation does not follow symlinks at either path.
+ *
+ * It varies between platforms when the operation throws errors, and if so what
+ * they are. It's always an error to rename anything to a non-empty directory.
+ *
+ * Requires `allow-read` and `allow-write` permissions.
+ *
+ * @example Usage
+ * ```ts ignore
+ * import { renameSync } from "@std/fs/unstable-rename";
+ * renameSync("old/path", "new/path");
+ * ```
+ *
+ * @tags allow-read, allow-write
+ *
+ * @param oldpath The current name/path of the file/directory.
+ * @param newpath The updated name/path of the file/directory.
+ */
+export function renameSync(oldpath: string | URL, newpath: string | URL): void {
+  if (isDeno) {
+    Deno.renameSync(oldpath, newpath);
+  } else {
+    try {
+      getNodeFs().renameSync(oldpath, newpath);
+    } catch (error) {
+      throw mapError(error);
+    }
+  }
+}

fs/unstable_rename_test.ts

@@ -1,12 +1,21 @@
 // Copyright 2018-2025 the Deno authors. MIT license.
 
-import { assert, assertRejects } from "@std/assert";
-import { rename } from "./unstable_rename.ts";
+import { assert, assertRejects, assertThrows } from "@std/assert";
+import { rename, renameSync } from "./unstable_rename.ts";
 import { NotFound } from "./unstable_errors.js";
-import { lstatSync } from "node:fs";
 import { mkdir, mkdtemp, open, rm, stat, symlink } from "node:fs/promises";
 import { platform, tmpdir } from "node:os";
 import { join, resolve } from "node:path";
+import {
+  closeSync,
+  lstatSync,
+  mkdirSync,
+  mkdtempSync,
+  openSync,
+  rmSync,
+  statSync,
+  symlinkSync,
+} from "node:fs";
 
 /** Tests if the original file/directory is missing since the file is renamed.
  * Uses Node.js Error instances to check because the `lstatSync` function is
@@ -191,3 +200,182 @@ Deno.test("rename() rejects with NotFound for renaming a non-existent file", asy
     await rename("non-existent-file.txt", "new-name.txt");
   }, NotFound);
 });
+
+Deno.test("renameSync() renames a regular file", () => {
+  const tempDirPath = mkdtempSync(resolve(tmpdir(), "renameSync_"));
+  const testFile = join(tempDirPath, "testFile.txt");
+  const renameFile = join(tempDirPath, "renamedFile.txt");
+
+  const testFd = openSync(testFile, "w");
+  closeSync(testFd);
+
+  renameSync(testFile, renameFile);
+  assertMissing(testFile);
+  const renameFileStat = statSync(renameFile);
+  assert(renameFileStat.isFile);
+
+  rmSync(tempDirPath, { recursive: true, force: true });
+});
+
+Deno.test("renameSync() throws with Error when an existing regular file is renamed with an existing directory path", () => {
+  const tempDirPath = mkdtempSync(resolve(tmpdir(), "renameSync_"));
+  const testFile = join(tempDirPath, "testFile.txt");
+  const testDir = join(tempDirPath, "testDir");
+
+  const testFd = openSync(testFile, "w");
+  closeSync(testFd);
+  mkdirSync(testDir);
+
+  assertThrows(() => {
+    renameSync(testFile, testDir);
+  }, Error);
+});
+
+Deno.test("renameSync() throws with Error when an existing file path is renamed with an existing directory path", () => {
+  const tempDirPath = mkdtempSync(resolve(tmpdir(), "renameSync_"));
+  const testFile = join(tempDirPath, "testFile.txt");
+  const testDir = join(tempDirPath, "testDir");
+
+  const testFd = openSync(testFile, "w");
+  closeSync(testFd);
+  mkdirSync(testDir);
+
+  assertThrows(() => {
+    renameSync(testFile, testDir);
+  }, Error);
+
+  rmSync(tempDirPath, { recursive: true, force: true });
+});
+
+Deno.test("renameSync() throws with Error when an existing directory is renamed with an existing directory containing a file", () => {
+  const tempDirPath = mkdtempSync(resolve(tmpdir(), "renameSync_"));
+  const emptyDir = join(tempDirPath, "emptyDir");
+  const fullDir = join(tempDirPath, "fullDir");
+  const testFile = join(fullDir, "testFile.txt");
+
+  mkdirSync(fullDir);
+  mkdirSync(emptyDir);
+  const testFd = openSync(testFile, "w");
+  closeSync(testFd);
+
+  assertThrows(() => {
+    renameSync(emptyDir, fullDir);
+  }, Error);
+
+  rmSync(tempDirPath, { recursive: true, force: true });
+});
+
+Deno.test("renameSync() throws with Error on Windows and succeeds on *nix when an existing directory is renamed with another directory path", () => {
+  const tempDirPath = mkdtempSync(resolve(tmpdir(), "renameSync_"));
+  const testDir = join(tempDirPath, "testDir");
+  const anotherDir = join(tempDirPath, "anotherDir");
+
+  mkdirSync(testDir);
+  mkdirSync(anotherDir);
+
+  if (platform() === "win32") {
+    assertThrows(() => {
+      renameSync(testDir, anotherDir);
+    }, Error);
+  } else {
+    renameSync(testDir, anotherDir);
+    assertMissing(testDir);
+    const anotherDirStat = statSync(anotherDir);
+    assert(anotherDirStat.isDirectory());
+  }
+
+  rmSync(tempDirPath, { recursive: true, force: true });
+});
+
+Deno.test("renameSync() throws with Error on *nix and succeeds on Windows when an existing directory is renamed with an existing regular file path", () => {
+  const tempDirPath = mkdtempSync(resolve(tmpdir(), "renameSync_"));
+  const testFile = join(tempDirPath, "testFile.txt");
+  const testDir = join(tempDirPath, "testDir");
+
+  const testFd = openSync(testFile, "w");
+  closeSync(testFd);
+  mkdirSync(testDir);
+
+  if (platform() === "win32") {
+    renameSync(testDir, testFile);
+    const fileStat = statSync(testFile);
+    assert(fileStat.isDirectory());
+  } else {
+    assertThrows(() => {
+      renameSync(testDir, testFile);
+    }, Error);
+  }
+
+  rmSync(tempDirPath, { recursive: true, force: true });
+});
+
+Deno.test({
+  name:
+    "renameSync() throws with Error when renaming an existing directory with a valid symlink'd regular file path",
+  ignore: platform() === "win32",
+  fn: () => {
+    const tempDirPath = mkdtempSync(resolve(tmpdir(), "renameSync_"));
+    const testDir = join(tempDirPath, "testDir");
+    const testFile = join(tempDirPath, "testFile.txt");
+    const symlinkFile = join(tempDirPath, "testFile.txt.link");
+
+    mkdirSync(testDir);
+    const testFd = openSync(testFile, "w");
+    closeSync(testFd);
+    symlinkSync(testFile, symlinkFile);
+
+    assertThrows(() => {
+      renameSync(testDir, symlinkFile);
+    }, Error);
+
+    rmSync(tempDirPath, { recursive: true, force: true });
+  },
+});
+
+Deno.test({
+  name:
+    "renameSync() throws with Error when renaming an existing directory with a valid symlink'd directory path",
+  ignore: platform() === "win32",
+  fn: () => {
+    const tempDirPath = mkdtempSync(resolve(tmpdir(), "renameSync_"));
+    const testDir = join(tempDirPath, "testDir");
+    const anotherDir = join(tempDirPath, "anotherDir");
+    const symlinkDir = join(tempDirPath, "symlinkDir");
+
+    mkdirSync(testDir);
+    mkdirSync(anotherDir);
+    symlinkSync(anotherDir, symlinkDir);
+
+    assertThrows(() => {
+      renameSync(testDir, symlinkDir);
+    }, Error);
+
+    rmSync(tempDirPath, { recursive: true, force: true });
+  },
+});
+
+Deno.test({
+  name:
+    "rename() rejects with Error when renaming an existing directory with a symlink'd file pointing to a non-existent file path",
+  ignore: platform() === "win32",
+  fn: () => {
+    const tempDirPath = mkdtempSync(resolve(tmpdir(), "renameSync_"));
+    const testDir = join(tempDirPath, "testDir");
+    const symlinkPath = join(tempDirPath, "symlinkPath");
+
+    mkdirSync(testDir);
+    symlinkSync("non-existent", symlinkPath);
+
+    assertThrows(() => {
+      renameSync(testDir, symlinkPath);
+    }, Error);
+
+    rmSync(tempDirPath, { recursive: true, force: true });
+  },
+});
+
+Deno.test("renameSync() throws with NotFound for renaming a non-existent file", () => {
+  assertThrows(() => {
+    renameSync("non-existent-file.txt", "new-name.txt");
+  }, NotFound);
+});