nextjs-api-router/README.md

Lightweight tool to build clean restful API routes for your Next.js application.

# nextjs-api-router

Lightweight router class to build spotless (restful) API route handlers for your Next.js server application.

- [Installation](#installation)
- [Usage](#usage)
- [API](#api)
  - [Router](#router)
  - [Controller](#controller)
  - [Handler](#handler)

## Installation

```bash
# npm
$ npm install next-js-api-router

# yarn
$ yarn add nextjs-api-router
```

## Usage

First create a controller object that contains all handlers for the HTTP methods you want to handle on your specific route.

```typescript
// API controller: controllers/example/index.ts

import type { Controller } from "nextjs-api-router";

const controller: Controller = {
  GET: (req, res) => {
    res.send("Hello world from nextjs-api-router!");
  },
  POST: (req, res) => {
    res.send(req.body);
  },
};

export default controller;
```

Import the controller in a new router class in the API handler file in `/pages/api/%your-route%`. Export the `router.handle` function by default to make your API work.

```typescript
// API handler: pages/api/example.ts

import { Router } from "nextjs-api-router";
import controller from "../controllers/example";

const router = new Router(controller);
export default router.handle();
```

## API

### Router

The `Router` class manages the controller object inside the class itself. By instantiating it can optionally be given a `controller` object in the constructor.

The controller can be modifiied all time with the `router.controller` property of the class. For example:

```typescript
router.controller.GET = (req, res) => {
  res.send("");
};
```

The `router.handle` function returns a function that handles the configured HTTP method handlers when sending a request to the server.

By passing handlers as arguments to the `router.use` method It's also possible to create middleware functions on the `Router` class. This middleware handler will be executed on every request to the route.

```typescript
const router = new Router(controller);

const logger = (req, res, next) => {
  console.log(req.method, Date.now()
  next();
};

router.use(logger);
```

### Controller

A controller object can be passed to the `Router` class constructor. It contains all the handlers for the HTTP methods used in the router. These handlers can be assigned singular or as an array (like middleware).

```typescript
import type { Controller, Handler } from "nextjs-api-router";

const verify: Handler = (req, res, next) => {
    // do some verification here
    next();
}

const controller: Controller {
  // Just single handler functions
  GET: (req, res) => {res.send("Hello world!")},
  DELETE: (req, res) => {res.send("Goodbye world...")},

  // Multiple handlers
  POST: [verify, (req, res) => {
    res.send("You're verified now!")
  }],
}
```

### Handler

The handler function is a function called inside the router. It has access to the request and the response of the server, and can be used as middleware, using the `next` parameter, to execute the next handler in series.

```typescript
import { Router } from 'nextjs-api-router';
import type { Controller, Handler } from "nextjs-api-router";


const logger: Handler = (req, res, next) => {
  console.log(req.method, Date.now()
  next();
};

const reply: Handler = (req, res, next) => {
  res.send("You got this!")
};

const controller: Controller {
    GET: [logger, reply]
}

const router = new Router();

// Controller can also be passed in as parameter of the handle function
export default router.handle(controller);
```