|
| 1 | + |
| 2 | + |
| 3 | +# ip-filter [![npm version][npmv-img]][npmv-url] [![License][license-img]][license-url] [![Libera Manifesto][libera-manifesto-img]][libera-manifesto-url] |
| 4 | + |
| 5 | +> Validates valid IPs (IPv4 and IPv6) using [micromatch][] - glob patterns, RegExp, string or array of globs. If match returns the IP, otherwise null. |
| 6 | +
|
| 7 | +Please consider following this project's author, |
| 8 | +[Charlike Mike Reagent](https://github.com/tunnckoCore), and :star: the project |
| 9 | +to show your :heart: and support. |
| 10 | + |
| 11 | +<div id="readme"></div> |
| 12 | + |
| 13 | +[![Code style][codestyle-img]][codestyle-url] |
| 14 | +[![CircleCI linux build][linuxbuild-img]][linuxbuild-url] |
| 15 | +[![CodeCov coverage status][codecoverage-img]][codecoverage-url] |
| 16 | +[![Renovate App Status][renovateapp-img]][renovateapp-url] |
| 17 | +[![Make A Pull Request][prs-welcome-img]][prs-welcome-url] |
| 18 | +[![Time Since Last Commit][last-commit-img]][last-commit-url] |
| 19 | + |
| 20 | +<!-- [![Semantically Released][standard-release-img]][standard-release-url] --> |
| 21 | + |
| 22 | +If you have any _how-to_ kind of questions, please read the [Contributing |
| 23 | +Guide][contributing-url] and [Code of Conduct][code_of_conduct-url] documents. |
| 24 | +For bugs reports and feature requests, [please create an issue][open-issue-url] |
| 25 | +or ping [@tunnckoCore](https://twitter.com/tunnckoCore) at Twitter. |
| 26 | + |
| 27 | +[![Conventional Commits][ccommits-img]][ccommits-url] |
| 28 | +[![Minimum Required Nodejs][nodejs-img]][npmv-url] |
| 29 | +[![NPM Downloads Monthly][downloads-monthly-img]][npmv-url] |
| 30 | +[![NPM Downloads Total][downloads-total-img]][npmv-url] |
| 31 | +[![Share Love Tweet][twitter-share-img]][twitter-share-url] |
| 32 | +[![Twitter][twitter-img]][twitter-url] |
| 33 | + |
| 34 | +Project is [semantically](https://semver.org) versioned & automatically released |
| 35 | +from [GitHub Actions](https://github.com/features/actions) with |
| 36 | +[Lerna](https://github.com/lerna/lerna). |
| 37 | + |
| 38 | +[![Become a Patron][patreon-img]][patreon-url] |
| 39 | +[![Buy me a Kofi][kofi-img]][kofi-url] |
| 40 | +[![PayPal Donation][paypal-img]][paypal-url] |
| 41 | +[![Bitcoin Coinbase][bitcoin-img]][bitcoin-url] |
| 42 | +[![Keybase PGP][keybase-img]][keybase-url] |
| 43 | + |
| 44 | +| Topic | Contact | |
| 45 | +| :--------------------------------------------------------------- | ------------------------------------------------: | |
| 46 | +| Any legal or licensing questions, like private or commerical use | ![tunnckocore_legal][tunnckocore_legal] | |
| 47 | +| For any critical problems and security reports | ![tunnckocore_security][tunnckocore_security] | |
| 48 | +| Consulting, professional support, personal or team training | ![tunnckocore_consulting][tunnckocore_consulting] | |
| 49 | +| For any questions about Open Source, partnerships and sponsoring | ![tunnckocore_opensource][tunnckocore_opensource] | |
| 50 | + |
| 51 | +<!-- Logo when needed: |
| 52 | +
|
| 53 | +<p align="center"> |
| 54 | + <a href="https://github.com/tunnckoCore/opensource"> |
| 55 | + <img src="./media/logo.png" width="85%"> |
| 56 | + </a> |
| 57 | +</p> |
| 58 | +
|
| 59 | +--> |
| 60 | + |
| 61 | +## Table of Contents |
| 62 | + |
| 63 | +- [Install](#install) |
| 64 | +- [API](#api) |
| 65 | + * [ipFilter](#ipfilter) |
| 66 | +- [See Also](#see-also) |
| 67 | +- [Contributing](#contributing) |
| 68 | + * [Guides and Community](#guides-and-community) |
| 69 | + * [Support the project](#support-the-project) |
| 70 | +- [Contributors](#contributors) |
| 71 | +- [License](#license) |
| 72 | + |
| 73 | +_(TOC generated by [verb](https://github.com/verbose/verb) using [markdown-toc](https://github.com/jonschlinkert/markdown-toc))_ |
| 74 | + |
| 75 | +## Install |
| 76 | + |
| 77 | +This project requires [**Node.js**](https://nodejs.org) **>=10.13** |
| 78 | +_(see |
| 79 | +[Support & Release Policy](https://github.com/tunnckoCoreLabs/support-release-policy))_. |
| 80 | +Install it using [**yarn**](https://yarnpkg.com) or |
| 81 | +[**npm**](https://npmjs.com).<br> _We highly recommend to use Yarn when you |
| 82 | +think to contribute to this project._ |
| 83 | + |
| 84 | +```bash |
| 85 | +$ yarn add ip-filter |
| 86 | +``` |
| 87 | + |
| 88 | +## API |
| 89 | + |
| 90 | +<!-- docks-start --> |
| 91 | + |
| 92 | +_Generated using [jest-runner-docs](https://ghub.now.sh/jest-runner-docs)._ |
| 93 | + |
| 94 | +### [ipFilter](./src/index.js#L44) |
| 95 | + |
| 96 | +Filter `ip` against glob `patterns`, using [micromatch][] under the hood, |
| 97 | +so `options` are passed to it. |
| 98 | + |
| 99 | +<span id="ipfilter-signature"></span> |
| 100 | + |
| 101 | +#### Signature |
| 102 | + |
| 103 | +```ts |
| 104 | +function(ip, patterns, options) |
| 105 | +``` |
| 106 | + |
| 107 | +<span id="ipfilter-params"></span> |
| 108 | + |
| 109 | +#### Params |
| 110 | + |
| 111 | +- `ip` **{string}** - Accepts only valid IPs by default |
| 112 | +- `patterns` **{string|array}** - Basically everything that [micromatch][]'s second argument can accept. |
| 113 | +- `options` **{object}** - Pass `strict: false` if want to validate non-ip values, |
| 114 | + options are also passed to [micromatch][]. |
| 115 | +- `returns` **{string}** - a `string` or `null` If not match returns `null`, otherwise the passed `ip` as string. |
| 116 | + |
| 117 | +<span id="ipfilter-examples"></span> |
| 118 | + |
| 119 | +#### Examples |
| 120 | + |
| 121 | +```js |
| 122 | +const ipFilter = require('ip-filter'); |
| 123 | +
|
| 124 | +console.log(ipFilter('123.77.34.89', '123.??.34.8*')); // => '123.77.34.89' |
| 125 | +console.log(ipFilter('123.222.34.88', '123.??.34.8*')); // => null |
| 126 | +console.log(ipFilter('123.222.33.1', ['123.*.34.*', '*.222.33.*'])); // => '123.222.33.1' |
| 127 | +
|
| 128 | +// should notice the difference |
| 129 | +console.log(ipFilter('123.222.34.88', ['123.*.34.*', '!123.222.**'])); |
| 130 | +// => null |
| 131 | +console.log(ipFilter('123.222.34.88', ['123.*.34.*', '!123.222.*'])); |
| 132 | +// => '123.222.34.88' |
| 133 | +``` |
| 134 | + |
| 135 | +<span id="ipfilter-examples"></span> |
| 136 | + |
| 137 | +#### Examples |
| 138 | + |
| 139 | +```js |
| 140 | +const ipFilter = require('ip-filter'); |
| 141 | +// |
| 142 | +// NON-STRICT mode |
| 143 | +// |
| 144 | +
|
| 145 | +const res = ipFilter('x-koaip', ['*-koaip', '!foo-koa*'], { strict: false }); |
| 146 | +console.log(res); // => 'x-koaip' |
| 147 | +
|
| 148 | +const res = ipFilter('x-koa.foo', ['*-koa.*', '!foo-koa.*'], { strict: false }); |
| 149 | +console.log(res); // => 'x-koa.foo' |
| 150 | +``` |
| 151 | + |
| 152 | +<!-- docks-end --> |
| 153 | + |
| 154 | +**[back to top](#readme)** |
| 155 | + |
| 156 | +## See Also |
| 157 | + |
| 158 | +Some of these projects are used here or were inspiration for this one, others |
| 159 | +are just related. So, thanks for your existance! |
| 160 | + |
| 161 | +- [ip-regex](https://www.npmjs.com/package/ip-regex): Regular expression for matching IP addresses (IPv4 & IPv6) | [homepage](https://github.com/sindresorhus/ip-regex#readme "Regular expression for matching IP addresses (IPv4 & IPv6)") |
| 162 | +- [is-match-ip](https://www.npmjs.com/package/is-match-ip): Matching IPs using [micromatch][] and [ip-filter][] - glob patterns, RegExp… [more](https://github.com/tunnckocore/is-match-ip#readme) | [homepage](https://github.com/tunnckocore/is-match-ip#readme "Matching IPs using [micromatch][] and [ip-filter][] - glob patterns, RegExp, string or array of globs. Returns matcher function.") |
| 163 | +- [is-match](https://www.npmjs.com/package/is-match): Create a matching function from a glob pattern, regex, string… [more](https://github.com/jonschlinkert/is-match) | [homepage](https://github.com/jonschlinkert/is-match "Create a matching function from a glob pattern, regex, string, array, object or function.") |
| 164 | +- [koa-ip-filter](https://www.npmjs.com/package/koa-ip-filter): Middleware for [koa][] that filters IPs against glob patterns, RegExp… [more](https://github.com/tunnckocore/koa-ip-filter#readme) | [homepage](https://github.com/tunnckocore/koa-ip-filter#readme "Middleware for [koa][] that filters IPs against glob patterns, RegExp, string or array of globs. Support custom `403 Forbidden` message and custom ID.") |
| 165 | +- [micromatch](https://www.npmjs.com/package/micromatch): Glob matching for javascript/node.js. A replacement and faster alternative to… [more](https://github.com/micromatch/micromatch) | [homepage](https://github.com/micromatch/micromatch "Glob matching for javascript/node.js. A replacement and faster alternative to minimatch and multimatch.") |
| 166 | +- [to-file-path](https://www.npmjs.com/package/to-file-path): Create a filepath from an object path (dot notation), list… [more](https://github.com/tunnckocore/to-file-path#readme) | [homepage](https://github.com/tunnckocore/to-file-path#readme "Create a filepath from an object path (dot notation), list of arguments, array, number or Arguments object.") |
| 167 | + |
| 168 | +**[back to top](#readme)** |
| 169 | + |
| 170 | +## Contributing |
| 171 | + |
| 172 | +### Guides and Community |
| 173 | + |
| 174 | +Please read the [Contributing Guide][contributing-url] and [Code of |
| 175 | +Conduct][code_of_conduct-url] documents for advices. |
| 176 | + |
| 177 | +For bug reports and feature requests, please join our [community][community-url] |
| 178 | +forum and open a thread there with prefixing the title of the thread with the |
| 179 | +name of the project if there's no separate channel for it. |
| 180 | + |
| 181 | +Consider reading the |
| 182 | +[Support and Release Policy](https://github.com/tunnckoCoreLabs/support-release-policy) |
| 183 | +guide if you are interested in what are the supported Node.js versions and how |
| 184 | +we proceed. In short, we support latest two even-numbered Node.js release lines. |
| 185 | + |
| 186 | +### Support the project |
| 187 | + |
| 188 | +[Become a Partner or Sponsor?][kofi-url] :dollar: Check the **OpenSource** |
| 189 | +Commision (tier). :tada: You can get your company logo, link & name on this |
| 190 | +file. It's also rendered on package's page in [npmjs.com][npmv-url] and |
| 191 | +[yarnpkg.com](https://yarnpkg.com/en/package/ip-filter) sites too! :rocket: |
| 192 | + |
| 193 | +Not financial support? Okey! |
| 194 | +[Pull requests](https://github.com/tunnckoCoreLabs/contributing#opening-a-pull-request), |
| 195 | +stars and all kind of |
| 196 | +[contributions](https://opensource.guide/how-to-contribute/#what-it-means-to-contribute) |
| 197 | +are always welcome. :sparkles: |
| 198 | + |
| 199 | +## Contributors |
| 200 | + |
| 201 | +This project follows the |
| 202 | +[all-contributors](https://github.com/all-contributors/all-contributors) |
| 203 | +specification. Contributions of any kind are welcome! |
| 204 | + |
| 205 | +Thanks goes to these wonderful people |
| 206 | +([emoji key](https://allcontributors.org/docs/en/emoji-key)), consider showing |
| 207 | +your [support](#support-the-project) to them: |
| 208 | + |
| 209 | +<!-- ALL-CONTRIBUTORS-LIST:START --> |
| 210 | +<!-- prettier-ignore-start --> |
| 211 | +<!-- markdownlint-disable --> |
| 212 | +<table> |
| 213 | + <tr> |
| 214 | + <td align="center"><a href="https://tunnckoCore.com"><img src="https://avatars3.githubusercontent.com/u/5038030?v=4" width="100px;" alt=""/><br /><sub><b>Charlike Mike Reagent</b></sub></a><br /><a href="#infra-tunnckoCore" title="Infrastructure (Hosting, Build-Tools, etc)">🚇</a> <a href="https://github.com/node-formidable/node-formidable/commits?author=tunnckoCore" title="Code">💻</a> <a href="https://github.com/node-formidable/node-formidable/commits?author=tunnckoCore" title="Documentation">📖</a> <a href="#ideas-tunnckoCore" title="Ideas, Planning, & Feedback">🤔</a> <a href="#maintenance-tunnckoCore" title="Maintenance">🚧</a> <a href="https://github.com/node-formidable/node-formidable/commits?author=tunnckoCore" title="Tests">⚠️</a></td> |
| 215 | + </tr> |
| 216 | +</table> |
| 217 | + |
| 218 | +<!-- markdownlint-enable --> |
| 219 | +<!-- prettier-ignore-end --> |
| 220 | + |
| 221 | +<!-- ALL-CONTRIBUTORS-LIST:END --> |
| 222 | + |
| 223 | +**[back to top](#readme)** |
| 224 | + |
| 225 | +## License |
| 226 | + |
| 227 | +Copyright (c) 2015-present, |
| 228 | +[ Charlike Mike Reagent]( https: //tunnckocore.com) `<[email protected]>` |
| 229 | +& [contributors](#wonderful-contributors).<br> Released under the |
| 230 | +[MPL-2.0 License][license-url]. |
| 231 | + |
| 232 | +<!-- badges --> |
| 233 | + |
| 234 | +<!-- prettier-ignore-start --> |
| 235 | + |
| 236 | +[contributing-url]: https://github.com/tunnckoCore/opensource/blob/master/CONTRIBUTING.md |
| 237 | +[code_of_conduct-url]: https://github.com/tunnckoCore/opensource/blob/master/CODE_OF_CONDUCT.md |
| 238 | + |
| 239 | +<!-- Heading badges --> |
| 240 | + |
| 241 | +[npmv-url]: https://www.npmjs.com/package/ip-filter |
| 242 | +[npmv-img]: https://badgen.net/npm/v/ip-filter?icon=npm&cache=300 |
| 243 | + |
| 244 | +[license-url]: https://github.com/tunnckoCore/opensource/blob/master/packages/ip-filter/LICENSE |
| 245 | +[license-img]: https://badgen.net/npm/license/ip-filter?cache=300 |
| 246 | + |
| 247 | +[libera-manifesto-url]: https://liberamanifesto.com |
| 248 | +[libera-manifesto-img]: https://badgen.net/badge/libera/manifesto/grey |
| 249 | + |
| 250 | +<!-- Front line badges --> |
| 251 | + |
| 252 | +[codecoverage-img]: https://badgen.net/badge/coverage/unknown/grey?icon=codecov&cache=300 |
| 253 | + |
| 254 | +[codecoverage-url]: https://codecov.io/gh/tunnckoCore/opensource |
| 255 | + |
| 256 | +[codestyle-url]: https://github.com/airbnb/javascript |
| 257 | +[codestyle-img]: https://badgen.net/badge/code%20style/airbnb/ff5a5f?icon=airbnb&cache=300 |
| 258 | + |
| 259 | +[linuxbuild-url]: https://github.com/tunnckocore/opensource/actions |
| 260 | +[linuxbuild-img]: https://badgen.net/github/checks/tunnckoCore/opensource/master?cache=300&label=build&icon=github |
| 261 | + |
| 262 | +[ccommits-url]: https://conventionalcommits.org/ |
| 263 | +[ccommits-img]: https://badgen.net/badge/conventional%20commits/v1.0.0/green?cache=300 |
| 264 | + |
| 265 | +[standard-release-url]: https://github.com/standard-release/standard-release |
| 266 | +[standard-release-img]: https://badgen.net/badge/semantically/released/05c5ff?cache=300 |
| 267 | + |
| 268 | +[community-img]: https://badgen.net/badge/join/community/7b16ff?cache=300 |
| 269 | +[community-url]: https://github.com/tunnckocorehq/community |
| 270 | + |
| 271 | +[last-commit-img]: https://badgen.net/github/last-commit/tunnckoCore/opensource/master?cache=300 |
| 272 | +[last-commit-url]: https://github.com/tunnckoCore/opensource/commits/master |
| 273 | + |
| 274 | +[nodejs-img]: https://badgen.net/badge/node/>=10.13/green?cache=300 |
| 275 | + |
| 276 | +[downloads-weekly-img]: https://badgen.net/npm/dw/ip-filter?icon=npm&cache=300 |
| 277 | +[downloads-monthly-img]: https://badgen.net/npm/dm/ip-filter?icon=npm&cache=300 |
| 278 | +[downloads-total-img]: https://badgen.net/npm/dt/ip-filter?icon=npm&cache=300 |
| 279 | + |
| 280 | +[renovateapp-url]: https://renovatebot.com |
| 281 | +[renovateapp-img]: https://badgen.net/badge/renovate/enabled/green?cache=300 |
| 282 | + |
| 283 | +[prs-welcome-img]: https://badgen.net/badge/PRs/welcome/green?cache=300 |
| 284 | +[prs-welcome-url]: http://makeapullrequest.com |
| 285 | + |
| 286 | +<!-- TODO: update icon --> |
| 287 | + |
| 288 | +[paypal-url]: https://www.paypal.com/cgi-bin/webscr?cmd=_s-xclick&hosted_button_id=HYJJEZNSGAPGC&source=url |
| 289 | +[paypal-img]: https://badgen.net/badge/PayPal/donate/003087?cache=300&icon=https://simpleicons.now.sh/paypal/fff |
| 290 | + |
| 291 | +<!-- TODO: update icon --> |
| 292 | + |
| 293 | +[kofi-url]: https://ko-fi.com/tunnckoCore |
| 294 | +[kofi-img]: https://badgen.net/badge/Buy%20me/a%20coffee/29abe0c2?cache=300&icon=https://rawcdn.githack.com/tunnckoCore/badgen-icons/f8264c6414e0bec449dd86f2241d50a9b89a1203/icons/kofi.svg |
| 295 | + |
| 296 | +<!-- TODO: update icon --> |
| 297 | + |
| 298 | +[bitcoin-url]: https://www.blockchain.com/btc/payment_request?address=3QNHKun1K1SUui1b4Z3KEGPPsWC1TgtnqA&message=Open+Source+Software&amount_local=10¤cy=USD |
| 299 | +[bitcoin-img]: https://badgen.net/badge/Bitcoin%20tip/3QNHKun...b4Z3KEGPPsWC1TgtnqA/yellow?cache=300&icon=https://simpleicons.now.sh/bitcoin/fff |
| 300 | +[keybase-url]: https://keybase.io/tunnckoCore |
| 301 | +[keybase-img]: https://badgen.net/keybase/pgp/tunnckoCore?cache=300 |
| 302 | +[twitter-url]: https://twitter.com/tunnckoCore |
| 303 | +[twitter-img]: https://badgen.net/twitter/follow/tunnckoCore?icon=twitter&color=1da1f2&cache=300 |
| 304 | +[patreon-url]: https://www.patreon.com/bePatron?u=5579781 |
| 305 | +[patreon-img]: https://badgen.net/badge/Become/a%20patron/F96854?icon=patreon |
| 306 | + |
| 307 | +<!-- [patreon-img]: https://badgen.net/badge/Patreon/tunnckoCore/F96854?icon=patreon --> |
| 308 | + |
| 309 | +[patreon-sponsor-img]: https://badgen.net/badge/become/a%20sponsor/F96854?icon=patreon |
| 310 | +[twitter-share-url]: https://twitter.com/intent/tweet?text=https://ghub.now.sh/ip-filter&via=tunnckoCore |
| 311 | +[twitter-share-img]: https://badgen.net/badge/twitter/share/1da1f2?icon=twitter |
| 312 | +[open-issue-url]: https://github.com/tunnckoCore/opensource/issues/new |
| 313 | +[tunnckocore_legal]: https://badgen.net/https/liam-badge-daknys6gadky.runkit.sh/com/legal/tunnckocore?label&color=A56016&icon=https://svgshare.com/i/Dt6.svg |
| 314 | +[tunnckocore_consulting]: https://badgen.net/https/liam-badge-daknys6gadky.runkit.sh/com/consulting/tunnckocore?label&color=07ba96&icon=https://svgshare.com/i/Dt6.svg |
| 315 | +[tunnckocore_security]: https://badgen.net/https/liam-badge-daknys6gadky.runkit.sh/com/security/tunnckocore?label&color=ed1848&icon=https://svgshare.com/i/Dt6.svg |
| 316 | +[tunnckocore_opensource]: https://badgen.net/https/liam-badge-daknys6gadky.runkit.sh/com/opensource/tunnckocore?label&color=ff7a2f&icon=https://svgshare.com/i/Dt6.svg |
| 317 | +[tunnckocore_newsletter]: https://badgen.net/https/liam-badge-daknys6gadky.runkit.sh/com/newsletter/tunnckocore?label&color=5199FF&icon=https://svgshare.com/i/Dt6.svg |
| 318 | + |
| 319 | +<!-- prettier-ignore-end --> |
| 320 | + |
| 321 | +[ip-filter]: https://github.com/tunnckocore/ip-filter |
| 322 | +[is-match]: https://github.com/jonschlinkert/is-match |
| 323 | +[koa]: https://github.com/koajs/koa |
| 324 | +[micromatch]: https://github.com/micromatch/micromatch |
0 commit comments