This article discusses what an SDD is, why some engineers do not want it and while other engineers embrace it, tips on writing an SDD, some necessary components of a design doc, and how to measure if the documentation process was a waste of time.

What is a Software Design Document?

An SDD provides a detailed description of your software design. It functions as a reference for software engineers to build. It contains assumptions, dependencies relating to the software and its uses, general constraints, goals, guidelines, and all development methods involved in developing the software.

Arguments against SDD

• Humans not wanting to write: Writing documents can be tiresome. Some engineers have formed the habit of documenting after building since building is where the fun is. Sometimes you are staring at the screen not knowing where to start or how to continue.
• Pace of software growth: This is similar to the argument that people have against writing comments, it is argued that the code is likely to move and change so fast that the comment becomes obsolete since the engineer might not remember to update it. Now compare this to a doc separate from your code. The likelihood of keeping up might be lower. Assuming this becomes true, then the developers who built a whole multi-page document might feel like they had wasted time putting it all together and the developers who are new to the system might not be able to trust what the SDD says again.
• Management pressure: Others complain that the pressure from management reduces the chances of dedicating time to putting together a whole document.

Arguments for SDD

• Timeline Calculation: Knowing exactly what to do and how you plan to do it, makes it easier to calculate how long it will take for it to be done with ease and better accuracy.
• Meet Stakeholders Criteria: It becomes easier to know exactly what the stakeholders are looking out for since you think about the task thoroughly before building, asking questions for clarity, sharing the documents with all stakeholders, and getting feedback. This makes it easier to build systems that meet the stakeholder's criteria.
• Point of Reference: The document serves as a point of reference whenever you are unsure how to proceed or have others mentioning new issues with claims that it was discussed before you started building the project.
• Easier to onboard new Engineers to the Project: The document ensures that any engineer joining the team can easily pick up the project since the SDD is easy to read and comprehend and covers all aspects of the project.
• Decision making: It ensures that all design decisions are made and the ones not made are noted.

Tips for Writing an SDD

• Keep it simple: Make it so simple that even a five-year-old reading the doc will have no other option than to understand what you have written. Okay, that may be over the top, but you get the point.
• Use of Images: Where necessary, throw in something pictorial to drive home the point. It might be a chart, diagram, or graph. Also, provide a link to the editable copy.
• Jokes: Just like salt to a meal, ensures that the meal does not taste bland. Adding safe-for-work jokes to your doc will spice it up a little and make it not a boring read. But like salt to a meal, adding too much might distract from the purpose.
• Preempt: Preempting possible scenarios, and questions your reviewers may throw at you will help you go through it and get fully prepared before presenting it to your reviewer.

Deciding if the SDD is a Success

It is either you finish the task on time, with it meeting stakeholders' requirements and running properly, or you find an issue that needs solving before you complete the project. You then look to ensure it is not a dead end and if it is a dead end, you may decide to leave the project or find a better solution.

Components of a Design Doc

• Title and People: This section contains the document’s title, authors, reviewers, the date the document was last updated, and everyone who will work on the project alongside you.
• Summary: This section contains an easy-to-grasp top-level summary every engineer should read to decide if they are meant to go on reading the document.
• Background: In this section, we discuss what the problem we are trying to solve is, why a solution is necessary, how the solution can be accessed, and how the solution fits into the goals and strategy of the team.
• Goals: This section looks at how success will be measured and the tools to measure it. It also looks at how it affects the end user, especially in scenarios where you have direct access to them. Either the direct users are humans or other systems.
• Milestones: Your document should contain a clear high-level list of important activities when they are expected to be accomplished, and who is responsible for accomplishing them.
• Solutions: Here, we look into the existing solutions (if any) and how the solution is being used. Then we look into the new solutions, the technical diagrams, architecture, and system designs as well as the user stories to explain them all.
• Discussion: All unanswered questions are presented so that the reader can weigh in their opinions (if any).

Conclusion

I believe having a doc like this will solve the problems I faced, mentioned at the beginning. I have started using one for my team and me. Though it does not include all the components mentioned since they are small tasks expected to run in a sprint or two. But having a document similar to this has been of immense blessing in helping us solve a lot of issues before building. If you are not in favour of the SDD, it is understandable. We all will not like everything ☺️.

If you made it this far, thanks for reading!

The five principles are:

• Single Responsibility Principle.

• Open Closed Principle.

• Liskov Substitution Principle.

• Interface Segregation Principle.

• Dependency Inversion Principle.

This article explains each of the solid principles with examples in TypeScript. Even if you do not understand TypeScript, the article is written to be simple and easy to understand, like codebases written following these principles.

Prerequisites

This article assumes you have basic knowledge of TypeScript and object-oriented programming. As the examples are all classes written in TypeScript.

Single Responsibility Principle

The principle states that a class should have only one reason to change. In order to achieve that, a class should only do one thing alone. This makes a class smaller and less fragile. It also ensures that people can work on various parts of the codebase without having a merge conflict

class User {
    create() {
        console.log('User created')
    }

    index() {
        console.log('Users returned')
    }

    fetch() {
        console.log('User returned')
    }

    sendNotification() {
        console.log('Notification sent')
    }

    login() {
        console.log('Login successful')
    }

    logout() {
        console.log('Logout successful')
    }
}

Looking at the example above, we can see that the Single Responsibility Principle is not being obeyed. This class handles other issues, such as authentication and notification. So to follow the principle, we will move the sendNotification method to a different class where everything pertaining to notifications is being handled and move the login and logout method to an authentication class where login and logout will be taken care of.

Open-Closed Principle

This principle states that a class should only be opened for extension and closed for modification. This principle ensures that:

• Existing classes do not have new bugs introduced to them.

