Forem: Yari Antonieta

NodeJs Layered Architecture

Yari Antonieta — Mon, 04 Oct 2021 14:30:23 +0000

Something that was not intuitive to me when I was getting into this software development world was how to build the software's architecture. Sure, I understood how to write functions, and components but optimally organizing them was not something I learned alone.

Some time ago, I was assigned the task to refactor the NodeJS codebase architecture into layered architecture. I didn't have any idea what layered architecture was or how it looked like. So I DuckDuckGoed and Googled search and quickly noticed a couple of blog posts about layered architecture but not actual code examples. So I'm providing a before and after layered architecture example based on what I learned!

Before going into this software architecture journey, let's understand what layered architecture is.

What is Layered Architecture?

A pattern used in software development where roles and responsibilities within the application (app) are separated into layers. Per Chapter 1: Layered Architecture from Software Architecture Patterns by Mark Richards: "Each layer in the architecture forms an abstraction around the work that needs to be done to satisfy a particular business request."

So, one of layered architecture's goals is to separate concerns among components. Another goal is to organize layers so they can perform a specific role within the app.

A small app consists of three (3) layers: Router Layer, Service Layer, and Data Access Layer (DAL). The number of layers will depend on how complex your app turns out.

Router Layer contains the app programming interface (API) routes of the app. Its only job is to return a response from the server.

Service Layer handles the business logic of the app. This means that data is transformed or calculated to meet the database model's requirements before being sent to the server.

Data Access Layer (DAL) has access to the database to create, delete, or edit data. It is where all the request and response from server logic is handled. If there is no database connected directly into the app, this layer may include Hypertext Transfer Protocol or http requests to the server.

A key concept of the architecture layer is how data move between layers. To understand this movement, let's look at the diagram below for reference.

Layered architecture diagram

Moving between Layers

The data journey starts at the presentation layer once the user clicks a button. The click triggers a function that sends the API's data request, located at the router layer. The router layer method calls a component located at the service layer, and its concern is to wait for the service layer's response to return it.

At the service layer, the data is transformed or calculated. Hypothetically, if a user must reset their password every 90 days, it's here at the service layer, where the calculations are done before passing the results to the server. After transformation, the service layer component calls an injected DAL component, and the data is passed into the DAL.

Finally, the data request is made to the database at the DAL. The DAL is structured as a request inside a promise, the promise being resolved with the database's response.

When the DAL promise resolves with the database's response, the response returns to the service layer, which then the service layer itself returns to the router layer. When the response reaches the router layer, the data reaches the user back at the presentation layer.

It is crucial to understand that the data moves from one layer to another layer without skipping layers in between. The data request moves from the router layer to the service layer and then to the DAL.

Later, the response is returned from the DAL to the service layer, and finally, to the router layer. Neither the request nor the response goes from the router layer to the DAL layer or from the DAL layer to the router layer.

Now that we understand what layered architecture software is, let's learn how layered architecture was implemented. Let's use, as a reference, the action of updating a profile to illustrate software before and after layered architecture.

Implementing Layered Architecture

Before Layered Architecture Implementation

Let's begin with the file structure before implementing the layered architecture.

my-project/
├── node_modules/
├── config/
│   ├── utils.js
├── components/
├── pages/
│   ├── profile.js
│   ├── index.js
├── public/
│   ├── styles.css
├── routes/
│   ├── alerts.js
│   ├── notifications.js
│   ├── profile.js
│   ├── index.js
├── app.js
├── routes.js
├── package.json
├── package-lock.json
└── README.md

The pages / profile.js directory contains the front-end code for the user profile. It's here where the user interaction triggers the data trajectory to the server and back. Even though this directory doesn't contain NodeJs code, it's important to understand when NodeJs interacts with the app's front end side.

For this example, the front-end is written with the ReactJs framework.

const Profile = ({ user }) => {
  // User prop is destructured
  const { id, name, lastname, email } = user;
  // Form states are initialized with user prop's information
  const [nameState, handleName] = useState(`${name}`);
  const [lNameState, handleLName] = useState(`${lastname}`);
  const [emailState, handleEmail] = useState(`${email}`);
  // Url that sends request to api
  const url = `profile/update/${id}`;

  return (
    <form
      action={url}
      method="post"
      style={{ display: 'flex', flexDirection: 'column' }}
    >
      <input
        placedholder="Name"
        value={nameState}
        onChange={handleName}
        type="text"
        name="name"
      />
      <input
        placedholder="Last Name"
        value={lNameState}
        onChange={handleLName}
        type="text"
        name="lastname"
      />
      <div style={{ display: 'flex', flexDirection: 'row' }}>
        <input
          placedholder="Email"
          value={emailState}
          onChange={handleEmail}
          required
          type="email"
          name="email"
        />
        <button type="submit">
          Save
        </button>
      </div>
    </form>
  );
};

export default Profile;

The code above is the entry point where the end-user interacts with the app. It's a form that includes text inputs for the name, last name, and email and a "save" button.

The user types inside the text input the information described by the placeholder. Later, the user saves her/his/their information for future reference by clicking the "save" button. When the "save" button is clicked, it triggers a POST routing method that sends the user data to the Uniform Resource Locator, or URL, passed into the method.

Before implementing the layered architecture, the codebase I encountered included all the app routing methods inside the directory my-project / routes.js. It looked similar to:

module.exports = (app, routes) => {
  // Profile
  app.get('/profile/:id/:message?', routes.profile.details);
  app.post('/profile/new/:page?, routes.profile.create);
  app.post('/profile/update/:id/:page?', routes.profile.update);
  app.post('/profile/delete/:id', routes.profile.delete);

  // Notifications
  app.get('/notifications', routes.notifications.add);
  app.post('/notifications/send/:message?', routes.notifications.send);

  // Alerts
  app.get('/alerts/breaking', routes.alerts.read);
  app.post('/alerts/breaking', routes.alerts.send);
};

By keeping all the routing methods in the same directory, this codebase may introduce compiling errors or software bugs between components that, normally, wouldn't interact between themselves.

Each routing method requires three parameters: 1) route, 2) authentication and, 3) request/response method. The request/response method sends and receives the data request to the server.

Another detail worth highlighting about the codebase before implementing layered architecture is that the request/response methods for the profile component were defined within the routes / profile.js directory:

const moment = require('moment');
const apiUrl = require('../config/constants').API_URL;
const baseApiUrl = `${apiUrl}`;

const profile = {
    details: (req, res) => {
        const { id } = req.params;

        request({
            uri: `${baseApiUrl}/${id}`,
            method: 'GET',
            json: true,
        }, (err, r, body) => {
            const { id, name, lastname, email } = body;
            const info = {
                id,
                name,
                lastname,
                email,
            };

            if (err || r.statusCode !== 200) {
                res.status(400).json({
                    error: err || r.statusCode
                });
                return null;
            }
            res.json({
                status: 'success',
                post: info,
            });
        });
    },

    create: (req, res) => {
        const { id, name, lastname, email } = req.body;
        const createDate = moment().format();
        const info = {
            id,
            name,
            lastname,
            email,
            createDate,
        };

        request({
            uri: `${baseApiUrl}`,
            method: 'POST',
            body: info,
            json: true,
        }, (err, r, body) => {
            if (err || r.statusCode !== 201) {
                res.status(400).json({
                    error: err || r.statusCode
                });
                return null;
            }
            res.json({
                status: 'success',
                post: body,
            });
        });
    },

    update: (req, res) => {
        const { id, name, lastname, email } = req.body;
        const updateDate = moment().format();
        const info = {
            name,
            lastname,
            email,
            updateDate,
        };

        request({
            uri: `${baseApiUrl}/${id}`,
            method: 'PUT',
            body: info,
            json: true,
        }, (err, r, body) => {
            if (err || r.statusCode !== 200) {
                res.status(400).json({
                    error: err || r.statusCode,
                    statusText: err || body.message,
                });
                return null;
            }
            res.json({
                status: 'success',
                post: body,
            })
        });
    },

    delete: (req, res) => {
        const { id } = req.params;

        request({
            uri: `${baseApiUrl}/${id}`,
            method: 'DELETE',
            json: true,
        }, (err, r, body) => {
            if (err || r.statusCode !== 200) {
                res.status(400).json({
                    error: err || r.statusCode
                });
                return null;

            }
            res.json({
                success: 'OK',
            });
        });
    },
}

module.exports = profile;

Notice how, in the create and update methods, data is being transformed by creating a new object with specific key names and values. This includes the creation date and update date timestamps values added at the create and update methods. Timestamps are included, so they comply with the server's data models.

Right after data transformation, there is an http request to the server. Whatever the server response is, the response is sent back to the front-end in JSON format. So, this codebase handles the business logic and server access at the same layer.

Overall, the before mentioned code base mixed too many concerns between layers of work. At the routing layer, components that do not interact between themselves throughout the app are handled together. While business logic and server requests are also handled together.

Layered Architecture Implementation

Recalling the objectives for layered architecture, it's important to separate concerns among components. Also, layers must perform a specific role within the app.

To separate concerns, I created a module for profile, notification, and for alerts. Inside each module, I created the three layers: 1) Router layer that includes all the routing method for the specific module, 2) Service layer that includes business logic components, and 3) DAL that includes the server request and response method.

Below is an example of the file structure considering layered architecture:

my-project/
├── node_modules/
├── config/
│   ├── utils.js
├── components/
├── modules/
│   │   ├── profile/
│   │   │   ├── routesProfile.js
│   │   │   ├── serviceProfile.js
│   │   │   ├── dalProfile.js
│   │   │   ├── index.js
│   │   ├── notification/
│   │   │   ├── routesNotification.js
│   │   │   ├── serviceNotification.js
│   │   │   ├── dalNotification.js
│   │   │   ├── index.js
│   │   ├── alerts/
│   │   │   ├── routesAlert.js
│   │   │   ├── serviceAlert.js
│   │   │   ├── dalAlert.js
│   │   │   ├── index.js
├── pages/
│   ├── profile.js
│   ├── index.js
├── public/
│   ├── styles.css
├── app.js
├── routes.js
├── package.json
├── package-lock.json
└── README.md

Same as before implementation, the front-end side triggers the routing method.

Instead of having all the routing methods from the app in my-project/routes.js, I:

1) Imported all modules indexes in my-project/routes.js. An example of modules/ profile / index.js below.

// Inside modules/profile/index.js

const profileService = require('./profileService');
const profileRoutes = require('./profileRoutes');

module.exports = {
  profileService,
  profileRoutes,
};

