windows-like-renamer

⚠️ Package Renamed

This package has been renamed to awesome-renamer.

Please install the new package instead:

npm uninstall windows-like-renamer
npm install awesome-renamer

Rename files and directories with Windows Explorer-style numbered names, while validating names against Windows filename rules.

Features

• Renames files and directories asynchronously.
• Adds counters such as (2), (3), and so on.
• Avoids numbered-name collisions with items in the same directory.
• Removes invalid Windows filename characters or reports them as errors.
• Rejects empty names and Windows reserved names such as CON, AUX, and NUL.
• Includes TypeScript declarations and supports ESM and CommonJS.

Installation

npm install windows-like-renamer

Quick start

import { renameFileSameAsWindowsOS } from "windows-like-renamer";

const renamedTo = await renameFileSameAsWindowsOS(
  "C:/documents/draft.txt",
  "report.txt",
);

console.log(renamedTo); // "report.txt"

The file is renamed in its current directory. The returned value is the final filename, not its full path.

Usage

Rename a file

import { renameFileSameAsWindowsOS } from "windows-like-renamer";

const finalName = await renameFileSameAsWindowsOS(
  "C:/uploads/photo.jpg",
  "holiday.jpg",
);

console.log(finalName); // "holiday.jpg"

If holiday.jpg already exists, the package uses holiday (2).jpg. If that also exists, it tries holiday (3).jpg and continues increasing the counter until it finds an available name.

Return the absolute path

Set returnValue to "absolutePath" when you need the full destination path instead of only its filename:

import { renameFileSameAsWindowsOS } from "windows-like-renamer";

const finalPath = await renameFileSameAsWindowsOS(
  "C:/uploads/photo.jpg",
  "holiday.jpg",
  { returnValue: "absolutePath" },
);

console.log(finalPath); // "C:\\uploads\\holiday.jpg" on Windows

Rename a directory

import { renameFileSameAsWindowsOS } from "windows-like-renamer";

const finalName = await renameFileSameAsWindowsOS(
  "C:/projects/untitled-folder",
  "archive",
);

console.log(finalName); // "archive"

Handle invalid characters

By default, invalid Windows filename characters are removed:

import { renameFileSameAsWindowsOS } from "windows-like-renamer";

const finalName = await renameFileSameAsWindowsOS(
  "C:/documents/draft.txt",
  "report:final?.txt",
);

console.log(finalName); // "reportfinal.txt"

Pass "error" to reject the name instead:

await renameFileSameAsWindowsOS(
  "C:/documents/draft.txt",
  "report:final?.txt",
  { onInvalidChar: "error" },
);
// Throws: Filename contains invalid chars: ...

Validate a name without renaming anything

import { validateFileName } from "windows-like-renamer";

validateFileName("quarter:one?.pdf");
// => "quarterone.pdf"

validateFileName("quarter:one?.pdf", "error");
// Throws because the name contains invalid characters

This is useful for validating form input or previewing the sanitized name before performing a filesystem operation.

CommonJS

const {
  renameFileSameAsWindowsOS,
  validateFileName,
} = require("windows-like-renamer");

API

renameFileSameAsWindowsOS(oldFilePath, newName, options?)

Renames a file or directory and resolves with the final filename.

| Parameter | Type | Description | | --- | --- | --- | | oldFilePath | string | Path of the existing file or directory. | | newName | string | Requested name. It is validated before the rename. | | options | RenameOptions | Optional validation and return-value settings. |

Returns a Promise<string> containing either the final filename or its absolute path, according to options.returnValue.

Rename options

| Property | Type | Default | Description | | --- | --- | --- | --- | | onInvalidChar | "escape" \| "error" | "escape" | Remove invalid characters or throw an error. | | returnValue | "name" \| "absolutePath" | "name" | Choose whether the resolved value is the final filename or destination path. |

Options can be combined:

const finalPath = await renameFileSameAsWindowsOS(
  "C:/documents/draft.txt",
  "report:final?.txt",
  {
    onInvalidChar: "escape",
    returnValue: "absolutePath",
  },
);

Notes:

• If newName exactly matches the current basename, no filesystem rename is performed and that name is returned.
• A counter beginning at (2) is added when the requested name conflicts with an existing item.
• The original file extension is preserved. Pass a name compatible with that extension—for example, rename a .txt file with a name ending in .txt.
• Filesystem errors from Node.js, such as a missing source path or insufficient permissions, are passed through to the caller.

validateFileName(filename, onInvalidChar?)

Validates and optionally sanitizes a filename without accessing the filesystem.

| Parameter | Type | Description | | --- | --- | --- | | filename | string | Filename to validate. | | onInvalidChar | "escape" \| "error" | Optional. Defaults to "escape". |

Returns the validated string.

The following characters and control-character range are treated as invalid:

< > : " / \ | ? * and ASCII control characters 0x00-0x1F

The validator also rejects blank names and the reserved names CON, PRN, AUX, NUL, COM1–COM9, and LPT1–LPT9 (case-insensitive).

Use cases

• Reproducing Explorer-like numbered names in upload or document workflows.
• Preventing duplicate generated names in a directory.
• Sanitizing user-provided filenames before saving them.
• Renaming exported reports, downloaded assets, or generated media.
• Sharing filename-validation behavior between a UI and a Node.js backend.

Error handling

Because renaming touches the filesystem, wrap calls in try/catch when an error should be shown to a user or logged:

import { renameFileSameAsWindowsOS } from "windows-like-renamer";

try {
  const finalName = await renameFileSameAsWindowsOS(
    "C:/documents/draft.txt",
    "CON",
  );

  console.log(`Renamed to ${finalName}`);
} catch (error) {
  console.error("Could not rename the file:", error);
}

Testing

Run the API test suite with:

npm test

The tests cover filename validation, invalid-character errors, file and directory renaming, collision counters, and both return-value modes.

License

MIT