# koa-router-groups

> Middleware groups for koa-router.

Latest version **1.0.0** (published 2018-12-03) · MIT license · 0 weekly downloads

## Install

```sh
npm install koa-router-groups
pnpm add koa-router-groups
yarn add koa-router-groups
bun add koa-router-groups
```

## Health

**Score 15/100 (F)** — status: abandoned.

Positive: no vulnerabilities.

Warnings: low downloads; no types; no esm support.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 1.0.0 |
| Published | 2018-12-03 |
| First published | 2018-12-03 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | none |
| Module format | CommonJS |
| Dependencies | 2 |
| Unpacked size | 11.7 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 1 |
| Author | Andraž Dobnikar |
| Maintainers | adobnikar |
| Keywords | koa, router, middleware, groups, auth, permission |

## Links

- npm: https://www.npmjs.com/package/koa-router-groups
- Repository: https://github.com/adobnikar/koa-router-groups
- Homepage: https://bitbucket.org/adobnikar/node-koa-router-groups#readme
- Issues: https://bitbucket.org/adobnikar/node-koa-router-groups/issues
- npm.io page: https://npm.io/package/koa-router-groups

## Dependencies (2)

- [lodash.isstring](https://npm.io/package/lodash.isstring.md) ^4.0.1
- [lodash.isfunction](https://npm.io/package/lodash.isfunction.md) ^3.0.9

## Alternatives

- [@clerk/clerk-expo](https://npm.io/package/@clerk/clerk-expo.md) — 133.6K weekly downloads
- [@pothos/plugin-authz](https://npm.io/package/@pothos/plugin-authz.md) — 12.4K weekly downloads
- [@bounded-sh/client](https://npm.io/package/@bounded-sh/client.md) — 3.2K weekly downloads
- [@luigi-project/plugin-auth-oauth2](https://npm.io/package/@luigi-project/plugin-auth-oauth2.md) — 2.3K weekly downloads
- [@nocobase/plugin-verification](https://npm.io/package/@nocobase/plugin-verification.md) — 2.0K weekly downloads

## Recent versions

- 1.0.0 (latest) — 2018-12-03

## README

# Middleware groups for koa-router #

## Requirements ##

- requires **node v7.6.0** or higher for ES2015 and async function support

## Installation ##

Run the npm install command:
```bash

npm i koa-router-groups --save
# or
yarn add koa-router-groups

```

After installing koa-router-groups, all you need to do is extend an existing koa router instance with the extend function.
```javascript
const Koa = require("koa");
const KoaRouter = require("koa-router");
const KoaRouterGroups = require("koa-router-groups");

let koa = new Koa();
let koaRouter = new KoaRouter();
KoaRouterGroups.extend(koaRouter);
```

## Quick Example ##

```javascript

const Koa = require("koa");
const KoaRouter = require("koa-router");
const KoaRouterGroups = require("koa-router-groups");

let app = new Koa();
let router = new KoaRouter();
KoaRouterGroups.extend(router); // Extend the router with "registerMiddleware", "pushMiddleware", "popMiddleware" and "group" functions.

// Register some middleware functions.
router.registerMiddleware("logger", async (ctx, next) => { /* Middleware function. */ });
router.registerMiddleware("body", async (ctx, next) => { /* Middleware function. */ });
router.registerMiddleware("auth", async (ctx, next) => { /* Middleware function. */ });
router.registerMiddleware("auth.admin", async (ctx, next) => { /* Middleware function. */ });
router.registerMiddleware("auth.root", async (ctx, next) => { /* Middleware function. */ });

// Push 3 middleware functions that every route will use to the stack.
router.pushMiddleware("logger", async (ctx, next) => { /* Middleware function. */ }, "body");

router.group("auth", () => {

	// ... define routes here that need to pass "auth" middleware ...

	router.group("auth.admin", () => {
		// ... define routes here that need to pass "auth" and "auth.admin" middleware ...
	});

	router.group("auth.root", () => {
		// ... define routes here that need to pass "auth" and "auth.root" middleware ...
	});
});

// Remove the 3 middlewares that were pushed to the stack.
router.popMiddleware();

app.use(router.routes()).use(router.allowedMethods());

// Start the server.
let server = app.listen(process.env.SERVER_PORT || 3000);

// ...

```

## Functions ##

### .registerMiddleware(name, middleware) ###

```javascript
/**
 * Registers the middleware so that it can be called/used with the reference name string instead of directly using the function definition.
 * 
 * @param {string} name Middleware name for reference.
 * @param {function} middleware Middleware function.
 */
```

### .pushMiddleware(...middleware) ###

```javascript
/**
 * Push a batch of middleware functions to the top of the middleware stack.
 * 
 * @param {...function} ...middleware Batch of middleware functions.
 */
```

### .popMiddleware() ###

```javascript
/**
 * Pops the batch of middleware functions that is on top of the middleware stack.
 */
```

### .group(...middleware, callback) ###

```javascript
/**
 * Group routes that use the same middleware.
 * 
 * @param {...function} ...middleware Batch of middleware functions.
 * @param {function} callback Callback wrapper function. Any routes within this function will have to pass the batch of middleware function.
 */
```

## Full Example ##

A working example can be found in this repository. You can start it by running the `example/example.js` file.
If you want to read the source of the example you can download the [example.zip](./example.zip) and extract it to a folder. The most important files in the example are `example/example.js` and `example/example-routes.js`.

### Contents of `example/example.js` - this is the server file ###

```javascript

"use strict";

const Koa = require("koa");

// Require middlewares.
const mwResponseTime = require("./middleware/response-time");
const mwLogger = require("./middleware/logger");
const mwOptions = require("./middleware/options");
const mwErrorHandler = require("./middleware/error-handler");

// Require router.
const routes = require("./example-routes");

// Server setup.
let app = new Koa(); // Create a Koa server instance.
// Define which middleware every request will have to pass through:
app.use(mwResponseTime);
app.use(mwLogger);
app.use(mwOptions);
app.use(mwErrorHandler);

// Apply routes.
let router = routes(app);

// Start the server.
let server = app.listen(process.env.SERVER_PORT || 3000);
if (server.address() === null) {
	let errMsg = 'Error: Please select a different server port by configuring the ".env" file.';
	console.error(errMsg);
	process.exit(1);
}
console.log("Server: http://127.0.0.1:" + server.address().port);

```

### Contents of `example/example-routes.js` - this is the routes file ###

```javascript

"use strict";

const KoaRouter = require("koa-router");
const KoaRouterGroups = require("koa-router-groups");

// Require middlewares.
const mwBodyParser = require("koa-bodyparser");
const mwAuth = require("./middleware/auth");

// Require controllers.
const Controller = require("./controllers/exmaple-controller");

// Route definitions.
module.exports = function (app) {
	// Create Koa Router.
	let router = new KoaRouter();
	KoaRouterGroups.extend(router); // Extend the router with "group" and "registerMiddleware" functions.
	
	// Register middlewares.
	router.registerMiddleware("body", mwBodyParser({
		jsonLimit: '50mb',
		formLimit: '50mb',
		textLimit: '50mb',
	}));
	router.registerMiddleware("auth", mwAuth);

	// Push the middleware used by all routes to the stack.
	router.pushMiddleware("body");

	// Define API functions.
	router.get("auth.login", "/login", Controller.login);

	// Auth group. Any routes in this group need to pass the "AuthMiddleware.auth" middleware.
	router.group("auth", () => {
		// Logout route.
		router.get("auth.logout", "/logout", Controller.logout);

		// Get protected data.
		router.get("data.index", "/data", Controller.index);
	});

	// Apply the routes to the app.
	app.use(router.routes()).use(router.allowedMethods());

	return router;
};

```

---
_Source: https://npm.io/package/koa-router-groups · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._