{"id":28608227,"url":"https://github.com/vfile/vfile-rename","last_synced_at":"2025-06-11T21:40:39.485Z","repository":{"id":36462792,"uuid":"225352251","full_name":"vfile/vfile-rename","owner":"vfile","description":"utility to rename the path parts of a vfile","archived":false,"fork":false,"pushed_at":"2023-06-14T09:45:48.000Z","size":99,"stargazers_count":3,"open_issues_count":0,"forks_count":1,"subscribers_count":6,"default_branch":"main","last_synced_at":"2025-05-16T20:17:53.748Z","etag":null,"topics":["file","vfile","vfile-util","virtual"],"latest_commit_sha":null,"homepage":"https://unifiedjs.com","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/vfile.png","metadata":{"files":{"readme":"readme.md","changelog":null,"contributing":null,"funding":null,"license":"license","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null},"funding":{"github":"unifiedjs","open_collective":"unified"}},"created_at":"2019-12-02T10:55:03.000Z","updated_at":"2023-02-09T09:31:48.000Z","dependencies_parsed_at":"2024-06-20T23:28:56.706Z","dependency_job_id":"9e502329-75db-4b97-b800-e3c47b382751","html_url":"https://github.com/vfile/vfile-rename","commit_stats":null,"previous_names":[],"tags_count":9,"template":false,"template_full_name":null,"purl":"pkg:github/vfile/vfile-rename","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vfile%2Fvfile-rename","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vfile%2Fvfile-rename/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vfile%2Fvfile-rename/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vfile%2Fvfile-rename/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/vfile","download_url":"https://codeload.github.com/vfile/vfile-rename/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vfile%2Fvfile-rename/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":259346986,"owners_count":22843814,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["file","vfile","vfile-util","virtual"],"created_at":"2025-06-11T21:40:24.181Z","updated_at":"2025-06-11T21:40:39.478Z","avatar_url":"https://github.com/vfile.png","language":"JavaScript","funding_links":["https://github.com/sponsors/unifiedjs","https://opencollective.com/unified"],"categories":[],"sub_categories":[],"readme":"# vfile-rename\n\n[![Build][build-badge]][build]\n[![Coverage][coverage-badge]][coverage]\n[![Downloads][downloads-badge]][downloads]\n[![Size][size-badge]][size]\n[![Sponsors][sponsors-badge]][collective]\n[![Backers][backers-badge]][collective]\n[![Chat][chat-badge]][chat]\n\n[`vfile`][vfile] utility to rename a file.\n\n## Contents\n\n*   [What is this?](#what-is-this)\n*   [When should I use this?](#when-should-i-use-this)\n*   [Install](#install)\n*   [Use](#use)\n*   [API](#api)\n    *   [`convert(renames)`](#convertrenames)\n    *   [`rename(file, renames)`](#renamefile-renames)\n    *   [`Move`](#move)\n    *   [`Renames`](#renames)\n    *   [`Spec`](#spec)\n    *   [`SpecAffix`](#specaffix)\n*   [Types](#types)\n*   [Compatibility](#compatibility)\n*   [Security](#security)\n*   [Contribute](#contribute)\n*   [License](#license)\n\n## What is this?\n\nThis package is a utility to add different data-driven ways to rename files.\n\n## When should I use this?\n\nThis package is mostly useful when creating higher level tools that include\nsupport for renaming files to end users.\n\n## Install\n\nThis package is [ESM only][esm].\nIn Node.js (version 16+), install with [npm][]:\n\n```sh\nnpm install vfile-rename\n```\n\nIn Deno with [`esm.sh`][esmsh]:\n\n```js\nimport {rename} from 'https://esm.sh/vfile-rename@3'\n```\n\nIn browsers with [`esm.sh`][esmsh]:\n\n```html\n\u003cscript type=\"module\"\u003e\n  import {rename} from 'https://esm.sh/vfile-rename@3?bundle'\n\u003c/script\u003e\n```\n\n## Use\n\n```js\nimport {VFile} from 'vfile'\nimport {rename} from 'vfile-rename'\n\nconst file = new VFile({path: 'readme.md'})\nfile.path // =\u003e readme.md\n\n// Set extname:\nrename(file, '.html')\nfile.path // =\u003e readme.html\n\n// Set basename:\nrename(file, 'main.md')\nfile.path // =\u003e main.md\n\n// Set path properties:\nrename(file, {stem: 'index'})\nfile.path // =\u003e index.md\n\n// Change path properties:\nrename(file, {stem: {suffix: '.bak'}})\nfile.path // =\u003e index.bak.md\n\n// All together:\nrename(file, ['readme.md', '.htm', {stem: 'index', extname: {suffix: 'l'}}])\nfile.path // =\u003e index.html\n```\n\n## API\n\nThis package exports the identifiers [`convert`][api-convert] and\n[`rename`][api-rename].\nThere is no default export.\n\n### `convert(renames)`\n\nCreate a function (the move) from `renames`, that when given a file changes\nits path properties.\n\n###### Parameters\n\n*   `renames` ([`Renames`][api-renames], optional)\n    — rename instructions\n\n###### Returns\n\nA move ([`Move`][api-move]).\n\n### `rename(file, renames)`\n\nRename a file.\n\nWhen given something, returns a vfile from that, and changes its path\nproperties.\n\n###### Parameters\n\n*   `file` (`VFile`)\n    — file to rename\n*   `renames` ([`Renames`][api-renames], optional)\n    — rename instructions\n\n###### Returns\n\nNothing (`undefined`).\n\n### `Move`\n\nMove (TypeScript type).\n\n###### Parameters\n\n*   `file` ([`VFile`][vfile])\n    — file to change\n\n###### Returns\n\nNothing (`undefined`).\n\n### `Renames`\n\nRename instructions (TypeScript type).\n\n*   if the bound rename is a normal string starting with a dot (`.`), sets\n    `file.extname`\n*   otherwise, if the bound rename is a normal string, sets `file.basename`\n*   otherwise, if the bound test is an array, all renames in it are\n    performed\n*   otherwise, if the bound rename is an object, renames according to the\n    [`Spec`][api-spec]\n\n###### Type\n\n```ts\ntype Renames = Array\u003cMove | Spec | string\u003e | Move | Spec | string\n```\n\n### `Spec`\n\nAn object describing path properties to values (TypeScript type).\n\nFor each property in spec, if its value is string, the value of the path\nproperty on the given file is set.\nIf the value is object, it can have a prefix or suffix key, the value of\nthe path property on the given file is prefixed and/or suffixed.\n\n###### Fields\n\n*   `basename` ([`SpecAffix`][api-spec-affix] or `string`, optional)\n    — change basename (`'index.min.js'`).\n*   `dirname` ([`SpecAffix`][api-spec-affix] or `string`, optional)\n    — change dirname (`'~'`).\n*   `extname` ([`SpecAffix`][api-spec-affix] or `string`, optional)\n    — change extname (`'.js'`).\n*   `path` ([`SpecAffix`][api-spec-affix], `URL`, or `string`, optional)\n    — change file path (`'~/index.min.js'`).\n*   `stem` ([`SpecAffix`][api-spec-affix] or `string`, optional)\n    — change stem (`'index.min'`).\n\n### `SpecAffix`\n\nDefine prepending and/or appending (TypeScript type).\n\n###### Fields\n\n*   `prefix` (`string`, optional)\n    — substring to prepend before the field\n*   `suffix` (`string`, optional)\n    — substring to append after the field.\n\n## Types\n\nThis package is fully typed with [TypeScript][].\nIt exports the types [`Move`][api-move], [`Renames`][api-renames],\n[`Spec`][api-spec], and [`SpecAffix`][api-spec-affix].\n\n## Compatibility\n\nProjects maintained by the unified collective are compatible with maintained\nversions of Node.js.\n\nWhen we cut a new major release, we drop support for unmaintained versions of\nNode.\nThis means we try to keep the current release line, `vfile-rename@^3`,\ncompatible with Node.js 16.\n\n## Security\n\nUse of `vfile-rename` is safe.\n\n## Contribute\n\nSee [`contributing.md`][contributing] in [`vfile/.github`][health] for ways to\nget started.\nSee [`support.md`][support] for ways to get help.\n\nThis project has a [code of conduct][coc].\nBy interacting with this repository, organization, or community you agree to\nabide by its terms.\n\n## License\n\n[MIT][license] © [Titus Wormer][author]\n\n\u003c!-- Definitions --\u003e\n\n[build-badge]: https://github.com/vfile/vfile-rename/workflows/main/badge.svg\n\n[build]: https://github.com/vfile/vfile-rename/actions\n\n[coverage-badge]: https://img.shields.io/codecov/c/github/vfile/vfile-rename.svg\n\n[coverage]: https://codecov.io/github/vfile/vfile-rename\n\n[downloads-badge]: https://img.shields.io/npm/dm/vfile-rename.svg\n\n[downloads]: https://www.npmjs.com/package/vfile-rename\n\n[size-badge]: https://img.shields.io/badge/dynamic/json?label=minzipped%20size\u0026query=$.size.compressedSize\u0026url=https://deno.bundlejs.com/?q=vfile-rename\n\n[size]: https://bundlejs.com/?q=vfile-rename\n\n[sponsors-badge]: https://opencollective.com/unified/sponsors/badge.svg\n\n[backers-badge]: https://opencollective.com/unified/backers/badge.svg\n\n[collective]: https://opencollective.com/unified\n\n[chat-badge]: https://img.shields.io/badge/chat-discussions-success.svg\n\n[chat]: https://github.com/vfile/vfile/discussions\n\n[npm]: https://docs.npmjs.com/cli/install\n\n[esm]: https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c\n\n[esmsh]: https://esm.sh\n\n[typescript]: https://www.typescriptlang.org\n\n[contributing]: https://github.com/vfile/.github/blob/main/contributing.md\n\n[support]: https://github.com/vfile/.github/blob/main/support.md\n\n[health]: https://github.com/vfile/.github\n\n[coc]: https://github.com/vfile/.github/blob/main/code-of-conduct.md\n\n[license]: license\n\n[author]: https://wooorm.com\n\n[vfile]: https://github.com/vfile/vfile\n\n[api-convert]: #convertrenames\n\n[api-rename]: #renamefile-renames\n\n[api-move]: #move\n\n[api-renames]: #renames\n\n[api-spec]: #spec\n\n[api-spec-affix]: #specaffix\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvfile%2Fvfile-rename","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fvfile%2Fvfile-rename","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvfile%2Fvfile-rename/lists"}