2) Called routing layer.

3) Pass each module into its routing layer. Example below.

// Inside my-projects/routes.js
const profile = require('./modules/profile/index');
const alert = require('./modules/alert/index');
const notification = require('./modules/notification/index');

module.exports = (
  app,
) => {

  profile.profileRoutes(app, profile);
  alert.alertasRoutes(app, alert);
  notification.notificationRoutes(app, notification);
};

Look how clean the my-project/routes.js is! Instead of handling all the app's routing methods, we call the module's routing layer. In this case, the profile module.

The front-end triggers a call to profile.profileRoutes(app, profile) to access all the routing methods regarding the profile component.

Routing Layer

Here is an example of how I wrote the routing layer for the profile module.

// Inside modules/profile/routingProfile.js

module.exports = (app, routes) => {
// Route for get profile details
app.get('/profile/:id/:message?', 
   async (req, res) => {
    const { params} = req;
    const { id } = params;
    try {
      const details = await 
        profile.profileService.getProfileDetails(id);
      res.json(details);
    } catch (error) {
      res.json({ status: 'error', message: error.message });
    }
});

// Route for post create profile
app.post('/profile/new/:page?',
  async (req, res) => {
    const { body} = req;
    try {
      const new = await 
        profile.profileService.postCreateProfile(body);
      res.json(new);
    } catch (error) {
      res.json({ status: 'error', message: error.message });
    }
});

// Route for post update profile
app.post('/profile/update/:id/:page?', async (req, res) => {
    const { body, params} = req;
    const { id } = params;

    try {
      const update = await 
        profile.profileService.postUpdateProfile(id, body);
      res.json(update);
    } catch (error) {
      res.json({ status: 'error', message: error });
    }
  });

// Route for post delete profile
app.post('/profile/delete/:id', 
  async (req, res) => {
    const { params } = req;
    const { id } = params;
    try {
        const delete = await 
          profile.profileService.postDeleteProfile(id);
        res.json(delete);
      } catch (e) {
        res.json({ status: 'error', error: e });
      }
  });
}

Notice how the routing method calls the corresponding service layer method and waits for its response. Also, notice how that's the routing layer's only job.

Let's recall that the URL valued triggered from the front-end when the user's clicked the "update" button is "/profile/update/:id/." The routing layer will have to wait for postUpdateProfile() method's response at the service layer to finish its work.

Now that the service layer is called let's see how I wrote the profile module's service layer.

Service Layer

An example of the service layer I wrote below:

const moment = require('moment');
const { API_URL } = require('../../config/constants');

const baseApiUrl = `${API_URL}`;
const profileDal = require('./profileDal')();

const profileService = {
  /**
   * Gets profile detail
   * @param {String} id - profile identification number
   */
  getDetailProfile: (id) => profileDal.getDetailProfile(id, token),

  /**
   * Creates profile
   * @param {Object} body - profile information
   */
  postCreateProfile: (body) => {
    const { name, lastname, email } = body;
    const createDate = moment().format();
    const profile = {
      name,
      lastname,
      email,
      createDate,
    };
    return profileDal.postCreateProfile(profile);
  },

  /**
   * Updates profile
   * @param {String} id - profile identification number
   * @param {Object} body - profile information
   */
  postUpdateProfile: (id, body) => {
    const { name, lastname, email } = body;
    const updateDate = moment().format();
    const data = {
      name,
      lastname,
      email,
      updateDate,
    };

    return profileDal.postUpdateProfile(id, data);
  },

  /**
   * Deletes the selected profile
   * @param {String} id - profile identification number
   */
  postDeleteProfile: (id) => profileDal.postDeleteProfile(id),
};

module.exports = profileService;

This layer is specific to business logic for the profile module. It focuses on transforming the data, so it complies with the request method's data models.

So, if the data model requires a timestamp to create and update data, it's here where you may want to include that data. See postUpdateProfile() above for example.

You can also validate data in the service layer. Validating data in this layer guarantees that the DAL will receive the data as needed and that its only job will be to send data to the middleware or server. Furthermore, validating data in the service layer allows the DAL to be used by multiple modules with different validation requirements.

The DAL is injected in this layer to be called within every method in this layer. The results of the data transformation are passed into the DAL to be sent to the server.

Data Access Layer

The DAL I wrote for the profile module is something like:

const request = require('request');
const { API_URL } = require('../../config/constants');

const baseApiUrl = `${API_URL}`;

