@flmnt/bantam

bantam

Bantam is an extensible, ultra lightweight, NodeJS framework for creating RESTful microservices.

Features include:

• built on top of Koa
• built with Typescript (works with vanilla JS)
• simple REST routing
• segregated business logic
• convention over configuration paradigm
• expressive logging (decent error reporting!)
• live reloading in developer mode

Need to build a Python microservice? Check out Pantam

Getting started

Our goal with Bantam is reduce the work bootstrapping microservices.

With Bantam you can create a basic REST API in 5 minutes or less.

Examples

• Domain segregated example
• Event based example
• Typescript example

Installation

First, install the required packages.

For Typescript:

% npm i @flmnt/bantam ts-node ts-node-dev typescript
% npm i @types/node @types/koa @types/koa-bodyparser @types/koa-router

Or for Javascript:

% npm i @flmnt/bantam node-dev

Once you have installed Bantam you can initialise your app; this can be done with either a brand new or existing app.

% npx @flmnt/bantam init

Follow the CLI instructions and then start building your microservice!

Setup

Bantam expects the following folder structure:

| index.ts       // can have any name, it's where you run your app
| actions        // where your domain logic sits
|  |  index.ts   // primary logic lives here (might be all you need)
|  |  other.ts   // add as many other "domains" as you like (optional)

In the root level index.ts file add the following to run Bantam:

import Bantam from '@flmnt/bantam';

const app = new Bantam();

app.run();

In the actions folder create the following files.

actions/index.ts

class Index {

  fetchAll: (ctx) => { ... },

  fetchSingle: (id, ctx) => { ... },

  create: (data, ctx) => { ... },

  update: (id, data, ctx) => { ... },

  delete: (id, ctx) => { ... },

}

actions/other.ts

class Other {

  fetchSingle: (id, ctx) => { ... },

  create: (data, ctx) => { ... },

  // NB: add as few methods as you need...

}

The setup above will make the following routes available:

GET      /            // Index.fetchAll()
GET      /:id         // Index.fetchSingle()
POST     /            // Index.create()
PATCH    /:id         // Index.update()
DELETE   /:id         // Index.delete()

GET      /other/:id   // Other.fetchSingle()
POST     /other       // Other.create()

And that's you ready to go!

Development

Start the development server with:

% npx @flmnt/bantam serve --dev

Your application will be served on http://localhost:3000

In development mode, when you make changes to files the application will update itself.

Production

To serve your microservice in production use:

% npx @flmnt/bantam serve

Your application is served at http://your-host:3000

You can change the port number via the configuration options.

.bantamrc.js

After running npx @flmnt/bantam init you will have a .bantamrc.js file in your directory with some CLI config options like this:

module.exports = {
  actionsFolder: 'actions',
  language: 'typescript',
  entrypoint: 'index.js',
};

The .bantamrc file provides configuration options for the CLI. You only need to change it if you switch language, change your main file (entrypoint) or rename your actions folder.

Add New Routes

To add a new action (resource) you can either create a new file in the actions folder or use the CLI to make the file for you:

% npx @flmnt/bantam action index.ts

You can add the standard methods (fetchAll, fetchSingle, create, update, delete) to an action class which will automatically create the standard routes.

If you'd like to create custom methods for your action class you can create custom getters like this:

// GET -> /custom-method/
getCustomMethod(ctx) {
  return ctx.body = 'Custom response';
}

And custom setters like this:

// POST -> /custom-method/
setCustomMethod(data, ctx) {
  console.log(data);
  return ctx.body = 'Custom response';
}

From version 0.2.0 onwards you can also create a do method, which is a custom post method that also expects an identifier as part of the url.

// POST -> /custom-method/{id}
doCustomMethod(id, data, ctx) {
  console.log(id, data);
  return ctx.body = 'Custom response';
}

Bantam will ignore methods that are not "standard" methods or do not start with get or set. However if you want to ensure that your method will be ignored you can prefix the method with an underscore, like this:

_myHiddenMethod() {
  // do something secret
}

Creating Responses

Each method in an action file is passed a context (ctx) argument which you use to build a response. You can read the Koa context API here.

Creating standard responses is very straightforward.

fetchAll(ctx) {
  ctx.body = 'Your response here';
}

Changing status code is also simple.

fetchAll(ctx) {
  ctx.body = 'Your response here';
  ctx.status = 201;
}

Adjusting headers requires you to use the ctx.set() method.

fetchAll(ctx) {
  ctx.body = 'Your response here';
  ctx.status = 201;
  ctx.set('Cache-Control', 'no-cache');
}

Async/Await Support

Feel free to create synchronous or asynchronous action, methods. Bantam can handle both.

async getAsyncExample() {
  const result = await findRecords();
  ctx.body = result;
}

getSyncExample() {
  ctx.body = 'static content';
}

Configuration Options

For advanced configuration pass an options object when instantiating Bantam.

import Bantam from '@flmnt/bantam';

const options = {
  port: 80,
  ...
};

const app = new Bantam(options);

app.run();

The options object can have the following properties:

port: integer

Sets the port number when serving the app in production mode.

Default: 3000

devPort: integer

Sets the port number when serving the app in development mode.

Default: 3000

actionsFolder: string

The folder that contains your action files.

Default: "actions"

actionsIndexFile: string

The primary action file in your action folder.

Default: "index"

actionsFileExt: string

The file extension for action files.

Default: "ts"

onShutdown: () => Promise<void>

Asynchronous function called prior to shutdown.

Default: "async () => {})"

Extending Bantam

Bantam has been built on top of Koa, to expose the Koa application and extend Bantam's functionality you can do the following:

import Bantam from '@flmnt/bantam';

const app = new Bantam();

app.extend((koaApp) => {

  koaApp.use(async (ctx, next) => {
    // your code here...
    await next();
  });

  return koaApp;
});

app.run();

If you need to add middlewear to specific routes, you'll likely want to interact with the Bantam router, which is provided by Koa Router.

import Bantam from '@flmnt/bantam';

const app = new Bantam();

app.extend((koaApp, koaRouter) => {

  koaApp.use(initMiddlewear());

  koaRouter.use('/url', useMiddlewear());

  return [koaApp, koaRouter];
});

app.run();

NB: if you adjust the router as well as the Koa app, make sure your callback returns an array with the app and then the router (in that order)

Debugging

If you're struggling to debug and issue and unsure what routes Bantam has created for you, you can use logRoutes() to find out.

const app = new Bantam();

app.run().then((app) => {
  app.logRoutes();
});

Also check trailing slashes in your urls, these are important.

In the example below the url test/1 and test/custom-method both trigger fetchSingle() but the url test/custom-method/ (with the trailing slash) triggers getCustomMethod().

// actions/test.js

// GET -> test/custom-method
// GET -> test/:id
fetchSingle() {}

// GET -> test/custom-method/
getCustomMethod() {}

Contribution

We welcome feedback, suggestions and contributions.

If you have an idea you want to discuss please open an issue.

Licenses

Free for personal and commerical use under the MIT License

Basil the Bantam was created with a free vector from Vectorportal.com

Changelog

[1.1.2] - 2021-04-07

Added

• Log every request for easier debugging