fast-glob - npm Package Compare versions

Comparing version 1.0.1 to 2.0.0

index.js

@@ -1,4 +0,8 @@
-const fGlob = require('./out/fglob');
-module.exports = fGlob.default;
-module.exports.default = fGlob.default;
-module.exports.sync = fGlob.sync;
+const pkg = require('./out/index');
+
+module.exports = pkg.async;
+module.exports.default = pkg.async;
+
+module.exports.async = pkg.async;
+module.exports.sync = pkg.sync;
+module.exports.stream = pkg.stream;

package.json

 {
   "name": "fast-glob",
-  "version": "1.0.1",
+  "version": "2.0.0",
   "description": "Is a faster `node-glob` alternative",
@@ -14,3 +14,4 @@ "license": "MIT",
   },
-  "typings": "out/fglob.d.ts",
+  "main": "index.js",
+  "typings": "index.d.ts",
   "keywords": [
@@ -23,29 +24,55 @@ "glob",
   "devDependencies": {
-    "@types/micromatch": "^2.3.29",
-    "@types/mocha": "^2.2.41",
-    "@types/node": "^7.0.27",
-    "@types/rimraf": "0.0.28",
-    "fs-extra": "^3.0.1",
-    "glob": "^7.1.2",
-    "mocha": "^3.4.2",
-    "rimraf": "^2.6.1",
-    "tslint": "^5.4.2",
-    "tslint-config-xo": "^1.2.0",
-    "typescript": "^2.3.4"
+    "@types/bash-glob": "^2.0.0",
+    "@types/compute-stdev": "^1.0.0",
+    "@types/execa": "^0.8.1",
+    "@types/glob": "^5.0.34",
+    "@types/glob-parent": "^3.1.0",
+    "@types/glob-stream": "^6.1.0",
+    "@types/globby": "^6.1.0",
+    "@types/merge2": "^1.1.4",
+    "@types/micromatch": "^3.1.0",
+    "@types/minimist": "^1.2.0",
+    "@types/mocha": "^2.2.46",
+    "@types/node": "^9.3.0",
+    "@types/rimraf": "2.0.2",
+    "bash-glob": "^2.0.0",
+    "compute-stdev": "^1.0.0",
+    "execa": "^0.8.0",
+    "fast-glob": "^1.0.1",
+    "glob-stream": "^6.1.0",
+    "globby": "^7.1.1",
+    "minimist": "^1.2.0",
+    "mocha": "^4.1.0",
+    "rimraf": "^2.6.2",
+    "tslint": "^5.8.0",
+    "tslint-config-mrmlnc": "^1.0.0",
+    "typescript": "^2.6.2"
   },
   "dependencies": {
-    "bash-glob": "^1.0.1",
-    "glob-parent": "^3.1.0",
-    "micromatch": "^3.0.3",
-    "readdir-enhanced": "^1.5.2"
+    "glob-parent": "3.1.0",
+    "merge2": "1.2.1",
+    "micromatch": "3.1.5",
+    "readdir-enhanced": "2.2.0"
   },
   "scripts": {
     "clean": "rimraf out",
-    "lint": "tslint src/**/*.ts",
+    "lint": "tslint src/{,**/}*.ts -p . -t stylish",
     "compile": "tsc",
-    "test": "rimraf .tmp && mocha out/{,**/}*.spec.js -s 0",
+    "test": "mocha \"out/**/*.spec.js\" -s 0",
     "build": "npm run clean && npm run lint && npm run compile && npm test",
-    "watch": "npm run clean && npm run lint && npm run compile -- --sourceMap --watch",
-    "bench": "npm run clean && npm run lint && npm run compile && bash benchmark/benchmark.sh"
+    "watch": "npm run clean && npm run lint & npm run compile -- --sourceMap --watch",
+    "bench-async-1": "node ./out/benchmark --depth 1",
+    "bench-async-5": "node ./out/benchmark --depth 5",
+    "bench-async-10": "node ./out/benchmark --depth 10",
+    "bench-async-50": "node ./out/benchmark --depth 50",
+    "bench-async-100": "node ./out/benchmark --depth 100",
+    "bench-async": "npm run bench-async-1 && npm run bench-async-5 && npm run bench-async-10 && npm run bench-async-50 && npm run bench-async-100",
+    "bench-sync-1": "node ./out/benchmark --depth 1 --type sync",
+    "bench-sync-5": "node ./out/benchmark --depth 5 --type sync",
+    "bench-sync-10": "node ./out/benchmark --depth 10 --type sync",
+    "bench-sync-50": "node ./out/benchmark --depth 50 --type sync",
+    "bench-sync-100": "node ./out/benchmark --depth 100 --type sync",
+    "bench-sync": "npm run bench-sync-1 && npm run bench-sync-5 && npm run bench-sync-10 && npm run bench-sync-50 && npm run bench-sync-100",
+    "bench": "npm run build && npm run bench-async && npm run bench-sync"
   }
 }

