Skip to content

Commit 3e51da8

Browse files
jkyberneeesjkyberneees
committed
refactoring documentation
1 parent 8d986c1 commit 3e51da8

File tree

4 files changed

+191
-102
lines changed

4 files changed

+191
-102
lines changed

‎README.md‎

Lines changed: 18 additions & 102 deletions
Original file line numberDiff line numberDiff line change
@@ -1,17 +1,21 @@
1-
# middleware-if-unless
2-
Invokes connect-like middleware if / unless routing criteria matches. Inspired on [express-unless](https://www.npmjs.com/package/express-unless) module.
3-
>
1+
# Introduction
2+
Invokes connect-like middleware if / unless routing criteria match.
3+
> Inspired by the [express-unless](https://www.npmjs.com/package/express-unless) module.
44
55
## Main features
66
- Advanced routes matching capabilities. Uses [find-my-way](https://www.npmjs.com/package/find-my-way) or any compatible router to match the routes.
7-
- `iff`: execute middleware only if the routes matches. Ideal use case: API gateways (see: [fast-gateway](https://www.npmjs.com/package/fast-gateway))
8-
- `unless`: execute middleware always unless the routes matches.
9-
- Arbitraty chaining of iff -> unless of vice-versa.
10-
- Low overhead, crazy fast implementation.
7+
- `iff`: execute middleware only if routing criteria is a match. Ideal use case: API gateways (see: [fast-gateway](https://www.npmjs.com/package/fast-gateway))
8+
- `unless`: execute middleware unless routing criteria is a match.
9+
- Arbitraty chaining of `iff -> unless` of vice-versa.
10+
- Low overhead, blazing fast implementation.
1111

12+
# Usage
13+
Install
14+
```bash
15+
npm i middleware-if-unless
16+
```
1217

13-
# Usage example
14-
How to extend any connect-like middleware:
18+
Extending middleware
1519
```js
1620
const iu = require('middleware-if-unless')()
1721

@@ -25,7 +29,7 @@ const middleware = function (req, res, next) {
2529
iu(middleware)
2630
```
2731
## unless
28-
Execute middleware unless routing restrictions matches:
32+
Execute middleware unless routing criteria is a match:
2933
```js
3034
const app = require('express')()
3135
app.use(middleware.unless([
@@ -36,8 +40,8 @@ app.use(middleware.unless([
3640
```
3741
In this example, all requests except `[GET] /not/allowed/to/hit` will cause the middleware to be executed.
3842

39-
## if
40-
Execute middleware only if routing restrictions matches:
43+
## iff
44+
Execute middleware only if routing criteria is a match:
4145
```js
4246
const app = require('express')()
4347
app.use(middleware.iff([
@@ -50,94 +54,6 @@ app.use(middleware.iff([
5054
...
5155
```
5256
In this example, only a `[POST|DELETE|PUT|PATCH] /tasks/:id` request will cause the middleware to be executed.
53-
### Chaining
54-
You can optionally chain iff -> unless or vice-versa:
55-
```js
56-
app.use(middleware
57-
.iff(req => req.url.startsWith('/pets')) // 4 check
58-
.iff([ // 3 check
59-
'/pets/*',
60-
'/pets/:id/*'
61-
]).unless([ // 2 check
62-
'/pets/:id/owners',
63-
{
64-
url: '/pets/:id', methods: ['DELETE']
65-
}
66-
]).unless(req => req.url.endsWith('.js')) // 1 check
67-
)
68-
```
69-
# Configuration
70-
## module
71-
```js
72-
const iu = require('middleware-if-unless')(
73-
// optional router configuration:
74-
// https://www.npmjs.com/package/find-my-way#findmywayoptions
75-
{
76-
}
77-
,
78-
// optional router factory:
79-
// allows to override find-my-way as default router
80-
function(opts){}
81-
)
82-
```
83-
### Known compatible routers:
84-
- https://www.npmjs.com/package/find-my-way
85-
- https://www.npmjs.com/package/anumargak
8657

87-
## iff / unless
88-
Both methods share the same configuration format:
89-
90-
### - routing criteria is a function
91-
```js
92-
middleware.iff(req => req.url.startsWith('/pets'))
93-
```
94-
### - routing criteria is an array of routes
95-
```js
96-
middleware.iff([
97-
'/login', // if string is passed, the GET method is inferred
98-
{
99-
methods: ['DELETE', 'POST', '...'],
100-
url: '/tasks/:id/*'
101-
}
102-
])
103-
```
104-
### - routing criteria is an object
105-
```js
106-
middleware.unless({ endpoints: [
107-
'/login', // if string is passed, the GET method is inferred
108-
{
109-
methods: ['DELETE', 'POST', '...'],
110-
url: '/tasks/:id/*'
111-
}
112-
]})
113-
```
114-
#### Supporting Accept-Version header
115-
Optionally, you can also restrict your middleware execution to specific versions using the `Accept-Version` header:
116-
> The `version` value should follow the [semver](https://semver.org/) specification.
117-
```js
118-
middleware.iff({ endpoints: [
119-
{
120-
methods: ['GET'],
121-
url: '/tasks/:id',
122-
version: '2.0.0'
123-
}
124-
]})
125-
```
126-
In the example, a `GET /tasks/:id` request will only execute the middleware if the `Accept-Version` header matches `2.0.0`. For example:
127-
- Accept-Version=2.0.0
128-
- Accept-Version=2.x
129-
- Accept-Version=2.0.x
130-
131-
#### Updatings requests params object
132-
Optionally, you can override the `req.params` object with the parameters of the matching route defined on your configs:
133-
```js
134-
middleware.iff({ endpoints: [
135-
{
136-
methods: ['GET'],
137-
url: '/tasks/:id',
138-
version: '2.0.0',
139-
updateParams: true // enabling this config will result in req.params = {id: ...}
140-
}
141-
]})
142-
```
143-
> This feature can be really useful for business specific middlewares using the `iff` matching type.
58+
# More
59+
- Website and documentation: https://iff-unless.21no.de

‎docs/.nojekyll‎

Whitespace-only changes.

‎docs/README.md‎

Lines changed: 151 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,151 @@
1+
# Introduction
2+
Invokes connect-like middleware if / unless routing criteria match.
3+
> Inspired by the [express-unless](https://www.npmjs.com/package/express-unless) module.
4+
5+
## Main features
6+
- Advanced routes matching capabilities. Uses [find-my-way](https://www.npmjs.com/package/find-my-way) or any compatible router to match the routes.
7+
- `iff`: execute middleware only if routing criteria is a match. Ideal use case: API gateways (see: [fast-gateway](https://www.npmjs.com/package/fast-gateway))
8+
- `unless`: execute middleware unless routing criteria is a match.
9+
- Arbitraty chaining of `iff -> unless` of vice-versa.
10+
- Low overhead, blazing fast implementation.
11+
12+
# Usage
13+
Install
14+
```bash
15+
npm i middleware-if-unless
16+
```
17+
18+
Extending middleware
19+
```js
20+
const iu = require('middleware-if-unless')()
21+
22+
const middleware = function (req, res, next) {
23+
res.body = 'hit'
24+
25+
return next()
26+
}
27+
28+
// extend middleware with iff/unless capabilities
29+
iu(middleware)
30+
```
31+
## unless
32+
Execute middleware unless routing criteria is a match:
33+
```js
34+
const app = require('express')()
35+
app.use(middleware.unless([
36+
'/not/allowed/to/hit'
37+
]))
38+
39+
...
40+
```
41+
In this example, all requests except `[GET] /not/allowed/to/hit` will cause the middleware to be executed.
42+
43+
## iff
44+
Execute middleware only if routing criteria is a match:
45+
```js
46+
const app = require('express')()
47+
app.use(middleware.iff([
48+
{
49+
methods: ['POST', 'DELETE', 'PUT', 'PATCH'],
50+
url: '/tasks/:id'
51+
}
52+
]))
53+
54+
...
55+
```
56+
In this example, only a `[POST|DELETE|PUT|PATCH] /tasks/:id` request will cause the middleware to be executed.
57+
# Chaining
58+
You can optionally chain iff -> unless or vice-versa:
59+
```js
60+
app.use(middleware
61+
.iff(req => req.url.startsWith('/pets')) // 4 check
62+
.iff([ // 3 check
63+
'/pets/*',
64+
'/pets/:id/*'
65+
]).unless([ // 2 check
66+
'/pets/:id/owners',
67+
{
68+
url: '/pets/:id', methods: ['DELETE']
69+
}
70+
]).unless(req => req.url.endsWith('.js')) // 1 check
71+
)
72+
```
73+
# Configuration
74+
```js
75+
const iu = require('middleware-if-unless')(
76+
// optional router configuration:
77+
// https://www.npmjs.com/package/find-my-way#findmywayoptions
78+
{
79+
}
80+
,
81+
// optional router factory:
82+
// allows to override find-my-way as default router
83+
function(opts){}
84+
)
85+
```
86+
Known compatible routers:
87+
- https://www.npmjs.com/package/find-my-way
88+
- https://www.npmjs.com/package/anumargak
89+
90+
## iff / unless
91+
Both methods use the same signature/contract.
92+
93+
### Matching criteria is a function
94+
```js
95+
middleware.iff(req => req.url.startsWith('/pets'))
96+
```
97+
### Matching criteria is an array of routes
98+
```js
99+
middleware.iff([
100+
'/login', // if string is passed, the GET method is inferred
101+
{
102+
methods: ['DELETE', 'POST', '...'],
103+
url: '/tasks/:id/*'
104+
}
105+
])
106+
```
107+
### Matching criteria is an object
108+
```js
109+
middleware.unless({ endpoints: [
110+
'/login', // if string is passed, the GET method is inferred
111+
{
112+
methods: ['DELETE', 'POST', '...'],
113+
url: '/tasks/:id/*'
114+
}
115+
]})
116+
```
117+
### Supporting Accept-Version header
118+
Optionally, you can also restrict your middleware execution to specific versions using the `Accept-Version` header:
119+
> The `version` value should follow the [semver](https://semver.org/) specification.
120+
```js
121+
middleware.iff({ endpoints: [
122+
{
123+
methods: ['GET'],
124+
url: '/tasks/:id',
125+
version: '2.0.0'
126+
}
127+
]})
128+
```
129+
In the example, a `GET /tasks/:id` request will only execute the middleware if the `Accept-Version` header matches `2.0.0`. For example:
130+
- Accept-Version=2.0.0
131+
- Accept-Version=2.x
132+
- Accept-Version=2.0.x
133+
134+
### Updatings requests params object
135+
Optionally, you can override the `req.params` object with the parameters of the matching route defined on your configs:
136+
```js
137+
middleware.iff({ endpoints: [
138+
{
139+
methods: ['GET'],
140+
url: '/tasks/:id',
141+
version: '2.0.0',
142+
updateParams: true // enabling this config will result in req.params = {id: ...}
143+
}
144+
]})
145+
```
146+
> This feature can be really useful for business specific middlewares using the `iff` matching type.
147+
148+
# Support / Donate 💚
149+
You can support the maintenance of this project:
150+
- PayPal: https://www.paypal.me/kyberneees
151+
- [TRON](https://www.binance.com/en/buy-TRON) Wallet: `TJ5Bbf9v4kpptnRsePXYDvnYcYrS5Tyxus`

‎docs/index.html‎

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,22 @@
1+
<!DOCTYPE html>
2+
<html lang="en">
3+
<head>
4+
<meta charset="UTF-8">
5+
<title>middleware-if-unless</title>
6+
<meta http-equiv="X-UA-Compatible" content="IE=edge,chrome=1" />
7+
<meta name="description" content="Invokes connect-like middleware if / unless routing criteria match.">
8+
<meta name="viewport" content="width=device-width, initial-scale=1.0, minimum-scale=1.0">
9+
<link rel="stylesheet" href="//cdn.jsdelivr.net/npm/docsify@4/lib/themes/vue.css">
10+
</head>
11+
<body>
12+
<div id="app"></div>
13+
<script>
14+
window.$docsify = {
15+
name: 'middleware-if-unless',
16+
repo: 'https://github.com/BackendStack21/middleware-if-unless'
17+
}
18+
</script>
19+
<!-- Docsify v4 -->
20+
<script src="//cdn.jsdelivr.net/npm/docsify@4"></script>
21+
</body>
22+
</html>

0 commit comments

Comments
 (0)