• New additions are tested in isolation.

• The single responsibility principle is not broken.

This means that we should only be able to add new functionality to a class and not edit existing code. Looking at the example from the Single Responsibility Principle, let's assume the business tells us we have new users all the way from the planet Mars and more coming from other planets later. Our business has decided to have them sign up. We do not need to edit the create method to have them come in, instead, we can make the user class abstract, the create method abstract, and create a new class for Martians with a create method to overwrite the existing create method on the user class. While also having access to the initial methods on the User class.

abstract class User {
    abstract create(): void

    index() {
        console.log('Users returned')
    }

    fetch() {
        console.log('User returned')
    }
}

class Earthlings {
    create() {
        console.log('User created')
    }
}

class Martian extends User {
    create() {
        console.log('User created')
    }
}

From the example above, we moved the existing implementation of the create function to New Classes. So while the user class contains methods solely for all users, the Martian class will also contain methods and properties for users from mars.

Interface Segregation Principle

This principle is all about having separate interfaces. If a class does not implement a property or function in an interface, then it has no dealings with that interface in the first place.

So going back to our Authentication class we mentioned earlier. Our interface for it will look like

interface Auth {
    login(): void;

    logout(): void;
}

class Authentication implements Auth{
    login() {

    }

    logout() {

    }
}

Liskov Substitution Principle

A superclass can be swapped with a subclass, and the method using the class will not notice the change. Using the principle if such a swap happens, nothing should break, and the system should perform as if no change happened. This means that if we are to override an existing method, the new implementation should exhibit similar behaviour to the existing method in the base class. For example,

Looking at the image, we realise that the plastic duck cannot be substituted for a live duck.

Another example will be

class Animal {
    walk() {}

    speak() {}

    eat() {}
}

class Lion extends Animal {}

class snake extends Animal {}

From our example, we realised that this is a bad example since a snake cannot walk but crawl. So let’s have an example that adheres to this principle

class Animal {
    speak() {}

    eat() {}
}

class WalkingAnimal extends Animal {
    walk() {}
}

class CrawlingAnimal extends Animal {
    crawl() {}
}

class Lion extends WalkingAnimal {}

class Snake extends CrawlingAnimal {}

From this last example, we can see that, Lion can be substituted with Animal or WalkingAnimal class, and it will function well.

Dependency Inversion Principle

Looking at our earlier examples. Let's assume the Auth class needs to send a notification whenever a user logs in. Our auth class will look like this:

class Authentication {
    login() {
        const alert = new Alert();
        alert.send()

        console.log('User logged in')
    }

    logout() {

    }
}

class Alert {
    send() {
        console.log('Notification sent')
    }
}

The issue with this first is that the open and closed principle can easily be broken once we decide to switch our notification class, while already breaking the Dependency Inversion Principle.

So what is the Dependency Inversion Principle? The principle states that:

• A high-level class should not depend on a low-level class.

• A high-level class and a low-level class should depend on an abstraction.

• An abstraction should not depend on any class implementation.

From the example, we can see that our high-level class is the authentication class while the low-level class is the Alert class.

So what is an abstraction? To illustrate, you own a car but cannot describe how the car ignition comes on in full detail. But the car manufacturers decided a long time ago that such knowledge should not be a burden to you. So they provide you with a simple interface such as a point where you insert a key and turn the key or a button. From our illustration, we can say that abstraction is simply the act of separating the content of a class from its implementation.

The example below shows how Dependency Inversion can be achieved.

class Authentication {
    login(alert: IAlert) {
        alert.send()

        console.log('User logged in')
    }

    logout() {

    }
}

interface IAlert {
    send() :void
}

class Alert implements IAlert {
    send(): void {
        console.log('Notification sent')
    }
}

const auth = new Authentication()
auth.login(new Alert())

Looking at the example we can see that both the Authentication and the Alert class depend on the IAlert interface. Also, this method makes the code less rigid. Let’s assume that for some reason management decides to introduce sending alerts using SMS instead of emails. And a new class is created. All it needs to do is implement the IAlert interface and be passed as an argument in the login method and we are good to go.

Conclusion

If you have made it to this point, thanks so much and I hope this article was informative.

We have covered the five SOLID principles with practical examples of how they can be applied. I hope you get to apply it as much as possible to make your code less fragile, rigid, and more testable, understandable, and maintainable. Thanks.

• Why we need a test double?
• The different types of test doubles.
• What look out for when using a test double.

Why use a test double

We use test doubles in any of these situations

• The object it depends on is not available.
• There is an uncertainty in the result the object will return.
• Running the object will lead to undesirable side effects.

Types of test doubles

We look at five(5) types of test doubles.

• Dummy Object: As the name implies are dummies, nothing special about them. They are in use when you need to fill a position, as a necessary parameter to call a method or create an instance of a class. Dummy objects are empty, no methods, no properties, so it cannot take any action and does not need to.

• Fake Object: Like an imitation of an original look like the original but is lacking in some ways. The fake object unlike the dummy object contains some implementation of the object in production. Unlike the object in production, fake objects have a lot of short cuts and are more simplified. The shortcut and simplification allow for the avoidance of undesirable side effects. An in-memory database used in testing is an example of a fake object.

• Test Spy: Test spy like a spy sits back to gather information about the interaction of the logic under test and the object it is replacing. The details in this information are verified after the logic under test is done with the test. Spies verifies actions felt outside the code under test.

• Mock: A Mock is like a spy, but an impatient one if I may say. A mock verifies the action triggered by the logic under test, but felt by other systems takes place by defining the expectations for it before the logic under test is run.

• Test stub: A test stub is an object that has no logic but only a predefined response.

What to avoid when using test doubles