README.md

@@ -1,31 +0,62 @@
-# fast-glob
+# :rocket: fast-glob
 
-> Is a faster (1.5-8x for most cases) `node-glob` alternative.
+> Is a faster [`node-glob`](https://github.com/isaacs/node-glob) alternative.
 
+[![Build Status](https://travis-ci.org/mrmlnc/fast-glob.svg?branch=master)](https://travis-ci.org/mrmlnc/fast-glob)
+[![Build status](https://ci.appveyor.com/api/projects/status/i4xqijtq26qf6o9d?svg=true)](https://ci.appveyor.com/project/mrmlnc/fast-glob)
+
+## :bulb: Highlights
+
+  * :rocket: Fast by using Streams and Promises. Used [readdir-enhanced](https://github.com/BigstickCarpet/readdir-enhanced) and [micromatch](https://github.com/jonschlinkert/micromatch).
+  * :beginner: User-friendly, since it supports multiple and negated patterns (`['*', '!*.md']`).
+  * :vertical_traffic_light: Rational, because it doesn't read excluded directories (`!**/node_modules`).
+  * :gear: Universal, because it supports Synchronous, Promise and Stream API.
+  * :money_with_wings: Economy, because it provides `fs.Stats` for matched path if you wanted.
+
+## Donate
+
+If you want to thank me, or promote your Issue.
+
+[![Donate](https://img.shields.io/badge/Donate-PayPal-green.svg)](https://paypal.me/mrmlnc)
+
+> Sorry, but I have work and support for packages requires some time after work. I will be glad of your support and PR's.
+
 ## Install
 
 ```
-$ npm i -S fast-glob
+$ npm install --save fast-glob
 ```
 
-## Why?
+## Usage
 
-  * Fast by using Streams, Promises and Bash Globbing on Linux machines. Used [readdir-enhanced](https://github.com/BigstickCarpet/readdir-enhanced), [micromatch](https://github.com/jonschlinkert/micromatch) and [bash-glob](https://github.com/jonschlinkert/bash-glob).
-  * You can limit the depth of your search (only for non-Bash mode).
-  * You can get not only file paths, but also their `fs.Stats` objects with the additional `path` property.
-  * You can transform file path or `fs.Stats` object before sending it to an array.
+#### Asynchronous
 
-## Usage
+```js
+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));
+```
+
+#### Synchronous
+
 ```js
-const fastGlob = require('fast-glob');
+const fg = require('fast-glob');
 
-// Async
-fastGlob('dir/**/*.txt').then((files) => {
-  console.log(files); // ['dir/a.txt', ...]
-});
+const entries = fg.sync(['src/**/*.js', '!src/**/*.spec.js']);
+console.log(entries);
+```
 
-// Sync
-const files = fastGlob.sync('dir/**/*.txt');
-console.log(files); // ['dir/a.txt', ...]
+#### Stream
+
+```js
+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));
 ```
@@ -35,126 +66,241 @@
 
-### fastGlob(patterns, [options])
+### fg(patterns, [options])
+### fg.async(patterns, [options])
 
-  * patterns `String|String[]` Patterns to be matched
-  * options `Object`
-  * return `String[]` or `fs.Stats[]` with `path` property
+Returns a `Promise<Array>` of matching entries.
 
-### fastGlob.sync(patterns, [options]) => []
+#### patterns
 
-  * patterns `String|String[]` Patterns to be matched
-  * options `Object`
-  * return `String[]` or `fs.Stats[]` with `path` property
+  * Type: `string|string[]`
 
-## options
+#### options
 
-| Option      | Type              | Default                | Description |
-|:------------:|:-----------------:|:---------------------:|:------------|
-| `cwd`        | `String`          | `process.cwd`         | The current working directory in which to search |
-| `deep`       | `Number|Boolean`  | `true`                | The 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. |
-| `ignore`     | `String|String[]` | `[]`                  | Add a pattern or an array of glob patterns to exclude matches. |
-| `stats`      | `Boolean`         | `false`               | Return `fs.Stats` with `path` property instead of file path. |
-| `onlyFiles`  | `Boolean`         | `false`               | Return only files. |
-| `onlyDirs`   | `Boolean`         | `false`               | Return only directories. |
-| `bashNative` | `String[]`        | `['darwin', 'linux']` | Use bash-powered globbing (2-15x faster on Linux, but slow on BashOnWindows) for specified platforms. See [available values for array](https://nodejs.org/dist/latest-v7.x/docs/api/process.html#process_process_platform). |
-| `transform`  | `Function`        | `null`                | Allows you to transform a path or `fs.Stats` object before sending to the array. |
+  * Type: `Object`
 
-## Compatible with `node-glob`?
+See [options](https://github.com/mrmlnc/fast-glob#Options) section for more detailed information.
 
-Not fully, because `fast-glob` not implements all options of `node-glob`.
+### fg.sync(patterns, [options])
 
-## Example for `transform` option
+Returns a `Array` of matching entries.
 
+### fg.stream(patterns, [options])
+
+Returns a [`ReadableStream`](https://nodejs.org/api/stream.html#stream_readable_streams).
+
+## Options
+
+#### cwd
+
+  * Type: `string`
+  * Default: `process.cwd()`
+
+The current working directory in which to search.
+
+#### deep
+
+  * Type: `number|boolean`
+  * Default: `true`
+
+The 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.
+
+#### ignore
+
+  * Type: `string[]`
+  * Default: `[]`
+
+An array of glob patterns to exclude matches.
+
+#### dot
+
+  * Type: `boolean`
+  * Default: `false`
+
+Allow patterns to match filenames starting with a period (files & directories), even if the pattern does not explicitly have a period in that spot.
+
+#### stats
+
+  * Type: `number|boolean`
+  * Default: `false`
+
+Return `fs.Stats` with `path` property instead of file path.
+
+#### onlyFiles
+
+  * Type: `boolean`
+  * Default: `true`
+
+Return only files.
+
+#### onlyDirectories
+
+  * Type: `boolean`
+  * Default: `false`
+
+Return only directories.
+
+#### followSymlinkedDirectories
+
+  * Type: `boolean`
+  * Default: `true`
+
+Follow symlinked directories when expanding `**` patterns.
+
+#### unique
+
+  * Type: `boolean`
+  * Default: `true`
+
+Prevent duplicate results.
+
+#### markDirectories
+
+  * Type: `boolean`
+  * Default: `false`
+
+Add a `/` character to directory entries.
+
+#### absolute
+
+  * Type: `boolean`
+  * Default: `false`
+
+Return absolute paths for matched entries.
+
+#### nobrace
+
+  * Type: `boolean`
+  * Default: `false`
+
+Disable expansion of brace patterns (`{a,b}`, `{1..3}`).
+
+#### noglobstar
+
+  * Type: `boolean`
+  * Default: `false`
+
+Disable matching with globstars (`**`).
+
+#### noext
+
+  * Type: `boolean`
+  * Default: `false`
+
+Disable extglob support (patterns like `+(a|b)`), so that extglobs are regarded as literal characters.
+
+#### nocase
+
+  * Type: `boolean`
+  * Default: `false`
+
+Use a case-insensitive regex for matching files.
+
+#### matchBase
+
+  * Type: `boolean`
+  * Default: `false`
+
+Allow 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`.
+
+#### transform
+
+  * Type: `Function`
+  * Default: `null`
+
+Allows you to transform a path or `fs.Stats` object before sending to the array.
+
 ```js
-fastGlob('dir/**/*.txt', { transform: readFilePromise }).then((files) => {
-  console.log(files); // ['dir/a.txt', ...]
-  return Promise.all(files);
-}).then((files) => {
-  console.log(files); // ['content from dir/a.txt', ...]
+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.
+
+```ts
+import * as fg from 'fast-glob';
+
+interface IEntry {
+	path: string;
+}
+
+const entries: IEntry[] = fg.sync<IEntry>(['*.md'], {
+	transform: (entry) => typeof entry === 'string' ? { path: entry } : { path: entry.path }
+	// Will throw compilation error for non-IEntry types (boolean, for example)
 });
 ```
 
-## Benchmark
+## How to exclude directory from reading?
 
-**Tech specs:**
+You can use a negative pattern like this: `!**/node_modules`. Also you can use `ignore` option. Just look at the example below.
 
- * Intel Core i7-3610QM
- * RAM 8GB
- * SSD (555MB/S, 530MB/S)
- * Windows 10 + VirtualBox with Manjaro
- * Node.js v7.3.0
+  * **first/**
+    * **second/**
+      * file.md
+    * file.md
 
-```shell
-$ npm run bench
+If you don't want to read the `second` directory, you must write the following pattern: `!**/second`.
 
-==============================
-Benchmark for 10 files
-==============================
+```js
+fg.sync(['**/*.md', '!**/second']); // ['first/file.txt']
+fg.sync(['**/*.md'], { ignore: '**/second' }); // ['first/file.txt']
+```
 
-bash: 6 ms
-node-glob (10): 19.47606 ms
-bash-glob (10): 23.406374 ms
-fast-glob (10) as native: 25.359293 ms
-fast-glob (10) as fast: 33.696387 ms
+> :warning: When you write `!**/second/**` it means that the directory will be **read**, but all the entries will not be included in the results.
 
-==============================
-Benchmark for 50 files
-==============================
+You have to understand that if you write the pattern to exclude directories, then the directory will not be read under any circumstances. But… you can specify a more meaningful pattern, which will be launched in parallel with the first.
 
-bash: 6 ms
-node-glob (54): 28.43855 ms
-bash-glob (54): 20.731202 ms
-fast-glob (54) as native: 22.709236 ms
-fast-glob (54) as fast: 25.057461 ms
+```js
+fg.sync(['**/*.txt', '!**/second', 'first/second/**/*.txt']); // ['first/file.txt', 'first/second/file.txt']
+```
 
-==============================
-Benchmark for 100 files
-==============================
+However, be aware that it may not work as you expect in case where inside the `second` directory there is a directory matching to the pattern for exluding directory. Yes, sounds complicated. Simpler: the `second` directory inside the `second` directory.
 
-bash: 5 ms
-node-glob (109): 34.811618 ms
-bash-glob (109): 21.624256 ms
-fast-glob (109) as native: 26.291311 ms
-fast-glob (109) as fast: 29.61791 ms
+## Compatible with `node-glob`?
 
-==============================
-Benchmark for 500 files
-==============================
+Not fully, because `fast-glob` does not implement all options of `node-glob`. See table below.
 
-bash: 7 ms
-node-glob (549): 90.513766 ms
-bash-glob (549): 23.116938 ms
-fast-glob (549) as native: 30.978642 ms
-fast-glob (549) as fast: 61.367613 ms
+| node-glob    | fast-glob |
+| :----------: | :-------: |
+| `cwd`        | [`cwd`](#cwd) |
+| `root`       | – |
+| `dot`        | [`dot`](#dot) |
+| `nomount`    | – |
+| `mark`       | [`markDirectories`](#markdirectories) |
+| `nosort`     | – |
+| `nounique`   | [`unique`](#unique) |
+| `nobrace`    | [`nobrace`](#nobrace) |
+| `noglobstar` | [`noglobstar`](#noglobstar) |
+| `noext`      | [`noext`](#noext) |
+| `nocase`     | [`nocase`](#nocase) |
+| `matchBase`  | [`matchbase`](#matchbase) |
+| `nodir`      | [`onlyFiles`](#onlyfiles) |
+| `ignore`     | [`ignore`](#ignore) |
+| `follow`     | [`followSymlinkedDirectories`](#followsymlinkeddirectories) |
+| `realpath`   | – |
+| `absolute`   | [`absolute`](#absolute) |
 
-==============================
-Benchmark for 1000 files
-==============================
+## Benchmarks
 
-bash: 11 ms
-node-glob (1099): 139.44816 ms
-bash-glob (1099): 35.691985 ms
-fast-glob (1099) as native: 36.770455 ms
-fast-glob (1099) as fast: 84.387065 ms
+**Tech specs:**
 
-==============================
-Benchmark for 5000 files
-==============================
+Server: [Vultr Bare Metal](https://www.vultr.com/pricing/baremetal)
 
-bash: 43 ms
-node-glob (5499): 584.910373 ms
-bash-glob (5499): 90.38803 ms
-fast-glob (5499) as native: 97.143759 ms
-fast-glob (5499) as fast: 233.977073 ms
+  * Processor: E3-1270v6 (8 CPU)
+  * RAM: 32GB
+  * Disk: SSD
 
-==============================
-Benchmark for 10000 files
-==============================
+You can see results [here](https://gist.github.com/mrmlnc/f06246b197f53c356895fa35355a367c) for latest release.
 
-bash: 96 ms
-node-glob (10999): 1143.377267 ms
-bash-glob (10999): 169.416486 ms
-fast-glob (10999) as native: 198.930152 ms
-fast-glob (10999) as fast: 531.693878 ms
-```
+## Related
 
+  * [readdir-enhanced](https://github.com/BigstickCarpet/readdir-enhanced) – Fast functional replacement for `fs.readdir()`.
+  * [globby](https://github.com/sindresorhus/globby) – User-friendly glob matching.
+  * [node-glob](https://github.com/isaacs/node-glob) – «Standard» glob functionality for Node.js
+  * [bash-glob](https://github.com/micromatch/bash-glob) – Bash-powered globbing for node.js.
+  * [glob-stream](https://github.com/gulpjs/glob-stream) – A Readable Stream interface over node-glob that used in the [gulpjs](https://github.com/gulpjs/gulp).
+
 ## Changelog
@@ -161,0 +307,0 @@

New alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Major refactor

Supply chain risk

Package has recently undergone a major refactor. It may be unstable or indicate significant internal changes. Use caution when updating to versions that include significant changes.

Found 1 instance in 1 package

Fixed alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Filesystem access

Supply chain risk

Accesses the file system, and could potentially read sensitive data.

Found 1 instance in 1 package

Improved metrics

Total package byte prevSize

86192

increased by364.15%

Number of package files

66

increased by214.29%

Lines of code

2131

increased by639.93%

Number of lines in readme file

312

increased by87.95%

Number of low supply chain risk alerts

1

decreased by-66.67%

Worsened metrics

Dev dependency count

25

increased by127.27%

Number of medium supply chain risk alerts

1

increased byInfinity%

Dependency changes

• + Addedmerge2@1.2.1

• + Addedmerge2@1.2.1(transitive)

• + Addedmicromatch@3.1.5(transitive)

• + Addedreaddir-enhanced@2.2.0(transitive)

• - Removedbash-glob@^1.0.1

• - Removedasync-each@1.0.6(transitive)

• - Removedbash-glob@1.0.2(transitive)

• - Removedbash-path@1.0.3(transitive)

• - Removedcross-spawn@5.1.0(transitive)

• - Removedes6-promise@4.2.8(transitive)

• - Removedis-glob@4.0.3(transitive)

• - Removedisexe@2.0.0(transitive)

• - Removedlru-cache@4.1.5(transitive)

• - Removedmicromatch@3.1.10(transitive)

• - Removedpseudomap@1.0.2(transitive)

• - Removedreaddir-enhanced@1.5.2(transitive)

• - Removedshebang-command@1.2.0(transitive)

• - Removedshebang-regex@1.0.0(transitive)

• - Removedwhich@1.3.1(transitive)

• - Removedyallist@2.1.2(transitive)

• Updatedglob-parent@3.1.0

• Updatedmicromatch@3.1.5

• Updatedreaddir-enhanced@2.2.0