Node.js app in the real world : what they never really tell you — A 5 part series

Our use case : a REST API written in JavaScript under Node.js with a Mongodb database

I’ll use a Koa server : apart from being very elegant , Koa will allow us to implement only what we really need. We will also use an ODM (Object-Document Mapping), namely Mongoose, because this series do not intend to focus on database management.

Photo by Lachlan Donald on Unsplash

If you prefer Express or Hapi, the native Mongodb driver or even an SQL database, don’t worry too much : most of what I have to say will still hold.

Of course this series I’m introducing here will probably make a few opinionated claims here and there, but I’ll try to keep their number low for one thing, and always provide reasonable arguments. The approach outlined is one among many, but it has been thought out quite a lot and has, I feel, some coherence to it.

This series aims at developers with prior knowledge of some JavaScript, some Node.js and some design patterns, because we’ll cut short sometimes in order to get quickly to the point. Beginners should get the gist of it all though, as it follows common sense rules.

By all means this series is not a full-blown tutorial : there will be gaps for you to fill but hopefully you’ll get on track and have something to think through.

Let’s be ambitious too and try to apply some, yet not all, of the (good in most practical cases) principles of Domain-Driven Design (DDD), namely :

• A domain model where the business logic lives and with zero dependencies (to other librairies as well as to Node.js modules),
• A thin app layer with zero hard dependencies (except of course on the domain) and Dependencies Injection (DI) mechanism,
• An infrastructure layer containing all the implementation-specific code, notably data access,
• A presentation layer with an HTTPinterface for the API and a Command Line Interface (CLI) app,
• Extra thin controllers with dependency inversion principle,
• Overall Separation of Concerns(SoC),
• Single Responsibilty Principle(SRP) as much as possible,
• 100% unit test coverage,
• Dont Repeat Yourself (DRY) code as much as possible,
• Keep It Simple, Stupid (KISS) principle as much as possible,
• Aiming at open/closed principlefor classes (I will use mostly classes, more on this later), and more generally getting as close as possible from SOLID code and Inversion of Control (IoC).

But I have chosen not to use the Command Query/Read Segregation(CQRS) which is interesting but in a lot of practical cases (including our own here) overcomplicated. You’ll see throughout the series that while following a constrained architecture is obviously worthwhile in the long run, I’ll have no hesitation to deviate from the canon for practical reasons, or simply to avoid overkill.

I will define or provide quick summary of all the principles mentioned above in the various parts of the series, as our use case will unfold.

A visual representation of a highly decoupled software architecture. As stated on the picture itself, we’ll use in this series only what we (practically) need. Courtesy of Herberto Graca

All of this is certainly not trivial but very much worth doing, and it requires good planification.

In our 5 part series we will dive into the practical questions that you will face doing so. See below.

Why choosing DDD you’ll ask ? Well certainly DDD certainly means more code but adds lots of benefits that makes it more than worth : what if you want to change your database or even your ODM ? what if you want to change your server framework or even rewrite your app in another language, or package parts of it only ? DDD will allow this through the power of decoupling.

Decoupling is highly powerful indeed. In the approach I’ll take, I’ll be using dependency injection, meaning we will not rely on concrete implementation (only the infrastructure and presentation layers have dependencies). This means easy dependency swapping and vastly facilitates unit testing and code coverage. Code is more readable too.

In the app layer, you’ll see code like the one below. Concrete implementation of the remove() method is hidden :

See Gist

Oh by the way, in all our code snippets, we’ll omit (except in a few edge cases) the export statements, but don’t forget to add them in your own code.

I’ll be using mostly classes, as stated above, instead of (factory) functions. I’ll not enter a debate here on whether Object Oriented Programming (OOP) or Functional Programming are better/more suited. You’ll find lots of articles on this subject, like this one. It really does not matter much for the architecture I’ll be presenting if we choose one or the other.

Though I know classes were somehow forcibly added into the JavaScript language, I’ll still use them for two main reasons : they feel elegant to me (I really care about readibility as you might have already guessed), and they might be easier to port to other languages. But again, using a functional approach would be fine too.

---

Part 1 is about :

• How to organize code, name files and write simple, readable, intuitive code, under good coding guidelines ?
• How to minimize dependencies by implementing a service container for dependency injection ?
• When and how to use events ?

Part 2 is about :

• How to implement the repository pattern (we hinted this already), separate domain classes from database models and add some automated persistence logic in accordance with the domain ?
• How to set up your HTTP server ?
• How to handle routing and manage controllers ?

Part 3 is about :

• How to manage authentication ?
• How to manage access control ?
• How to handle errors properly ?

Part 4 is about :

• How to comment code and create useful documentation ?
• How to aim at 100% unit test coverage ?
• How to use some CLI commands consuming your app services ?

Part 5 is about :

• How to deploy in production ?
• How to implement useful decorators ?
• How to go beyond infinity ?

Stay tuned for Part 1 !

PS / One small disclaimer in case you haven’t noticed : English is not my native language, so I do apologize for any mistake I’ll be making (or have already made).