These are a few tips to have in mind when using test doubles.

• Do not use too many test doubles in a test.
• Your test doubles should not be complex.
• Do not replace data structures with test doubles.

Conclusion

In conclusion, I hope this explains to beginners what test doubles are and the various types. If you have made it here kindly like the article and drop a comment. Thanks.

Requirements

• A free or paid Twilio account. If you are new to Twilio you can sign up by clicking here.
• Knowledge of javascript or a desire to learn.
• Web browser.
• A device with Whatsapp installed on it and working.

Setting up a Twilio function

1. After logging in to your Twilio account.
2. Click on the icon with the three dots at the left top corner below the home icon to open the menu.
3. Clicking on the icon opens the sidebar, on the sidebar scroll down to the RUNTIME section and click on Functions.

1. We need to create a service. A service is like an application container to store your functions for a project. To create a service, we click on the create service button

1. Clicking on the button, a modal popup asking you to name the service. The name will be the first part of your serverless domain.

1. After inputting the name and clicking on the Next button. It creates a service.

2. We next add a function to the service by clicking on the add button at the top left side of the screen.

1. Click on the add function option. Input the name of the function and press the enter button. The function forms and a code sample in the code editor appear to get you started.

Sending Whatsapp messages

After setting up a function we need to configure it to send Whatsapp messages. The following steps below explain how to do it.

1. Click on the three horizontal dots beside the function name. Select the Copy URL option.
2. Click on the icon with three dots on the top left corner of the screen to open the side menu.
3. Select Programmable messaging.
4. Select Settings at the bottom of the sidebar menu.
5. Select Whatsapp Sandbox Settings
6. Input the URL generated when you created the function into WHEN A MESSAGE COMES IN field.
7. Scroll to the bottom and click on save. Let us move back to the code editor of the existing function. Follow steps two(2) to three(3) steps mentioned when discussing how to set up a Twilio function, above.
8. Click on services or manage services.
9. From the list of existing services, click on the service we are working with.
10. Click on the function you are working with to ensure it appears on the code editor if it is not open.
11. Delete the entire content of the function block except for the return statement.
12. Paste the following code to send a hello world response back when we send a message.

    let twiml = new Twilio.twiml.MessagingResponse();
    twiml.message('Hello World');
    

13. Click on Save and after saving click on Deploy All. Below is a GIF showing the entire process.

Test

To test what has been done so far, we need to go to step five(5) of sending Whatsapp message above to get the Whatsapp number and sandbox name.

On your device open your Whatsapp application and send join to the number to get it connected. Send any message to the Whatsapp number and get the hello world message specified in twiml.message('Hello World');.

Sending a Text message

To send text messages we need to set up a new function. On creating the new function, we set the necessary environment variable and visibility of the function.

Setting Environment Variable

To set environment variables we need to follow this few steps:

1. Go down to the Settings section at the bottom towards the left and click on Environment Variables.

1. Click on the check box that says "Add my Twilio Credentials (ACCOUNT_SID) and (AUTH_TOKEN) to ENV". If it is not checked already.

Set Function Visibility

Every function by default has their visibility set to "Protected" which means we need to have a valid Twilio signature to our request headers to invoke the function. For this tutorial, we will be using the "Public" option that allows us to invoke the function from the browser. To set the visibility of a function we:

1. Click on the drop-down menu to the right of the function name
2. Select the visibility we want, which for now is public.

We go back to the function block, delete every code in it, make the function asynchronous and add a try-catch block.

