feat: add name property to RenameObject and allow RenameFunc to return RenameObject (#251)

Author: sapphi-red

.changeset/large-kings-show.md

@@ -0,0 +1,13 @@
+---
+'vite-plugin-static-copy': minor
+---
+
+Add `name` property to the `rename` object form and allow rename functions to return a `RenameObject`. The `name` property replaces the file's basename (filename + extension), and can be combined with `stripBase` to both flatten directory structure and rename the file in one step. Rename functions can now return `{ name, stripBase }` objects instead of only strings, making it easier to declaratively control output paths from dynamic rename logic.
+
+```js
+// node_modules/lib/dist/index.js → vendor/lib.js
+{ src: 'node_modules/lib/dist/index.js', dest: 'vendor', rename: { name: 'lib.js', stripBase: true } }
+
+// src/pages/events/test.html → dist/events/index.html
+{ src: 'src/pages/**/*.html', dest: 'dist/', rename: { stripBase: 2, name: 'index.html' } }
+```

src/options.ts

@@ -1,14 +1,20 @@
 import type { WatchOptions } from 'chokidar'
 
 type MaybePromise<T> = T | Promise<T>
+type WithRequiredSingleKey<T, K extends keyof T> = {
+  [P in K]-?: Required<T[P]>
+} & T
+
+type OptionalRenameObject = { stripBase?: number | true; name?: string }
+export type RenameObject =
+  | WithRequiredSingleKey<OptionalRenameObject, 'stripBase'>
+  | WithRequiredSingleKey<OptionalRenameObject, 'name'>
 
 export type RenameFunc = (
   fileName: string,
   fileExtension: string,
   fullPath: string,
-) => MaybePromise<string>
-
-export type RenameObject = { stripBase: number | true }
+) => MaybePromise<string | RenameObject>
 
 /**
  * @param content content of file
@@ -46,18 +52,23 @@ export type Target = {
   /**
    * Rename the output file.
    *
-   * When a string is provided, the matched file is renamed to that string.
+   * When a string is provided, it is a shorthand for `{ name: string }`.
    *
-   * When an object `{ stripBase: number | true }` is provided, the given number
-   * of leading directory segments from the matched path are stripped from the
-   * destination. When `true`, all directory segments are stripped (equivalent to
-   * flat copy).
+   * When an object is provided:
+   * - `name`: replaces the file's basename (filename + extension).
+   * - `stripBase`: the given number of leading directory segments from the matched
+   *   path are stripped from the destination. When `true`, all directory segments
+   *   are stripped (equivalent to flat copy).
+   * - When both are provided, `stripBase` is applied first, then `name` replaces
+   *   the basename.
    *
    * When a function is provided, it receives `(fileName, fileExtension, fullPath)`
-   * and should return the new file name.
-   * The returned value is joined with the resolved `dest` directory using
-   * `path.join`, so it can include path segments (e.g. `subdir/file.txt`) or
-   * `../` traversals to restructure the output.
+   * and should return the new file name or a `RenameObject`.
+   * When a string is returned, it is joined with the resolved `dest` directory
+   * using `path.join`, so it can include path segments (e.g. `subdir/file.txt`)
+   * or `../` traversals to restructure the output.
+   * When a `RenameObject` is returned, it is applied the same way as the object
+   * form above.
    *
    * @example
    * ```js
@@ -69,6 +80,11 @@ export type Target = {
    * { src: 'src/pages/**\/*.html', dest: 'dist/', rename: { stripBase: true } }
    * // Copies ../../src/pages/events/test.html to dist/test.html
    * { src: '../../src/pages/**\/*.html', dest: 'dist/', rename: { stripBase: true } }
+   * // Copies foo.txt to dist/newname.txt (name only)
+   * { src: 'foo.txt', dest: 'dist/', rename: { name: 'newname.txt' } }
+   * // Copies src/pages/events/test.html to dist/events/newname.txt (stripBase + name)
+   * { src: 'src/pages/**\/*.html', dest: 'dist/', rename: { stripBase: 2, name: 'newname.txt' } }
+   *
    * // Copies src/pages/events/test.html to dist/src/pages/events/test2.html
    * { src: 'src/pages/**\/*.html', dest: 'dist/', rename: (name, ext) => `${name}2.${ext}` }
    * // Copies src/pages/events/test.html to dist/pages/events/test.html

src/utils.ts

@@ -184,28 +184,50 @@ export const groupTargetsByDirectoryTree = <T extends { resolvedDest: string }>(
   return groups
 }
 
+function applyRenameObject(
+  renameObj: RenameObject,
+  target: string,
+  dir: string,
+): string {
+  let result = target
+  if ('stripBase' in renameObj && renameObj.stripBase !== undefined) {
+    const dirSegments = dir ? dir.split('/') : []
+    const goUp = '../'.repeat(dirSegments.length)
+    const stripCount =
+      renameObj.stripBase === true ? dirSegments.length : renameObj.stripBase
+    const remaining = dirSegments.slice(stripCount).join('/')
+    result = remaining ? `${goUp}${remaining}/${target}` : `${goUp}${target}`
+  }
+  if ('name' in renameObj && renameObj.name !== undefined) {
+    const parsed = path.parse(result)
+    result = path.join(parsed.dir, renameObj.name)
+  }
+  return result
+}
+
 async function renameTarget(
   target: string,
   rename: string | RenameObject | RenameFunc,
   src: string,
   dir: string,
 ): Promise<string> {
-  const parsedPath = path.parse(target)
-
   if (typeof rename === 'string') {
     return rename
   }
-
-  if (typeof rename === 'object' && 'stripBase' in rename) {
-    const dirSegments = dir ? dir.split('/') : []
-    const goUp = '../'.repeat(dirSegments.length)
-    const stripCount =
-      rename.stripBase === true ? dirSegments.length : rename.stripBase
-    const remaining = dirSegments.slice(stripCount).join('/')
-    return remaining ? `${goUp}${remaining}/${target}` : `${goUp}${target}`
+  if (typeof rename === 'object') {
+    return applyRenameObject(rename, target, dir)
   }
 
-  return rename(parsedPath.name, parsedPath.ext.replace('.', ''), src)
+  const parsedPath = path.parse(target)
+  const result = await rename(
+    parsedPath.name,
+    parsedPath.ext.replace('.', ''),
+    src,
+  )
+  if (typeof result === 'object') {
+    return applyRenameObject(result, target, dir)
+  }
+  return result
 }
 
 export const collectCopyTargets = async (

test/fixtures/vite.config.ts

@@ -223,6 +223,26 @@ export default defineConfig({
           dest: 'fixture23',
           rename: { stripBase: true },
         },
+        {
+          src: 'foo.txt',
+          dest: 'fixture24',
+          rename: { name: 'newname.txt' },
+        },
+        {
+          src: 'dir/bar.txt',
+          dest: 'fixture24',
+          rename: { stripBase: 1, name: 'newname2.txt' },
+        },
+        {
+          src: 'foo.txt',
+          dest: 'fixture24',
+          rename: () => ({ name: 'fn-renamed.txt' }),
+        },
+        {
+          src: 'dir/bar.txt',
+          dest: 'fixture24',
+          rename: () => ({ stripBase: 1 }),
+        },
       ],
     }),
     viteStaticCopy({

test/testcases.ts

@@ -247,6 +247,26 @@ export const testcases: Record<string, Testcase[]> = {
       src: './dir/deep/bar.txt',
       dest: '/fixture23/bar.txt',
     },
+    {
+      name: 'rename object with name only',
+      src: './foo.txt',
+      dest: '/fixture24/newname.txt',
+    },
+    {
+      name: 'rename object with stripBase and name',
+      src: './dir/bar.txt',
+      dest: '/fixture24/newname2.txt',
+    },
+    {
+      name: 'rename function returning object with name',
+      src: './foo.txt',
+      dest: '/fixture24/fn-renamed.txt',
+    },
+    {
+      name: 'rename function returning object with stripBase',
+      src: './dir/bar.txt',
+      dest: '/fixture24/bar.txt',
+    },
     {
       name: 'parallel copy to same dir (1)',
       src: './eexist/a/1.txt',