meseret

Opinionated, feature-packed professional node.js server framework.

Meseret is a framework designed from the ground up to allow easy professional-grade node.js server configuration setup (code-wise).

Here are some of its features:

Server Setup:

• Koa server with preconfigured compression, static serving & caching, body parsing (JSON and forms), direct JSON response, console logging and session support.
• Support for more Koa middleware, and koa-router routes.
• Listening on multiple HTTP and/or HTTPS servers.
• Static-serving (hosting) multiple public directories.

Database Models:

• MongoDB connection and Mongoose models.
• A ModelFactory for type enabled Mongoose schema paths, methods and statics: bringing static-type support (and IDE auto-complete) to the data schema.
• GridFS support to store small and large files in MongoDB.

WebSocket Support:

• Socket.io integration support (connects SocketIO.Servers to the ServerApp).

Single Page Application Support:

• Serves any SPA file.
• Serves build files of SPA front-end projects, built using frameworks such as Angular and React, even when in different packages.
• All 404 responses can be redirected to an SPA file, if specified.

Coding Style:

• TypeScript everywhere.
• Configuration-based architecture (using TypeScript code).

Installation

Inside a Node.js package, install meseret using:

Yarn:

yarn add meseret

or NPM:

npm install meseret --save

Language

Your application code is recommended to be written in TypeScript when you use this framework.

A Simple ServerApp

A simple app that makes Koa listen on port 3000 looks like:

import { ServerApp } from 'meseret'
 
new ServerApp({
  name: 'App Name',
  httpServers: [{ port: 3000 }]
}).start() // returns a Promise

A new ServerApp receives a configuration object (called IServerAppConfig) as a parameter. The start() method launches the server application on http://localhost:3000; it returns a Promise.

A Realistic Example

We are now going to create the back-end of a small "task organization" application using meseret. Its main source file looks something like:

// src/app.ts
 
import { ServerApp } from 'meseret'
import { join } from 'path'
 
import { TasksModel } from './models/tasks.model'
import { TaskRouter } from './routers/task.router'
 
const taskOrganizer = new ServerApp({
  name: 'Task Organizer',
 
  mongoUris: process.env.MONGO_URI || 'mongodb://localhost/task-organizer',
  models: [TasksModel],
 
  publicDirs: [join(process.cwd(), 'react', 'build')],
  spaFileRelativePath: join('react', 'build', 'index.html'),
 
  routers: [TaskRouter],
 
  httpServers: [
    {
      hostname: process.env.HOSTNAME || '127.0.0.1',
      port: Number(process.env.PORT) || 3000
    }
  ]
})
 
taskOrganizer.start().catch(console.error)
 
export { taskOrganizer }
 
// optionally, you may...
export const dbConn = () => taskOrganizer.dbConn // to access the mongoose connection
export const gfs = () => taskOrganizer.grid // to access GridFS from other files
export const app = () => taskOrganizer.app // the Koa application instance

In this code, we imported a ServerApp from meseret and created an instance (taskOrganizer) by passing it a (config: IServerAppConfig) as its first parameter. Then we called start() on taskOrganizer to launch our application based on the config we provided it. This configuration we passed to the ServerApp is the most important piece of code here. The job the ServerApp performs when start() is called will be discussed later in detail at the end of this example project.

Now we are moving our attention to the mongoose database model that's imported and used in taskOrganizer (the TasksModel). When it comes to models, it is recommended that we use the ModelFactory from meseret. Although this method is optional and relatively verbose when compared to pure mongoose, it provides support for static-typing and auto-completing mongoose models in IDEs, even deep down to the data schema level. The code for TasksModel looks something like:

// src/models/tasks.model
 
import { ModelFactory, FunctionsType } from 'meseret'
 
export interface ITasksSchemaPaths {
  desc: string
  done: boolean
}
 
export interface ITasksSchemaMethods extends FunctionsType {
  tickToggle: () => Promise<boolean>
}
 
export interface ITasksSchemaStatics extends FunctionsType {} // empty for now
 
const factory = new ModelFactory<
  ITasksSchemaPaths,
  ITasksSchemaMethods,
  ITasksSchemaStatics
>({
  name: 'tasks', // collection/model name
 
  paths: {
    desc: { type: String, required: true, trim: true },
    done: { type: Boolean, required: true, default: false }
  },
 
  methods: {
    async tickToggle(): Promise<boolean> {
      const task = factory.documentify(this) // for static-type support of the `this` in this document's context
      task.done = !task.done
      await task.save()
      return task.done
    }
  },
 
  statics: {
    // empty for now
    // `factory.modelify(this)` is available in functions here, for static-type support of the `this` in this model's context
  }
})
 
