DEV Community: Ciro Ivan

Idiomatic JavaScript Backend. Part 3

Ciro Ivan — Sun, 02 Sep 2018 00:33:05 +0000

Hi everyone! This part of series Idiomatic JavaScript Backend.

Important Information

For best experience please clone this repo: https://github.com/k1r0s/ritley-tutorial. It contains git tags that you can use to travel through different commits to properly follow this tutorial :)

$ git tag

1.preparing-the-env
2.connecting-a-persistance-layer
3.improving-project-structure
4.creating-entity-models
5.handling-errors
6.creating-and-managing-sessions
7.separation-of-concerns
8.everybody-concern-scalability

Go to specific tag

$ git checkout 1.preparing-the-env

Go to latest commit

$ git checkout master

See differences between tags on folder src

$ git diff 1.preparing-the-env 2.connecting-a-persistance-layer src

6. Creating and managing sessions

ritley doesn't offer an orthodox way to handle sessions.

The End!

Not kidding.. yeah, well but what ritley does best is to provide you tools to drop behaviors and requirements from method to method, modules and even projects.

Now, for the rest of the requirements such as showing a list of users or updating an user need clients to allow creating sessions by using its credentials.

Hence lets create a couple of users if you don't have any!

$ curl -d '{ "name": "Randell Kovalsky", "mail": "rk@foo.b", "pass": "asd123"}' localhost:8080/users

Create few users by using previous command, lets say 3 or 4 users its enough.

Now, remember about src/resources/session.resource.js? time to add a feature:

import { AbstractResource } from "@ritley/core";
import SessionModel, { SessionInvalidCredentialsError } from "../models/session.model";

import {
  Default,
  MethodNotAllowed,
  Created,
  Throws,
  Unauthorized,
  BadRequest,
  Dependency,
  ReqTransformBodyAsync
} from "@ritley/decorators";


@Dependency("sessionModel", SessionModel)
export default class SessionResource extends AbstractResource {
  @Default(MethodNotAllowed) get() {}
  @Default(MethodNotAllowed) put() {}
  @Default(MethodNotAllowed) delete() {}

  constructor() {
    super("/sessions");
  }

  @Throws(SyntaxError, BadRequest)
  @Throws(SessionInvalidCredentialsError, Unauthorized)
  @Default(Created)
  @ReqTransformBodyAsync
  async post(req) {
    const body = await req.body;
    const payload = body.toJSON();
    const user = await this.sessionModel.validateCredentials(payload);
    return this.sessionModel.upsertSession(user);
  }
}

Lets review the requirements along with previous snippet:

post method should create a session by identifying the client through user credentials
validateCredentials just return the user from the database by comparing mail and password (encrypted).
upsertSession method creates or updates the session. It always receive an user and returns a session with an expiration date of +30 minutes.
get, put and delete methods must be explicitly rejected with HTTP 405
file proper responses on each case: success, wrong json on payload, wrong credentials, errors during session creation.

You probably realized about we duplicated code on parsing payload from src/resources/user.resource.js. This is just temporal, we'll fix later on.

And we've added a dependency by the name of sessionModel where specific non-transporter-layer logic should be placed such as creating, updating, managing expiration, credential validation... I'm not going to paste but you can check the code here.

So now, running the project again and executing this command on the term:

$ curl -d '{ "mail": "<mail>", "pass": "<pass>"}' localhost:8080/sessions

Now the server answers you with something like this:

{"uid":"TjVNZy8yk","expiration":1535293179182,"userUid":"xqR16Gi7w"}

Well, here sessions are very simple and unorthodox. Successful authentication is a json with the uid of the session, an expiration timestamp and the associated user's uid as userUid.

As defined on requirements to use that newly created session the client should provide a header -H "x-session: <session_uid>" on every call that requires a session.

For instance if we would list all registered users on the app we should do this:

$ curl -H "x-session: TjVNZy8yk" localhost:8080/users

Now we have to modify our src/resources/user.resource.js to fulfill GET call:

 import { AbstractResource } from "@ritley/core";
 import UserModel, { UserValidationError, UserMailInUseError } from "../models/user.model";
+import SessionModel, { SessionNotCreatedError, SessionExpiredError } from "../models/session.model";

 import {
   Dependency,
   ReqTransformBodyAsync,
   Default,
   Throws,
   BadRequest,
   Conflict,
   Created
+  Ok,
+  Unauthorized
 } from "@ritley/decorators"; 

 @Dependency("userModel", UserModel)