module.exports = () => ({
  /**
   * Gets profile details
   * @param {String} id - profile id
   */
  getDetailProfile: (id) => new Promise((resolve, reject) => {
    request({
      uri: `${baseApiUrl}/${id}`,
      method: 'GET',
      json: true,
    }, (err, r, body) => {
      const { id, name, lastname, email } = body;
      const profile = {
        id,
        name,
        lastname,
        email,
      };

      if (err || r.statusCode !== 200) {
        return reject(err);
      }
      return resolve({
        status: 'success',
        profile,
      });
    });
  }),

  /**
   * Creates new profile
   * @param {Object} body - profile information
   */
  postCreateProfile: (body) => new Promise((resolve, reject) => {
    request({
      uri: baseApiUrl,
      method: 'POST',
      body,
      json: true,
    }, (err, r, b) => {
      if (err || r.statusCode !== 201) {
        return reject(err);
      }
      return resolve(b);
    });
  }),

  /**
   * Updates profile
   * @param {String} id - profile id
   * @param {Object} body - profile information
   */
  postUpdateProfile: (id, body) => new Promise((resolve, reject) => {
    request({
      uri: `${baseApiUrl}/${id}`,
      method: 'PUT',
      body,
      json: true,
    }, (err, r, b) => {
      if (err || r.statusCode !== 200) {
        return reject(err);
      }

      return resolve({
        status: 'success',
        post: b,
      });
    });
  }),

  /**
   * Deletes profile
   * @param {String} id - profile id
   */
  postDeleteProfile: (id, token) => new Promise((resolve, reject) => {
    request({
      uri: `${baseApiUrl}/${id}`,
      method: 'DELETE',
      json: true,
    }, (err, r) => {
      if (err || r.statusCode !== 200) {
        return reject(err);
      }
      return resolve({ status: 'OK' });
    });
  }),
});

The DAL methods receive variables from the service layer. These variables are required for http requests. When the http request is triggered by receiving the service layer's variables, it dispatches a promise that is expected to resolve with an object. The object is defined after the server response is available.

If the request is successful, the DAL promise is resolved with an object that returns to the service layer, which itself returns to the routing layer. When the routing layer receives the object returned by the service layer, the routing layer sends the object in JSON format to the front-end.

And that, my friends, is how I implemented layered architecture for a NodeJs code base. I know that it looks like a lot of work, but I did learn so much about this codebase after this project that I feel completely comfortable implementing or fixing things.

Thank you so much for reading this far!

By the Way

I wrote a lot of this article listening to the Afro House Spotify playlist. A great playlist for banging your head while writing.

This article was originally posted on ctrl-y blog. Also, you can find a Spanish version of this article in ctrl-y blog/es.

What is the Rendering Engine?

Yari Antonieta — Tue, 16 Jun 2020 20:30:56 +0000

This article was originally posted on ctrl-y blog. Also, you can find a Spanish version of this article in ctrl-y blog/es.

On the Side Note section at the end of each article, I like to share what I was listening to while writing machine or human words. I ❤️ music so I spend time (sometimes a bit too much) searching for, or creating, long playlists so I can listen to them while I'm working.

Recently, I was hearing the Ladybug’s Podcast episode: “Level Up with Javascript” were one of the podcasts’ host resumed how the web browser works. She explained it so helpful and straightforward that it picked my curiosity into searching a bit more about the topic.

The Ladybugs suggested some resources, so I followed suit. And wow, I had not appreciated the processes that occur between ‘Saving’ my front-end code and observe my code elements on the screen.

The rendering engine is one of the basic components of a web browser. It’s responsible for interpreting the HTML (Hypertext Markup Language), CSS (Cascading Style Sheets), and Javascript files to present (render) them on screen, in other words, convert them to pixels.

The process that goes from interpreting HTML, CSS, and Javascript to pixel conversion can be grouped in 4 (four) general steps:

Parsing of the HTML document to DOM (Document Object Model).
CSS file interpretation (CSSOM – Cascading Style Sheets Object Model) for each of the DOM nodes.
Creation of the new tree that includes the DOM, and each node’s style and layout.
A render tree is rendered.

But, before we go any further with a web browser’s render tree, have you ever participated, or seen, a sports game where fans of a team sing while a visual shows as big as the dimensions of a public sector? The following image is an example of what I am talking about.

Credit: Scene from a Youtube video recorded by the user barcelona.jp

Why the question?

Because I am going to explain how the rendering engine of the browser works similarly as a stadium filled with people that together, they illustrate a message while they chant to their favorite team.

Disclaimer: To use a sports event as an example will result in a limitation of a detailed explanation. So, I will explain the details of certain processes in separate articles. This will help to maintain this article short, and prevent you from getting bored of reading me.

Parsing: HTML to DOM

Web browsers do not interpret HTML files the same as programmers write them. That is why the rendering engine is in charge of parsing (analyze and separate) the HTML structure into objects that the browser can read.

The rendering engine receives the HTML files as a stadium receives sports fans waiting in line. With lots of people entering consecutively but the stadium does not understand how does each fan group relates to one another or how are they going to be seated.

That’s what the stadium staff is for. They can read each person’s ticket and direct them to their respective chair to structure the team visual that will be seen during the game.

When browsers parse, they consider the HTML tags, and how they are nested, to create objects and relate them, including the DOM (Document Object Model).

The DOM is a document that models the relationship between the different objects, or nodes, that structure the web page.

The document model can be manipulated using Javascript. Some manipulation examples include adding nodes and changing node colors.

The process of creating these objects is more complex, so I will not be detailing the process in this article. But, by this point, the DOM knows how the web page will be structured. Although it still has not interpreted how the web page will be styled or laid out.

On our sports fan example, by this point, each fan group has entered the stadium and are seated. But, they still do not have the colored cardboard they are going to display during the chant.

CSSOM Construction

Ten (10) minutes before the game starts, the stadium staff with lots of colored cardboard on hand, begin to walk to each corner of the seated rows.

Each cardboard has a seat number assigned, so the visual, at large, makes sense. Let’s say that each carton was appointed to a specific chair by a style calculation.

