Merge pull request #43 from kaelzhang/5.0.0

5.0.0

CHANGELOG.md

@@ -1,19 +1,27 @@
-# `node-ignore` 4 ChangeLog
+# `node-ignore` 5 ChangeLog
+
+# 5.x
+
+## 2018-08-13, Version 5.0.0
+
+- **SEMVER-MAJOR**: [#20](https://github.com/kaelzhang/node-ignore/issues/20): it will throw if an invalid pathname passes into `.ignores(pathname)`, see [Upgrade 4.x -> 5.x](https://github.com/kaelzhang/node-ignore#upgrade-4x---5x).
+- **FEATURE**: [#31](https://github.com/kaelzhang/node-ignore/issues/31): adds a new method [`.test(pathname)`](https://github.com/kaelzhang/node-ignore#testpathname-pathname-since-500).
+- **BENCHMARK**: improves performance by 26%.
 
 # 4.x
 
-## 2018-06-22, Version 4.0.0
+## 2018-08-12, Version 4.0.6
 
-- **SEMVER-MAJOR**: Drop support for node < 6 by default.
-- **FEATURE**: supports the missing character ranges and sets, such as `*.[a-z]` and `*.[jJ][pP][gG]`
-- **FEATURE**: new option: `ignorecase` to make `ignore` case sensitive.
-- **FEATURE**: supports question mark which matches a single character.
-- **PATCH**: fixes typescript declaration.
+- **PATCH**: `Object.prototype` methods will not ruin the result any more.
 
 ## ~ 2018-08-09, Version 4.0.1 - 4.0.5
 
 - **PATCH**: updates README.md about frequent asked quesions from github issues.
 
-## 2018-08-12, Version 4.0.6
+## 2018-06-22, Version 4.0.0
 
-- **PATCH**: `Object.prototype` methods will not ruin the result any more.
+- **SEMVER-MAJOR**: Drop support for node < 6 by default.
+- **FEATURE**: supports the missing character ranges and sets, such as `*.[a-z]` and `*.[jJ][pP][gG]`
+- **FEATURE**: new option: `ignorecase` to make `ignore` case sensitive.
+- **FEATURE**: supports question mark which matches a single character.
+- **PATCH**: fixes typescript declaration.

README.md

@@ -52,10 +52,9 @@ Since `4.0.0`, ignore will no longer support `node < 6` by default, to use in no
 
 - [Usage](#usage)
 - [`Pathname` Conventions](#pathname-conventions)
-- [Guide for 2.x -> 3.x](#upgrade-2x---3x)
-- [Guide for 3.x -> 4.x](#upgrade-3x---4x)
 - See Also:
   - [`glob-gitignore`](https://www.npmjs.com/package/glob-gitignore) matches files using patterns and filters them according to gitignore rules.
+- [Upgrade Guide](#upgrade-guide)
 
 ## Usage
 
@@ -152,7 +151,7 @@ if (fs.existsSync(filename)) {
 
 instead.
 
-## .filter(paths: Array<Pathname>): Array<Pathname>
+## .filter(paths: Array&lt;Pathname&gt;): Array&lt;Pathname&gt;
 
 ```ts
 type Pathname = string
@@ -166,13 +165,13 @@ Filters the given array of pathnames, and returns the filtered array.
 
 #### 1. `Pathname` should be a `path.relative()`d pathname
 
-`Pathname` should be a string that have been `path.join()`ed, or the return value of `path.relative()` to the current directory.
+`Pathname` should be a string that have been `path.join()`ed, or the return value of `path.relative()` to the current directory,
 
 ```js
-// WRONG
+// WRONG, an error will be thrown
 ig.ignores('./abc')
 
-// WRONG, for it will never happen.
+// WRONG, for it will never happen, and an error will be thrown
 // If the gitignore rule locates at the root directory,
 // `'/abc'` should be changed to `'abc'`.
 // ```
@@ -212,6 +211,26 @@ Then the `paths` might be like this:
 ]
 ```
 
+#### 2. filenames and dirnames
+
+`node-ignore` does NO `fs.stat` during path matching, so for the example below:
+
+```js
+// First, we add a ignore pattern to ignore a directory
+ig.add('config/')
+
+// `ig` does NOT know if 'config', in the real world,
+//   is a normal file, directory or something.
+
+ig.ignores('config')
+// `ig` treats `config` as a file, so it returns `false`
+
+ig.ignores('config/')
+// returns `true`
+```
+
+Specially for people who develop some library based on `node-ignore`, it is important to understand that.
+
 Usually, you could use [`glob`](http://npmjs.org/package/glob) with `option.mark = true` to fetch the structure of the current directory:
 
 ```js
@@ -230,21 +249,6 @@ glob('**', {
 })
 ```
 
-#### 2. filenames and dirnames
-
-`node-ignore` does NO `fs.stat` during path matching, so for the example below:
-
-```js
-ig.add('config/')
-
-// `ig` does NOT know if 'config' is a normal file, directory or something
-ig.ignores('config')    // And it returns `false`
-
-ig.ignores('config/')   // returns `true`
-```
-
-Specially for people who develop some library based on `node-ignore`, it is important to understand that.
-
 ## .ignores(pathname: Pathname): boolean
 
 > new in 3.2.0
@@ -261,9 +265,21 @@ Creates a filter function which could filter an array of paths with `Array.proto
 
 Returns `function(path)` the filter function.
 
+## .test(pathname: Pathname) since 5.0.0
+
+Returns `TestResult`
+
+```ts
+interface TestResult {
+  ignored: boolean
+  // true if the `pathname` is finally unignored by some negative pattern
+  unignored: boolean
+}
+```
+
 ## `options.ignorecase` since 4.0.0
 
-Similar as the `core.ignorecase` option of [git-config](https://git-scm.com/docs/git-config), `node-ignore` will be case insensitive if `options.ignorecase` is set to `true` (default value), otherwise case sensitive.
+Similar as the `core.ignorecase` option of [git-config](https://git-scm.com/docs/git-config), `node-ignore` will be case insensitive if `options.ignorecase` is set to `true` (the default value), otherwise case sensitive.
 
 ```js
 const ig = ignore({
@@ -275,15 +291,56 @@ ig.add('*.png')
 ig.ignores('*.PNG')  // false
 ```
 
+## static `ignore.isPathValid(pathname): boolean` since 5.0.0
+
+Check whether the `pathname` is valid according to the [convention](#1-pathname-should-be-a-pathrelatived-pathname).
+
+```js
+ignore.isPathValid('./foo')  // false
+```
+
 ****
 
 # Upgrade Guide
 
-## Upgrade 2.x -> 3.x
+## Upgrade 4.x -> 5.x
 
-- All `options` of 2.x are unnecessary and removed, so just remove them.
-- `ignore()` instance is no longer an [`EventEmitter`](nodejs.org/api/events.html), and all events are unnecessary and removed.
-- `.addIgnoreFile()` is removed, see the [.addIgnoreFile](#addignorefilepath) section for details.
+Since `5.0.0`, if an invalid `Pathname` passed into `ig.ignores()`, an error will be thrown, while `ignore < 5.0.0` did not make sure what the return value was, as well as
+
+```ts
+.ignores(pathname: Pathname): boolean
+
+.filter(pathnames: Array<Pathname>): Array<Pathname>
+
+.createFilter(): (pathname: Pathname) => boolean
+
+.test(pathname: Pathname): {ignored: boolean, unignored: boolean}
+```
+
+See the convention [here](#1-pathname-should-be-a-pathrelatived-pathname) for details.
+
+If there are invalid pathnames, the conversion and filtration should be done by users.
+
+```js
+const path = require('path')
+const {isPathValid} = require('ignore') // introduced in 5.0.0
+
+const paths = [
+  // invalid
+  //////////////////
+  '',
+  false,
+  '../foo',
+  '.',
+  //////////////////
+
+  // valid
+  'foo'
+]
+.filter(isValidPath)
+
+ig.filter(paths)
+```
 
 ## Upgrade 3.x -> 4.x
 
@@ -293,6 +350,12 @@ Since `4.0.0`, `ignore` will no longer support node < 6, to use `ignore` in node
 var ignore = require('ignore/legacy')
 ```
 
+## Upgrade 2.x -> 3.x
+
+- All `options` of 2.x are unnecessary and removed, so just remove them.
+- `ignore()` instance is no longer an [`EventEmitter`](nodejs.org/api/events.html), and all events are unnecessary and removed.
+- `.addIgnoreFile()` is removed, see the [.addIgnoreFile](#addignorefilepath) section for details.
+
 ****
 
 # Collaborators

appveyor.yml

@@ -18,7 +18,7 @@ test_script:
   - node --version
   - npm --version
   # run tests
-  - npm run test-no-cov
+  - npm run test-no-report
 
 # Don't actually build.
 build: off

index.d.ts

@@ -1,36 +1,50 @@
+type Pathname = string
+
+interface TestResult {
+  ignored: boolean
+  unignored: boolean
+}
+
 interface Ignore {
   /**
    * Adds a rule rules to the current manager.
    * @param  {string | Ignore} pattern
    * @returns IgnoreBase
    */
-  add(pattern: string | Ignore): Ignore
+  add(pattern: string | Ignore): this
   /**
    * Adds several rules to the current manager.
    * @param  {string[]} patterns
    * @returns IgnoreBase
    */
-  add(patterns: (string | Ignore)[]): Ignore
+  add(patterns: (string | Ignore)[]): this
 
   /**
    * Filters the given array of pathnames, and returns the filtered array.
    * NOTICE that each path here should be a relative path to the root of your repository.
    * @param paths the array of paths to be filtered.
    * @returns The filtered array of paths
    */
-  filter(paths: string[]): string[]
+  filter(pathnames: Pathname[]): Pathname[]
   /**
    * Creates a filter function which could filter
    * an array of paths with Array.prototype.filter.
    */
-  createFilter(): (path: string) => boolean
+  createFilter(): (pathname: Pathname) => boolean
 
   /**
    * Returns Boolean whether pathname should be ignored.
    * @param  {string} pathname a path to check
    * @returns boolean
    */
-  ignores(pathname: string): boolean
+  ignores(pathname: Pathname): boolean
+
+  /**
+   * Returns whether pathname should be ignored or unignored
+   * @param  {string} pathname a path to check
+   * @returns TestResult
+   */
+  test(pathname: Pathname): TestResult
 }
 
 interface Options {
@@ -42,4 +56,8 @@ interface Options {
  */
 declare function ignore(options?: Options): Ignore
 
+declare namespace ignore {
+  export function isPathValid (pathname: string): boolean
+}
+
 export default ignore