+@Dependency("sessionModel", SessionModel)
 export default class UserResource extends AbstractResource {
   constructor() {
     super("/users");
@@ -23,11 +26,21 @@ export default class UserResource extends AbstractResource {
   @Throws(UserMailInUseError, Conflict)
   @Default(Created)
   @ReqTransformBodyAsync
   async post(req) {
     const body = await req.body;
     const payload = body.toJSON();
     await this.userModel.validate(payload);
     await this.userModel.isUnique(payload);
     return this.userModel.create(payload);
   }
+
+  @Throws(SessionNotCreatedError, Unauthorized)
+  @Throws(SessionExpiredError, Unauthorized)
+  @Default(Ok)
+  async get(req) {
+    const uid = req.headers["x-session"];
+    const session = await this.sessionModel.sessionExists({ uid });
+    await this.sessionModel.revalidate(session);
+    return this.userModel.searchBy();
+  }
 }

As you can see we've just added get method.

Now users are able to:

create users and define credentials
create a session using credentials
list users using a session

Although there are some issues here:

user.resource.js contains code that handles calls from sessionModel which is not explicitly related. though is relation is implicit by business rules. Se need to address that relationship more implicit. Because now involves mixing different domain concerns.
Also, sessions management may involve errors that aren't related to users too.
Next development cycles may include new resources, lets say /cities or something are we going to copy and paste code in order to manage sessions, payload parsing and all its error specific handling? (many people actually do)

7. Separation of concerns

How to address the problem with replication?

Old school OOP programmers will try to group shared behaviors on upper classes and then, place specific behaviors as a subclasses but that's hard to scale, too many strong relationships, complex code bases.

On the other hand FP programmers will create a pipe of middlewares (req, res, next) that doesn't allow too much for building abstractions that can become something known as middleware hell. Functions are monoliths, to a certain point, in general, it doesn't scale quite well due to wrong encapsulation and side-effects problems.

I'm not here to argue against paradigms, I'm just trying to generally assess enterprise wide used solutions such as Spring, .NET and expressJS by its coding banner.

My point is that every paradigm or technique is good, but it doesn't make sense to use it to solve all problems like previous frameworks did.

Both paradigms defined above doesn't avoid you to explicitly call them and hence deal with duplication at some point. Completely get rid of duplication is impossible though but, problem with duplication isn't solely the amount of code that you have to paste all across your code base... is about dealing with lines of code that involve calls, assignments, sending arguments... more code, more to read, track, test, maintain, etc. By reading some method's code how you can tell if all code placed is related to the main concern? for instance:

increasePrice(amount) {
  ...requiredStuff1(amount)
  ...callAnotherService(this)
  ...etc
  this.price += amount;
  ...logThatPriceCorrectlyIncreases(this.price)
}

How many times you read some piece of code and then asked: What this code is really doing?, haven't you?

Lets try to decouple shared behaviors into something more portable and declarative.

Going back to our project, lets illustrate this by coding what I think is the solution to this problem: both src/resource/user.resource.js and src/resource/session.resource.js need to receive body payload, actually the do it by using @ReqTransformBodyAsync, but we still need to actually parse the body string to JSON and handle errors if any.

Would be nice if @ReqTransformBodyAsync solve the entire problem, right? then we would be able to put our wonderful decorator on every single method that needs that chunk of behavior when we actually need it. We don't want to call app.use().

Of course @ritley/decorators doesn't know what kind of stuff we need to do regarding on error handling, every project is different, you may need to call a Logger, who knows. It only provides request buffer concatenation which is the most basic that a library can do for you!

But, it allows you to extend decorators. Lets create a file on src/decorators/req-body-json.decorator.js:

import { beforeMethod } from "kaop-ts";

import {
  BadRequest,
  ReqTransformBodyAsync
} from "@ritley/decorators";

function parseRequestBody(meta) {
  const [req, res] = meta.args;
  req.body.then(body => {
    try {
      const payload = body.toJSON();
      meta.commit(payload);
    } catch (e) {
      BadRequest(res, e.message);
    }
  })
}

export default beforeMethod(
  ...ReqTransformBodyAsync.advices(),
  parseRequestBody
)

Well, first we need to understand what @ReqTransformBodyAsync actually do:

creates a promise that will resolve when Request payload will be fully received and it assigns it to req.body.

We're just extending this decorator by adding a behavior right after first one concludes.

Hence this new decorator contains the behavior of @ReqTransformBodyAsync and our custom function that basically tries to parse request payload into a json, if there is an error it will file a HTTP 400 Bad Request, if succeeds it will execute the method that is decorating with an additional parameter which resolves to the json's payload.

Don't panic if this sounds like Spanish for you. Let me show you this:

 import { AbstractResource } from "@ritley/core";
 import SessionModel, { SessionInvalidCredentialsError } from "../models/session.model";
+import ParseReqBody from "../decorators/req-body-json.decorator";

 import {
   Default,
@@ -7,9 +8,7 @@ import {
   Created,
   Throws,
   Unauthorized,
   BadRequest,
   Dependency,
-  ReqTransformBodyAsync
} from "@ritley/decorators";


@@ -25,14 +24,10 @@ export default class SessionResource extends AbstractResource {
     super(SessionResource.URI);
   }

-  @Throws(SyntaxError, BadRequest)
   @Throws(SessionInvalidCredentialsError, Unauthorized)
   @Default(Created)
-  @ReqTransformBodyAsync
+  @ParseReqBody
-  async post(req) {
+  async post(req, res, payload) {
-    const body = await req.body;
-    const payload = body.toJSON();
     const user = await this.sessionModel.validateCredentials(payload);
     return this.sessionModel.upsertSession(user);
   }
 }

That means both src/resources/user.resource.js and src/resources/session.resource.js will use it, so we can get rid of SyntaxError check too.

Now payload requirement is defined outside of the method code, like a dependency, but rather than a service, you're injecting a behavior. This is like middlewares on steroids.

Wonder that you can declare @ResolveUploadedFile("/path/:filename") on top of some method and, in the background, receive a request with a multiplart/form-data payload (a file), save the file into a predefined route, etc, and after all execute the method that you decorated like if nothing really happened? Yes, we can.

Lets create a decorator called @ValidateSession to clean up our src/resources/user.resource.js from non-related user domain:

 import { AbstractResource } from "@ritley/core";
 import UserModel, { UserValidationError, UserMailInUseError } from "../models/user.model";
-import SessionModel, { SessionNotCreatedError, SessionExpiredError } from "../models/session.model";
+import ParseReqBody from "../decorators/req-body-json.decorator";
+import ValidateSession from "../decorators/validate-session.decorator";

 import {
   Dependency,
   Default,
   Throws,
   BadRequest,
   Conflict,
   Created,
   Ok,
-  ReqTransformBodyAsync,
-  Unauthorized
 } from "@ritley/decorators";

 @Dependency("userModel", UserModel)
-@Dependency("sessionModel", SessionModel)
 export default class UserResource extends AbstractResource {
   constructor() {
     super("/users");
   }

-  @Throws(SyntaxError, BadRequest)
   @Throws(UserValidationError, BadRequest)
   @Throws(UserMailInUseError, Conflict)
   @Default(Created)
-  @ReqTransformBodyAsync
+  @ParseReqBody
-  async post(req) {
+  async post(req, res, payload) {
-    const body = await req.body;
-    const payload = body.toJSON();
     await this.userModel.validate(payload);
     await this.userModel.isUnique(payload);
     return this.userModel.create(payload);
   }

-  @Throws(SessionNotCreatedError, Unauthorized)
-  @Throws(SessionExpiredError, Unauthorized)
   @Default(Ok)
+  @ValidateSession
-  async get(req) {
+  get(req) {
-    const uid = req.headers["x-session"];
-    const session = await this.sessionModel.sessionExists({ uid });
-    await this.sessionModel.revalidate(session);
     return this.userModel.searchBy();
   }
 }

And now, remember that code related with the session management? We moved this to a proper separate location. We've created another folder:

src/
├── config
│   ├── database.config.js
│   └── lowdb.json
├── decorators
│   ├── req-body-json.decorator.js
│   └── validate-session.decorator.js
├── index.js
├── models
│   ├── session.model.js
│   └── user.model.js
├── resources
│   ├── session.resource.js
│   └── user.resource.js
└── services
    ├── database.service.js
    └── encrypt.service.js

To recap, session and user resources both share payload management, so we've created a decorator that encapsulates required behavior to parse req body and then we've defined on both resources. We did similar with session requirement since next feature edit users will rely on it.

So, as you can see, ritley provides OO standards in order to deal with basic architecture and separation of concerns but enhances it with FP extensions as middleware decorators that can be plugged before a method, after a method, if method throws an error. So that's pretty neat.

8. Everybody's concern, scalability

Do I need to explain you how to write scalable apps? If you are still here you might know a few tips on this. Isn't solely a matter of which tools you choose, it certainly impact but most of times is all about decisions that you did… or indeed the framework did.

ritley only took decisions on http/transport layer. That means you are the only one to blame on other concerns. it scares right? Some might see it as a redemption.

As you saw on previous parts during this tutorial, plain, simple, well understood architectures empowers developers to write better code.

Now we need to add the last feature, user edition. Lets add a PUT method handler on src/resources/user.resource.js:

@Throws(UserInsufficientPermError, Forbidden)
@Default(Ok)
@ValidateSession
@ParseReqBody
@ReqTransformQuery
put(req, res, session, payload) {
  return this.userModel.putUser(req.query.uid, session.userUid, payload);
}

Have you noticed that request payload will not be parsed if user doesn't have a valid session? decorator order does matter :D, simply because it goes before [top-to-down].

That's all we've to do on our http layer.

Note that, we are calling putUser on src/models/user.model.js. Lets see whats new here:

@@ -43,6 +43,14 @@ export default class UserModel {
     }
   }

+  isAllowedToEdit(requestedUserUid, currentUserUid) {
+    if(requestedUserUid === currentUserUid) {
+      return Promise.resolve();
+    } else {
+      return Promise.reject(new UserInsufficientPermError);
+    }
+  }
+
   update(uid, { mail, name }) {
     return this.database.update("users", { uid }, { mail, name });
   }
@@ -50,6 +58,10 @@ export default class UserModel {
   postUser(payload) {
     return this.validate(payload).then(() => this.isUnique(payload).then(() => this.create(payload)));
   }
+
+  putUser(requestedUserUid, currentUserUid, payload) {
+    return this.isAllowedToEdit(requestedUserUid, currentUserUid).then(() => this.update(requestedUserUid, payload));
+  }
 }

 export class UserValidationError extends Error {
@@ -63,3 +75,9 @@ export class UserMailInUseError extends Error {
     super("mail is already taken, try another one")
   }
 }
+
+export class UserInsufficientPermError extends Error {
+  constructor() {
+    super("you don't have permissions to perform this action")
+  }
+}

That means an user can only update its own profile.

Lets try this by running a curl command:

$ curl -X PUT -H "x-session: <session_uid>" -d '{ "name": "Jean-Luc Godard"}' localhost:8080/users?uid=<target_user_uid>

You get back either a verbose error or newly updated user.

You may noticed to handle querystring parameters and access req.query we've added @ReqTransformQuery on put method. Now you may be asking: "Do I have to add a decorator for every single case?". If you're building a more complex application you probably need to define a more complex class base, instead of pile 7 decorators per method you might extend your resources from MyAbstractResource rather of generic ritley's AbstractResource. You may need to build a framework on top of this LMAO.

This chapter is completed. Now users can change their names! (...)

Some tips on scalable software:

As always, try to scale horizontaly, avoid more than two levels of inheritance on classes, remember that you can extend decorators that fit best your case, etc.

For instance previous feature we just added on edit users only involved additions on the commit, we didn't change previous code. Thats the gold rule for scalability.

Any chunk of code non-related to any feature should be easy to extend, but not suited for modification.

You should not try to abstract your business logic since you don't even known whats going next. As a programmer you need to represent business logic as it is and deal with infrastructure code with abstraction and modular approaches. That is what defines software quality.

For example our specific decorators that target session management defines a closed design which can be easily extended since most of business logic is defined on models and decorator it self only provides the glue to attach it into classes.

Common problems related with scalability like huge code changes of unrelated domains are due to bad/closed design when you cannot access this service from here because there is another service that is doing nasty stuff on the background.. most likely due to miss placed responsibility.

Your job is always to keep concerns on separated layers.

9. Conclusion

ritley its a very simple concept. It was created 9 months ago but completely rewrited to be released as OSS. The basic concept is to provide common patterns on transport layer without wrapping nodejs documentation. In fact it only dispatch request to the proper handler by mapping your classes, hence its quite fast, well tested, and easy to master since you don't need to learn anything that you probably known if you're a casual node developer.

Library core is less than 80 lines (at the time I'm writing this) and likely will remain quite simple. Though library extension @ritley/decorators is about 200 lines. Even though is still small in comparison to other frameworks.

Congratulations comrade. Did you enjoy the article? let me know your thoughts down below or lets chat on twitter :) thank you ❤

Did you like the idea about the library? Do you want to contribute? I'm always open to new ideas!

Idiomatic JavaScript Backend. Part 2

Ciro Ivan — Sat, 01 Sep 2018 11:19:13 +0000

Hi everyone! This part of series Idiomatic JavaScript Backend.

Part 1/3
Part 3/3

Important Information

For best experience please clone this repo: https://github.com/k1r0s/ritley-tutorial. It contains git tags that you can use to travel through different commits to properly follow this tutorial :)

$ git tag

1.preparing-the-env
2.connecting-a-persistance-layer
3.improving-project-structure
4.creating-entity-models
5.handling-errors
6.creating-and-managing-sessions
7.separation-of-concerns
8.everybody-concern-scalability

Go to specific tag

$ git checkout 1.preparing-the-env

Go to latest commit

$ git checkout master

See differences between tags on folder src

$ git diff 1.preparing-the-env 2.connecting-a-persistance-layer src

4. Creating entity models

Ritley doesn't tell you exactly how to build entity models, that's not our concern so I'll try to be brief.

Models encapsulate all logic related with the domain. For instance creating users, encrypting passwords, validate fields, etc. While Resources translate this logic into the HTTP layer.

Our first model will be located into src/models/user.model.js:

import DataService from "../services/database.service";
import EncryptService from "../services/encrypt.service";
import { Provider, Dependency } from "@ritley/decorators";


@Provider.factory
@Dependency("database", DataService)
@Dependency("encrypt", EncryptService)
export default class UserModel {

  static userPublicPredicate = collection => collection.map(({ pass, ...user }) => ({
    ...user
  }))

  validate(payload) {
    const requiredProps = ["name", "pass", "mail"];
    const props = Object.keys(payload);
    if(requiredProps.every(prop => props.includes(prop))) {
      return Promise.resolve();
    } else {
      return Promise.reject();
    }
  }

  create(payload) {
    const pass = this.encrypt.encode(payload.pass);
    return this.database.create("users", { ...payload, pass });
  }

  isUnique({ mail }) {
    return new Promise((resolve, reject) =>
      this.database.exists("users", { mail }).then(reject, resolve));
  }

  searchBy(predicate) {
    return this.readUsers(predicate).then(UserModel.userPublicPredicate);
  }

  readUsers(predicate) {
    if(predicate) {
      return this.database.filter("users", predicate);
    } else {
      return this.database.read("users");
    }
  }

  update(uid, { mail, name }) {
    return this.database.update("users", { uid }, { mail, name });
  }
}

We've just implemented many methods that will be used later on, for now we're going to use validate, isUnique and create to fit requirements on user creation.

Note we've included a new package for password encryption.

Again all non topic packages as such are just placeholders, you can use any other you like :)

we run: $ npm install cpass

Now lets take a look over src/resources/user.resource.js:

 import { AbstractResource } from "@ritley/core";
-import DataService from "../services/database.service";
+import UserModel from "../models/user.model";

-import { Dependency, ReqTransformBodySync } from "@ritley/decorators";
+import { Dependency, ReqTransformBodyAsync } from "@ritley/decorators";

-@Dependency("database", DataService)
+@Dependency("userModel", UserModel)
 export default class UserResource extends AbstractResource {
   constructor() {
     super("/users");
   }

-  @ReqTransformBodySync
-  post(req, res) {
-    const payload = req.body.toJSON();
-    this.database.create("users", payload).then(user => {
-      res.statusCode = 200;
-      res.end(JSON.stringify(user));
-    });
+  @ReqTransformBodyAsync
+  async post(req, res) {
+    const body = await req.body;
+    const payload = body.toJSON();
+    await this.userModel.validate(payload);
+    await this.userModel.isUnique(payload);
+    const user = await this.userModel.create(payload);
+    res.statusCode = 200;
+    res.end(JSON.stringify(user));
   }
 }

As I said before, using async/await feature transforms our post method into a promise, so we're going to use @ReqTransformBodyAsync instead of previous one @ReqTransformBodySync. First one is promise based, so it makes sense to use it with async/await code such as previous snippet.

Of course we've removed this.database calls and DataService from resources. You don't want to mess with persistence layer on your http layer ;)

Our service now fulfills the requirements for user creation but we're missing exception handling here. If JSON isn't well formed, payload doesn't contain required fields, provided email is taken or something we'll held an unhanded rejection or maybe an exception will terminate our app 😰

let's see what's next!

5. Handling exceptions

So, how to file proper responses anytime when an errors pops by?

Well, first of all we need to look at there:

const body = await req.body;
const payload = body.toJSON();
await this.userModel.validate(payload);
await this.userModel.isUnique(payload);
const user = await this.userModel.create(payload);
res.statusCode = 200;
res.end(JSON.stringify(user));

All errors originate from there or subsequent calls and should be handled here (around here) because it involves sending back feedback to the client.

But that is quite difficult and involves a lot of intrusion you may think.

To better understand what means to deal with nested promise rejections in nodejs I recommend this article about promise rejections, or at least keep on the desktop.

Wrapping every specific case with try ... catch can be a nightmare. Lets start by separate every task into new methods that will handle single operations, for instance payload parsing:

parseBody(req, res) {
  try {
    return req.body.toJSON();
  } catch (e) {
    res.statusCode = 400; // Bad Request
    res.end("payload isn't well formed");
  }
}

And of course this works! Lets see how it looks:

import { AbstractResource } from "@ritley/core";
import UserModel from "../models/user.model";

import { Dependency, ReqTransformBodyAsync } from "@ritley/decorators";

@Dependency("userModel", UserModel)
export default class UserResource extends AbstractResource {
  constructor(_database) {
    super("/users");
  }

  @ReqTransformBodyAsync
  async post(req, res) {
    const body = await req.body;
    const payload = this.parseBody(body, res);
    await this.validate(payload, res);
    await this.isUnique(payload, res);
    const user = await this.create(payload, res);
    res.statusCode = 200;
    res.end(JSON.stringify(user));
  }

  parseBody(body, res) {
    try {
      return body.toJSON();
    } catch (e) {
      res.statusCode = 400;
      res.end("payload isn't well formed");
    }
  }

  validate(payload, res) {
    return this.userModel.validate(payload).catch(() => {
      res.statusCode = 400;
      res.end("missing fields, required: [name, mail, pass]");
    })
  }

  isUnique(payload, res) {
    return this.userModel.isUnique(payload).catch(() => {
      res.statusCode = 409;
      res.end("mail is already taken, try another one");
    })
  }

  create(payload, res) {
    return this.userModel.create(payload).catch(() => {
      res.statusCode = 500;
      res.end("there was an error creating your user, try again");
    })
  }
}

mmh! that's huge, does it make sense to expand our code that much only to properly catch exceptions? well...

Even though we're handling errors on every single task that may involve rejections or exceptions we're going to run into UnhandledPromiseRejectionWarning because async generators wraps the whole method into a promise, but we cannot handle post it self, because it gets called by the library and it should not do this by ourselves.

To avoid this we can create a new async method that get's called by post so we can handle async call from outside, kind of a workaround:

post(req, res) {
  this.handledPost(req, res).catch(() => console.log('rejection from inside'));
}

async handledPost() {
  ...lots of awaits that may be rejected but locally handled
}

Another may elegant solution is to use more abstractions since we're repeating the same pattern many times.@ritley/decorators provides some in order to make our life easier, for example:

 import {
+  Default,
+  Catch,
   InternalServerError,
   BadRequest,
   Conflict,
   Created
 } from "@ritley/decorators";

And probably there's not too much to explain:

import { AbstractResource } from "@ritley/core";
import DataService from "../services/database.service";
import UserModel from "../models/user.model";

import {
  Dependency,
  ReqTransformBodyAsync,
  Default,
  Catch,
  InternalServerError,
  BadRequest,
  Conflict,
  Created
} from "@ritley/decorators";

@Dependency("userModel", UserModel)
export default class UserResource extends AbstractResource {
  constructor(_database) {
    super("/users");
  }

  @Default(Created)
  @ReqTransformBodyAsync
  async post(req, res) {
    const payload = await this.parseBody(req, res);
    await this.validate(payload, res);
    await this.isUnique(payload, res);
    return await this.create(payload, res);
  }

  @Catch(BadRequest, "payload isn't well formed")
  parseBody(req) {
    return req.body.then(body => body.toJSON());
  }

  @Catch(BadRequest, "missing fields, required: [name, mail, pass]")
  validate(payload) {
    return this.userModel.validate(payload);
  }

  @Catch(Conflict, "mail is already taken, try another one")
  isUnique(payload) {
    return this.userModel.isUnique(payload);
  }

  @Catch(InternalServerError, "there was an error creating your user, try again")
  create(payload) {
    return this.userModel.create(payload);
  }
}

As you can see these abstractions reduce a bit our code base and improve readability.

As you may wonder @Catch(responseFn, content) looks for synchronous exceptions on the method but checks as well if returned value was a promise, if so, adds a catch() callback to it. Either a synchronous error or promise rejection will be handled and responseFn will be invoked with our res <Response> object.

So: BadRequest, Conflict, InternalServerError, Created... are just functions exported by @ritley/decorators that receive a res <Response> object and resolve the proper message to the client. So by calling BadRequest(res, "wrong!") client will receive a HTTP 400 with "wrong!" as a response body.

In the other hand @Default(responseFn) do quite the same but checking for promise resolution using then(). It also attaches a catch() to prevent possible unhandled rejections, but it will be resolved with HTTP 500 such a case, because that error was not properly handled indeed.

In other words Default tells whats going to happen if everything goes well, and Catch wraps sensible calls with an error message, like checkpoints.

But there is even more:

 import { AbstractResource } from "@ritley/core";
-import UserModel from "../models/user.model";
+import UserModel, { UserValidationError, UserMailInUseError } from "../models/user.model";

-import { Dependency, ReqTransformBodyAsync } from "@ritley/decorators";
+import {
+  Dependency,
+  ReqTransformBodyAsync,
+  Default,
+  Throws,
+  InternalServerError,
+  BadRequest,
+  Conflict,
+  Created
+} from "@ritley/decorators";

 @Dependency("userModel", UserModel)
 export default class UserResource extends AbstractResource {
@@ -9,14 +18,16 @@ export default class UserResource extends AbstractResource {
     super("/users");
   }

+  @Throws(SyntaxError, BadRequest)
+  @Throws(UserValidationError, BadRequest)
+  @Throws(UserMailInUseError, Conflict)
+  @Default(Created)
   @ReqTransformBodyAsync
   async post(req, res) {
     const body = await req.body;
     const payload = body.toJSON();
     await this.userModel.validate(payload);
     await this.userModel.isUnique(payload);
-    const user = await this.userModel.create(payload);
-    res.statusCode = 200;
-    res.end(JSON.stringify(user));
+    return this.userModel.create(payload);
   }
 }

You can use @Throws decorator to explicitly tell which type of exception we've to expect in order to trigger specific responses to the client. Mind blowing, right?

See how we're exporting custom errors from our model layer src/models/user.model.js:

     if(requiredProps.every(prop => props.includes(prop))) {
       return Promise.resolve();
     } else {
-      return Promise.reject();
+      throw new UserValidationError
     }
   }

@@ -29,7 +28,7 @@ export default class UserModel {

   isUnique({ mail }) {
     return new Promise((resolve, reject) =>
-      this.database.exists("users", { mail }).then(reject, resolve));
+      this.database.exists("users", { mail }).then(() => reject(new UserMailInUseError), resolve));
   }

   searchBy(predicate) {
@@ -48,3 +47,15 @@ export default class UserModel {
     return this.database.update("users", { uid }, { mail, name });
   }
 }
+
+export class UserValidationError extends Error {
+  constructor() {
+    super("missing fields, required: [name, mail, pass]")
+  }
+}
+
+export class UserMailInUseError extends Error {
+  constructor() {
+    super("mail is already taken, try another one")
+  }
+}

So @Throws(errorType, responseFn) just goes beyond. While @Catch will handle any exception regardless of error type, @Throws just provides more concrete way to handle out http layer.

This is the final look for now on src/resources/user.resource.js:

import { AbstractResource } from "@ritley/core";
import UserModel, { UserValidationError, UserMailInUseError } from "../models/user.model";

import {
  Dependency,
  ReqTransformBodyAsync,
  Default,
  Throws,
  InternalServerError,
  BadRequest,
  Conflict,
  Created
} from "@ritley/decorators";

@Dependency("userModel", UserModel)
export default class UserResource extends AbstractResource {
  constructor() {
    super("/users");
  }

  @Throws(SyntaxError, BadRequest)
  @Throws(UserValidationError, BadRequest)
  @Throws(UserMailInUseError, Conflict)
  @Default(Created)
  @ReqTransformBodyAsync
  async post(req, res) {
    const body = await req.body;
    const payload = body.toJSON();
    await this.userModel.validate(payload);
    await this.userModel.isUnique(payload);
    return this.userModel.create(payload);
  }
}

Just to recap. Whether to use @Throws or @Catch is up to you although @Catch can be considered as a @Throws(Error, fn) alias because it will be executed on any exception. But @Throws is more deterministic because you can tie your HTTP responses to specific kind of errors or success.

Basically all the framework logic is on http layer. Models are completely independent despite providers.

ritley defines http triggers that will invoke specific operations on the model that, either success or fail, will be handled back using a declarative set of expressions on top of the same trigger. This basically allows for non-intrusive and declarative development on the backend.

That's all for now folks! Following chapter on series will be about handling sessions, separation of concerns and to keep things scalable with ritley. Cya!

Idiomatic JavaScript Backend. Part 1

Ciro Ivan — Fri, 31 Aug 2018 20:24:12 +0000

Hi everyone! This part of series Idiomatic JavaScript Backend.

Part 2/3
Part 3/3

Important Information

For best experience please clone this repo: https://github.com/k1r0s/ritley-tutorial. It contains git tags that you can use to travel through different commits to properly follow this tutorial :)

$ git tag

1.preparing-the-env
2.connecting-a-persistance-layer
3.improving-project-structure
4.creating-entity-models
5.handling-errors
6.creating-and-managing-sessions
7.separation-of-concerns
8.everybody-concern-scalability

Go to specific tag

$ git checkout 1.preparing-the-env

Go to latest commit

$ git checkout master

See differences between tags on folder src

$ git diff 1.preparing-the-env 2.connecting-a-persistance-layer src

0.What

Hi everyone! today's topic is about building an App with NodeJS.

What we're gonna do? We will build a service for allowing users to:

create its own profile
create a session
list other users
edit its own user

And…

We're going to use cURL!

Its not relevant to check, but you can click here to see the full requirements on what this app should fulfill.

Now I'm going to slowly build it from scratch!

1. Preparing the environment

Let's do our "Hello World" with ritley to get started:

.
├── .babelrc
├── package.json
└── src
    └── index.js

In this tutorial we're going to use Babel. To do so with nodejs we need babel-node to run our app. So this is our package.json:

{
  "name": "tutorial",
  "version": "1.0.0",
  "description": "",
  "main": "index.js",
  "scripts": {
    "start": "babel-node src"
  },
  "keywords": [],
  "author": "",
  "license": "ISC",
  "dependencies": {
    "@ritley/core": "^0.3.3",
    "@ritley/standalone-adapter": "^0.2.0",
  },
  "devDependencies": {
    "@babel/core": "^7.0.0-beta.55",
    "@babel/node": "^7.0.0-beta.55",
    "@babel/plugin-proposal-class-properties": "^7.0.0-beta.55",
    "@babel/plugin-proposal-decorators": "^7.0.0-beta.55",
    "@babel/plugin-transform-async-to-generator": "^7.0.0-rc.1",
    "@babel/preset-env": "^7.0.0-beta.55"
  }
}

Why @ritley/core and @ritley/standalone-adapter ? :|

As ritley is quite small, many features are separated on different packages. As core is indeed required, standalone adapter too because we're going to run a node server by ourselves here. If you're on serverless environments such as firebase you can keep going without it.

This would be our .babelrc:

{
  "presets": [["@babel/preset-env", {
    "targets": {
        "node": "current"
      }
    }]],
  "plugins": [
    ["@babel/plugin-proposal-decorators", { "legacy": true }],
    ["@babel/plugin-proposal-class-properties", { "loose": false }],
    ["@babel/plugin-transform-async-to-generator"]
  ]
}

And our hello world src/index.js:

import { setAdapter, AbstractResource } from "@ritley/core";
import Adapter from "@ritley/standalone-adapter";

setAdapter(Adapter, {
  "port": 8080
});

class SessionResource extends AbstractResource {
  constructor() {
    super("/sessions");
  }

  get(req, res) {
    res.statusCode = 200;
    res.end("Hello from sessions!");
  }
}

class UserResource extends AbstractResource {
  constructor() {
    super("/users");
  }

  get(req, res) {
    res.statusCode = 200;
    res.end("Hello from users!");
  }
}

new SessionResource;
new UserResource;

In previous snippet we import standalone-adapter and we bind it to the core by calling setAdapter(<adapter> [, <options>]). This will create and bind a new HttpServer to any AbstractResource subclass. You can check how it works.

When building a ritley app you've to choose an adapter. That defines how requests are sent to resources.

ritley uses https://nodejs.org/api/http.html (req, res)api so probably you're quite familiar with it.

Note that we've created two similar classes, we could do this instead:

import { setAdapter, AbstractResource } from "@ritley/core";
import Adapter from "@ritley/standalone-adapter";

setAdapter(Adapter, {
  "port": 8080
});

class DefaultResource extends AbstractResource {
  get(req, res) {
    res.statusCode = 200;
    res.end(`Hello from ${this.$uri}`);
  }
}

new DefaultResource("/sessions");
new DefaultResource("/users");

Anyways we're going to keep it separated as both resources will start diverge quite soon.

now you can $ npm start and then run some curl commands to see if everything is working properly:

$ curl localhost:8080/users
$ curl localhost:8080/sessions

This is our first step!

2. Connecting a persistence layer

We need to have some kind of persistence layer. We're going to install lowdb because we don't need too much overhead for now.

Everyone favorite part: its time to install new dependencies!:

$ npm install lowdb shortid

However we need to keep in mind that any dependency, whatever we attach to our project, should be easy to replace. That's we're going to wrap lowdb into an interface with "CRUD alike" methods to keep things extensible.

Lets continue by implement our database.service.js using lowdb:

import low from "lowdb";
import FileAsync from "lowdb/adapters/FileAsync";
import config from "./database.config";
import shortid from "shortid";

export default class DataService {
  onConnected = undefined

  constructor() {
    this.onConnected = low(new FileAsync(config.path, {
      defaultValue: config.defaults
    }))
  }

  create(entity, newAttributes) {
    return this.onConnected.then(database =>
      database
      .get(entity)
      .push({ uid: shortid.generate(), ...newAttributes })
      .last()
      .write()
    )
  }
}

For now we only implement create method. That's fine now.

.
└── src
    ├── database.config.js
    ├── database.service.js
    ├── index.js
    └── lowdb.json

Our project is growing fast! We've created database.config.js too which contains important data that may be replaced quite often so we keep it here:

export default {
  path: `${__dirname}/lowdb.json`,
  defaults: { sessions: [], users: [] }
};

You can skip this paragraph if you've already used lowdb. Basically you need to specify the actual path of the physic location of the database, since it doesn't need a service like other database engines. Hence lowdb is way simpler and fun to play with, though less powerful and should not be used to build enterprise projects. That's why I'm wrapping the whole lowdb implementation on a class that exposes crud methods, because its likely to be replaced anytime.

And now, we've changed our src/index.js to properly connect database to controllers:

@@ -1,5 +1,6 @@
 import { setAdapter, AbstractResource } from "@ritley/core";
 import Adapter from "@ritley/standalone-adapter";
+import DataService from "./database.service";

 setAdapter(Adapter, {
   "port": 8080
@@ -17,15 +18,18 @@ class SessionResource extends AbstractResource {
 }

 class UserResource extends AbstractResource {
   constructor() {
     super("/users");
+    this.database = new DataService;
   }

-  get(req, res) {
-    res.statusCode = 200;
-    res.end("Hello from users!");
+  post(req, res) {
+    this.database.create("users", { name: "Jimmy Jazz" }).then(user => {
+      res.statusCode = 200;
+      res.end(JSON.stringify(user));
+    });
   }
 }

 new SessionResource;
 new UserResource;

We've changed as well our get method to a post to emulate a real case of creation request. By running this command we get back the newly created data!

$ curl -X POST localhost:8080/users

Check src/lowdb.json to see the changes!

Okay so, we just connected lowdb and run our first insertion!

3. Improving the project structure

We need to organize a bit our project.

First we're going to arrange our folders like this:

// forthcoming examples will only show src/ folder
src/
├── config
│   ├── database.config.js
│   └── lowdb.json
├── index.js
├── resources
│   ├── session.resource.js
│   └── user.resource.js
└── services
    └── database.service.js

Now lets remove a bit of code from src/index.js in order to have only the following:

import { setAdapter } from "@ritley/core";
import Adapter from "@ritley/standalone-adapter";

import SessionResource from "./resources/session.resource"
import UserResource from "./resources/user.resource"

setAdapter(Adapter, {
  "port": 8080
});

new SessionResource;
new UserResource;

So basically we moved our controllers (aka resources) to a separated folder called resources.

Next is to setup Dependency Injection on src/resources/user.resource.js to be able to inject an instance of our database service.

In order to do so we're going to install an extension package called @ritley/decorators:

$ npm install @ritley/decorators

Then, lets make a few changes on src/services/database.service.js to be exported as a singleton provider:

 import config from "../config/database.config";
+import { Provider } from "@ritley/decorators";

+@Provider.singleton
 export default class DataService {
   onConnected = undefined

By adding @Provider.singleton we will be able to construct only one instance every time the provider gets executed. That means all classes that declare it as a dependency will share the same instance.

Lets add it to src/resources/user.resource.js:

 import DataService from "../services/database.service";
+import { Dependency, ReqTransformBodySync } from "@ritley/decorators";

+@Dependency("database", DataService)
 export default class UserResource extends AbstractResource {
   constructor() {
     super("/users");
-    this.database = new DataService;
   }

+  @ReqTransformBodySync
   post(req, res) {
+    const payload = req.body.toJSON();
+    this.database.create("users", payload).then(user => {
-    this.database.create("users", { name: "Jimmy Jazz" }).then(user => {
       res.statusCode = 200;

@Dependency executes DataService (now its a provider) then receives an instance and assigns it as a named property after class local constructor gets executed.

So basically we removed complexity that involves service instantiation on controllers. I guess you're familiar with these practices.

You may noticed that we've also removed hardcoded payload and we've placed @ReqTransformBodySync on top of the post method.

This decorator allows to access request body or payload by delaying method execution till its fully received. Like body-parser does but more explicit because you don't need to bother yourself reading method contents to know that it requires payload to properly work, and its more pluggable since you can configure at method level.

Now try to execute this command:

$ curl -d '{ "name": "Pier Paolo Pasolini" }' localhost:8080/users

-X POST is assumed if -d (payload) is provided.

You should reveive a HTTP 200 OK response with ur new user created! Check database contents :)

That's all for now folks! On next chapter on series we will see how ritley manages to link models with controllers, handle exceptions and manage sessions.

How to write Scalable Nodejs Services [+Code Examples]

Ciro Ivan — Thu, 12 Apr 2018 08:19:32 +0000

I recenlty had the opportunity to use OOP patterns on Nodejs environment, and I had a big time doing so.

Lets see what we’re gonna build this time:

Build an API service that provides two resources: apps and developers , but more resources will be added in the future.
Data is read from a NoSql database, but where to read the data may change in the future.
When serving apps, we need to provide its associated developer on a special attribute “author_info” (every model may contain different rules which define how items are served).
For now this service will be only responsible for reading data, but we should allow create and update operations on each model.
We need to be able to change output format for particular models (we have partners that still work with xml format).

Model raw format as is stored on database is as follows:

developer

{
    "id": 23,
    "name": "AresGalaxy",
    "url": "https://aresgalaxy.io/"
},

app

{
    "id": 21824,
    "developer_id": 23,
    "title": "Ares",
    "version": "2.4.0",
    "url": "http://ares.en.softonic.com",
    "short_description": "Fast and unlimited P2P file sharing",
    "license": "Free (GPL)",
    "thumbnail": "https://screenshots.en.sftcdn.net/en/scrn/21000/21824/ares-14-100x100.png",
    "rating": 8,
    "total_downloads": "4741260",
    "compatible": [
      "Windows 2000",
      "Windows XP",
      "Windows Vista",
      "Windows 7",
      "Windows 8"
    ]
},

When fetching developers resource, it should remain as it is. But on fetching apps we need to merge developer model like this:

{
    "id": 21824,
    "developer_id": 23,
    "author_info": {
        "id": 23,
        "name": "AresGalaxy",
        "url": "https://aresgalaxy.io/"
    },
    "title": "Ares",
    "version": "2.4.0",
    "url": "http://ares.en.softonic.com",
    "short_description": "Fast and unlimited P2P file sharing",
    "license": "Free (GPL)",
    "thumbnail": "https://screenshots.en.sftcdn.net/en/scrn/21000/21824/ares-14-100x100.png",
    "rating": 8,
    "total_downloads": "4741260",
    "compatible": [
      "Windows 2000",
      "Windows XP",
      "Windows Vista",
      "Windows 7",
      "Windows 8"
    ]
},

So here are my thoughts on this:

We need to declare resources in a very straightforward manner, but it seems like every resource may be different, both in format and output.

So we need to extract “common” parts from Resource concept and build different and independent implementations for each Model.

What’s a Model ? On REST paradigm we usually call Resource to some domain item that is represented through an URL (api.io/rest/employee), we can easily interact with it using HTTP verbs and providing several parameters.

When writing maintainable APIs we need to differenciate from code which describes rules for every resource and code which defines how HTTP connections are fulfilled.

So I end up by creating two basic entities which are models and resources.

Resources are classes which carry out the HTTP communication, for now we only have a single class because both apps and developers doesn’t contain differences at this layer.
Models are classes which describe how operations, like reading data from database, joining data, formatting output, etc. is done for a particular domain entity, like developer and app, which are different and should be independent.

So we have two models classes developer and app and a single resource class. But, on runtime we’ve two resource instances, each of those has its model instance which is in charge of the specific domain rules.

So this is the start script:

const { setConfig } = require("ritley");
setConfig(require("./ritley.conf"));
const BasicResource = require("./resources/basic-resource");
[
  require("./models/app"),
  require("./models/developer"),
].forEach(Model => new BasicResource(new Model));

We’re using ritley. A lightweight package I made a month ago for fast backend development and specifically REST services.

So in the previous code we only require our ritley configuration which basically setups rest path, static assets folder (if needed) and the port to listen.

Then we just loop over models, and create a resource instance to be tied with its model and we’re up and ready.

Lets take a look over folder structure:

.
├── adapters
│ ├── low.conf.js
│ ├── low.js
│ └── low-provider.js
├── low.database.json
├── models
│ ├── app.js
│ ├── common.js
│ └── developer.js
├── package.json
├── README.md
├── resources
│ └── basic-resource.js
├── ritley.conf.js
├── run.js
├── test
│ └── developers.test.js
4 directories, 13 files

We’ve created models/common.js abstract class to be a starting point for further models:

const { inject, createClass } = require("kaop")
const LowProvider = require("../adapters/low-provider");
module.exports = CommonModel = createClass({
  adapter: null,
  constructor: [inject.args(LowProvider), function(_db) {
    this.adapter = _db;
  }],
  read() {
    return new Promise(resolve => resolve("read not implemented"));
  },
  find() {
    return new Promise(resolve => resolve("find not implemented"));
  },
  toString(obj) {
    return JSON.stringify(obj);
  }
});

You may noticed that I’m not using harmony ES classes. Thats because we need something like decorators and we don’t want to use any code transformer for now. Instead we’re using kaop to easily allow reflection techniques such as Dependency Injection.

So basically previous code declares an abstract model that will contain a lowdb instance adapter to access database. If we change our database service we only have to care about importing another provider.

Code below represents models/developer.js:

const { extend } = require("kaop");
const CommonModel = require("./common");
module.exports = DeveloperModel = extend(CommonModel, {
  path: "developer",
  read() {
    return new Promise(resolve =>
      resolve(this.adapter.getCollection("developers")));
  }
});

This only differs from common model on read method implementation, so we just replace it with a new one.

Note that our DeveloperModel contains path property which will be used by basic resource to listen several paths. Here is how:

const { extend, override } = require("kaop");
module.exports = BasicResource = extend(AbstractResource, {
  constructor: [override.implement, function(parent, _model) {
    parent(_model.path);
    this.model = _model;
  }],
  get(request, response) {
    let prom = null;
    if(request.query.id) {
      prom = this.model.find(request.query);
    } else {
      prom = this.model.read();
    }
    prom.then(result =>
      this.writeResponse(response, this.model.toString(result)));
  },
  writeResponse(response, body) {
    body && response.write(body);
    response.statusCode = 200;
    response.end();
  }
});

BasicResource extends from AbstractResource overriding its constructor for providing the path as you can see on highlighted line, which will be invoked for each instance. As we saw on the start script, models are passed down to resources to properly build our HTTP listeners. BasicResource’s get method will intercept all HTTP GET requests pointing to each path. One instance which was configured with developer model will effectively listen only on <host>/rest/developer path and so forth.

So, a client requesting <host>/rest/developer will be answered by BasicResource instance which was created with DeveloperModel instance.

For instance if we want to allow POST or PUT requests we need to write down a post method on BasicResource, ritley allow us to simply write methods named as HTTP verbs, so any requests that matches will be handled. If we need to allow POST only on several paths we may need to extend BasicResource into AdvancedResource or something which allows more HTTP verbs. This is best practices to properly separate concerns.

And perhaps models need to be grouped by what kind of resource they need to be mounted on.

For example:

const { setConfig } = require("ritley");
setConfig(require("./ritley.conf"));
const BasicResource = require("./resources/basic-resource");
const AdvancedResource = require("./resources/advanced-resource");
[
  require("./models/app"),
  require("./models/developer"),
].forEach(Model => new BasicResource(new Model));
[
  require("./models/company")
].forEach(Model => new AdvancedResource(new Model));

Now lets take a look over initial requirements to see if this is a good approach (question — answer ):

Build an API service that provides two models: apps and developers , but more resources will be added in the future. — adding new models is pretty easy, we only have to create a new one by extending from common one, implement needed methods and declare on start script
Data is read from a NoSql database, but where to read the data may change in the future. — code responsible for accessing data services is on adapter folder, we’re using an awesome resource such as lowdb . We have 3 different files: low.conf.js which contains database path, low.js which wraps lowdb methods into domain related actions for models to consume and low-provider.js which declares a singleton dependency for injecting into models so we can rapidly switch over different database services :)
When serving apps, we need to provide its associated developer on a special attribute “author_info” (every model may contain different rules which define how items are served). — every model has its own methods for retrieving data down to resources so we can build de data as we fit. For this particular case, we created a method on the db adapter because nested models will be a pretty common case here adapters/low.js:

getMappedCollection(uid, joinuid, joinkey, newkey) {
  const joincollection = this.instance.get(joinuid);
  return this.instance
    .get(uid)
    .map(app => this.mergePredicate(
      app,
      joincollection.find({ "id": app[joinkey]}),
      newkey)
    )
    .value();
},
mergePredicate(app, subject, newkey) {
  return { ...app, { [newkey]: ...subject } };
},

and then, since app model is the only one who provides nested items we make use of it models/app.js:

read() {
  return new Promise(resolve =>
    resolve(this.adapter.getMappedCollection(
      "apps", "developers", "developer_id", "author_info")
    ));
},

For now this service will be only responsible for reading data, but we should allow create and update operations on each model. — already solved but gonna show an example:

const { extend, override } = require("kaop");
const BasicResource = require("./basic-resource");
// we only need to implement a new method since this class inherits
// from BasicResource
module.exports = AdvancedResource = extend(BasicResource, {
  post(request, response) {
    // create entry logic
  }
});

We need to be able to change output format for particular models (we have partners that still work with xml format). — if a particular model needs to output differently from others then we need to override toString() method from models/common.js . Say that DeveloperModel needs to output on XML format because some of our partners is still working with 2008 SQL Server so far..

const { extend } = require("kaop");
const CommonModel = require("./common");
const xmlconverter = require("awesomexmlparser");
module.exports = DeveloperModel = extend(CommonModel, {
  path: "developer",
  read() {
    return new Promise(resolve =>
      resolve(this.adapter.getCollection("developers")));
  },
  toString(obj) {
    return xmlconverter.stringify(obj);
  }
});

That’s all for today! Thank you so much :)

You can check the code here https://github.com/k1r0s/micro-ritley-lowdb-example

Angular Tutorial: Separation of Concerns using ES7 Decorators

Ciro Ivan — Mon, 18 Sep 2017 07:08:22 +0000

This tutorial is intended to create a simple Angular app which drives a “common issue in OOP paradigm which is code duplication and hidden patterns usually found in real world that can be solved using Inversion of Control techniques and allowing us to perform declarative programming.

Resources (what this article is about):

The App

The app should load a list of users (authors) in its home page.
If a list element is clicked a dialog should be presented
That dialog should have a brief[1] about the selected user and two buttons
One button should close the dialog
Other button should load user specific â€˜post page’
Clicking on an user from â€˜South Elvis’ will trigger a random exception
Exception should be cached, an error dialog[2] should be presented
Post page should render selected user’s specific posts

[1] User dialog format/content isn’t part of tutorial’s scope

[2] Error dialog format/content isn’t part of tutorial’s scope

Rules

Each time we perform an ajax request we must show a loading dialog
All ajax request should be stored for cache purposes

Technical details

Users (writers) resource is placed here: https://jsonplaceholder.typicode.com/ users

Posts resource is placed here: https://jsonplaceholder.typicode.com/ posts

Let’s start

You can follow these instructions, step by step.

Prepare your workspace

$ git clone https://github.com/k1r0s/angular2-srp-showcase.git
$ git checkout normal-oop
$ npm install

Run the code

$ npm start
browse localhost:4200

Read the code

Okay so lets start by openingsrc/app/components/writers/writers.component.ts . This component has the following responsibilities:

Invoke a service to fetch users
Render users list
Listen clicks on users list
Invoke a service to store users request result and the selected user to be loaded on â€˜posts screen’
Invoke a service to build a dialog to render selected user
Handle an exception if selected user is from â€˜South Elvis’

Now lets look over src/app/components/user-posts/user-posts.component.ts . This one has the following responsibilities:

Grab selected user from cache
Invoke a service to fetch user’s specific posts
Render a post list
Invoke a service to store posts request result for that specific user

Common OOP drives repetition:

In OOP, each method is an action or verb domain related.

Cross Cutting Concerns are pieces of code that brings nothing to understand what this action is really doing by mixing infrastructure concerns with domain concerns.

  // stuff that matters

  // this stuff only represents "SHOW A DIALOG, DOMAIN SPEAKING"
  // 
  this.dialogRef = this.dialogFactory.open( 
    dialogThatNeedsToBeShowed,
    { data: dialogsRequiredData }
  )

  // stuff that matters

Let’s see the code at https://github.com/k1r0s/angular2-srp-showcase/blob/normal-oop/src/app/components/writers/writers.component.ts#L41

Most of times a method body that should describe a business action is entangled with code that does not describe at all that action. Like opening a dialog, capturing exceptions, subscribe to close events, etc.

In OOP we try to separate concerns by declaring classes that are responsible to manage outdoor interactions that describe what business wants to happen (domain speaking). Usually that classes invoke other classes that describe how things should be fulfited.

A common issue in OOP paradigm is that, to replicate a behavior, code must be replicated too. Sometimes class extension isn’t enough because your behavior doesn’t always occur in the same spot or you simply don’t have enough time to change whole app arquitecture. For example, a log service has to be invoked at the end of some method calls printing method’s arguments and result but that implementation isn’t important at all in terms of domain problem meaning that code is polluting your app. Can you deal with logs calls with class extension? nope.

What about projects with 12 developers coding the same behavior with different implementation? That’s hidden patterns. For example when a developer is used to add a feature similar or identical a previous one most of them will seek that previous implementation on the code base to look â€˜how to deal with the same problem’ or simply paste that code in their feature changing some variables related with the context of that specific screen or feature, while some developers will implement their own code to solve the same problem. We don’t care about which implementation is the best. Different implementations for the same problem drives bugs, code is harder to mantain, etc. An easy solution to deal with this are interface definition that all developers must agree. But still duplication spreads.

Authentication, Ajax resolution, UX action invocation, exception handling… almost anything that isn’t related with business logic its likely to be invoked in several places and that implementations can pollute your domain logic.

Examples

Lets back to writers component

What is really doing writers.component.ts at setup ?

Reading the code we may conclude that:

Is reading from cache if resource was already fulfilled (if so list is assigned) and all steps below are skipped
If that cache is empty: We must show a loading dialog[2] and we fetch users resource
Then we should store that resource on cache by calling a service
Then we should hide loading dialog
Then we should asign the list to be rendered by the component

Many concerns take place as this code gets executed. In terms of domain this is simply fetch and render users list. There are a few domain rules that apply on this, catch resources, show a loading dialog while requesting a resource …

That behavior also gets replicated on user-posts.component.ts . But on this case there is a domain concern before: grab the selected user from cache.

There is a way to code that implementation abstracting us from component’s specific domain? Yes!

We already defined some interfaces that writers.component.ts and user-posts.component.ts share: LoadingDialog, ResourceContainer<T>, LoadingDialog, CacheContainer . We also assure that there are no hidden patterns.

Both components have to fetch some resource when created
Both components have to show a loading dialog at anytime
Both have to write/read from cache something

Hence we can achieve this on both components:

Note that the same behavior needs to be invoked in different spots and with different context/arguments.

writers.component.ts (code)

user-posts.component.ts (code)

And this works, trust me (running example).

Tip argsDriverIndex param for @ArgsCacheReader its just a specification of which method arguments index will be used as a serialized key to read/write from cache. This means that user-posts.component.ts will access cache having first fetchPosts argument. Therefore it will not call the same resource twice.

Is important to know that these decorators can be imported everywhere and are completly standalone (that depends on you). Meaning that you can remove some of them without messing callstack while in common OOP implementations you face side effects.

Conclusion

Method and class Decorators are a powerful tool against repetition and, it also provides a needed abstraction layer needed in modern applications. We have cleared infrastructure code from our component by using declarative programing whichs aims for:

“Remove side effects by describing what the program must accomplish in terms of the problem domain, rather than describe how to accomplish it as a sequence of the programming language primitives”.

Our code is clear as water and easy to mantain.

We have to understand that we have created a strong association with two components which can become very different in the near future. So if our abstraction is somehow deprecated, we must remove this decorator from that component which no longer match a pattern (interface), paste its implementation and code the difference.

Bonus

Why Decorators?

Decorators are bread and butter in modern libraries like Angular, Vue (addon), also in backend, for instance Nest framework provides a lot of built in decorators to enhace your dev experience, improve readability, separate concerns.. etc.

Decorators are nice because provide you a language feature that allows you to add/remove/manage rich implementations without messing in language primitives.

Maybe in the near future decorators will be used as “standalone plugins which can be downloaded and plugged in your code providing features (example).

For instance, Angular’s @Component decorator is a neat way to register your class as a web component into angular boilerplate. So why you wont define some for your own needs?

How to @ in Typescript/Babel?

Babel does not support interfaces to deal with hidden patterns , but it supports method and class decorators.

Currently if you need to write a function that needs to be called before specific constructor in some classes you need to deal with ES7 decorators API which is well explained in TS docs.

I created a library that makes very easy define your own method/class decorators. It will allow you to change, extend, modify the behavior of methods and constructors non-invasively. Of course this tutorial example was made using that library.

Give a try!

This post was originally published on medium.com

How To Handle Exceptions With Aspect Programming And Blame Covfefe

Ciro Ivan — Sat, 03 Jun 2017 11:43:40 +0000

Today I'm going to show you a brief, yet useful example of Aspect Oriented Programming.

import * as React from "react";

import Sidebar from "../Sidebar/Sidebar.main";
import Content from "../Content/Content.main";

import { Advices } from "../../advices/Advices"
import { onException, afterMethod } from "kaop-ts"

export default class Root extends React.Component<null, null> {

    someProp: any

    @onException(Advices.blameCovfefe)
    @afterMethod(Advices.throwOnError)
    render(){
        return (
            <div className="mainContainer">
                <Sidebar />
                <Content />
                {this.someProp.nil}
            </div>
        )
    }
}

This is what we get on execution:

Uncaught TypeError: Cannot read property 'nil' of undefined despite the constant negative press covfefe

Here is the implementation of Advices

import { AdvicePool, adviceMetadata, IMetadata } from 'kaop-ts'

export class Advices extends AdvicePool {
  static blameCovfefe (@adviceMetadata meta: IMetadata) {
    meta.exception.message += " despite the constant negative press covfefe"
  }

  static throwOnError (@adviceMetadata meta: IMetadata) {
    if(meta.exception) {
      throw meta.exception
    }
  }
}

Maybe this is not a good example, but if you know Twitter's API it might be useful to distract several taxpayers..

But if you think previous example was funny somehow.. Instead of throwing an exception, it would be nice render an error component each time our app fails:

import { AdvicePool, adviceMetadata, IMetadata } from 'kaop-ts'
import { Covfefe } from './covfefe-components'

export class Advices extends AdvicePool {
  static blameRussia (@adviceMetadata meta: IMetadata) {
    if(meta.exception) {
      meta.result = <Covfefe/>
    }
  }
}

Okay

Welp. The idea about Aspect Oriented Programming (aka AOP) is to manage common problems in one place and still access to the needed context.

In this article we're going to use kaop-ts

In the previous example we need to capture exceptions when they occur somehow but we don't want to mess our code pasting same blocks of code everywhere. We simply want to tell our application to apply encapsulated patterns in several life cycle hooks in OOP paradigm (aka: 'Join Points').

AOP is an extension of OOP. It helps us to encourage abstraction and modularity. It is a strong tool against repetition.

You probably remember situations where you've had to paste some blocks of code only replacing one variable or reference in order to replicate some behavior. Think about logs, yeah.

But there are many other cases, most of them are fairly covered by frameworks. In NodeJS environments, for example, Express deals with lots of "common problems" that almost nobody has to deal with, like receiving payload from a HTTP request.

AOP is everywhere, but most frameworks don't provide you tools to extend this technique, by providing access to Join Points. AngularJS, for example, brought a bunch of nice solutions to common problems when JQuery or EJS/Underscore templates were the only way to deal with DOM manipulation.

Modern frameworks that include DOM manipulation like Vue or Angular, and many others encourage declarative programming, which includes implicit instructions to be executed to achieve its purpose (DOM manipulation) my removing the side effects. React is more explicit, the idea of JSX with the virtualDOM was simply awesome.

kaop-ts is nice for building big things from the bottom with a powerful layer of abstraction and architecture assets. But it also enhances your code by providing access to Join Points (aka: 'apply encapsulated patterns in several life cycle hooks in OOP paradigm by accessing dynamic contexts').

Nowadays it includes access to: AfterInstance, BeforeInstance, AfterMethod, BeforeMethod, OnException where you can retrieve:

export class Registry extends AdvicePool {
  static log (@adviceMetadata meta: IMetadata) {
    meta.args // Arguments to be received by decorated method
    meta.propertyKey // Name of the decorated method as string
    meta.scope // Instance or the context of the call stack
    meta.rawMethod // Original method (contains metadata)
    meta.target // Class definition
    meta.result // The returned value by the method
  }
}

You may read and write these references and, of course, perform async request without messing the call-stack. In other words, you can access service layer within Advices (aka: 'functions that are executed within Join Points') and perform async requests to retrieve data and inject to decorated methods.

Read this piece of code carefully:

// view.ts
import { beforeMethod } from 'kaop-ts'
import { PersistanceAdvices } from './persistance-advices'
import { FlowAdvices } from './flow-advices'
import { OrderModel } from './order-model'

class View {
  @beforeMethod(PersistanceAdvices.read, OrderModel)
  @beforeMethod(FlowAdvices.validate)
  update (data?) { ... }
}


// persistance-advices.ts
import { AdvicePool, adviceMetadata, adviceParam, IMetadata } from 'kaop-ts'
import { Service } from './somewhere'
import { ICommonModel } from './somewhere'

export class PersistanceAdvices extends AdvicePool {
  static read (@adviceMetadata meta: IMetadata, @adviceParam(0) model: ICommonModel) {
    Service.get(model.url)
    .then(data => meta.args.push(data))
    .then(this.next) 
  }
}

this.next is a tool to explicitly tell kaop-ts that the current operation needs time to finish, so following operations will wait until fulfilled

Note that View class has a method called update, if we instantiate View and call update() on it we re going to trigger a composed call-stack, but the implementation is clean, declarative and is out of side effects.

Our viewInstance will receive request data as an argument in update method and it will be executed as if we provided explicitly as an argument.

So, thanks for reading. Hope you enjoy it. Checkout the repo and feel free to contribute :) happy codding!

Hail covfefe.