// optionally, you may manually also access the built schema
export const TasksSchema = factory.schema
 
// finally, create & export the model
export const TasksModel = factory.model
TasksModel.collection.createIndex({ '$**': 'text' }).catch(console.error)

In the code above, the ModelFactory is imported from meseret and used to create an instance called factory. It receives three types to support type-checks and auto-complete of the data schema here and elsewhere in the project. These types represent the mongoose schema's paths, methods and statics, respectively. In the code above, these types are interfaces, namely ITasksSchemaPaths, ITasksSchemaMethods and ITasksSchemaStatics in order.

As you can see above the methods' and statics' type interfaces extend FunctionsType from meseret. This is essential to guarantee that the mongoose method and static functions defined in the factory have valid signatures as their interface/type definitions above.

However, meseret does not currently support this guaranteed match between the type definition and actual implementation for schema paths (it's in the works... shh!). Until this gets support, developers should manually check if their path interfaces match their paths definition.

TIP: If you have an empty paths, methods or statics you may pass just {} to the ModelFactory. Therefore, our code above could have eliminated the ITasksSchemaStatics and the factory would have been defined as:

const factory = new ModelFactory<ITasksSchemaPaths, ITasksSchemaMethods, {}>({

Just like the ServerApp, meseret's ModelFactory receives an object (this time, whose type is IModelFactoryConfig). This object configures the name of the mongoose model (which is required) and, optionally, the paths, methods and statics for the model.

Inside the mongoose method and static function definitions, the this keyword represents the document and model, respectively. Meseret adds static-type support to these thiss using factory.documentify(this) and factory.modelify(this), respectively.

Finally, we see the factory.model code at the very last line. The ModelFactory's .model is a getter that generates a normal mongoose model based on the IModelFactoryConfig provided earlier. It is to be used elsewhere in our project, just like a normal mongoose model would have been.

Moving on...

Below is how we create the koa-routers used in the ServerApp. Nothing out of the ordinary here.

// src/routers/task.router
 
import * as Router from 'koa-router'
import { TasksModel } from '../models/tasks.model'
 
const TaskRouter = new Router({ prefix: '/api/task' })
 
// POST /api/task/new
TaskRouter.get('/new', async ctx => {
  ctx.body = await TasksModel.create(ctx.request.body)
})
 
// GET /api/task/all
TaskRouter.get('/all', async ctx => {
  ctx.body = await TasksModel.find({})
})
 
// GET /api/task/one/:_id
TaskRouter.get('/one/:_id', async ctx => {
  ctx.body = await TasksModel.findById(ctx.params._id)
})
 
// ... more route definitions
 
export { TaskRouter }

To recap, the above router (TaskRouter) and the model (TasksModel) are included in the ServerApp (taskOrganizer). When the taskOrganizer is started, it:

1. connects to a MongoDB server at a specified MONGO_URI environment variable (or defaults to mongodb://localhost/task-organizer),
2. loads configured Mongoose database models (TasksModel),
3. launches an HTTP Koa server at a specified HOSTNAME and PORT environment variables (or defaults to http://127.0.0.1:3000),
4. serves the static directory ./react/build/,
5. serves an SPA from ./react/build/index.html, and
6. handles requests that match definitions in TaskRouter.

Based on this and the default configuration, the started ServerApp implicitly takes care of:

• Koa Context body parsing (using koa-body),
• caching static requests (using koa-static-cache),
• response GZip compression (using koa-compress),
• JSON format responses (using koa-json),
• logging every request and response (using koa-logger), and
• creating a GridFSStream instance based on the MongoDB connection (using gridfs-stream).

In addition, a keys option can be provided to set Koa ctx.keys for signing cookies. If the keys are set, session support will be enabled automatically (using koa-session).

These features can be explicitly turned off (or modified) inside the config parameter of the ServerApp instance.

Besides the above built-in feature middleware packages, you may specify your own Koa middleware in the config to be used for each HTTP and/or HTTPS requests. You can also find the original Koa application instance using taskOrganizer.app, among many other variables.

Whew!

API

IServerAppConfig Options

The name option is the only required of all the IServerAppConfig options. Below is a list of all the available options:

P.S. more API documentation is coming soon.

Licence

Made with ♥ in Addis Ababa.

MIT License © 2017-2018 Kaleab S. Melkie.