exports.handler = async function(context, event, callback) {
  try {

 catch(error) {

  }
}

Next we:

1. Make a call to getTwilioClient method. It is in the context parameter. The context parameter is where we can interact with the environment variable and also the pre-initialised Twilio REST Client. So it returns an initialised twilioClient.

   const twilioClient = context.getTwilioClient();
   

2. Set the variables to, from and body using the event parameter or a pre-defined value.

    let from = event.From;
    let to = event.To;
    let body = event.Body;
   

   1. Make a call to the Twilio REST Client API by passing by chaining the create method to messages method and the message method to the twilioClient. We pass the body, to and from variables in an object to the create method.

      await twilioClient.messages
      .create({
        body,
        to,
        from,
      });
      

3. Add the return statement both in the try block and also the catch block. return callback(null, 'success'); to the try block and return callback(error); to the catch block.

4. Click on save and then on Deploy All after saving.

The code will finally look like.

exports.handler = async function(context, event, callback) {
  try {
    const twilioClient = context.getTwilioClient();

    let from = event.From;
    let to = event.To;
    let body = event.Body;

    await twilioClient.messages
      .create({
        body,
        to,
        from,
      });

    return callback(null, 'success');  
  } catch(error) {
    return callback(error);
  }
}

Testing

To test the SMS sending we

1. Click on the three horizontal dots beside the function name. Select the Copy URL option.
2. Open a browser and paste the URL there
3. Add the query parameters From, To and Body in this manner. ?From=+15095550100&To=+15105550100&Body=Hello%20World It is important to note that if you are using a trial account. From will be your trial phone number found on your dashboard. To will be the number used in creating the Twilio account or any other phone number you add to it.
4. Attach it to the URL in the browser and get a success response.

Conclusion

If you have made it this far, thanks. We looked at how to set up Twilio functions to send SMS and Whatsapp messages. How it does not need installing Twilio in your codebase and allows your messaging service to run outside your application. Drop your comments and feedback in the comment section and click on the like button. Thanks.

Importance of flow chart

• breaking down complex algorithms
• helps team members understand the order in which a process follows
• creates a visual representation of the steps involved in a project
• helps document a process

Flow chart symbols

We will look at the five most used flow chart symbols

• Terminators: This symbol is oval-shaped and sometimes appear as a circle. It signifies the beginning or end of a process depending on where it appears.

• Data: This symbol takes the shape of a parallelogram. It signifies the input or output of data.

• Decision: This symbol has the shape of a rhombus or diamond. It shows that a decision needs to be taken, it branches out based on the outcome of the decision.

• Processes: This symbol can be a rectangle or square but mostly a rectangle. It shows the next step to be taken.

• Arrow: This symbol shows the direction of flow from one step to the other.

Sample flow chart

The sample flow chart shows the steps involve when a user tries to log in on a webpage.

Tools for creating a flow chart

These tools consist of a pen and paper to software tools that are free and some that are paid. Below are examples of some:

• Pen and Paper
• diagrams.net
• Pencil Project
• Creately
• Lucidchart

Flow chart best practices

To create a flow chart we should always keep it in mind to have it very simple and to be consistent. Some steps we can follow to achieve that includes

• Use standard symbols
• Make the text readable even if it means spanning your flow chart across many pages.
• Spacing between symbols, Colour schemes and symbol size should be consistent
• Flow direction should be top to bottom or left to right and never interchangeable
• While drawing a decision symbol, flow direction should be to the right for negative answers and downwards for positive answers.
• Never assume everyone knows what each symbol in your flow chart represent, use a key to describe each symbol and its meaning.
• Double-check the processes to ensure they are fully represented in the flow chart.

Installation

1. We run npm init -y. It sets up a new Node.js project in the current folder with the default details without asking any questions.
2. We install typescript globally using npm install -g typescript. Next, we set up a new typescript project by running the command tsc --init. The tsc --init command creates a tsconfig.json file.
   Open the generated tsconfig.json file and update the following details

    "target": "es2015",
    "outDir": "./dist",     
    "rootDir": "./src",
   

   The key rootDir describes the root directory that typescript will compile from. The key outDir describes the directory to save the compiled file. The key target describes the lowest level to compile the code to.
3. We install AdonisJs Ace which is a tool for creating command-line applications in Node.js

   npm i --save @adonisjs/ace
   

4. We install type definition for Node.js, that allows you to use global values like process, require etc. in typescript.

   npm i --save @types/node
   

Creating the Shebang

According to Wikipedia

In computing, a shebang is the character sequence consisting of the characters number sign and exclamation mark at the beginning of a script. It is also called sha-bang, hashbang, pound-bang, or hash-pling.

The Shebang tells the operating system what interpreter to use in running the script. To create the shebang:

1. We create the src folder, in the project root folder.
2. We create a folder called bin in the src folder.
3. We create a file we will call numb-cli.ts.
4. We paste the shebang by pasting the line below.

#!/usr/bin/env node

console.log('Welcome')

1. We update the package.json file by adding the key-value pair.

   "bin": {
    "numb-cli": "dist/bin/numb-cli.js"
   },
   

   Testing the Shebang

   To test if the shebang is working,
2. We compile the typescript file into javascript by running the command tsc on the terminal.
3. We install the package globally by running the command npm link
4. We run the package by running the command numb-cli.
5. It should return the response Welcome. N.b: To uninstall the package, use the command npm unlink.

Create index.ts file

After testing the shebang, we add the line import ".."; in place of console.log('Welcome'). The new line will import the index.ts file, which we will create in the src folder. In the package.json file we update, the value for the key "main" with "dist/index.js",. So the package.json file becomes:

{
  "name": "numb-cli",
  "version": "1.0.0",
  "description": "",
  "main": "dist/index.js",
  "scripts": {
    "test": "echo \"Error: no test specified\" && exit 1"
  },
  "bin": {
    "numb-cli": "dist/bin/numb-cli.js"
  },
  "keywords": [],
  "author": "",
  "license": "ISC",
  "dependencies": {
    "@adonisjs/ace": "^5.0.8",
    "@types/node": "^14.14.7"
  }
}

And the src/bin/numb-cli.ts becomes:

#!/usr/bin/env node

import "..";

In the index.ts file, we import ace, and set it up to execute commands

import ace from '@adonisjs/ace';

ace.wireUpWithCommander()
ace.invoke()

This should work when tested, but the @adonisjs/ace package has no type definition so it will not compile the typescript to javascript. Let us create a declaration file for @adonisjs/ace.

Creating declaration file

At the root of the src folder:

1. Create a folder called @adonisjs
2. Create a file called ace.d.ts
3. Paste in the line declare module '@adonisjs/ace'; On testing, a response like the one below will appear.

Creating commands

To create commands, we extend the ace command class. The new class enables us to overrides the signature, description and the handle method.

• Signature method: The signature method is a getter that returns the name of the command
• Description method: The description method is a getter that returns a description of the command.
• Handle method: This is a method that is called when we call the command. It is an asynchronous method. It accepts two (2) parameters which are not compulsory,
• args
• options We register the new command by passing it as a parameter to the ace.addCommand method, which we call in the src/index.ts file.

The src/index.ts file becomes

import ace from '@adonisjs/ace';
import Random from './commands/Random';

ace.addCommand(Random);

ace.wireUpWithCommander();
ace.invoke();

We will call the command subclass Random and keep it in a Random.ts file in the commands folder. The Random.ts file will contain:

import {Command} from '@adonisjs/ace';

class Random extends Command {
    static get signature ():string {
        return 'random';
    }

    static get description ():string {
        return "Returns a random fact about a number";
    }

    async handle () {
        console.log('Welcome');
    }
}

export default Random;

On testing the created command we get

Asking questions

@adonisjs/ace provides methods to ensure that interaction with users occurs. To interact with users, we will use the ask and the choice method amongst others. The ask method accepts the question and a default answer which is optional as parameters. It allows a user to input a response to the question asked. The choice method accepts 3 parameters, a question, an array of options to choose from and an optional default option. Using the two methods mentioned above, we ask the users what number he/she wants a random fact about and what category the random fact will be about. The code in the Random.ts file will look like this:

import {Command} from '@adonisjs/ace';

class Random extends Command {
    static get signature ():string {
        return 'random';
    }

    static get description ():string {
        return "Returns a random fact about a number";
    }

    async handle () {
        const number:number = await this
            .ask('Input a number')

        const category:string = await this
            .choice('Select a category', [
                'trivia',
                'math',
                'date',
                'year'
            ]);
    }
}

export default Random;

Testing the CLI should return:

Making an HTTP request

There is a need to use the details gotten earlier from the user in other get the random fact. @adonisjs/ace does not have the capability to make an HTTP request. To make an HTTP request we install the got NPM package.

npm i got

The command above installs got as a dependency. Next, we import got into the Random.ts file.

import got from 'got';

In the handle method of the Random class, we make an HTTP get request to the URL that returns the fact.

const url:string = `http://numbersapi.com/${number}/${category}`

const response = await got(url);

Displaying response

At this point, the user needs to see the random fact. This is possible with either the methods provided by @adonisjs/ace Command class or with the use of methods of the Console class. The @adonisjs/ace methods each give the displayed text to a unique colour. With the console methods, the text becomes beautiful using the this.chalk method of the Command class. this.chalk accesses an instance of kleur offering flexibility to the user. We add Icons to the displayed response by using the this.icon method of the Command class and passing one of the acceptable parameters which are:

• success
• error
• info
• warn Each of this parameter represents a particular colour and an icon. For the CLI we add the snippet below to display other response as well our icon

  this.success(`${response.body} -  ${this.icon('success')}`);
  

Handling exceptions

We have built the CLI this far:

• Creating a command;
• Asking questions;
• Accepting responses;
• Making an external HTTP request;
• Getting back results;
• Displaying the results to the user.

But what if there is an exception since we did not confirm user input and other errors that may occur from making an external network call. To handle this @adonisjs/ace provides an event listener onError. The onError listens for exceptions, notes the command that throws it, and passes the exception and the command to a closure function. The closure function is where we display the error message from and stop the running process. The onError listener is a method of the ace class and is placed in the index.ts file. Since the use of icons and colourful text displays works as methods on the command class. We create an instance of the Command class so we can use its methods. To throw an exception we check the user input ensuring it is a whole number. So in the handle method of the Random class, we add these checks:

// check if number is of datatype number
if(isNaN(number)) {
    throw new Error(`${number} is not a number.`)
}

// ensures that number is not a float
if(number % 1 != 0) {
    throw new Error(`${number} should not be a decimal number`)
}

The index.ts file becomes:

import ace, {Command} from '@adonisjs/ace';

interface ErrorMessage {
    message: string;
}

const command = new Command()

ace.onError(function (error:ErrorMessage, commandName:string) {
    command.error(`${commandName} reported ${error.message} - ${command.icon('error')}`)

    process.exit(1)
  })

The interface ErrorMessage used above ensures the datatype of keys within the error object. So it becomes the datatype for the object.

Conclusion

This article explains how to build a Nodejs CLI using typescript and @adonisjs/ace. Always remember to compile to javascript before running and to always unlink before linking back when testing a new update. Finally, the code in the index.ts file will be:

import ace, {Command} from '@adonisjs/ace';
import Random from './commands/Random';

ace.addCommand(Random);

interface ErrorMessage {
    message: string;
}

const command = new Command()

ace.onError(function (error:ErrorMessage, commandName:string) {
    command.error(`${commandName} reported ${error.message} - ${command.icon('error')}`)

    process.exit(1)
  })

ace.wireUpWithCommander();
ace.invoke();

and the class in the Random.ts file will be:

import { Command } from '@adonisjs/ace';
import got from 'got';

class Random extends Command {
    static get signature ():string {
        return 'random';
    }

    static get description ():string {
        return "Returns a random fact about a number";
    }

    async handle () {
        const number:number = await this
            .ask('Input a number')
        if(isNaN(number)) {
            throw new Error(`${number} is not a number.`)
        }

        if(number % 1 != 0) {
            throw new Error(`${number} should not be a decimal number`)
        }

        const category:string = await this
            .choice('Select a category', [
                'trivia',
                'math',
                'date',
                'year'
            ]);

        const url:string = `http://numbersapi.com/${number}/${category}`

        const response = await got(url);

        this.success(`${response.body} - ${this.icon('success')}`);
        process.exit(0)
    }
}

export default Random;

To learn more about @adonisjs/ace you can check the official documentation here. @adonisjs/ace also has the ability to work with the filesystem and the database. I hope this helps as a starting point in showing how to use the @adonisjs/ace and also how to use it with typescript. If you have come this far thanks for reading. Kindly drop your comments in the comment section.

Finding locally installed node modules

To locate where the locally installed modules will be located or are placed. We use the command npm root. If you are in a folder without any node modules installed and which has not being initialised using npm init for a node package. The command returns the location where your node modules will exist. If you are in a folder with a node module installed or which has been initialised for a node package. The command returns the node modules location.

Here it returns the would-be location of the node_modules folder. if it existed. Let us check for the installed modules in the node_modules folder returned in the image above using the npm list command.

From the GIF above we can see that there are no node packages located in the node_modules folder.

From the motion graphics below, we see that the npm _commands folder is empty.

We install some packages into the folder using the npm install <package name> command. Check for the node_modules folder and the installed modules. To check for the installed modules, we use the npm list command used earlier.

Finding globally installed node modules

We know that locally installed node modules are located at the root of the package in the node_modules folder. So, where are our globally installed node modules? To find the location we add the suffix -g to the command we used earlier. So the command becomes npm root -g.

The GIF above shows the location of where all globally installed modules are installed. To list the modules installed globally, we add the suffix -g to the command used earlier. The command becomes npm list -g.

The command npm list or npm list -g also returns the dependency in each installed module. To avoid displaying the dependency use suffix --depth=0.

Conclusion

This article has shown how to find the location of node modules installed locally and globally and how to list out each module. All from the comfort of your command line application.

Prerequisite

I will assume you have Node.Js and VS code editor installed on your system and you can create a REST API. The code used is found in this repo.

Debugger Features

Breakpoints

Breakpoints specify where the running code will break into the debugger. You can create a breakpoint to be absolute or conditional.

• Absolute Breakpoints: The debugger stops running the code when it gets to where a breakpoint is specified. It turns on or off by clicking on the editor margin.

• Conditional Breakpoints: Conditional breakpoint signifies that a criterion becomes true before the breakpoint breaks the code execution. To create a conditional breakpoint, you right-click on the editor margin and select the one you want. Two types of conditional breakpoint exist:

  • Expression: The breakpoint breaks the code when the expression becomes true.

  • Hit Count: It determines how many times a line of code needs to be hit before the code breaks execution at that line.

• Logpoint: Logpoint is a breakpoint which does not break the running code but prints a message. The value in a variable can be displayed by putting the braces in curly braces. A logpoint can be created by right-clicking on the editor margin and selecting logpoint.

After creating each breakpoint it appears in the BREAKPOINTS section at the bottom of the sidebar.

Variables

This section appears at the top sidebar when a debug section is paused by a breakpoint or with the use of the pause icon on the debug toolbar. The variable section allows you to:

• View the value of variables in the code at the point in which the code was paused.
• Change the value of a variable by double-clicking on it, inputting your desired value, and pressing the enter key.
• Add a variable to a watch list.

Watch

This section allows you to focus on the specific variable(s). You choose which variable to focus on by right-clicking on the variable and selecting the "Add to Watch" option.

Debug toolbar

The debug toolbar appears at the top of the editor when a debug section starts. From left to right each of the icons represents:

• Continue / Pause
• Step Over
• Step Into
• Step Out
• Restart
• Stop

Debug console

It displays logged output while debugging a program. This output is logged either with the Node.js console module or VS code's debugger logpoint. To open the debug console, click on view and select Debug Console or use the shortcut Ctrl + Shift + Y.

Debugging a Function

We have a function in a file called app.js which finds the sum of all the numbers in an array.

function add (data) {
  let sum = 0;
  let counter = 0
  for (let element of data) {
    counter++
    sum = element + sum
  } 
  return sum
}

const result = add([1, 2, 3, 4, 5])

In other to run the debugger, we have to:

• Click on the run icon in the activity bar. Since no launch.json file has been created yet, the run start view is shown as seen above

• Click on the Run and Debug button. A prompt appears asking you to select the environment.

• This selection will be made based on where your code is meant to run. Since the function will be running on the Node.js environment. Node.js will be selected.

From the image above app.js was run with VS code's debugger. So it begs the question, is that all? No!

The features above show there is more to debugging with VS code's debugger.

Debugging a web API

• Create a configuration file: The file allows you to save and configure debugging setup details. The setup is saved in a launch.json file in a .vscode folder
• Start the debugging process
• Make a request to an endpoint. It is that simple.

Create a configuration file

• Click on the run icon
• Click on "create a launch.json file"

• Select "Node.js" as environment: This creates a launch.json file in a .vscode folder. The content of the file is:

  {
    // Use IntelliSense to learn about possible attributes.
    // Hover to view descriptions of existing attributes.
    // For more information, visit: https://go.microsoft.com/fwlink/?linkid=830387
    "version": "0.2.0",
    "configurations": [
        {
            "type": "node",
            "request": "launch",
            "name": "Launch Program",
            "skipFiles": [
                "<node_internals>/**"
            ],
            "program": "${file}"
        }
    ]
  }
  

• The program value is generated based on what file is open. The value can be edited to point to the file that starts the API server.

  {
    // Use IntelliSense to learn about possible attributes.
    // Hover to view descriptions of existing attributes.
    // For more information, visit: https://go.microsoft.com/fwlink/?linkid=830387
    "version": "0.2.0",
    "configurations": [
        {
            "type": "node",
            "request": "launch",
            "name": "Launch Program",
            "skipFiles": [
                "<node_internals>/**"
            ],
            "program": "api/index.js"
        }
    ]
  }
  

  Start the debugging process

  Click on the Start Debugging icon. It starts up the server and displays whatever message you wrote to ensure the server is running.

Make a request to an endpoint.

You can make a request with any HTTP method using tools like postman etc.

Conclusion

This article has explained the features of VS code debugger. How to set it up for use in debugging a function and also a web API. VS code also has debuggers for other languages and they are found under extensions by searching for debuggers. Will like to hear from you about other ways you have used the VS code's debugger in the comment section below. Thanks.

What are microframeworks?

Judging from the term "micro" we might say an extremely small framework, and this shows that it is smaller than a framework in scope or capacity. So this means that a microframework can be a framework without its own template engine, database abstraction layer, a logger, a body-parser, a validator, an authentication module, etc.

When to use a microframework

The answer to this question is never a straightforward answer but some things can be put into consideration to help in making the decision to use a microframework.

• Control: One question to ask is how much control are you willing to have and how much are you willing to surrender, this ranges from you having the choice to pick the different libraries you prefer for the project as you build instead of being stuck with the one that comes packaged with the framework to selecting the folder structure you desire for your project.

• Size: How big is the project? The answer to this question helps you realise if installing all the packages a framework comes with is necessary, so if I am building APIs that have no interaction with the database, requires no authentication for users, and accepts no user input. Do I need to install a framework that comes bundled with a template engine, a database abstraction layer, a validator, and an authentication library or just one that has a routing library and enables me to make a request and simply returns a response?

Examples of microframework

Below are a few examples:

• Express: This is a fast Nodejs framework that is used to build web applications. It is very minimalist and a backbone for many frameworks. It gives the users the freedom to fully structure there project the way they want and to select, whatever library the desire and need to accomplish the task before them. To learn more follow this link

• Lumen: This is a PHP framework that is based on Laravel but made for building APIs and microservices. It gives one the power to use the needed Laravel features with little configuration while been fast. To learn more follow this link

Getting Started

First, we install the Twilio helper library using npm, if you prefer you can use yarn. npm install twilio into the project.

Setting up Configuration

So we open up the config folder and create a file in it called sms.js. The configuration object will be created in such a way that it can contain various SMS service providers configuration details. The details will be fed from the environment file.

const Env = use('Env')

module.exports = {
  /*
  |--------------------------------------------------------------------------
  | Connection
  |--------------------------------------------------------------------------
  |
  | Connection to be used for sending SMS. 
  | A connection needs to have a corresponding object below.
  |
  */
  connection: Env.get('SMS_CONNECTION'),
  sms_sender: Env.get('SMS_SENDER'),
  /*
  |--------------------------------------------------------------------------
  | TWILIO
  |--------------------------------------------------------------------------
  |
  | Here we define the configuration for sending SMS via TWILIO.
  |
  */
  twilio: {
    driver: 'twilio',
    accountSid: Env.get('TWILIO_SMS_ACCOUNTS_ID'),
    auth_token: Env.get('TWILIO_SMS_AUTH_TOKEN')
  },
}

The connection determines which SMS service provider the system is using, sms_sender defines the number sending the SMS, twilio is the object containing the configuration details for the Twilio SMS service provider, any other service provider needed can be configured by adding the configuration object like the twilio object.

Setting up the Providers Folder

The providers folder will contain all providers and will live in the root of your app. In the providers folder we create a folder called Sms, here is where all the magic will happen.

|-- app
| |--config
| |-- providers
|   |-- sms
| |-- start

Setting the Source folder

In the newly created providers/sms folder, we need to have a folder where the code interacts with the npm package. the folder will be named src, which will contain an index.js file and other files for the different SMS service providers. In this demo, we will call it a Twilio.js file which will contain the class that interacts with the Twilio node.js helper function.

const Twilio = require('twilio')

class TwilioDriver {
  constructor (config, sender) {
    this.config = config
    this.messageBody = null
    this.sendTo = null
    this.sender = sender
  }

  to (to) {
    this.sendTo = to
    return this
  }

  body (body) {
    this.messageBody = body
    return this
  }

  async sendSms () {
    const client = Twilio (this.config.accountSid, this.config.auth_token)

    return await client.messages.create ({
      body: this.messageBody,
      from: this.sender,
      to: this.sendTo
    })
  }
}

module.exports = TwilioDriver

Next, we create an index.js file in the src folder, the file will require other files in the src folder, pass it into an object and export the object. The index.js file will look like this:

module.exports = {
  twilio: require('./Twilio')
}

Creating the Service Provider index file

This file takes in the config file and the index.js file from the src folder, it will reside in the Sms folder. It takes in the connection property of the config file and decides which SMS service provider to instantiate.

const Driver = require('./src')

class Sms {
  constructor (Config) {
    this.Config = Config
  }

  prepare () {
    /**
     * Read connection name using Config
     * provider
     */

    const SmsConfig = this.Config.get('sms')
    const name = SmsConfig.connection
    const sender = SmsConfig.sms_sender
    const config = SmsConfig[name]

    const SmsDriver = Driver[name]


    /**
     * Return the instance back
     */
    return new SmsDriver (config, sender)
  }
}

module.exports = Sms

BInding to the IOC container

Here we use service provider to bind all our previous work to the IOC container. The service provider is a class we extend, it comes with a register and a boot method but we only need to use the register method. In the register method, the configuration from the config file is passed into the Sms class located in the sms/index.js file. The first parameter of this.app.bind defines the name used to address the provider when importing it later for use.

const { ServiceProvider } = require('@adonisjs/fold')

class SmsProvider extends ServiceProvider {
  register () {
    this.app.bind('Sms', () => {
      const Config = this.app.use('Adonis/Src/Config')
      return new (require('.'))(Config).prepare()
    })
  }
}

module.exports = SmsProvider

this.app references the ioc object, so we can use this.app.bind or this.app.singleton and it will be the same with ioc.bind or ioc.singleton

Registering the Provider

To register the newly created provider, open the app.js file in the start folder in the root of the app.

• require the path module

  const path = require('path')
  

• Add the path to the new provider in the providers array

  const providers = [
  path.join(__dirname, '..', 'providers', 'sms/Provider'),
  ]
  

  Using the Provider

  At this point, we can import the provider into any part of the project using

  const Sms = use('Sms')
  

  Moving Further

  So if there is a need to use another SMS service provider nodeJs helper library, we add the configuration to the config/Sms.js file, we add the class to interact with the helper library in the providers/sms/src folder to handle it. The class will contain the to method, the body method and the sendSms method. So as not to break existing code. Finally, remember to define the new name of the service provider in the .env file and let it be the name of one of the properties in the config/Sms.js file holding a configuration object.

In conclusion, we have seen have to configure an NPM package as a service provider for AdonisJs, the principles remain the same and a Provider.js file is always necessary, the rest are defined based on the needs of the developer.

What are exceptions?

Exceptions are events that occur and cause the running of a program to be disrupted. When they occur they bubble to the top of the call stack looking for a handler at each level when one is found, the program continues running from there. I have always handled exceptions with the try-catch-finally block, so when a program is disrupted in the try block, it gets handled in the catch block, and no matter what happens in the try or catch block the finally block runs. The finally block is optional, leave it out if you have nothing to run after the try-catch block.

  function() {
    try {
      // Block of code to be executed
    } catch(error) {
      // Handles exceptions
     } finally {
       // Runs after no matter the outcome of the code.
    }
  }

Handling exceptions in AdonisJs 4.1

AdonisJs following its principle of putting the developer's joy first, have gone ahead to ensure that you worry less about configuration by ensuring that some features come prebuilt so you just have to plug and code. To learn more about AdonisJs, follow this link. How does one handle exceptions during an HTTP life cycle in AdonisJs?

• Firstly, one could use the try-catch block and return an error message in the catch block if an exception is thrown, in any method handling an HTTP request or any other running process.

• Secondly, AdonisJs comes prebuilt with a global exception handler, which can be configured to match the developer's need, by default it handles all exceptions and displays them in a nice format. To use the AdonisJs exception handler, run the command, adonis make:handler, once successful a Handler.js file is created in the exceptions folder. It contains an ExceptionHandler class which inherits from the BaseExceptionHandler class. The class contains two methods, the handle method which returns the error message, and the report method which is meant for reporting errors either to the stderr or via an application management tool. What if I need to create exceptions to handle an error, for example, I need to return a not found error message, then we have to run adonis make:exception notFound, which creates a NotFoundException class in the exceptions folder located in the app folder. The exception class contains only a handle method, though you can add a report method to it and it inherits from the LogicalException class. Then I import the exception into the file where it is needed, const NotFoundException = use('App/Exceptions/NotFoundException'). When there is a need to call the exception, it is called by using throw new NotFoundException() and if you need to pass an error message then it will be throw new NotFoundException('X not found'). To further handle it you can look at the block of code below.

  async handle (error, { request, response }) {
    if(error.name == 'NotFoundException') {
      return response.status(404).send({
        status: 'Not Found', 
        error: error.message // or your error message
      })  
    }
  
  // To handle other forms of exception/error
  
    return response.status(500).send({
      status: 'System Error', 
      error: 'System encountered an error' // or your error message
    })
  }
  

  Or

  const NotFoundException = use('App/Exceptions/NotFoundException')

  async handle (error, { request, response }) {
    if(error.name == 'NotFoundException') {
      throw new NotFoundException().handle(error, response)  
    }

  // To handle other forms of exception/error

    return response.status(500).send({
      status: 'System Error', 
      error: 'System encountered an error' // or your error message
    })
  }

And in the NotFoundException.js file, the handle method will contain

  async handle (error, response}) {
      return response.status(404).send({
        status: 'Not Found', 
        error: error.message // or your error message
      })  

  }

