{"_id":"@cjser/unused-filename","name":"@cjser/unused-filename","dist-tags":{"latest":"4.0.1-cjser.2"},"versions":{"4.0.1-cjser.2":{"name":"@cjser/unused-filename","version":"4.0.1-cjser.2","description":"Get an unused filename by appending a number if it exists: `file.txt` → `file (1).txt`","license":"MIT","repository":{"type":"git","url":"https://code.moenext.com/3rdeye/cjser.git"},"funding":"https://github.com/sponsors/sindresorhus","author":{"name":"Sindre Sorhus","email":"sindresorhus@gmail.com","url":"https://sindresorhus.com"},"type":"module","exports":{"require":"./dist-cjser/index.cjs","default":"./index.js"},"engines":{"node":"^12.20.0 || ^14.13.1 || >=16.0.0"},"scripts":{"test":"xo && ava && tsd"},"keywords":["unused","filename","filepath","file","name","available","safe","unique","usable","filesystem","fs","exists","path"],"dependencies":{"@cjser/escape-string-regexp":"5.0.0-cjser.2","@cjser/path-exists":"5.0.0-cjser.2"},"devDependencies":{"ava":"^3.15.0","tsd":"^0.19.0","xo":"^0.46.4"},"main":"./dist-cjser/index.cjs","cjser":{"sourceVersion":"4.0.1","cjserVersion":2,"original":{"name":"unused-filename","version":"4.0.1","exports":"./index.js","repository":"sindresorhus/unused-filename","dependencies":{"escape-string-regexp":"^5.0.0","path-exists":"^5.0.0"},"files":["index.js","index.d.ts"],"scripts":{"test":"xo && ava && tsd"}}},"_id":"@cjser/unused-filename@4.0.1-cjser.2","gitHead":"a4bef54d7d22d3d9a6b84528457938d84cd65fe7","_nodeVersion":"20.14.0","_npmVersion":"10.7.0","dist":{"integrity":"sha512-kz1mxLXXgjkE95FJrRGuVwkh7QnGuElRYGfB2X58aC4cR9ultJo4OuNLNoj5Qh1CKjdAcXzDPGfoBj22dDLAIQ==","shasum":"4419c4ad8dc91a17d503db711b1f12941163d9a4","tarball":"https://registry.npmjs.org/@cjser/unused-filename/-/unused-filename-4.0.1-cjser.2.tgz","fileCount":6,"unpackedSize":18281,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEYCIQCFw+PEVU7nA2cmRQt3Gt/QSLHPcfZ6G9H5fmgF/dLEpQIhAIH5sotKJQzRD4JGED3dv6BMVxtFKeKuY+MyZNo2yN8q"}]},"_npmUser":{"name":"nanahira","email":"nanahira@momobako.com"},"directories":{},"maintainers":[{"name":"nanahira","email":"nanahira@momobako.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/unused-filename_4.0.1-cjser.2_1778160537164_0.7931005813377103"},"_hasShrinkwrap":false}},"time":{"created":"2026-05-07T13:28:57.056Z","4.0.1-cjser.2":"2026-05-07T13:28:57.298Z","modified":"2026-05-07T13:28:57.531Z"},"maintainers":[{"name":"nanahira","email":"nanahira@momobako.com"}],"description":"Get an unused filename by appending a number if it exists: `file.txt` → `file (1).txt`","keywords":["unused","filename","filepath","file","name","available","safe","unique","usable","filesystem","fs","exists","path"],"repository":{"type":"git","url":"https://code.moenext.com/3rdeye/cjser.git"},"author":{"name":"Sindre Sorhus","email":"sindresorhus@gmail.com","url":"https://sindresorhus.com"},"license":"MIT","readme":"# unused-filename\n\n> Get an unused filename by appending a number if it exists: `file.txt` → `file (1).txt`\n\nUseful for safely writing, copying, moving files without overwriting existing files.\n\n## Install\n\n```sh\nnpm install unused-filename\n```\n\n## Usage\n\n```\n.\n├── rainbow (1).txt\n├── rainbow.txt\n└── unicorn.txt\n```\n\n```js\nimport {unusedFilename} from 'unused-filename';\n\nconsole.log(await unusedFilename('rainbow.txt'));\n//=> 'rainbow (2).txt'\n```\n\n## API\n\n### unusedFilename(filePath, options?)\n\nReturns a `Promise<string>` containing either the original `filename` or the `filename` increment by `options.incrementer`.\n\nIf an already incremented `filePath` is passed, `unusedFilename` will simply increment and replace the already existing index:\n\n```js\nimport {unusedFilename} from 'unused-filename';\n\nconsole.log(await unusedFilename('rainbow (1).txt'));\n//=> 'rainbow (2).txt'\n```\n\n### unusedFilenameSync(filePath, options?)\n\nSynchronous version of `unusedFilename`.\n\n#### filePath\n\nType: `string`\n\nThe path to check for filename collision.\n\n#### options\n\nType: `object`\n\n##### incrementer\n\nType: `(filePath: string) => [string, string]`\\\nDefault: Parentheses incrementer: `file.txt` → `file (1).txt`\n\nA function that accepts a file path, and increments its index.\n\nIt's the incrementer's responsibility to extract an already existing index from the given file path so that it picks up and continues incrementing an already present index instead of appending a second one.\n\nThe incrementer has to return a tuple of `[originalFilename, incrementedFilename]`, where `originalFilename` is the filename without the index, and `incrementedFilename` is a filename with input's index bumped by one.\n\n```js\nimport {unusedFilename} from 'unused-filename';\n\n// Incrementer that inserts a new index as a prefix.\nconst prefixIncrementer = (filename, extension) => {\n\tconst match = filename.match(/^(?<index>\\d+)_(?<originalFilename>.*)$/);\n\tlet {originalFilename, index} = match ? match.groups : {originalFilename: filename, index: 0};\n\toriginalFilename = originalFilename.trim();\n\treturn [`${originalFilename}${extension}`, `${++index}_${originalFilename}${extension}`];\n};\n\nconsole.log(await unusedFilename('rainbow.txt', {incrementer: prefixIncrementer}));\n//=> '1_rainbow.txt'\n```\n\n##### maxTries\n\nType: `number`\\\nDefault: `Infinity`\n\nThe maximum number of attempts to find an unused filename.\n\nWhen the limit is reached, the function will throw `MaxTryError`.\n\n### separatorIncrementer\n\nCreates an incrementer that appends a number after a separator.\n\n`separatorIncrementer('_')` will increment `file.txt` → `file_1.txt`.\n\nNot all characters can be used as separators:\n- On Unix-like systems, `/` is reserved.\n- On Windows, `<>:\"/|?*` along with trailing periods are reserved.\n\n```js\nimport {unusedFilename, separatorIncrementer} from 'unused-filename';\n\nconsole.log(await unusedFilename('rainbow.txt', {incrementer: separatorIncrementer('_')}));\n//=> 'rainbow_1.txt'\n```\n\n### MaxTryError\n\nThe error thrown when `maxTries` limit is reached without finding an unused filename.\n\nIt comes with 2 custom properties:\n\n- `originalPath` - Path without incrementation sequence.\n- `lastTriedPath` - The last tested incremented path.\n\nExample:\n\n```js\nimport {unusedFilename, MaxTryError} from 'unused-filename';\n\ntry {\n\tconst path = await unusedFilename('rainbow (1).txt', {maxTries: 0});\n} catch (error) {\n\tif (error instanceof MaxTryError) {\n\t\tconsole.log(error.originalPath); // 'rainbow.txt'\n\t\tconsole.log(error.lastTriedPath); // 'rainbow (1).txt'\n\t}\n}\n```\n\n## Related\n\n- [filenamify](https://github.com/sindresorhus/filenamify) - Convert a string to a valid safe filename\n\n## cjser\n\nThis package is a CommonJS-compatible build generated by cjser for projects that still need `require()` support. The source version matches the original npm package version, with a cjser prerelease suffix for this generated build.\nOriginal repository: https://github.com/sindresorhus/unused-filename\n","readmeFilename":"readme.md","_rev":"1-4712068e1fc6a4c19f60287b182dfc98"}