After converting the HTML into the DOM, the render engine assigns the styles described in the CSS file to each DOM node. This assignment is known as CSS style computation. This process includes selector pairing and style cascading process (hence the name Cascading Style Sheets).

CSS style computation is a topic that can take up to an entire article, so I will not inquire about that in this article. But, for the sake of this article, it is essential to know that during this stage, the rendering engine assigns styles to each DOM node like color, font, and border.

When DOM nodes are assigned a style, it constructs a new tree. This tree is called the CSSOM (Cascading Style Sheets Object Model).

Up to this point, the rendering engine knows the page's structure and each element’s style.

Rendering Tree

Stadium staff begins to distribute each colored cardboard, and the energy of the crowd transforms from conversations to the excitement for the beginning of the game.

The process of distributing the cardboard assigned to each seat can represent the size and position of the node on the screen.

The squared form of each cardboard can also represent the elements that will show on the screen.

Once each node from the DOM has its style assigned, the rendering engine computes the size of each node and its position on the screen.

The result of this computation is a rendering tree. Were boxes represent each of the web page’s elements.

All of a sudden, the microphone turns ON, and a staff member welcomes the crowd. The game is about to begin.

Paint the render tree

The rendering engine is responsible for painting on screen the new render tree.

What does painting on-screen means?

Part of the computer’s memory goes to pixels. It is in the pixel memory spaces were the rendering engine sets the style value for each node. That is how pixels get their color, shape, and position.

The crowd goes wild when the home team is announced. The battle chant begins. Each person from the crowd puts the cardboard over their head.

The cardboard paint each stadium seat with the color, shape, and position required for the message for the team can be appreciated.

“We are ready”, it reads. The energy is glorious.

Credit: Scene from a Youtube video recorded by the user barcelona.jp

Resources

As mentioned at the beginning of this writing, this article was inspired by Ladybug’s Podcast episode: “Level Up with Javascript”.

The Ladybug Podcat’s suggestions led me to a different podcast episode that inspired me with the illustrations, The Code Newbie episode: “How Do Browsers Work?. The programmer and artist Lin Clark details how web browsers function, and her work at Mozilla.

Also, Lin Clark wrote another article: “Inside a Super Fast CSS Engine: Quantum CSS (aka Stylo)” which details the role of CSS when rendering a page.

Lin Clark’s drawings and explanations helped me understand the rendering engine. She goes more into detail of what I vaguely explained in this article so I would invite you to read those articles if you want to inquire more.

Side Note

I wrote this article listening to the playlist “Creativity Boost” created by Mia Astral on Spotify. This playlist was recommended by a dear friend. It has a great mix of upbeat but smooth music that helped me focus.

A Morning in a Front End Developer’s Mac Terminal

Yari Antonieta — Wed, 01 Apr 2020 17:12:54 +0000

This story was originally posted on ctrl-y blog.

A Spanish version of this article can be found in ctrl-y blog/es.

On the Side Note section at the end of each article, I like to share what I was listening to while writing machine or human words. I ❤️ music so I spend time (sometimes a bit too much) searching for, or creating, long playlists so I can listen to them while I'm working.

Plays Fresh Prince of Bel-Air intro song:

🎵Now, this is a story all about how this Front End Developer turns her terminal upside down. And I’d like to take a minute, sit right there. I’ll tell you how I use the Mac terminal throughout the day to be clear. 🎵

A Slack message popped up. “Can you please check out what is causing this bug?, I am having a meeting with an important client at 3 pm today, and it would be nice to show this feature” it read.

So I searched for my “typing furiously” playlist , wrapped my hair in a bun, took a sip of coffee, and hit the Spotlight Search shortcut [command + spacebar ] to search for “Terminal” and access my Mac Operative System command line.

Terminal when opened

Note: Commands will be enclosed inside square brackets ( [ ] ) .

Let’s Command

“Where am I?” It sounded philosophical while I thought about it, but in actuality, by typing and entering [ pwd ] (Print Working Directory), I had a better idea. It is because the [ pwd ] is like my Google Maps for file, it shows me the directory where I am.

Current directory

“Great! I am in the directory I want to be in, but I do not remember the directory I want to navigate to,” I thought about instantly.

But I answered myself with: “That’s where [ ls ] (List Directory Content) comes in handy.” [ ls ] shows the content inside the current directory.

Content inside /Users/yari directory

My thoughts continued: “Now that I remembered in which directory I cloned the project, I need to [ cd ] (change directory) to get to the project’s local repository.”

By typing and entering [ cd ] followed by the subsequent directory names I want to navigate into, separating each directory name with a forward slash ( / ), I went ahead and started to change directory.

Change directory to src file

Until I found myself inside the src (source) directory. “Wait! Is package.json inside the src file? Let me [ ls ] this thing!” I continued.

Content inside the src directory

“Nope, there is no way I can run the web app from this directory,” I said to myself… out loud.

“Shhhhhh, I am in a meeting!” said Ramona, my coworker.

Whispering: “I need to go up a level in the directory, but how?”

That’s where the dots on the command line came in handy: [ cd .. ]. Two dots after cd means to go one level up the directory tree.

[ cd .. ] goes one level up the directory tree

My mind went: “Before running the app, I am going to make use of this moment to open the Visual Studio Code at this directory,” so I entered [ code . ] command.

[ code . ] command is used to open the code editor at the root directory

“Ok, let’s run the app,” I thought. I entered [ npm start ], and off it went.

