{"id":18389587,"url":"https://github.com/anseki/stats-filelist","last_synced_at":"2025-04-12T06:29:51.020Z","repository":{"id":57370243,"uuid":"44700799","full_name":"anseki/stats-filelist","owner":"anseki","description":"Get the list of files and directories with its `Stats`. And filter the list with evaluating path, path pattern, type, size, modified time, and more.","archived":false,"fork":false,"pushed_at":"2022-08-19T03:42:56.000Z","size":11,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-03-18T07:09:52.773Z","etag":null,"topics":["array","attribute","directory","directory-tree","exclude","extension","file","filter","find","fs-stats","include","list","modified-time","path","pattern","recursive","regexp","size","stats","type"],"latest_commit_sha":null,"homepage":null,"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/anseki.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}},"created_at":"2015-10-21T19:59:21.000Z","updated_at":"2022-03-16T03:51:00.000Z","dependencies_parsed_at":"2022-09-26T16:41:08.472Z","dependency_job_id":null,"html_url":"https://github.com/anseki/stats-filelist","commit_stats":null,"previous_names":[],"tags_count":4,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/anseki%2Fstats-filelist","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/anseki%2Fstats-filelist/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/anseki%2Fstats-filelist/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/anseki%2Fstats-filelist/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/anseki","download_url":"https://codeload.github.com/anseki/stats-filelist/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248528748,"owners_count":21119369,"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":["array","attribute","directory","directory-tree","exclude","extension","file","filter","find","fs-stats","include","list","modified-time","path","pattern","recursive","regexp","size","stats","type"],"created_at":"2024-11-06T01:43:50.744Z","updated_at":"2025-04-12T06:29:50.976Z","avatar_url":"https://github.com/anseki.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# statsFilelist\n\n[![npm](https://img.shields.io/npm/v/stats-filelist.svg)](https://www.npmjs.com/package/stats-filelist) [![GitHub issues](https://img.shields.io/github/issues/anseki/stats-filelist.svg)](https://github.com/anseki/stats-filelist/issues) [![dependencies](https://img.shields.io/badge/dependencies-No%20dependency-brightgreen.svg)](package.json) [![license](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)\n\nGet a list of files and directories with `Stats` of each item. And filter the list with evaluating path, path pattern, type, size, modified time, and more.\n\nBy default, statsFilelist gets all files and directories under specific directories recursively, and it returns an Array that includes the expanded [`fs.Stats`](https://nodejs.org/api/fs.html#fs_class_fs_stats) objects of each item.  \nThat expanded `fs.Stats` object has additional properties such as `fullPath`, `extension`, etc.. (See [`Stats` object](#stats-object).)  \nThe got `Stats` objects will be useful more than the path list because you are supposed to do something with those files or directories after getting those.\n\nIt returns the filtered list if you want. That filter evaluates that `Stats` object by using flexible ways such as RegExp, callback, etc..  \nAnd also, the filter can control the behavior of statsFilelist. For example, it make statsFilelist stop getting files any more when the file you want was found out.\n\n```js\nvar filelist = require('stats-filelist');\n\n// Asynchronous method:\nfilelist.get(['dir-1', 'dir-2'], function(list) {\n  console.log(list);\n}, /\\.js$/i); // Get JavaScript files.\n// `extension` property also can be used.\n\n// Synchronous method:\nvar list = filelist.getSync(['dir-1', 'dir-2'],\n  function(stats) { return stats.size \u003e 1024; }); // Get 1KB+ files.\nconsole.log(list);\n```\n\n## Methods\n\n### `get`, `getSync`\n\n```js\nfilelist.get(path, callback[, options])\n```\n\n```js\nfilelist.get(path, callback[, filter[, recursive]])\n```\n\n```js\nlist = filelist.getSync(path[, options])\n```\n\n```js\nlist = filelist.getSync(path[, filter[, recursive]])\n```\n\n`get` is asynchronous method, and `getSync` is synchronous method.\n\n`path` argument is a string as the path of target directory, or an Array that includes those of multiple target directories. The default value of `path` argument is `.` (i.e. current working directory).\n\n`callback` argument that is specified to `get` method is a function that is called with `list` Array when processing finished. That is same as `list` Array that is returned by `getSync` method.\n\nBy default, the `list` Array includes [`Stats` object](#stats-object)s. Also, what it includes can be specified via [`listOf`](#listof) option.\n\nFor example:\n\n```js\nconsole.log('File name: ' + list[3].name + ' Updated: ' + list[3].mtime);\n```\n\n`options` argument is an Object that has `filter` property, and more. (See [Options](#options).)  \n`filter` and `recursive` arguments are same as [`filter`](#filter) and [`recursive`](#options-recursive) option.  \nFor example, the following 2 codes work same:\n\n```js\nfilelist.get(path, callback, wanted);\n```\n\n```js\nfilelist.get(path, callback, { filter: wanted });\n```\n\n## Options\n\n`options` Object that is passed to the methods can have following properties:\n\n### `filter`\n\n*Type:* RegExp, string or function  \n*Default:* `undefined`\n\nBy default, the list statsFilelist returns includes all items under specific directories. This option decides whether the list includes each item.  \nThis can be one of following types:\n\n#### RegExp\n\nIf the full path of the current item matches this RegExp, that item is included to the list.\n\nFor example, the PNG files are listed ([`extension`](#extension) property of [`Stats` object](#stats-object) also can be used.):\n\n```js\nlist = filelist.getSync('./media', /\\.png$/i);\n```\n\nFor example, the files and directories except `debug.log` and `package.json` are listed:\n\n```js\nlist = filelist.getSync('./repo',\n  /^(?!.*[\\/\\\\](?:debug\\.log|package\\.json)$).+$/);\n```\n\nFor example, the files and directories except files starting with a dot are listed:\n\n```js\nlist = filelist.getSync('./project', /^(?!.*[\\/\\\\]\\.[^\\/\\\\]*$).+$/);\n```\n\nFor example, the files and directories under `css` directories are listed:\n\n```js\nlist = filelist.getSync('./websites', /[\\/\\\\]css[\\/\\\\]/i);\n```\n\n#### string\n\nIf the full path of the current item includes this string, that item is included to the list.  \n`/` and `\\` are replaced to the platform-specific file separator before this is used. In Windows, the string comparisons are case-insensitive (e.g. it  considers that `file.txt` is included in `FooFile.TXT`).\n\nFor example, the files and directories under `node_modules` directories are listed:\n\n```js\nlist = filelist.getSync('./dev', '/node_modules/');\n```\n\nFor example, the files and directories starting with a dot are listed:\n\n```js\nlist = filelist.getSync('./project', '/.');\n```\n\n#### function\n\nThis function decides whether the current item is included to the list, and also, it can control the behavior of statsFilelist.  \nIt is called with the [`Stats` object](#stats-object) of the current item.\n\n##### When it returns a boolean\n\n```js\ninclude = filter(stats)\n```\n\nIf this function returns a `true`, the current item is included to the list. If it returns a `false`, the current item is not included to the list.\n\nFor example, the directories are listed:\n\n```js\nlist = filelist.getSync(null, function(stats) {\n  return stats.isDirectory(); // Use `stats.isFile()` if you want files.\n});\n```\n\nFor example, the files and directories that were modified recently are listed:\n\n```js\nlist = filelist.getSync('./docs', function(stats) {\n  return stats.mtime \u003e yesterday;\n});\n```\n\nFor example, the `index.html` files are listed:\n\n```js\nlist = filelist.getSync('./public_html', function(stats) {\n  return stats.name === 'index.html';\n});\n```\n\n##### When it returns an Object\n\n```js\nobject = filter(stats)\n```\n\nIf this function returns an Object, the following properties of this Object decide whether the current item is included to the list, and it controls the behavior of statsFilelist:\n\n###### `include`\n\nIf `true` is specified to this property, the current item is included to the list. If `false` is specified to it, the current item is not included to the list.\n\nFor example, the files are listed:\n\n```js\nlist = filelist.getSync(null, function(stats) {\n  return {\n    include: stats.isFile()\n  };\n});\n```\n\n*If this Object has only `include` property, [that boolean can be returned](#when-it-returns-a-boolean) instead of this Object.*\n\n###### `exit`\n\nIf `true` is specified to this property, statsFilelist exits from current directory after processing of current item, and the remaining items in current directory are not processed.  \n*Note that the \"current directory\" means the parent directory of current item, it is not the directory current item points.*  \nThis is used to finish the method fast.\n\nFor example, it does not have to look for the file any more in that directory if it found out `public_html`, because any more `public_html` are clearly not existing under that directory tree:\n\n```js\nlist = filelist.getSync('./websites', function(stats) {\n  return stats.name === 'public_html' ? {\n      include: true,\n      exit: true\n    } : false; // Others are not listed.\n});\n```\n\n###### `stop`\n\nIf `true` is specified to this property, statsFilelist stops getting the items after processing of current item, and it returns the list that includes the items that were added until now, and the all remaining items are not processed.  \nThis is used to finish the method fast when you want to find out an only one file in the target path.\n\nFor example, it does not have to look for the file any more if it found out `foo.py`, because any more `foo.py` are clearly not existing under that project directory tree:\n\n```js\nlist = filelist.getSync('./project', function(stats) {\n  return stats.name === 'foo.py' ? {\n      include: true,\n      stop: true\n    } : false; // Others are not listed.\n});\n```\n\n###### \u003ca name=\"filter-recursive\"\u003e\u003c/a\u003e`recursive`\n\n*This is not [`recursive`](#options-recursive) option.*\n\nThis property overrides [`recursive`](#options-recursive) option temporarily.  \nWhen the current item is directory, if `true` is specified to this property, statsFilelist gets the items in that directory even if `false` is specified to `recursive` option. If `false` is specified to it, statsFilelist does not get the items in that directory even if `true` is specified to `recursive` option.  \nThis is used to finish the method fast.\n\nFor example, it does not have to list the files and directories in `node_modules` directory:\n\n```js\nlist = filelist.getSync('./websites', function(stats) {\n  return stats.name === 'node_modules' ? {\n      include: false,\n      recursive: false\n    } : true; // Others are listed.\n});\n```\n\n### \u003ca name=\"options-recursive\"\u003e\u003c/a\u003e`recursive`\n\n*Type:* boolean  \n*Default:* `true`\n\n*This is not [`recursive`](#filter-recursive) property of [`filter`](#filter) option.*\n\nBy default, statsFilelist gets all items under specific directories recursively. If `false` is specified to this property, statsFilelist does not get the items in the sub directories.  \nThis can be controlled on demand by [`recursive`](#filter-recursive) property of [`filter`](#filter) option.\n\n### `clearCache`\n\n*Type:* boolean  \n*Default:* `false`\n\nEver since it is loaded, statsFilelist caches the got [`Stats` object](#stats-object)s to finish the processing fast.  \nIf you want to clear the cache data to get the newest information such as modified time of the updated files, specify `true` to this option.\n\n### `listOf`\n\n*Type:* string  \n*Default:* `undefined`\n\nBy default, statsFilelist returns the list of [`Stats` object](#stats-object)s. If the name of property or method of `Stats` object is specified to this option, it returns the list of those values. That is value that was returned by specific method if the name of method is specified.\n\nFor example, the list of full paths of each file and directory is returned:\n\n```js\nlist = filelist.getSync(null, { listOf: 'fullPath' });\n```\n\n`list`:\n\n```js\n[\n  '/path/to/file-1',\n  '/path/to/file-2',\n  '/path/to/dir-1',\n  '/path/to/file-3'\n]\n```\n\nFor example, the list of names of each file and directory is returned:\n\n```js\nlist = filelist.getSync(null, { listOf: 'name' });\n```\n\n`list`:\n\n```js\n[\n  'file-1',\n  'file-2',\n  'dir-1',\n  'file-3'\n]\n```\n\nFor example, the list of booleans to indicate whether it is file (return value of `isFile` method) of each item is returned:\n\n```js\nlist = filelist.getSync(null, { listOf: 'isFile' });\n```\n\n`list`:\n\n```js\n[\n  true,\n  true,\n  false,\n  true\n]\n```\n\n## `Stats` object\n\nThe `Stats` object that is evaluated in filter and included to the list that is returned by statsFilelist by default is the expanded [`fs.Stats`](https://nodejs.org/api/fs.html#fs_class_fs_stats) object.  \nThis has native methods such as `isFile`, `isDirectory`, etc. and native properties such as `mode`, `size`, `mtime`, etc. and following additional properties:\n\n### `path`\n\nThe path of the item that was joined to specific target path.\n\n### `fullPath`\n\nThe full path of the item.\n\n### `dirPath`\n\nThe full path of the parent directory of the item.\n\n### `name`\n\nThe name of the item.\n\n### `extension`\n\nThe file extension of the item. This does not include `.` as separator.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fanseki%2Fstats-filelist","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fanseki%2Fstats-filelist","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fanseki%2Fstats-filelist/lists"}