Finally, I hope you enjoy using the adonis exception module on your next projects.

So I saw the tweet above the other day and it caught my attention, what are the alternatives? Why should I use them? Why is it better than console.log?

As developers at the early stage of learning javascript, console.log was one of the first set of things we learned. While using NodeJs REPL console.log was a quick way to debug. It required no dependencies since it is based on the NodeJs console module and is easy to use

Today, logging can be done for various reasons, like for debugging, error tracking, performance tracking, system usage analyses, and many more.

So it begs the question of why does console.log need alternatives.

Why console.log alternatives?

Well, we can say because a developer felt like creating a new NPM package but there are other tangible reasons.

• console.log() could not be toggled on/off, it was always on, but also it could be done manually by overwriting the console.log method, the snippet below shows how it is done in production.

if( process.env.NODE_ENV == "production" ) {
  console.log = function() {};
}

• console.log out of the box has no support for direct printing to a file, though this could be done as shown by the snippet below. So calling logger.log('a') will log to the output file and logger.error('a') will log to the error file.

const fs = require("fs");
const output = fs.createWriteStream("./logs/output"); 
const error = fs.createWriteStream("./logs/error");

const logger = new Console.log({stdout: output, stderr: error})

• console.log does not give you the ability to specify what you want to log, at a specific situation, for example, developers need logs for reasons different from that of the QA team, and console.log out of the box does not help with allowing one switch on what to log at a certain scenario

• Lastly, console.log is lacking when it comes to giving information pertaining to the data logged like the time of logging, how long it took for the process to run, the log level, basic HTTP information, etc. that exist in some loggers

Node.js logging libraries

What logging modules are available for nodeJs? We will look at four in no particular order:

• debug: It is a tiny javascript utility modeled after the Node.js debugging technique, works in Node.js and web browsers. it does not just display the data but adds colors to the output displayed as well as the time in milliseconds spent between two debug calls meaning that if it is passed before a block code and after, when we run the program it returns the amount of time it takes to run the program or the time debug was called. To read more about debug click here

• morgan: A Node.js HTTP request logger middleware that can log both to file and also the stdout, it allows you to decide what information to log by using the existing format and also to define yours. To read more about morgan click here

• winston: It is designed to be a simple and universal library, that can log to a database, a file, and to the stdout. It can be configured to log to all this at the same time. To read more about winston click here.

• pino: A logger that is five times faster than it's alternative according to its benchmark result, it allows you to send its logs to datastores or webpages through the use of its various transport tools. To read more about pino click here.

PS. Cover image by Free-Photos from Pixabay