Git Time!

"Before doing anything to the code, I need to make sure that locally I have the latest version of what is in development," my thoughts continued.

So it's time for the: "Git Routine."

"But first ☝️, let me open a new terminal tab or window, by typing [ command + t ], to keep the app running on the current one," I said to myself.

Let me tell you, reader of my thoughts, on what my Almost Four Steps Git Routine consists. I am assuming, though, that you know git basics. Do not worry if you do not know! Here is a quick intro.

Almost Four Steps Git Routine

Check Branch Status

First, check-in the status of the local work tree. Because frankly, I always forget what I was doing before. So, I enter the [ git status ] command.

Terminal after entering git status

If the branch is not clean, save changes

Second, I have learned, after many attempts, that git will not change branch if there are code changes, and changes are not stashed (saved temporarily) or committed (merged with master branch eventually).

So I proceeded to enter [ git stash ] to save changes temporarily.

Now let's see if I can change the branch from the current one to the development branch to make sure that I have the current version of the remote development branch.

Branch with changes not stashed or committed

[ git stash ] – Changes are stashed (saved temporarily)

Checks [ branch status ] to see if the working tree is clean

Change local branch

Now that the branch is clean, I need to change the HEAD of the work tree to the development branch. [ git checkout development ] does that.

[ git checkout development ] switches HEAD working tree to the development branch

Update development branch

Finally, update the local development branch with the remote repository's development branch. So I enter [ git pull origin development ].

[ git pull origin development ] command updates content from remote development branch to local development branch

The command [ git pull ] fetches the development branch content on the remote repository and merges the remote branch content with local branch content. The command [ origin development ] refers to the branch that the system will look up to make the update. Origin refers to the repository of origin, in this case, the remote repository. Development refers to the name of the work tree branch that the systems looks up to make updates.

After Routine

From this point forwards, my git commands vary from what I need to do in the day. This time, I need to fix a bug, so I need to create a new branch and perform those changes on that new branch. That requires me to change my HEAD work tree from development to the newly created work tree branch.

"What will be the name of the new branch?" started my thoughts again.

"Something verbose, straight to the point," pointed out a thought with the voice of my team lead.

"Let's go with fix/this-feature" I decided. So I entered [ git checkout -b 'fix/this-feature' ]

[ git checkout ] switches branches of work tree, [ -b ] creates a new working tree branch, [ 'fix/this-feature' ] is the new branch name.

Creates and switches to the new branch

To make sure that I am not in the development branch anymore, I hit again [ git status ].

[ git status ] to confirm that I am working on the new branch

"Yeah, I am at the new branch of the work tree," I confirmed to myself.

Next, I need to merge the updated branch with the new one, so the new work tree branch is up to date with the updated development branch. The command [ git merge development ] does that merge.

Few. I am glad that I got that out of the way. These steps up until changing branches from development to the new o reworked branch always make me nervous.

"Now, I am ready to catch that bug!" And so, I turned to my application and code editor to search for it.

An error occurred

I was having a groove on while writing code, and everything was working fine until something happened that a confusing error started appearing.

"Another application is already using the port," it read.

As an excellent debugger, I stopped the program with [ control + c ] ...

Terminal after entering [ control + c ]

... and reran. But it did not help.

So I asked my friend Google for some help, and it suggested to locate and kill the port process. To do this, I needed to identify the process id that I intended to kill and, well, terminate it.

The command to locate and display the list of the processes happening on a port is [ lsof -i:PORT ], where [ lsof ] stands for a list of open files, [ -i ] is the list of processes and [ PORT ] is the port number that we want to review. This case is the port 3000 so [ lsof -i:PORT ] is really entered as [ lsof -i:3000 ].

List of processes running in port 3000

After locating the process that I wanted to terminate, I proceed to enter [ sudo kill -9 15010 ] to kill the process. Where 15010 is the terminated processes' PID (process identification number).

[ sudo kill -9 15010 ] to kill the process with PID 15010 running at port 3000

Ready to start rerunning the app.

"Grrrrrlrllrrlrlr" growled my belly. "I am hungry, and I cannot think with my stomach screaming," I thought.

"Let's go to lunch," suggested Ramona.

"Please!" I responded and headed out to lunch feeling like:

Side Note

Enjoy a couple of Cheat Sheets including the commands used throughout this post!

Also, I wrote this story with the newly released Four Tet album, Sixteen Oceans playing in the background. The beginning of the first song sets an incredible mood for a subtle yet productive day. It has been my go-to album during this whole self quarantined time.

Thanks for reading! 😄

Filtering with GraphQL and Prisma: What NOT to do

Yari Antonieta — Tue, 24 Dec 2019 19:07:00 +0000

This article was originally posted on my blog: ctrl-y.

A Spanish version of this article can also be found in ctrl-y.

In the past months, I have been working with the magic package of React, Apollo, GraphQL, and Prisma. I say the magic package because learning these four layers of programming, provides you with the skills required to create apps from user click (React and Apollo) to handle and save information in the database (Prisma). They say that building this makes you a Full Stack developer.

I want to focus this article on GraphQL and Prisma because even thou I was already familiar with back-end languages, I only copied code. In other words, I didn’t understand how the back-end works.

I reached a massive roadblock when I started working with the search function for the digital product I am helping to develop.

