fast-glob
Advanced tools
Package description
The fast-glob package is a Node.js library that provides a fast and efficient way to match file paths against specified patterns. It uses the glob syntax, which is a way of filtering files in file systems using wildcard characters.
Synchronous file searching
This feature allows you to perform synchronous file searches, returning an array of paths that match the specified patterns. The example code searches for all files except markdown files.
const fg = require('fast-glob');
const paths = fg.sync(['**/*', '!**/*.md']);Asynchronous file searching
This feature allows you to perform asynchronous file searches, returning a promise that resolves with an array of paths that match the specified patterns. The example code searches for all files except markdown files and logs the result.
const fg = require('fast-glob');
fg.async(['**/*', '!**/*.md']).then(paths => {
console.log(paths);
});Stream interface for file searching
This feature provides a stream interface for file searching, emitting each matching path as a 'data' event. The example code searches for all files except markdown files and logs each matching path as it's found.
const fg = require('fast-glob');
const stream = fg.stream(['**/*', '!**/*.md']);
stream.on('data', (entry) => console.log(entry));The 'glob' package is one of the most well-known globbing libraries for Node.js. It is slower than fast-glob but has been around longer and has a large user base.
The 'node-glob' package is another alternative that provides similar functionality to fast-glob. It is also slower and less feature-rich compared to fast-glob.
The 'micromatch' package is a smaller, more focused library for matching files. It is highly performant and offers fine-grained control over the matching process, but it may not be as fast as fast-glob for large sets of files.
The 'minimatch' package is a minimal matching utility that works with the glob syntax. It is the matcher used internally by the 'glob' package and is less feature-rich compared to fast-glob.
Readme
Is a faster
node-globalternative.
['*', '!*.md']).!**/node_modules/**).fs.Stats for matched path if you wanted.If you want to thank me, or promote your Issue.
Sorry, but I have work and support for packages requires some time after work. I will be glad of your support and PR's.
$ npm install --save fast-glob
const fg = require('fast-glob');
fg(['src/**/*.js', '!src/**/*.spec.js']).then((entries) => console.log(entries));
fg.async(['src/**/*.js', '!src/**/*.spec.js']).then((entries) => console.log(entries));
const fg = require('fast-glob');
const entries = fg.sync(['src/**/*.js', '!src/**/*.spec.js']);
console.log(entries);
const fg = require('fast-glob');
const stream = fg.stream(['src/**/*.js', '!src/**/*.spec.js']);
const entries = [];
stream.on('data', (entry) => entries.push(entry));
stream.once('error', console.log);
stream.once('end', () => console.log(entries));
Returns a Promise with an array of matching entries.
Returns an array of matching entries.
Returns a ReadableStream when the data event will be emitted with Entry.
string|string[]This package does not respect the order of patterns. First, all the negative patterns are applied, and only then the positive patterns.
ObjectSee options section for more detailed information.
Return a set of tasks based on provided patterns. All tasks satisfy the Task interface:
interface Task {
/**
* Parent directory for all patterns inside this task.
*/
base: string;
/**
* Dynamic or static patterns are in this task.
*/
dynamic: boolean;
/**
* All patterns.
*/
patterns: string[];
/**
* Only positive patterns.
*/
positive: string[];
/**
* Only negative patterns without ! symbol.
*/
negative: string[];
}
The entry which can be a string if the stats option is disabled, otherwise fs.Stats with two additional path and depth properties.
stringprocess.cwd()The current working directory in which to search.
number|booleantrueThe deep option can be set to true to traverse the entire directory structure, or it can be set to a number to only traverse that many levels deep.
For example, you have the following tree:
test
└── one
└── two
└── index.js
:book: If you specify a pattern with some base directory, this directory will not participate in the calculation of the depth of the found directories. Think of it as a
cwdoption.
fg('test/**', { onlyFiles: false, deep: 0 });
// -> ['test/one']
fg('test/**', { onlyFiles: false, deep: 1 });
// -> ['test/one', 'test/one/two']
fg('**', { onlyFiles: false, cwd: 'test', deep: 0 });
// -> ['one']
fg('**', { onlyFiles: false, cwd: 'test', deep: 1 });
// -> ['one', 'one/two']
string[][]An array of glob patterns to exclude matches.
booleanfalseAllow patterns to match filenames starting with a period (files & directories), even if the pattern does not explicitly have a period in that spot.
booleanfalseReturn fs.Stats with two additional path and depth properties instead of a string.
booleantrueReturn only files.
booleanfalseReturn only directories.
booleantrueFollow symlinked directories when expanding ** patterns.
booleantruePrevent duplicate results.
booleanfalseAdd a / character to directory entries.
booleanfalseReturn absolute paths for matched entries.
:book: Note that you need to use this option if you want to use absolute negative patterns like
${__dirname}/*.md.
booleanfalseDisable expansion of brace patterns ({a,b}, {1..3}).
booleantrueThe nobrace option without double-negation. This option has a higher priority then nobrace.
booleanfalseDisable matching with globstars (**).
booleantrueThe noglobstar option without double-negation. This option has a higher priority then noglobstar.
booleanfalseDisable extglob support (patterns like +(a|b)), so that extglobs are regarded as literal characters.
booleantrueThe noext option without double-negation. This option has a higher priority then noext.
booleanfalseDisable a case-sensitive mode for matching files.
test/file.md, test/File.mdtest/file.* pattern (false): test/file.mdtest/file.* pattern (true): test/file.md, test/File.mdbooleantrueThe nocase option without double-negation. This option has a higher priority then nocase.
booleanfalseAllow glob patterns without slashes to match a file path based on its basename. For example, a?b would match the path /xyz/123/acb, but not /xyz/acb/123.
FunctionnullAllows you to transform a path or fs.Stats object before sending to the array.
const fg = require('fast-glob');
const entries1 = fg.sync(['**/*.scss']);
const entries2 = fg.sync(['**/*.scss'], { transform: (entry) => '_' + entry });
console.log(entries1); // ['a.scss', 'b.scss']
console.log(entries2); // ['_a.scss', '_b.scss']
If you are using TypeScript, you probably want to specify your own type of the returned array.
import * as fg from 'fast-glob';
interface IMyOwnEntry {
path: string;
}
const entries: IMyOwnEntry[] = fg.sync<IMyOwnEntry>(['*.md'], {
transform: (entry) => typeof entry === 'string' ? { path: entry } : { path: entry.path }
// Will throw compilation error for non-IMyOwnEntry types (boolean, for example)
});
You can use a negative pattern like this: !**/node_modules or !**/node_modules/**. Also you can use ignore option. Just look at the example below.
first/
├── file.md
└── second
└── file.txt
If you don't want to read the second directory, you must write the following pattern: !**/second or !**/second/**.
fg.sync(['**/*.md', '!**/second']); // ['first/file.txt']
fg.sync(['**/*.md'], { ignore: '**/second/**' }); // ['first/file.txt']
:warning: When you write
!**/second/**/*it means that the directory will be read, but all the entries will not be included in the results.
You have to understand that if you write the pattern to exclude directories, then the directory will not be read under any circumstances.
You cannot use UNC paths as patterns (due to syntax), but you can use them as cwd directory.
fg.sync('*', { cwd: '\\\\?\\C:\\Python27' /* or //?/C:/Python27 */ });
fg.sync('Python27/*', { cwd: '\\\\?\\C:\\' /* or //?/C:/ */ });
node-glob?Not fully, because fast-glob does not implement all options of node-glob. See table below.
| node-glob | fast-glob |
|---|---|
cwd | cwd |
root | – |
dot | dot |
nomount | – |
mark | markDirectories |
nosort | – |
nounique | unique |
nobrace | nobrace or brace |
noglobstar | noglobstar or globstar |
noext | noext or extension |
nocase | nocase or case |
matchBase | matchbase |
nodir | onlyFiles |
ignore | ignore |
follow | followSymlinkedDirectories |
realpath | – |
absolute | absolute |
Tech specs:
Server: Vultr Bare Metal
You can see results here for latest release.
fs.readdir().See the Releases section of our GitHub project for changelogs for each release version.
This software is released under the terms of the MIT license.
FAQs
It's a very fast and efficient glob library for Node.js
The npm package fast-glob receives a total of 38,220,001 weekly downloads. As such, fast-glob popularity was classified as popular.
We found that fast-glob demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
Ecma TC39 is meeting this week and has moved key ECMAScript proposals forward, advancing Deferred Import Evaluation, Error.isError(), RegExp Escaping, and Promise.try to the next stages.
Security News
Researchers have demonstrated that teams of LLM agents can exploit zero-day vulnerabilities with a 53% success rate, and the costs of using AI to do so are rapidly becoming more affordable than hiring a human penetration tester.
Security News
In an unprecedented surge, May 2024 saw the publication of over 5,000 CVEs, marking a historic milestone in cybersecurity with an average of 164 CVEs per day, nearly double the 2023 daily average.