@byteshift/harmony

What is Harmony?

Harmony is a semi-opinionated zero dependency HTTP library similar to the widely used express library. The main difference is that Harmony follows the "Model View Controller" (MVC) pattern and is designed for large scale structured TypeScript applications that are hosted via a NodeJS server.

Harmony is fully extensible via "event interceptors" and can handle nearly any templating engine you throw at it. It even supports the use of cookies and sessions out of the box to allow you to focus on one thing: Building your website.

Why should I use Harmony?

The Node ecosystem is full of various sized npm packages that all do their own thing. If you wish to build a web-server that supports cookies or sessions, a templating engine, the use of authentication, firewalls, or any form of dependency injection, you'll quickly realize that your project has over 100 dependencies, not to mention the size of your node_modules directory. If you find yourself teaching yourself how to use all these different libraries and basically "hacking" things together to make it work for you, and you're tired of focusing on other things besides building your own website or application, then Harmony would probably suit you best.

If you are familiar with one of the well known PHP frameworks like Symfony or Laravel, then getting started with Harmony will be a literal walk in the park.

What do I need to know before working with Harmony?

• Harmony is fully written in TypeScript and will work the best if your project is also written in the same language.
• Harmony makes use of decorators (also known as annotations) to configure routes and which template to render.

If you are unfamiliar with either TypeScript or the use of decorators, it is recommended to read up on these topics before diving straight in.

Quick start

Setting up your Harmony server is done in just a few easy steps. To make things easier, please make sure you have TypeScript up and running in your project.

1. Installing the package

Harmony is just another NPM package and can be installed as such.

Through NPM:

$ npm i @byteshift/harmony --save

Or through Yarn:

$ yarn add @byteshift/harmony

2. Configuring & starting Harmony

// app.ts
import {Harmony} from '@byteshift/harmony';

const harmony = new Harmony({
   port: 8080,
   https: {
       enabled: false
   }
});

// Start listening for incoming connections.
harmony.start();

If you navigate to http://127.0.0.1:8080/ in your browser, you should be presented with a 404 error page. This is because no routes have been set up yet.

3. Creating your first controller

A controller in Harmony is just another TypeScript class. Methods inside this class can be annotated with the @Route decorator to automatically use them as end-points of your server.

// MyController.ts
import {Route} from './Route';

export class MyController
{
    @Route("/", {methods: ["GET"]})
    public indexAction(): HtmlResponse
    {
        return new HtmlResponse('<h1>Hello World!</h1>');
    }
}

Now that we have your first controller, we'll need to let Harmony know this particular controller exists. Let's go back to our app.ts file and make a small adjustment.

// app.ts
import {Harmony}      from '@byteshift/harmony';
import {MyController} from "./MyController";

const harmony = new Harmony({
   port: 8080,
   https: {
       enabled: false
   },
   // You can define a list of controllers here.
   // Make sure each controller class has at least one @Route configured.
   controllers: [
       MyController
   ]
});

// Start listening for incoming connections.
harmony.start();

If you want to add controllers after the setup of Harmony, you can do so by calling the registerController method on the Harmony-instance like so:

harmony.registerController(HomeController);

If you navigate to http://127.0.0.1:8080/ in your browser, you should see the "Hello World!" message that was generated by MyController.indexAction.

Diving in deeper

The examples shown in the Quick Start chapter barely scratch the surface of what is possible with Harmony. Please refer to the GitHub wiki page for more in-depth documentation about each feature of Harmony.