At first, it’s easy to build functions because tutorials, even with complex topics, offer basic examples of how to create them. But what happens when basic examples are not enough?

The articles I read about filtering in the database, describe examples that consider the search of the terms inside one query. Sometimes these examples included nested data.

My roadblock, what happens when I need to filter more than one query?

I want to share with you my incorrect approach when working on this task. It took me a while to figure out why this approach was wrong, and what is a better approach when searching for data in different queries.

How Does ReactJs, Apollo, GraphQL, and Prisma Work Together?

Let’s make a quick recap of how ReactJs, Apollo, GraphQL, and Prisma work together.

ReactJs

It is a Javascript framework (that's what the Js is for) that handles the interface functions between user and software. When we work with a feature such as a website search, the data entry function, and search submission are handled by ReactJs.

Apollo

The ReactJs submit function must manually query the Apollo Client. Apollo communicates with GraphQL resolvers to request and receive information from the database using the GraphQL query language.

GraphQL

It is a query language for APIs that handles the website’s data. It is where the data schemas and resolver functions are defined.

GraphQL is a language. Therefore, we need to instruct which data will it filter and receive. These functions written in NodeJs (that is why usually resolver function files are Js and not Graphql) are called resolvers.

It is web developer-friendly because it gives the ability to specify the data that needs to be received by the website instead of collecting everything available on the endpoint.

Prisma

It is an interface between GraphQL and the database.

It is where the different queries from the database are defined and implemented.

Define queries in Prisma. After a couple of commandos, Prisma autogenerates a file with the GraphQL data schema in Prisma. The data is filtered from the database using this schema.

In summary…

Code Context Before Implementing the Search Function

Let’s make some assumptions before going the wrong path for the search implementation.

We are making multiple query searches on a database for a small business that handles farming equipment.

1) There are multiple queries available on the database

GraphQL’s and Prisma’s schemas are defined. An example of a data schema on Prisma data model (prisma/datamodel.prisma):

Next, the example of the GraphQL resolver schema (server/src/schema.graphql) with Prisma’s data schema imported:

Where the resolver company requires (! = “it is required so it can’t be null”) the id argument to return data type Company.

And the users and equipment resolvers do not require an argument to return a value. The resolver users should return an array of User data types, while the equipment resolver should return a data array of Equipment data types.

Also, the equipment resolver should return an array of no null values. Neither the data array can itself be null.

2) The query resolvers are defined

So the sever/src/resolvers/Query.js file:

The resolver for the company query must receive an id type argument. These resolvers should return the query data filtered by id.

The resolvers for the users and equipment queries do not require an argument to return filtered data. Therefore, it will return a data array of all the records of the requested query.

3) Queries requested by front-end have nested data

An example of an equipment query requested by Apollo:

An example of a company query requested by Apollo:

An example of a users query requested by Apollo:

Filter Data Using GraphQL and Prisma

Remember the company query we defined earlier? An id argument filters the company query. That’s a basic example of how to filter data in GraphQL. It’s easy to find documentation on this topic.

An example of the resolver for the company query if we want to search the id argument in each of the Company type items:

Most of the articles about filtering on GraphQL finish up to this point, where we can only filter data on a query.

But, what happens if I need to search for more than one query and the data is nested?

My initial Erroneous Approach of Filtering Multiple Queries

My instinct told me, after reading documentation, that I should filter queries editing the already defined resolvers (remember the previously stated examples).

But, the idea of performing multiple requests to the database seemed heavy. The “edit the resolvers” approach requires that the front-end triggers a network request for every filtered query at the moment the search is submitted.

I admit that the implementation of the search feature was after other elements in the app had been validated, so I inhibited myself from editing the resolvers that already worked.

Also, trying to consider that code repetition is a waste, fueled my reasoning that creating a query from the queries I needed to filter was the go-to approach for handling the server.

So, I defined my new query, Feed, on the Prisma data type schema (prisma/datamodel.prisma) as:

Import the query Feed to the GraphQL resolver schema after auto-generating the Prisma file, ** (server/src/schema.graphql) ** as:

Also, the auto-generated Prisma file provides the conditions you can use as a developer to filter data on Prisma. The feed resolver (sever/src/resolvers/Query.js) below:

Finally, the query requested from the front-end:

Some received data from the three queries as a result of these composite codes. But, the data was incomplete. I could access the nested data from the contacts and company inside the equipment. I could only see what type of data I was receiving, but the value was null.

Why this is not an adequate approach?

Looking through the documentation and frequently asked questions about this topic, the primary reason why invalid data is received when you should be able to access it is that because the data structure you are passing is incorrect.

But, what a correct schema for Feed would look like if we are already passing the right data types?

Queries have records attached to them in the database. An assigned id identifies these records. To assign these ids, one needs to create a function that allows the query to mutate (create a new id) and can save the data attached to the database record.

So, you need to create a Feed mutation and connect the data queries for User, Company, and Equipment. It means that you need to create and save on the database a record of type Feed every time you perform a search.

Imagine how loaded would be the database if, for every search you make, you save the query combination you defined as Feed!

Besides the fact that it would be too expensive and unnecessary to keep something like that, and we are not taking full advantage of the power of GraphQL.

Then, what should be an appropriate approach to do searches on multiple queries?

It’s obvious now, but to filter data queries is done in…. ta-da, the same data queries. So my instinct of adding the capacity to filter on the already defined resolvers was a better approach.

