{"id":23094192,"url":"https://github.com/kwooshung/files","last_synced_at":"2025-04-03T19:19:17.393Z","repository":{"id":216945302,"uuid":"742726704","full_name":"kwooshung/Files","owner":"kwooshung","description":"A convenient and efficient library for file operations.","archived":false,"fork":false,"pushed_at":"2024-02-18T00:02:31.000Z","size":236,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-03-30T18:01:44.480Z","etag":null,"topics":["file","file-node","files","files-node","filesystem","fs","node-file","node-files","node-fs"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","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/kwooshung.png","metadata":{"files":{"readme":"README.md","changelog":"changelogs/.history","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}},"created_at":"2024-01-13T07:16:43.000Z","updated_at":"2024-02-22T18:32:45.000Z","dependencies_parsed_at":"2025-02-09T07:23:20.139Z","dependency_job_id":"8bd5b312-5a99-4e0f-92ed-17a6d71b7801","html_url":"https://github.com/kwooshung/Files","commit_stats":null,"previous_names":["kwooshung/files"],"tags_count":10,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kwooshung%2FFiles","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kwooshung%2FFiles/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kwooshung%2FFiles/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kwooshung%2FFiles/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/kwooshung","download_url":"https://codeload.github.com/kwooshung/Files/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247061882,"owners_count":20877176,"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","file-node","files","files-node","filesystem","fs","node-file","node-files","node-fs"],"created_at":"2024-12-16T21:57:36.649Z","updated_at":"2025-04-03T19:19:17.364Z","avatar_url":"https://github.com/kwooshung.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\n\n# @kwooshung/files\n\n![GitHub Release Date - Published_At](https://img.shields.io/github/release-date/kwooshung/Files?labelColor=272e3b\u0026color=00b42A\u0026logo=github)\n![GitHub last commit](https://img.shields.io/github/last-commit/kwooshung/Files?labelColor=272e3b\u0026color=165dff)\n![GitHub code size in bytes](https://img.shields.io/github/languages/code-size/kwooshung/Files?labelColor=272e3b\u0026color=165dff)\n![GitHub top language](https://img.shields.io/github/languages/top/kwooshung/Files?labelColor=272e3b\u0026color=165dff)\n![GitHub pull requests](https://img.shields.io/github/issues-pr/kwooshung/Files?labelColor=272e3b\u0026color=165dff)\n![GitHub issues](https://img.shields.io/github/issues/kwooshung/files?labelColor=272e3b\u0026color=165dff)\n[![NPM Version](https://img.shields.io/npm/v/@kwooshung/files?labelColor=272e3b\u0026color=165dff)](https://www.npmjs.com/package/@kwooshung/files)\n[![Npm.js Downloads/Week](https://img.shields.io/npm/dw/@kwooshung/files?labelColor=272e3b\u0026labelColor=272e3b\u0026color=165dff\u0026logo=npm)](https://www.npmjs.com/package/@kwooshung/files)\n[![Github CI/CD](https://github.com/kwooshung/Files/actions/workflows/ci.yml/badge.svg)](https://github.com/kwooshung/Files/actions/)\n[![codecov](https://codecov.io/gh/kwooshung/Files/graph/badge.svg?token=VVZJE7H0KD)](https://codecov.io/gh/kwooshung/Files)\n[![Maintainability](https://api.codeclimate.com/v1/badges/4e51219d9c622f19fc96/maintainability)](https://codeclimate.com/github/kwooshung/Files/maintainability)\n[![GitHub License](https://img.shields.io/github/license/kwooshung/Files?labelColor=272e3b\u0026color=165dff)](LICENSE)\n[![Gitee Repo](https://img.shields.io/badge/gitee-files-165dff?logo=gitee)](https://gitee.com/kwooshung/Files/)\n![Github Stars](https://img.shields.io/github/stars/kwooshung/Files?labelColor=272e3b\u0026color=165dff)\n\n\u003cp align=\"center\"\u003e\n    \u003ca href=\"README.zh-CN.md\"\u003e中文\u003c/a\u003e | \n    \u003ca href=\"README.md\" style=\"font-weight:700;color:#165dff;text-decoration:underline;\"\u003eEnglish\u003c/a\u003e\n\u003c/p\u003e\n\u003c/div\u003e\n\n# Why Develop It?\n\n- There are many excellent file operation libraries in the community, but they were not quite suitable for me.\n- Developing a new wheel doesn't mean the existing ones are bad; it's just about creating something more suited to my needs. I'm not creating a wheel for the sake of it, but rather to have a wheel that fits my requirements better.\n- This project also utilizes some excellent community projects, such as [filehound](https://github.com/nspragg/filehound).\n- I found this tool quite useful in my daily development. It's simple to use, which is why I decided to open-source it, hoping it could help others.\n\n# Why Use It?\n\n- It's composed entirely of functions, making it easy to use.\n- All functions related to path operations are `normalized`, so you don't have to worry about the format of the paths.\n- As much as possible, recursion is avoided, which helps when dealing with a large number of files and prevents potential stack overflows.\n- You can import as needed; it supports `tree-shaking` as an `esm` module, so you don't need to worry about the size after packaging.\n- There is also a `commonjs` (`cjs`) version available for those using the `commonjs` specification.\n- All functions in this project are based on `fs/promises`.\n- There is only 1 third-party dependency, `hound`, which relies on [FileHound](https://github.com/nspragg/filehound) for file searching. If you don't need it, you can consider it as `0` third-party dependencies.\n\n# Install\n\n## npm\n\n```bash\nnpm install @kwooshung/files\n```\n\n## yarn\n\n```bash\nyarn add @kwooshung/files\n```\n\n## pnpm\n\n```bash\npnpm add @kwooshung/files\n```\n\n# Functions\n\n## [normalize](src/normalize/index.ts) Normalize Path\n\n```ts\nimport { normalize } from '@kwooshung/files';\n\nnormalize('a/b/c'); // a/b/c\nnormalize('a//b/////c'); // a/b/c\nnormalize('a\\\\b\\\\c'); // a/b/c\n```\n\n## [exists](src/exists/index.ts) Check if File or Directory Path Exists\n\n```ts\nimport { exists } from '@kwooshung/files';\n\nasync () =\u003e {\n  await exists('a/b/c'); // true\n};\n```\n\n## [exists/not](src/exists/not/index.ts) Check if File or Directory Path Does Not Exist\n\n```ts\nimport { notExists } from '@kwooshung/files';\n\nasync () =\u003e {\n  await notExists('a/b/c/aNotExists'); // true\n};\n```\n\n## [isFile](src/isFile/index.ts) Check if Path is a File\n\n```ts\nimport { isFile } from '@kwooshung/files';\n\nasync () =\u003e {\n  await isFile('a/b/c/test.txt'); // true\n};\n```\n\n## [isDir](src/isDir/index.ts) Check if Path is a Directory\n\n```ts\nimport { isDir } from '@kwooshung/files';\n\nasync () =\u003e {\n  await isDir('a/b/c'); // true\n};\n```\n\n## [makeDir](src/makeDir/index.ts) Create Directory\n\n```ts\nimport { makeDir } from '@kwooshung/files';\n\nasync () =\u003e {\n  await makeDir('a/b/c'); // Create a single directory\n  await makeDir(['a/b/c/1', 'd/e/f/2']); // Create multiple directories\n};\n```\n\n## [getDir](src/getDir/index.ts) Get Directory\n\n```ts\nimport { getDir } from '@kwooshung/files';\n\nasync () =\u003e {\n  await getDir('a/b/c'); // Returns an array of file or directory paths\n};\n```\n\n## [read](src/read/index.ts) Read File\n\n```ts\nimport { read } from '@kwooshung/files';\n\nasync () =\u003e {\n  await read('a/b/c/test.txt'); // Returns the file content, the encoding is utf8 by default\n  await read('a/b/c/test.txt', 'utf8'); // Returns the file content, specifying the encoding\n};\n```\n\n## [write](src/write/index.ts) Write to File\n\n- The third parameter has a default value of `{ append: false, overwrite: true, encoding: 'utf8' }`\n- If you are using `ts`, then the types of the third parameter `append` and `overwrite` are mutually exclusive, i.e.: when `append` is `true`, `overwrite` is `false`, and vice versa.\n\n```ts\nimport { write } from '@kwooshung/files';\n\nasync () =\u003e {\n  await write('a/b/c/test.txt', 'hello world'); // true\n\n  await write('a/b/c/test.txt', 'hello world', {\n    append: true, // Append\n    overwrite: false, // Not Overwrite\n    encoding: 'utf8' // Specify encoding\n  }); // true\n\n\n  await write('a/b/c/test.txt', 'hello world', {\n    append: false, // Not Append\n    overwrite: true // Overwrite, if the file does not exist, it will be created\n    encoding: 'utf8' // Specify encoding\n  }); // true\n\n  await write('a/b/c/test.txt', 'hello world', {\n    append: false, // Not Append\n    overwrite: true // Overwrite, if the file does not exist, it will be created\n  }); // true\n\n  await write('a/b/c/test.txt', 'hello world', {\n    encoding: 'binary' // Specify encoding\n  }); // true\n};\n```\n\n## [copy/file](src/copy/file/index.ts) Copy File\n\nAs long as no exception is thrown, the copy is successful, even if the target file already exists.\n\n```ts\nimport { copyFile } from '@kwooshung/files';\n\nasync () =\u003e {\n  await copyFile('a/b/c/1.txt', 'd/e/f/2.txt'); // 表示覆盖目标文件\n  await copyFile('a/b/c/1.txt', 'd/e/f/2.txt', false); // 即使目标文件已存在，虽然也不会覆盖，但是表示执行成功\n};\n```\n\n## [copy/dir](src/copy/dir/index.ts) Copy Directory\n\n- If no exception is thrown, it means the copy was successful, even if the target directory already exists.\n- If the target directory exists, it will merge with the source. Identical files will be overwritten, but you can pass `false` as the third argument to prevent overwriting.\n\n```ts\nimport { copyDir } from '@kwooshung/files';\n\nasync () =\u003e {\n  await copyDir('a/b/c', 'd/e/f');\n  await copyDir('a/b/c', 'd/e/f', false);\n};\n```\n\n## [move/file](src/move/file/index.ts) Move File\n\nMoving a file essentially copies the file and then deletes the source file. This approach ensures that if the move fails, the source file remains intact. It's a combination of `copy/file` and `remove`.\n\n```ts\nimport { moveFile } from '@kwooshung/files';\n\nasync () =\u003e {\n  await moveFile('a/b/c/1.txt', 'd/e/f/2.txt'); // 表示覆盖目标文件\n  await moveFile('a/b/c/1.txt', 'd/e/f/2.txt', false); // 即使目标文件已存在，虽然也不会覆盖，但是表示执行成功\n};\n```\n\n## [move/dir](src/move/dir/index.ts) Move Directory\n\nMoving a directory combines the functionalities of `copy/dir` and `remove`, thus it also follows the merging logic of `copy/dir`.\n\n```ts\nimport { moveDir } from '@kwooshung/files';\n\nasync () =\u003e {\n  await moveDir('a/b/c', 'd/e/f');\n  await moveDir('a/b/c', 'd/e/f', false);\n};\n```\n\n## [remove](src/remove/index.ts) Delete File or Directory\n\n```ts\nimport { remove } from '@kwooshung/files';\n\nasync () =\u003e {\n  await remove('a/b/c'); // Delete a single file or directory\n  await remove(['a/b/c/1', 'd/e/f/2']); // Delete multiple files or directories\n};\n```\n\n## [remove/emptyDirs](src/remove/emptyDirs/index.ts) Delete Empty Directories at a Specified Path\n\nThis will delete all empty directories under the specified path, including the path itself.\n\n```ts\nimport { removeEmptyDirs } from '@kwooshung/files';\n\nasync () =\u003e {\n  await removeEmptyDirs('a/b/c'); // Delete a single file or directory\n  await removeEmptyDirs(['a/b/c/1', 'd/e/f/2']); // Delete multiple files or directories\n};\n```\n\n## [size](src/size/index.ts) Get the Size of a Specified Path or Multiple Paths\n\n```ts\nimport { size } from '@kwooshung/files';\n\nasync () =\u003e {\n  await size('a/b/c'); // [{path: 'a/b/c', size: 1200;}]\n  await size(['a/b/c', 'd/e/f']); // [{path: 'a/b/c', size: 1200;}, {path: 'd/e/f', size: 2024;}]\n};\n```\n\n## [size/human](src/size/human/index.ts) Convert a Number to a Human-Readable Size\n\n```ts\nimport { sizeHuman } from '@kwooshung/files';\n\nsizeHuman(1024); // {size: '1.25', unit: 'KB'}\nsizeHuman(1024, 3); // {size: '1.234', unit: 'KB'}\n```\n\n## [size/unit](src/size/unit/index.ts) Convert the Size of Specified Paths to Human-Readable Format\n\nrecommended to use with [size](src/size/index.ts)\n\n```ts\nimport { sizeUnit } from '@kwooshung/files';\n\nasync () =\u003e {\n  await sizeUnit({path: 'a/b/c'; size: 1024;}); // [{path: 'a/b/c', size: '1200', unit: {size: '1.2', unit: 'KB'}}]\n  await sizeUnit([{path: 'a/b/c'; size: 1024;}, {path: 'd/e/f'; size: 2024;}]); // [{path: 'a/b/c', size: '1200', unit: {size: '1.2', unit: 'KB'}}, {path: 'd/e/f', size: '2024', unit: {size: '2.02', unit: 'KB'}}]\n};\n```\n\n## [hound](src/hound/index.ts) FileHound\n\n- A wrapper for [FileHound](https://github.com/nspragg/filehound), used for creating a new instance of [FileHound](https://github.com/nspragg/filehound);\n- Also features the capabilities of `FileHound.any`, which means: multiple `FileHound` instances can be passed in, and the results will be merged;\n\n```\nimport { hound } from '@kwooshung/files';\n\nconst fh1 = hound();\nfh1\n  .modified(\"\u003c 2 days\")\n  .find()\n  .each(console.log);\n\nconst fh2 = FileHound.create();\nfilehound\n  .addFilter(customFilter)\n  .find()\n  .each(console.log);\n\nhound(fh1, fh2);\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkwooshung%2Ffiles","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkwooshung%2Ffiles","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkwooshung%2Ffiles/lists"}