⚡ conductive

Pseudo Express.js framework for quickly & easily building RESTful APIs.

The Conductive framework is a collection of helpful components used for building APIs on top of Express.js.

These components are aimed to help maintain readability and reduce complexity across various applications.

Installation

npm install --save conductive

Router

The router is a higher-order function used for describing API routes & their functions.

It accepts a function as an argument, and passes the route() function back as a parameter.

You can find the full API documentation here.

import express from "express"
import { router } from "conductive"
import { validateToken } from "../middleware"

const authRouter = router((route) => {
  route({
    path: "/login",
    method: "POST",
    handler: async (request, response) => {
      // TODO: Implement login functionality.
    },
  })

  route({
    path: "/logout",
    method: "POST",
    middleware: [validateToken],
    handler: async (request, response) => {
      // TODO: Implement logout functionality.
    },
  })
})

const app = express()
app.use("/auth", authRouter)
app.listen(1337)

Errors

Conductive comes bundled with a useful set of error classes to help improve code readability.

These errors all extend the HTTPError class, which in turn extend the standard Javascript Error class.

You can find the full list of included errors here.

import { Unauthorized } from "conductive/errors"

export default async (request, response) => {
  throw new Unauthorized()
}

Error Messages

The included error messages are designed to be as generic as possible.

You can pass in your own message via the constructor().

import { Unauthorized } from "conductive/errors"

export default async (request, response) => {
  throw new Unauthorized("Invalid credentials!")
}

Error Handling

There are 2 middleware functions that are designed to help with error handling:

• handleNotFound - Used for throwing the NotFound error if a route can't be found.
• handleErrors - Used for handling all HTTPError messages.

import express from "express"
import { router } from "conductive"
import { handleNotFound, handleErrors } from "conductive/middleware"
import { Unauthorized } from "conductive/errors"

const exampleRouter = router((route) => {
  route({
    path: "/unauthorized",
    method: "GET",
    handler: async () => {
      throw new Unauthorized()
    },
  })

  route({
    path: "/bug",
    method: "GET",
    handler: async () => {
      throw new Error()
    },
  })
})

const app = express()
app.use(exampleRouter)
app.use(handleNotFound)
app.use(handleErrors)

app.listen(1337)

$ curl localhost:1337/unauthorized
{ "error": "Unauthorized!" }

$ curl localhost:1337/bug
{ "error": "Internal Server Error!" }

$ curl localhost:1337/abc123
{ "error": "Not Found: GET - /abc123" }

Any HTTPError errors will not be logged. However, other errors will be logged to stderr.

If an error is thrown that is not an instance of HTTPError, an InternalServerError will be thrown instead.

This is to negate the Improper Error Handling vulnerability.

Middleware

For now, Conductive includes only one other middleware function: validateRequest().

You may want to use this if you are defining your own middleware that requires schema validation.

This is the same function that is used in the router for schema validation.

You can find the full API documentation here.

import { validateRequest } from "conductive/middleware"

const validate = validateRequest({
  headers: {
    type: "object",
    required: ["authorization"],
    properties: {
      authorization: { 
        type: "string" 
      },
    },
  },
});

export const authenticateViaBearerToken = async (request, response) => {
  validate(request)

  const { authorization } = request.headers;
  // TODO: Implement authentication.
}