When we search multiple queries on the database, the front-end requests the data query individually. Apollo handles the requests to the GraphQL resolvers, so the response is as lean as the developer needs.

We do not need to define a new query to perform a search on multiple queries. So, let’s go back and re-define prisma/datamodel.prisma as:

Also, let’s go back and edit the GraphQL resolver schema (server/src/schema.graphql). Delete the Feed type definition and add the filter parameter to each query. The filter parameter is the data string the user wrote as the input for the search function:

Note: I assigned filter as an optional parameter so I can use these resolvers on other components.

On the GraphQL resolvers (sever/src/resolvers/Query.js), where the magic happens, we eliminate the feed resolver and edit the other resolvers, so each data query accepts the filter argument:

And the data queries that front-end requests:

This approach to filtering multiple queries should result in receiving all the data requested, including the nested data.

Ufff, we finished!

Thanks for reading all of this! 🙌🎉

It took me a while to come to this conclusion. If I can help you save a couple of hours or days by reading this article, that would be a mega mission accomplished!

Side Note

I wrote this article while listening to the Ladybug Podcast. It is rare for me to listen to a podcast while writing, but the topics the girls talked about motivated me to write this article.

Ladybug Podcast is a program focused on web development topics. Hosted by Kelly Vaughn, Ali Spittel, and Emma Wedekind.

Even thou I binge listened to the podcast, I am sharing the episode that is about GraphQL, which I also listened to while writing this article.

Web Dev Cheat Sheets

Yari Antonieta — Fri, 08 Nov 2019 15:57:27 +0000

Hi Devs!👋 Can you recommend a tool/app for web development cheat sheets? I would like to have cheat sheets stored in one place, so I don't have to waste time searching, bookmarking or saving them.

Thanks!

Industrial Engineering and Web Development

Yari Antonieta — Sat, 02 Nov 2019 20:41:51 +0000

Originally posted on ctrl-y blog, April 07, 2019.

Mental Change: From Industrial Engineering to Web Development

A frequent question I get asked when I talk about my career change from industrial engineering to web development is: “Is your Industrial Engineering knowledge useful for Web Development?”

I also asked myself that question before leaping and switched careers. But the more I learn about programming web-based products, the more I can relate Industrial Engineering with the development of digital products.

It wasn’t until I took a UI/UX Design workshop, that I realized that the UI/UX concepts came from human-centered manufacturing concepts.

So, how do I relate Web Development to Industrial Engineering?

Problem Solving

For starters, both professions require the capacity to solve problems. Ok, let me rephrase that. Both require the ability to visualize the problem and solve it. Some people are born with that talent. Others require a bachelor's degree to develop it (here, present 🙋‍♀️). But definitely, you need to train your brain into creating a mental map of the problem, for you to develop a mental map of solutions.

Ability to detail step procedures

In the regulated manufacturing world, it is required to document the processes that are performed to deliver a product to its final specifications. These documents may require a lot of detailed instructions, something that trains a person to think and write instructions step by step.

On the other hand, writing programs for web-based products is about detailing step by step the actions that you want the computer to do. The software should be written in a straightforward manner and efficient frameworks so that the software execution runs smoothly.

Design for Users

An industrial engineers’ work is to design a process so that the operator, or performer of that process, can execute their tasks seamlessly.

From the web development perspective, UX/UI design is about designing the digital product, so that the user does not have to work when using the product. Both professionals seek to minimize the user’s work.

Lean manufacturing, my soul-friend

Does Toyota sound familiar? One of their directors after the Second World War, Taiichi Ohno, created the lean manufacturing principles. The principles seek to eliminate waste, or Muda, that do not aggregate value to the final product. The seven (7) wastes are:

Overproduction
Wait time
Transportation
Movement
Over-processing
Defects
Inventory

I will not go into detail on the definition of each of the previously mentioned wastes, but here is a link that provides that information.

Even thou waste as a concept was developed based on manufacturing processes, its easy to apply them for the development of digital products.

The following table demonstrates a few examples of waste produced in manufacturing and web development.

Waste	Manufacturing	Web Development
Overporduction	1) Make the product before the client orders it. 2) To continue an operation when it should have been stopped.	1) Create functions that the client did not require. 2) Create variables that do not save the necessary data. 3) Make unnecessary continuous requests to the server.
Wait time	1) Product waiting to be processed because of the equipment is being maintained.	1) The time the server takes to send and receive requests. 2) Wait time until data can be presented to the user.
Transportation	1) Unnecessarily move product from a work station to another.	1) Migrate software from one platform to another because of idesign errors.
Movement	1) Scrap a product because of a sudden stop of the equipment causes damage to the product.	1) Change files that contain variables, components, or views from their respective directives.
Over-processing	1) Rework the same part multiple times to reach the required dimensions.	1) Rework code lines because methods used covered a use case but produced bugs on another.
Defects	1) Assembly error causes that a part of a product does not function appropriately.	1) BUGS! The software does not function correctly.
Inventory	1) Save too much raw material in a warehouse.	1) Create variables, and functions, just in case, a programmer needs them.

Physical and digital product development

It has been exciting to experiment and participate in the process of the development of physical and digital products.

Now, knowing that developing a product on the web is literally in my hands gives me a confidence in myself that was unprecedented.