Forem: Zhiyue Yi

How I Mentor Junior Software Engineers

Zhiyue Yi — Sun, 02 Jan 2022 08:45:35 +0000

In 2021, I happened to have chances to mentor some software engineer interns at my work. I mentored 5 interns in total and maximum 3 interns at the same time. This is a great experience to me and to be honest, I also learnt a lot while giving mentorship. So today, I'd like to share some of my ideas about mentoring junior software engineers.

1. Keep Your Mentee Group Size Small

I would admit that, at start, I was quite happy that I could mentor 3 interns at the same time. It was my first official experience practicing mentorship at work, so I was very happy that my capability was recognised by my superior. However, I found that I was too naive. More mentees means greater responsibilities and I would need to spare more time from my work to provide mentorship.

Why do I have to spend much time to mentee? Why not just assign the tasks and wait for results?

I suppose, Mentees usually are not familiar with team culture and norms when they just joined. They need guidance so that they can understand what to do and what not to do. In the beginning, they may not have any question because they would not know what to ask. Only when they actually start to work, will they find out that problems are everywhere. And because I am the mentor, I will be the first person they think of and ask for help. To let mentees be better adapt to work, I need to spend time for explanation and guidance.

I had maximum 3 interns with me at the same time, and they were doing 2 different areas of work, front end development and data warehouse development. While providing guidance to them, I had my own work to do as well. So it ended up that I had to work overtime.

Thus, keeping your mentee size small helps you mentor your mentees better, and put yourself in a more relax mode.

2. Prepare An On-boarding Guide

To minimise your time, you can prepare an on-boarding guide to explain fundamental questions. Probably you need to spend several hours to prepare it, but it's really useful because it can be reused every time!

I did an on-boarding guide and here's what I included in the guide:

How to setup the development machine, including software needs to install and environment variables to setup. If possible, it's better to also provide a way to verify if the software is correctly installed. There are often strange problems happening. It's better to provide a way of verification so that the mentees can at least check own their own first.
How to setup the project, including dependency installation, how to run the project and also environment variables to setup. This is definitely a must-do, otherwise, no one can work productively.
Who to ask if general problems are encountered. New comers are not familiar with the team structure. When some problems happen, the mentor is the first person they think of. However, sometimes the mentor might not know much about some specific topics, and they still need to direct the problem to someone who is more familiar. So why not just specify the people map in the guide? In the guide, you can specify system module owners who is the most familiar with that module, so that your mentee can be self-driven and directly approached the person who is the most knowledgeable to that problem.
List of video recordings of past technical sharing, tutorials or training. Sometimes we have internal trainings and sharing held, which can be recorded. Those trainings and sharing are often about our own projects or products. Having these links provide better opportunities to mentees to learn about the project by themselves and to mentors to save more time.
FAQs for quick references on strange problems. No matter how well you prepared, there are always strange issues happening. For example, a weird error message on python project initialization can be caused by a newly created remote development machine having setup issue during the creation. These are unusual problems which happen rarely and cannot be found in the knowledge base. So it's better to record this problem under FAQ session just in case it happens again and investigation time gets wasted.

3. Have Regular 1 on 1 Sessions

Mentors can be very busy on their own stuffs ans sometimes may omit the mentees. The best solution to this issue is to schedule repeated meetings with the mentee on a regular basis. It can be weekly or fortnightly (I do it fortnightly).

A 1 on 1 session can be short, such as 15 minutes, so that it does not create pressures to both sides.

Most importantly, 1 on 1 sessions are not meant for performance evaluation. The latter is too formal and makes people nervous. While the former is more relaxing, it can be just like chit-chatting. The purpose of 1 on 1 session is NOT to judge or evaluate, but to communicate and advise.

There are a few topics I often use during the 1 on 1 session:

How is it going recently? (A general question to warm up)
Do you encounter any problem at work?
Did you solve it, if so, how did you solve it? If not, how can I help so that you can solve it?
Does the work align with your expectation? If not, what is missing for you?

It's important to let the mentee to speak out, so these questions are all encouraging the mentee to share their thoughts. Probably a mentor is more knowledgeable in certain fields and more experienced, but in this communication, everybody is equal on the same page. In this way, the communication can be helpful and positive, true thoughts can be shared and then real problems can be revealed and fixed.

In the end, mentors can also share about their views, including praising for what mentee have done well, suggesting areas which mentees can improve on. When speaking about improvement parts, it's better to directly point out areas needs improvements with the focus on the fact only, and possibly provide a direction so that the mentee can know how to get improvement started.

In a word, 1 on 1 session is meant to align the expectations between mentors and mentees, find out the problems and solve it, on equal positions with respects.

4. Assign Tasks by Considering Difficulties

While assigning tasks to mentees, mentors need to understand the tasks too. Some tasks may be easy or small, and some tasks can be hard or big. It's important to assign suitable tasks to mentees considering their experiences, capabilities and time.

What I did is that,

In the beginning, you can assign simple tasks such as logic corrections, simple unit tests, typo corrections which are easy to complete, so that the mentees can be familiar with the work flow and the code base first.
Gradually, when mentees gets more familiar, you can assign them some small features such as developing a small form, writing a consolidation API, or non-urgent bug fixes. For bug fixes, though mentors are more experiences who can spot out the cause and find solutions right away, mentors should not directly tell the answer to the mentees. Instead, mentors should encourage the mentees to read through the code base and understand the contexts on their own, and finally let the mentees to solve the problems own their own. In this process, advices and hints can be provided at appropriate time, since there are definitely some contexts which are very hard for mentees to figure out on their own (such as lousy logic designs in legacy systems, which nobody knows exactly how it works :x)
When mentees are ready, you can assign a non-urgent mid-size feature like a small project to them, so that they can start to work independently. You can provide them a rough idea, and let them try to design the feature on their own. You can then review the design and help to improve. After that, mentees can start to independently work by themselves. At this step, the mentee is already at the stage where they are capable to work independently. And I think it will be a good time for mentees to graduate :D

Summary

These are what I learnt from the past one year experience of mentorship. To be honest, as a mentor, I am still quite newbie :) Please leave your comments below to share your thoughts about mentorship so that I could also learn from you. Cheers~!

Featured image is credited to Pixabay @pixabay from pexels

How to Open A File in Python Like A Pro

Zhiyue Yi — Sun, 04 Jul 2021 13:44:01 +0000

Read my original post in my blog here: How to Open A File in Python Like A Pro

It's a fundamental question. Usually people learn it at the time they get started with python.

And the solution is rather simple.

1st Attempt: use open()

file = open('./i-am-a-file', 'rb')
for line in f.readlines():
  print(line)
f.close()

But is that a good solution? What if the file does not existed? It those exceptions and the program ends.

So it's better to always check the existence of the file before reading / writing it.

2nd Attempt: File Existence Check

import os

file_path = './i-am-a-very-large-file'

if(os.path.isfile(file_path)):
  f = open(file_path, 'rb')
  for line in f.readlines():
    print(line)
  f.close()

Is this solution good enough? What if we have some other complex logics in every line, and it throws exceptions? In that situation, f.close() will not be called, resulted in the file not closed before the interpreter is closed, which is a bad practice as it might cause unexpected issues (for example, if a non-stop python program is running and it reads a temp file without closing it explicitly, while the OS (such as Windows) protects the temp file as it's being read, this temp file cannot be deleted until this program ends).

In this case, a better choice is to use with to wrap the file operation, so that it automatically close the file no matter the operation succeeds or fails.

3rd Attempt: use with

import os

file_path = './i-am-a-very-large-file'

if(os.path.isfile(file_path)):
  with open(file_path, 'rb') as f:
    for line in f.readlines():
      print(line)

Is this the perfect solution?

In most cases, yes, it is enough to handle the file operation.

But, what if you need to read a very very very large file, such as a 4GB file? If so, the python program will need read the whole file into the memory before it starts to perform your operation. If this is an API in your server, and several requests come in to read multiple large files, how much memory do you need, 16GB, 32GB, 64GB, just for a simple file operation?

We can do a very simple experiment in Window environment. First, let's create a 4GB with the following script.

import os

size = 1024*1024*1024*4 # 4GB 

with open('i-am-a-very-large-file', "wb") as f:
  f.write(os.urandom(size))

Now you have a 4GB large file and let's record our current memory statistic using Windows task manager.

From the screenshot, it shows the process python uses 5,154,136 KB memories, which is about 5.19 GB memories, just for reading this file only! You can clearly see the steep increasing line from the memory diagram. (FYI, I have a total of 24 GB memory)

Hence, to make our solution better, we have to think of a way to optimise it. If only we could read the line while we actually want to use it!

Here comes the concept of generator and we can have the following solution.

4th Attempt: use yield

import os

def read_file(f_path):
  BLOCK_SIZE = 1024

  if(os.path.isfile(f_path)):
    with open(file_path, 'rb') as f:
      while True:
        block = f.read(BLOCK_SIZE)
        if block:
          yield block
        else:
          return

file_path = './i-am-a-very-large-file'

for line in read_file(file_path):
  print(line)

And let's run it and monitor the memory change.

Yay! While the console crazily prints the meaningless texts, the memory usage is extremely low compared to the previous version, only 2,928 KB in total! And it's an absolutely flat line in the memory diagram!

Why is it so amazingly fast and memory-safe? The secret is that we use yield keyword in our solution.

To understand how yield works, we need to know the concept of generator. Here is a very clear and concise explanation about it, check out What does the “yield” keyword do? on StackOverflow.

As a quick summary, yield simply makes this read_file function to be a generator function. When read_file gets called, it runs until yield block, returns the first block of string and stops until the function gets called next time. So, only one block of file gets read each time read_file(file_path) is called.

To read the whole file, multiple times of read_file(file_path) need to call (for line in read_file(file_path)), and each time it only consume a little memory to read one block.

So that's how to open a file in python like a pro, given considerations about the extreme cases (actually quite common if your service is performance critical). Hope you enjoy this blog post and share your ideas here!

You can grab the demo source code on GitHub here: ZhiyueYi/how-to-open-a-file-in-python-like-a-pro-demo

Updates on 7 July

Thanks to @Vedran Čačić's comments, I learnt further about better solutions to it.

If we have a very large text file, we can simply use

5th Attempt

with open(path) as file:
    for line in file: print(line)

And it's totally OK.

Or if we really want to process a binary file in chunks (like what I did in 4th Attempt, 1024 bytes per block), we could also use BufferedReader in the built-in io library to achieve the same thing like this

6th Attempt

import sys
import io

file_path = './i-am-a-very-large-file'

with open(file_path, 'rb') as f:
    BLOCK_SIZE = 1024
    fi = io.FileIO(f.fileno())
    fb = io.BufferedReader(fi)

    while True:
        block = fb.read(1024)
        if block:
            print(block)
        else:
            break

And now I noticed that the method in 4th Attempt is just dumbly re-inventing the wheel (BufferedReader). LOL, knowledge is power.

Summary Here

So what's the lesson learnt besides opening a file?

I think, firstly, do not afraid to share your ideas even if it's not a perfect one (like what I did) and do not afraid to admit your mistakes. Share more and interact more, we can then gain insights from the others and improve ourselves. Cheers~

You can grab the demo source code on GitHub here: ZhiyueYi/how-to-open-a-file-in-python-like-a-pro-demo

6 Tips for Beginners to Write Good Unit Tests

Zhiyue Yi — Sun, 11 Oct 2020 09:18:25 +0000

Visit my Blog for the original post: 6 Tips for Beginners to Write Good Unit Tests

TLDR;

Unit tests are one of the fundamental components which safeguard the quality of our applications. It takes little efforts to write but produces much values in term of validating the correctness of the codes.

There are many articles talking about what unit test is and why it is important and necessary to write unit tests. In this blog post, I would not talk about these because I assume you are already aware of them :) So let's just shorten the long story and get to the tips directly.

1. Make Your Function Short for Easier Testing

I remember the time I just started with programming, I tended to put everything inside of one function. As long as I could make it work, I was satisfied. However, in reality, such function with a long long procedures may result that the function is hard to test.

Just imagine, a function with tens of condition checking and so many if-else blocks turn your codes into Lasagne. There can be so many possible outcomes from your function. To test this function, you have to write 20 or 30 unit tests to test all the branches of the conditions. That just sounds super tedious!

// Codes
function superLongFunction() {
  if (conditionA) {
    // A bunch of operations
    // ...
    // ...
    if(conditionB) {
      // A bunch of operations
      // ...
      // ...
      return;
    }
    // A bunch of operations
    // ...
    // ...
  } else if (conditionC) {
    someList.forEach(item => {
      if (item.flag) {
        // A bunch operations
        // ...
        // ...
      }

      if(item.flag2) {
        // A bunch of operations
        // ...
        // ...
      }
    });
  }
  // A bunch of operations
  // ...
  // ...
}

// Tests
describe('superLongFunction' () => {
  it('should ... condition A', () => { /* ... */ })
  it('should ... condition A', () => { /* ... */ })
  it('should ... condition A', () => { /* ... */ })
  it('should ... condition A', () => { /* ... */ })
  it('should ... condition A', () => { /* ... */ })
  it('should ... condition A', () => { /* ... */ })
  it('should ... condition A', () => { /* ... */ })
  it('should ... condition A', () => { /* ... */ })
  it('should ... condition B', () => { /* ... */ })
  it('should ... condition B', () => { /* ... */ })
  it('should ... condition B', () => { /* ... */ })
  it('should ... condition B', () => { /* ... */ })
  it('should ... condition B', () => { /* ... */ })
  it('should ... condition C', () => { /* ... */ })
  it('should ... condition C', () => { /* ... */ })
  it('should ... condition C', () => { /* ... */ })
  it('should ... condition C', () => { /* ... */ })
  it('should ... condition C', () => { /* ... */ })
  it('should ... condition C', () => { /* ... */ })
  it('should ... condition Others', () => { /* ... */ })
  it('should ... condition Others', () => { /* ... */ })
  it('should ... condition Others', () => { /* ... */ })
  it('should ... condition Others', () => { /* ... */ })
});

What is worse is that, if you update some of the logics, or refactor the function in future, it can be a real disaster for you to update so many unit tests!

How should we improve that? Well, it is simple by just breaking the super giant function into a multiple of small functions. In this way, you turn a large scope into several smaller scopes, with smaller sets of unit tests. Every set of unit tests just focuses on that particular function only, so that they don't have to bother about the changes in other functions!

// Codes
function shortFunction() {
  if (conditionA) {
    doA();
    checkB();
    doRestOfA();
  } else if (conditionC) {
    someList.forEach(item => {
      doC(item);
    });
  }
  doOthers();
}

function checkB() {
  if (conditionB) {
    doB();
  }
  doA();
}

function doC(item) {
  if (item.flag) {
    itemDo1();
  }

  if(item.flag2) {
    itemDo2();
  }
}

function doA() { /* A bunch of operations */ }
function doRestOfA() { /* A bunch of operations */ }
function doB() { /* A bunch of operations */ }
function doOthers() { /* A bunch of operations */ }
function itemDo1() { /* A bunch of operations */ }
function itemDo2() { /* A bunch of operations */ }

// Tests
describe('shortFunction' () => {
  it('should ...', () => { /* ... */ })
  it('should ...', () => { /* ... */ })
  it('should ...', () => { /* ... */ })
  it('should ...', () => { /* ... */ })
});

describe('doA', () => {
  it('should ...', () => { /* ... */ })
  it('should ...', () => { /* ... */ })
});

describe('doRestOfA', () => {
  it('should ...', () => { /* ... */ })
  it('should ...', () => { /* ... */ })
});

describe('doB', () => {
  it('should ...', () => { /* ... */ })
  it('should ...', () => { /* ... */ })
  it('should ...', () => { /* ... */ })
});

describe('doOthers', () => {
  it('should ...', () => { /* ... */ })
  it('should ...', () => { /* ... */ })
  it('should ...', () => { /* ... */ })
  it('should ...', () => { /* ... */ })
});

describe('itemDo1', () => {
  it('should ...', () => { /* ... */ })
  it('should ...', () => { /* ... */ })
});

describe('itemDo2', () => {
  it('should ...', () => { /* ... */ })
  it('should ...', () => { /* ... */ })
});

2. Don't Forget about Sad Paths

Sometimes we tend to be optimistic about our applications, just like we believe users would do exactly what we assume they would do. But in reality, there are always surprise from either your code or your users (LOL).

In unit tests, we should not only care about happy paths, but also we should consider sad paths.

So what are happy path and sad path?

It's just like the 2 sides of coins. If there is an if, then most likely you would have at least 2 test cases.

// Codes
function check() {
  if (flag) {
    // do something
  } else {
    // do something
  }
}

// Tests
describe('check', () => {
  it('should ... when flag is true', () => { /** some test codes **/ })
  it('should ... when flag is false', () => { /** some test codes **/ })
});

Or if your function is possible to throw some errors, you would have situation when function is operating normally and function is throwing errors.

function haveATry() {
  try {
    // do something
  } catch {
    // handle error
  }
}

// Tests
describe('check', () => {
  it('should ...', () => { /** some test codes **/ })
  it('should ... when error is thrown', () => { /** some test codes **/ })
});

When we are writing tests, if we always reminds ourselves about testing both happy paths and sad paths, are also forced to consider unexpected situations and how we will handle those cases gracefully. Eventually, we can build our application as robust as possible.

3. Tests Should Remain Dumb

When we are doing development, we try to be smart in implementations because smart codes may probably improve our code readability, flexibility or extensibility.

But when it comes to testings, we should instead be dumb, in terms of not writing logical conditions inside of our tests.

I have seen some for loops and if else blocks in tests such as

describe('some test suite', () => {
  it('should ...', () => {
    // Some testing codes...

    for (let i = 0; i < list.length; i++) {
      if (someCondition) {
        expect(someVariable).toBe(someValueA);
      } else if (someOtherCondition) {
        expect(someVariable).toBe(someValueB);
      } else {
        expect(someVariable).toBe(someValueC);
      }
    }

    // Some testing codes...
  });
});

Well, one of the reasons why we have tests is because we are human and we make mistakes when we write logics, especially complex logics.

And now, in tests, we are writing complex logics, which is possibly introducing bugs to your tests. And the sad thing is that we don't have more tests to test our tests (LOL).

Therefore, make your tests remain dumb and try not to write "smart" codes in your tests. Instead, you should do

describe('some test suite', () => {
  it('should ... when someCondition is true', () => {
    // Some testing codes...
    expect(someVariable).toBe(someValueA);
    // Some testing codes...
  });

  it('should ... when someOtherCondition is true', () => {
    // Some testing codes...
    expect(someVariable).toBe(someValueB);
    // Some testing codes...
  });

  it('should ... when both someCondition and someOtherCondition are false', () => {
    // Some testing codes...
    expect(someVariable).toBe(someVariable);
    // Some testing codes...
  });
});

Or you could try data driven testing, which we are going to discuss about in tip 6.

4. Mock Functions for Dependencies

When you are building modern applications, inevitably you have to deal with dependencies, such as external libraries or plugins. Then, you call their functions inside of your own functions and then you have to test it.

The question is, how are we going to deal with them in our unit tests?

Take a look at the following codes:

// Codes
function greetings() {
  const today = dayjs();
  const hour = today.hour();

  if (hour >= 5 && hour < 12) {
    return 'morning';
  }

  if (hour >= 12 && hour < 18) {
    return 'afternoon';
  }

  if (hour >= 18 && hour < 22) {
    return 'evening';
  }

  return 'midnight';
}

// Tests
describe(() => {
  expect(greetings()).toBe('afternoon');
})

Do you think such tests are reliable and stable? If you run tests at 3pm, your tests are just fine and you can enjoy your afternoon tea, but if you run tests at 7pm, your tests are going to break and you will have to work overtime (LOL).

So no, such tests are not stable, because it depends on an external library called dayjs. How are we going to solve it?

We are going to mock the behaviour of dayjs by forcing it to return the value we want to test. We can use jest.fn() or sinon.stub() depending on which testing framework you are using.

// Tests 
jest.mock("dayjs");

describe("greetings", () => {
  const mockDayjsHour = jest.fn();

  beforeAll(() => {
    dayjs.mockImplementation(() => ({
      hour: mockDayjsHour,
    }));
  });

  afterEach(() => {
    jest.clearAllMocks();
  });

  it("should return morning when the time is 5:00", () => {
    mockDayjsHour.mockImplementation(() => 5);
    expect(greetings()).toBe("morning");
  });

  it("should return morning when the time is 12:00", () => {
    mockDayjsHour.mockImplementation(() => 12);
    expect(greetings()).toBe("afternoon");
  });

  it("should return morning when the time is 18:00", () => {
    mockDayjsHour.mockImplementation(() => 18);
    expect(greetings()).toBe("evening");
  });
});

As you can see from the code snippets, in each test, we mock the dayjs().hour() to return different values, so that we can ensure in that test, the hour returned is determined, not varied by our actual time. And then, we can test the string returned by function given the determined hour here.

5. Use Boundary Testing Approach

Boundary testing is a very useful technique to test functions with inputs as range of values. When we have a range of values to be tested, such as the hours in the previous example, which is ranged from 0 to 23, instead of randomly picking up values in the range, we can use boundary testing approach to determine what the values are the ones we should tests.

For example, there are a total of 4 possible outcomes from this function, namely "morning", "afternoon", "evening" and "midnight", every one of which has its hour range, with both upper bound and lower bound.

Greeting	Range	Lower bound	Upper bound
Midnight	[0 - 5)	0	4
Morning	[5 - 12)	5	11
Afternoon	[12 - 18)	12	17
Evening	[18 - 23)	18	21
Midnight	[23 - 24)	22	23

From this table, we can know that, the minimum and maximum hour which can lead to "afternoon" are 12 and 17, that means

We don't need to tests the numbers in between 12 and 17 as they must be "afternoon" if tests of 12 and 17 both pass.
Any value outside of 12 and 17 (<12 or >17) are definitely not "afternoon"

Therefore, we can update our tests to something like:

jest.mock("dayjs");

describe("greetings", () => {
  const mockDayjsHour = jest.fn();

  beforeAll(() => {
    dayjs.mockImplementation(() => ({
      hour: mockDayjsHour,
    }));
  });

  afterEach(() => {
    jest.clearAllMocks();
  });

  it("should return morning when the time is 5:00", () => {
    mockDayjsHour.mockImplementation(() => 5);
    expect(greetings()).toBe("morning");
  });

  it("should return morning when the time is 11:00", () => {
    mockDayjsHour.mockImplementation(() => 11);
    expect(greetings()).toBe("morning");
  });

  it("should return morning when the time is 12:00", () => {
    mockDayjsHour.mockImplementation(() => 12);
    expect(greetings()).toBe("afternoon");
  });

  it("should return morning when the time is 17:00", () => {
    mockDayjsHour.mockImplementation(() => 17);
    expect(greetings()).toBe("afternoon");
  });

  it("should return morning when the time is 18:00", () => {
    mockDayjsHour.mockImplementation(() => 18);
    expect(greetings()).toBe("evening");
  });

  it("should return morning when the time is 22:00", () => {
    mockDayjsHour.mockImplementation(() => 21);
    expect(greetings()).toBe("evening");
  });

  it("should return midnight when the time is 22:00", () => {
    mockDayjsHour.mockImplementation(() => 22);
    expect(greetings()).toBe("midnight");
  });

  it("should return midnight when the time is 23:00", () => {
    mockDayjsHour.mockImplementation(() => 23);
    expect(greetings()).toBe("midnight");
  });

  it("should return midnight when the time is 00:00", () => {
    mockDayjsHour.mockImplementation(() => 0);
    expect(greetings()).toBe("midnight");
  });

  it("should return midnight when the time is 4:00", () => {
    mockDayjsHour.mockImplementation(() => 4);
    expect(greetings()).toBe("midnight");
  });
});

6. Use Data-driven Testing

With the previous example, you might notice that there are too many redundant codes for testing this one particular function. Is there any way to optimise it?

Yes, there is. You can use data-driven testing to test different conditions with different consequences. That means, the logic of your testing is not changed, what is changed is only your testing data and result. In Jest, you can use it.each function to achieve your purpose.

jest.mock("dayjs");

describe("greetings", () => {
  const mockDayjsHour = jest.fn();

  beforeAll(() => {
    dayjs.mockImplementation(() => ({
      hour: mockDayjsHour,
    }));
  });

  afterEach(() => {
    jest.clearAllMocks();
  });

  it.each`
    hour  | greeting
    ${5}  | ${'morning'}
    ${11} | ${'morning'}
    ${12} | ${'afternoon'}
    ${17} | ${'afternoon'}
    ${18} | ${'evening'}
    ${21} | ${'evening'}
    ${22} | ${'midnight'}
    ${23} | ${'midnight'}
    ${0}  | ${'midnight'}
    ${4}  | ${'midnight'}
  `('should return $greeting when the time is $hour:00', ({hour, greeting}) => {
    mockDayjsHour.mockImplementation(() => hour);
    expect(greetings()).toBe(greeting);
  })
});

In it.each, you can pass in a table as a string literal like the code above, or a nested array like this. By providing the conditions and the expected results, you can reuse the same piece of logics to tests. Also, it is more readable than directly using for loops.

Code for Demo

You can see this Gist for the demo code of these unit tests.

How to Properly Mock Typed Variables in Unit Tests with TypeScript

Zhiyue Yi — Sun, 16 Aug 2020 12:41:24 +0000

Visit my Blog for the original post: How to Properly Mock Typed Variables in Unit Tests with TypeScript

The Problem I Faced

When we are doing unit tests, most of the time, we have to create some variables with existing types and some mock values to test our functions. However, in TypeScript, you might have a headache creating the variable, if the mocked variable has many properties and you only want to mock some of the property values for specific tests.

Let's illustrate this problem with an example. (Jump to the bottom if you want to check the solution directly).

If you have the Order type has the following structure:

interface Order {
  id: number;
  buyer: string;
  items: {
    id: number;
    description: string;
    unit: number;
    unitPrice: number;
    discount: number;
  }[];
  promoCode: string;
  totalPrice: number;
  buyerMessage: string;
  remarks: string;
  createdAt: Date;
  updatedAt: Date;
}

And you want to test function called calculateTotalPrice(order: Order): boolean, which takes an order object with Order type as an input, calculate total price for all the items, compare the result with the totalPrice property, and lastly output the boolean of comparison result, which identifies if the calculation matches the existing total price record.

So, it's very simple to write a test for it:

describe('# calculateTotalPrice', () => {
  it('should return true if total price matches', () => {
    const mockOrder: Order = {
      // mock some values with total price matching with calculation from records
    }

    expect(calculateTotalPrice(mockOrder)).toBe(true);
  });

  it('should return false if total price does not match', () => {
    const mockOrder: Order = {
      // mock some values with total price NOT matching with calculation from records
    }

    expect(calculateTotalPrice(mockOrder)).toBe(false);
  });
});

Now the problem is, I ONLY need items and totalPrice properties for the test, but TypeScript linter yells to me for a complete data structure like this, how should I do?

The Not-so-good Ways to Solve It

Well, we can directly jump to the correct answer for this problem, because it's simple to adopt. But, I think it's more educational if we can learn from the bad cases and understand why they are bad.

Basically, there are 3 not-so-good ways to solve it, which I've tried them all for the past a few years. They are ranked by how bad it is in descending order.

#1: Make them optional, why bother? [BAD]

When I was an absolute beginner to TypeScript, I tend to use this simple and brutal method to solve this issue, marking all the properties optional like this:

interface Order {
  id?: number;
  buyer?: string;
  items?: {
    id?: number;
    description?: string;
    unit?: number;
    unitPrice?: number;
    discount?: number;
  }[];
  promoCode?: string;
  totalPrice?: number;
  buyerMessage?: string;
  remarks?: string;
  createdAt?: Date;
  updatedAt?: Date;
}

This is definitely a BIG no no!

That's because the properties are not really optional! They are only optional when you are doing tests. While in the actual code base, these properties can be mandatory. Marking them optional makes you convenient, but the consequence can be disastrous. In this way, you lose the capability to do null / undefined check for the properties, which results your code to likely have careless mistakes not being able to uncover!

In a word, never give in with your actual codes just because you want to have some conveniences in testing, or whatever other aspects!

#2: ANY way, we did it [Not-so-good]

The second way, is just turning TypeScript to "AnyScript" by adding any to the mocked variable, so that the type check can be ignored and less annoying.

it('should return true if total price matches', () => {
  const mockOrder: any = {
    items: [
      {
        unit: 2,
        unitPrice: 10,
        discount: 0,
      },
      {
        unit: 1,
        unitPrice: 5,
        discount: 1,
      }
    ],
    totalPrice: 24,
  };

  expect(calculateTotalPrice(mockOrder)).toBe(true);
});

Well, it actually works, at least in our case. However, the order type is lost. It is not convenient especially when you want to have the intellisense feature when you are constructing the mockOrder variable, as the text editor (mine is VS Code) won't be able to intelligently notify you what properties an Order object should have, which can be less convenient and annoying most of the time.

#3: I say it is AS it is! [Looks probably ok]

The third way, it is one step smarter than using any, which is to use as keyword to force adding the Order type at the variable declaration stage.

it('should return true if total price matches', () => {
  const mockOrder = {
    items: [
      {
        unit: 2,
        unitPrice: 10,
        discount: 0,
      },
      {
        unit: 1,
        unitPrice: 5,
        discount: 1,
      }
    ],
    totalPrice: 24,
  } as Order;

  expect(calculateTotalPrice(mockOrder)).toBe(true);
});

It actually works very well, and I really thought it was the ultimate answer to this problem because It has types and does not affect actual code base.

But I still feel something is missing here.

Hey, what if I put the property which doesn't belong to the Order object? For instance:

const mockOrder = {
  iShouldNotBeHereButHereIam: true,
  items: [
    {
      unit: 2,
      unitPrice: 10,
      discount: 0,
    },
    {
      unit: 1,
      unitPrice: 5,
      discount: 1,
    }
  ],
  totalPrice: 24,
} as Order;

In this case, you can't really lint the "illegal" property inside of the object, because you have forced the object to be an Order object, which is obviously not so right here.

The Good Way to Solve It: Use the Native Type Partial in TypeScript!

So here comes the best approach to this problem, which I just discovered it today.

It is to use the native type Partial in TypeScript.

According to TypeScript: Handbook - Utility, Partial constructs a type with all properties of Type set to optional. This utility will return a type that represents all subsets of a given type.

However, we cannot solely use partial here, because our object is nested.

// Lint error occurs:
// Type '{ unit: number; unitPrice: number; discount: number; }' is missing the following properties from type 'Item': id, description ts(2739)
const mockOrder: Partial<Order> = {
  items: [
    {
      unit: 2,
      unitPrice: 10,
      discount: 0,
    },
    {
      unit: 1,
      unitPrice: 5,
      discount: 1,
    }
  ],
  totalPrice: 24,
};

It's because the Partial only applies to the first level (totalPrice level), but not to the second level (unitPrice level). Hence, we can consider to add a custom RecursivePartial type to a global declaration file like src/declarations.d.ts. (Solution referred to use Partial in nested property with typescript - Stack Overflow)

type RecursivePartial<T> = {
  [P in keyof T]?: RecursivePartial<T[P]>;
};

Then you can complete the test like:

describe("# calculateTotalPrice", () => {
  it("should return true if total price matches", () => {
    const mockOrder: RecursivePartial<Order> = {
      items: [
        {
          unit: 2,
          unitPrice: 10,
          discount: 0,
        },
        {
          unit: 1,
          unitPrice: 5,
          discount: 1,
        },
      ],
      totalPrice: 24,
    };

    // Now we can safely transform the type to Order here
    expect(calculateTotalPrice(mockOrder as Order)).toBe(true);
  });
});

This method is good in our circumstances because your object is typed all the time (both in creation and in use) and actual code based does not get affected!

GitHub Demo is here ZhiyueYi/demo-in-blog

Cheers!

Featured image is credited to Chokniti Khongchum from Pexels

Include Your React Widgets in Any Web Page

Zhiyue Yi — Mon, 11 May 2020 13:37:02 +0000

Visit my Blog for the original post: Include Your React Widgets in Any Web Page

Hello everyone! It's been a long time since my last post because I was so busy with my study in the last semester and, of course, damn COVID-19! But anyway, I finally graduate from the university, so it's time to make a post! Woohoo!!

To combat COVID-19, I participated a government open source project, which requires me to build a react widget library and integrate to any web pages which can be written in any web frameworks, such as Angular, Vue or even Svelte.

Initially, I thought I may need web component to solve the problem, but eventually, I found a native javascript way to solve it, thanks to Dhrubajit for inspiring me!

The code is HERE and the Demo is HERE

Main Idea

To make the widget universal for all kinds of web applications, we can utilise <script> tag, which can load a bundled JavaScript file including the React run time and the widget itself. Then, in the target web page, we can create a <div> tag with a specific ID. Based on the ID, we can render the widget inside of the <div> tag. In this way, we can load our React widget in any web page, because they are all basically JavaScript!

The target of this demo is to allow the following HTML codes

<div id="simple-calendar" is-click-disabled min-year="2020"></div>
<script src="./simple-calendar.js"></script>

To render an equivalent react component as

<SimpleCalendar id="simple-calendar" isClickDisabled={true} minYear={2020}>

Setup

For the setup, you can just follow what I did in the demo project. The widget source codes are included in the src folder and the demo web page is in the docs folder.

The idea is that, we need to use Webpack to bundle whatever in the src folder, and then produce the bundled JavaScript file named simple-calendar.js to the docs folder. Then, the docs/index.html page can load the bundled JavaScript file by <script src="./simple-calendar.js"></script>. In this way, the React widget SimpleCalendar can be rendered in the docs/index.html page.

What's most interesting is that, docs/index.html is just a plain static web page, and it can still pass initial configurations to the <div> tag to render the react SimpleCalendar component.

Webpack Configuration

It's fairly easy to create a simple WebPack configuration for this Demo. Basically we just want to bundle the whole src folder with the entry file index.ts, and then output the bundled file to docs folder with a name as simple-calender.js.

I recommend you to read Demystifying Webpack written by my good friend Dhrubajit because his tutorial on Webpack configuration is AWESOME!

const path = require("path");

const config = {
  entry: path.join(__dirname, "./src/index.ts"),
  output: {
    path: path.resolve(__dirname, "./docs"),
    filename: "simple-calendar.js",
  },
  devtool: "source-map",
  resolve: {
    extensions: [".ts", ".tsx", ".js", ".css", ".txt"],
  },
  module: {
    rules: [
      {
        test: /\.ts(x?)$/,
        exclude: /node_modules/,
        include: [path.resolve("src")],
        loader: "ts-loader",
        options: {
          transpileOnly: false,
          compilerOptions: {
            module: "es2015",
          },
        },
      },
      {
        test: /\.css$/i,
        use: ["style-loader", "css-loader"],
      },
    ],
  },
};

module.exports = config;

HTML Tag Wrapper

Here comes the core function to achieve including react widgets in any web page, which is to find the element from the web page with a pre-defined element ID.

And then we need to get all the HTML tag attributes from the element, parse them into a key-value pair object, dump the object into the React Component (which is our SimpleCalendar component in src/simple-calendar.tsx file) and lastly, use ReactDOM to render the component.

function HtmlTagWrapper(Component: (props?: any) => JSX.Element) {
  const el = document.getElementById("simple-calendar");
  const attrs = el.attributes;

  const props = attrToObj(attrs);
  console.log(props);
  ReactDOM.render(<Component {...props} />, el);
}

Attributes to Object

It's actually a bit tricky to transform the attributes to key-value pair objects, because attributes are of the NamedNodeMap type. According to NamedNodeMap - Mozilla, a NamedNodeMap object can be access by index as in an array, or by key name as in an object.

function attrToObj(attrs: NamedNodeMap) {
  const attrsObj: { [key: string]: unknown } = {};
  const length = attrs.length;
  for (let i = 0; i < length; i++) {
    const { name, value } = attrs[i];
    attrsObj[parseKey(name)] = parseValue(value);
  }
  return attrsObj;
}

In the above code snippet, I can simply grab the name and value from attrs[i].

And here comes another tricky part for name and value. I have to parse them so that the constructed attrsObj can have correct keys and values.

Parse Keys and Values

Let's say you have a simple HTML div tag as <div id="simple-calendar" is-click-disabled min-year="2020">

You intend to have an attrsObj to be constructed as

{
  "id": "simple-calendar",
  "isClickDisabled": true,
  "minYear": 2020
}

However, from const { name, value } = attrs[i];, the values you get are all strings, the keys you get are all small letters connected with -

Therefore, you need to parse them, so that the values can be string, number, boolean respectively and the keys can be in camel cases without delimiters.

function parseValue(value: any) {
  if (value === "" || value === "true") {
    return true;
  }

  if (value === "false") {
    return false;
  }

  if (Number(value).toString() === value) {
    return Number(value);
  }

  return value;
}

function parseKey(key: string) {
  const parts = key.split("-");
  const newParts = [parts[0]];
  for (let i = 1; i < parts.length; i++) {
    const firstLetter = parts[i].slice(0, 1);
    const restOfLetters = parts[i].slice(1);
    const newPart = firstLetter.toUpperCase() + restOfLetters;
    newParts.push(newPart);
  }
  return newParts.join("");
}

Put Them Together

By implementing all of parts I mentioned above, finally you can just write an HTML div tag as

<div id="simple-calendar" is-click-disabled min-year="2020"></div>
<script src="./simple-calendar.js"></script>

To render an equivalent react component as

<SimpleCalendar id="simple-calendar" isClickDisabled={true} minYear={2020}>

And most importantly, you can put your <div> and <script> in any kind of web page because they are simply standard JavaScript and HTML!

Design a Table to Keep Historical Changes in Database

Zhiyue Yi — Thu, 16 Jan 2020 14:08:42 +0000

Visit my Blog for the original post: Design a Table to Keep Historical Changes in Database

Back to months ago, I encountered a classical problem: how to design a table so that it can keep historical changes in database?

Imagine you have a transaction table, which has the following fields:

Transaction

Column Name	Data Type
Id	int
Description	text
TransactionDate	date
DeliveryDate	date
Status	varchar(30)

Here comes the business requirements: the users want to keep the historical changes for transaction table for future usage, e.g. data analysis / auditing

How to design such a table which can keep the historical changes?

I have 3 different approaches to solve the problem.

1. Use Effective From and Effective To Fields

I DON'T like this approach but I've seen people practicing it, struggling with it but still insisting to do it. Hence, I would like to demonstrate why it's a bad approach doing so.

The idea is to have EffectiveFrom and EffectiveTo fields inside of the tables, which looks like this:

Column Name	Data Type
Id	int
Description	text
TransactionDate	date
DeliveryDate	date
Status	varchar(30)
EffectiveFrom	date
EffectiveTo	date

The EffectiveFrom and EffectiveTo fields are for validating the effectiveness of the records. For example, today is 2019-09-17, if the record has the EffectiveFrom being 2019-09-01 and EffectiveTo being 2019-09-30, then this record is active. If today's date is out of the range, then the record is inactive / disabled.

In that case, the effectiveness of the record is indirectly determined by these 2 fields. Hence, the following situation may happen

Id	Description	TransactionDate	DeliveryDate	Status	EffectiveFrom	EffectiveTo
100	A short text	2019-09-15	2019-09-28	Shipping	2019-09-15	2019-09-17
101	A short text	2019-09-15	null	Cancelled	2019-09-17	2019-09-30

Once the value is changed, the EffectiveTo field is set to a previous date, Disabled is set to true and a duplicated record is inserted into the table which contains the latest information, and DIFFERENT ID.

Such design actually meet the requirement of retaining historical changes in database, however, it's actually bad. By duplicating the record, the ID is changed from 100 to 101. As a developer, we know that there 2 transactions are the same transaction, it's just one is newer and the other one is older. But now there are 2 IDs to represent 1 record, which becomes a disaster for other tables linking to it.

For example, if you have a TransactionDetails table containing the transaction items which needs Transaction ID to establish the relationship, you would end up into troubles. Let's say I bought an iPad and Apple Pencil in this transaction 100. Now the transaction is updated to 101 but the iPad and Apple Pencil are still linking to 100.

To solve such a issue, you need to do more queries to identify which is the latest active ID and then link to it, which significantly increase the complexity.

And it's really bad.

2. Use a History Table

What if I want to keep a whole record as a history but doesn't want to affect my actual table? Then you may want to create a history table for Transaction, which has the same fields as Transaction table itself.

TransactionHistory

Column Name	Data Type
Id	int
Description	text
TransactionDate	date
DeliveryDate	date
Status	varchar(30)
AddBy	int
AddDate	date

The same example happens here: there is a transaction looks like this:

Id	Description	TransactionDate	DeliveryDate	Status
100	A short text	2019-09-15	2019-09-28	Shipping

Then a user with id 20 modifies the description to A not long text and DeliveryDate to 2019-10-01.

Now, you only have to insert one record, which is a duplicated record of the one in Transaction table, into TransactionHistory table, which looks like this:

Id	Description	TransactionDate	DeliveryDate	Status	AddBy	AddDate
100	A short text	2019-09-15	2019-09-28	Shipping	20	2019-09-17

Lastly, update the original record in Transaction table into

Id	Description	TransactionDate	DeliveryDate	Status
100	A not long text	2019-09-15	2019-10-01	Shipping

In this case, you are trying to save the old record completely into another table and then apply changes in the original table. It's better if the users want to have a full picture of how the record is changing.

However, the down side of this approach is that, redundant information is stored. For example, if you have a large number of fields, but only one or two fields are updated every time, it's actually a huge waste of space.

3. Use an Audit Table

A better solution is to create an audit table to record every single change in every field, which saves the spaces by eliminating redundant information. The table looks like this:

Audit

Column Name	Data Type
Id	int
Table	varchar(50)
Field	varchar(50)
RecordId	int
OldValue	varchar(255)
NewValue	varchar(255)
AddBy	int
AddDate	date

For example, there is a transaction looks like this:

Id	Description	TransactionDate	DeliveryDate	Status
100	A short text	2019-09-15	2019-09-28	Shipping

And now, another user with id 20 modifies the description to A not long text and DeliveryDate to 2019-10-01

Id	Description	TransactionDate	DeliveryDate	Status
100	A not long text	2019-09-15	2019-10-01	Shipping

Hence, there are 3 fields changed, Description, ModBy and ModDate. Respectively, there should be 3 records added into the audit table as shown below.

Id	Table	Field	RecordId	OldValue	NewValue	AddBy	AddDate
1	Transaction	Description	100	A short text	A not long text	20	2019-09-17
2	Transaction	DeliveryDate	100	2019-09-28	2019-10-01	20	2019-09-17

Lastly, update the original record in Transaction table into

Id	Description	TransactionDate	DeliveryDate	Status
100	A not long text	2019-09-15	2019-10-01	Shipping

In that case, it's very easy to query for field changes. For example, if I want to find out all the description changes for the transaction with ID 100, I can just query by

Select * from Audit where RecordId = 100 and Field = "description".

The downside of this approach is the possible huge increase of records. Since every change in different fields is one record in the Audit table, it may grow drastically fast such as tens of changes resulting in hundreds of audit records. In this case, table indexing plays a vital role for enhancing the querying performance.

Conclusion

In this article, I talked about 3 approaches to keep historical changes in database, which are effective from and effective to fields, history table and audit table.

Effective from and effective to fields is NOT recommend to use, and I recommend to use history table or audit table to solve the problem depending on cases.

Here is the comparison.

Audit Table

Record only data in changed fields
Pros:
- Not affecting actual table
- No Redundant information
Cons:
- No. of records may increase significantly
Suitable for: actual table has many fields, but often only a few fields are changed

History Table

Record the entire old record
Pros:
- Simple query to get the complete history
- Not affecting actual table
Cons
- Redundant information is stored
Suitable for:
- A lot of fields are changed in one time
- Generating a change report with full record history is needed

Featured image is credited to Joshua K. Jackson from Pexels

How to Create a Simple React Countdown Timer

Zhiyue Yi — Tue, 07 Jan 2020 05:29:28 +0000

Visit my Blog for the original post: How to Create a Simple React Countdown Timer

A Few Words in Front

Today I am going to share one interesting and useful small front-end feature implementation in React, a simple count down timer.

Solution

The correct implementation can be found at simple-react-countdown-timer if you wish to implement quickly without reading through my explanation.



import * as React from "react";
import { render } from "react-dom";

import "./styles.css";

function App() {
  const [counter, setCounter] = React.useState(60);

  // First Attempts
  // setInterval(() => setCounter(counter - 1), 1000);

  // Second Attempts
  // React.useEffect(() => {
  //   counter > 0 && setInterval(() => setCounter(counter - 1), 1000);
  // }, []);

  // Second Attempts - Inspection
  // React.useEffect(() => {
  //   counter > 0 &&
  //     setInterval(() => {
  //       console.log(counter);
  //       setCounter(counter - 1);
  //     }, 1000);
  // }, []);

  // Third Attempts
  // React.useEffect(() => {
  //   const timer =
  //     counter > 0 && setInterval(() => setCounter(counter - 1), 1000);
  //   return () => clearInterval(timer);
  // }, [counter]);

  // Suggested by Laurent
  React.useEffect(() => {
    counter > 0 && setTimeout(() => setCounter(counter - 1), 1000);
  }, [counter]);

  return (
    <div className="App">
      <div>Countdown: {counter}</div>
    </div>
  );
}

const rootElement = document.getElementById("root");
render(<App />, rootElement);

Explanation

First attempt, in an intuitive way

Initially, we utilise useState react hook to create a new state variable counter in the functional component. counter holds the number of seconds the counter should start with. Then a native JavaScript function, setInterval is called to trigger setCounter(counter - 1) for every 1000ms. Intuitively, it represents the number decreases by 1 every 1 second.



function App() {
  const [counter, setCounter] = React.useState(60);

  // First Attempts
  setInterval(() => setCounter(counter - 1), 1000);

  return (
    <div className="App">
      <div>Countdown: {counter}</div>
    </div>
  );
}

However, it works, in a terrible way. You can clearly notice that Initially the countdown works fine but then start to gradually accelerate.

That is because every time when setCounter is triggered, the App component get re-rendered. As the component is re-rendered, the App() function is executed again, therefore, the setInterval() function triggers again. Then there are 2 setInterval() running at the same time and both triggering setCounter(), which again, creates more setInterval().

Therefore, more and more setInterval() are created and the counter is deducted for more and more times, finally resulting in accelerating decrement.

Second attempt, utilizing useEffect hook

Ok, maybe we can solve the problem by just trigger the setInterval() once in the life cycle of a component by using useEffect() react hook.



function App() {
  const [counter, setCounter] = React.useState(60);

  // Second Attempts
  React.useEffect(() => {
    counter > 0 && setInterval(() => setCounter(counter - 1), 1000);
  }, []);

  return (
    <div className="App">
      <div>Countdown: {counter}</div>
    </div>
  );
}

useEffect is a react hook which accepts parameters including a function to be triggered at a specific point of time and an array of dependencies.

If the dependencies are not specified, the function is triggered every time any state inside of this component is updated.
If the dependencies are specified, only when the particular dependant state is changed, the function is triggered.
If the dependency array is empty, then the function is only triggered once when the component is initially rendered.

So in this way, surely setInterval() can only be triggered once when the component is initially rendered.

Are we getting the correct result here?

Wrong again! The countdown mysteriously freezes after being decremented by 1. I thought setInterval() should be running continuously? Why it is stopped? To find out what happened, let's add a console.log().



React.useEffect(() => {
  counter > 0 &&
    setInterval(() => {
      console.log(counter);
      setCounter(counter - 1);
    }, 1000);
}, []);

Now the console prints out:

All the numbers printed out are 60, which means the counter itself has not been decreased at all. But setCounter() definitely has run, then why isn't the counter updated?

This counter is indeed not decreased because the setCounter hook essentially does not change the counter within THIS function. The following illustration may make things clearer.

Because every time when the component is re-rendered, the App() function is called again. Therefore, within the App() scope, only in the first time, the useEffect() is triggered and the setInterval() is within the first time App() scope with the property counter always equal to 60.

In the global environment, there is only one setInterval() instance which contiguously set the counter to 59, causing new App() calls always get the state counter to be 59. That's why the counter seems to be freezed at 59. But in fact, it is not freezed, it is being reset all the time but the value is ALWAYS 59.

Third Attempts, useEffect with cancelling interval

To overcome the issue mentioned above, we need to trigger the setInterval() in every single App() call with different counter value, just as illustrated below.

To achieve that, we need to do 2 things:

Let setInterval() get triggered every time when component gets re-rendered Solution: add a dependency of counter in useEffect hook so that every time when the counter changes, a new setInterval() is called.
Clear setInterval() in this scope to avoid duplicated countdown Solution: add a callback function in useEffect hook to clear the interval in current scope so that only one setInterval() instance is running in the global environment at the same time.

Thus, the final solution is



function App() {
  const [counter, setCounter] = React.useState(60);

  // Third Attempts
  React.useEffect(() => {
    const timer =
      counter > 0 && setInterval(() => setCounter(counter - 1), 1000);
    return () => clearInterval(timer);
  }, [counter]);

  return (
    <div className="App">
      <div>Countdown: {counter}</div>
    </div>
  );
}

And it looks correct!

Thank you for reading!!

Update on 9 Dec 2019

Thanks to @Laurent, he suggested me to use setTimeout() to replace setInterval() in the final solution, which I think it's a better idea! setTimeout() only runs once, hence, we don't have to clear the setInterval() in every useEffect() change. Wonderful!

Variable Declaration in JavaScript: var, let or const?

Zhiyue Yi — Mon, 06 Jan 2020 08:32:17 +0000

Visit my Blog for the original post: Variable Declaration in JavaScript: var, let or const?

There are 4 ways of variable declaration in JavaScript. Beginner web developers are usuallly confused about the effects of different ways.

Hence, this article is for beginners to understand the differences among the 4 ways of declaring variables in JavaScript and when to use them.

Let's go through them

1. "Freestyle" Way (Yes, it works, but is strongly NOT recommanded!)

myVariable = 'abc'; It's possible that you declare a variable in JavaScript without using any keyword var, let, const. It simply means that you have created a global variable.

In node environment, let's run the following code snippet

a = "test";
console.log(a);
// output: test

The result shows test, which means it works!

However, if we add 'use strict' to enter strict mode, such declaration method is prohibited

"use strict";
a = "test";
console.log(a); // ReferenceError: a is not defined

An error is thrown. ReferenceError: a is not defined

This method is highly NOT recommanded because it is prohibited under strict mode and it will pollute your global environment. If your global environment contains too many useless temporary variables, your program will likely go into unpredicted errors and it will be a horrible experience to debug on such problem.

So, DO NOT use this way at all.

2. var

var is the most common way of declaring a variable in JavaScript. Before ES6 was released, you should always use var to declare your variables.

However, var also has its limitations because the variables declared with var is at function level.

What does it mean? See the following example.

"use strict";
function test() {
  for (var i = 0; i < 10; i++) {
    var count = i;
  }
  console.log(count);
}
test();
// Output: 9

Before running this piece of code, what do you expect the output of the function to be? Throwing an error? You might probably think that count is declared within the for loop, it should not be accessible outside of the loop.

But sorry, if you use var to declare a variable, the variable belongs to the function scope, which means that even though count is declared within the for loop, count still belongs to test() function. Hence, as long as it's within test() function, count is accessbile!

Another evidence is that, no error is thrown at all even if you console.log(count) before declaring it within a function! Since no error is thrown, it would be hard to trace when unexpected bug occurs.

"use strict";
function test() {
  console.log(count); // runs before declaration
  for (var i = 0; i < 10; i++) {
    var count = i;
  }
}
test();
// Output: undefined

The output shows undefined instead of throwing errors! Instead, errors will be thrown if the count is not declared at all!

"use strict";
function test() {
  console.log(count); // error is thrown
}
test();

3. let

let is introduced in ES6. It is scoped at block level, which resolves the difficulty you might encounter when using var.

By using let, the following code snippet correctly throws errors ReferenceError: count is not defined

"use strict";
function test() {
  for (let i = 0; i < 10; i++) {
    let count = i;
  }
  console.log(count); // ReferenceError: count is not defined
}
test();

That is because let makes count variable become block-scoped. count only exists in this for loop. It is a better way to use when declaring variables.

However, it also has its disadvantage. let is not compatible with old browsers such as IE 11. If you are writing JavaScript codes directly for browser display (not compiled by Babel) and need to take care of users with old browsers, you should consider to use var because incompatible let will likely cause problems in old browsers and stop webpage rendering once error occurs.

4. const

const is also introduced in ES6. Same as let, it is also scoped at block level. The only difference is that const variable is a constant, whose values cannot be changed.

"use strict";
const a = 1;
a = 2;

The above code snippet will throw error TypeError: Assignment to constant variable.

In addition, if you are working with arrays or objects, it's totally fine with constant declarations but modify it's attributes or members later. Consider the following code snippet:

"use strict";
const a = [];
const b = {};
a.push(1);
b.key = 2;
console.log("a", a);
console.log("b", b);
// output:
// a [ 1 ]
// b { key: 2 }

No error is occured. That is because the constant values of a and b are their addresses in the memory, instead of their members or attributes. If we assign the address of a to b as below, errors will then take place.

"use strict";
const a = [];
const b = {};
a = b; // TypeError: Assignment to constant variable.

Therefore, as long as you do not point a or b to another locations, no error would occur.

It is recommanded to do so to ensure that you are operating on the correct instance of object / array.

A little summary

You should never ever declare a variable without var, let or const!

Also, var should be avoided too unless you really have to consider browser compatibility issues.

The good practice is that you should always consider declaring a variable using const.
Using const by default helps you avoid unnecessary mistakes such as carelessly re-assign values to an important variable. unless you are sure that you would change its values later. Then the second option should always be let.

How to Create a Simple React Calendar with Styled Component

Zhiyue Yi — Sun, 05 Jan 2020 06:54:44 +0000

Visit my Blog for the original post: How to Create a Simple React Calendar with Styled Component

I found it quite interesting doing small components which are widely used in web developments. When I was a junior web developer, I tended to search libraries or plugins online if I need to build some featured. It could be a hard time to implement it because I didn't try to think how it actually works and I had to rely on the poorly written documents. And sometimes, customization was also difficult because it was hard to understand why the author did the plugin in their way.

The calendar was one of the most common examples. There are a lot of plugins online, but few of them really teach you how it works. When I was in my previous company as a junior developer, I was tasked to customize a calendar with integration of some business requirements, none of the libraries I found online fulfilled my needs. Then I realize, hey, why not build my own calendar from scratch?

It's not hard. Let's do it with React and Styled Component!

Solution

The final implementation can be found at simple-react-calendar if you wish to implement quickly without reading through my explanation.

import * as React from 'react';
import { useState, useEffect } from 'react';
import styled, { css } from 'styled-components';

const Frame = styled.div`
  width: 400px;
  border: 1px solid lightgrey;
  box-shadow: 2px 2px 2px #eee;
`;

const Header = styled.div`
  font-size: 18px;
  font-weight: bold;
  padding: 10px 10px 5px 10px;
  display: flex;
  justify-content: space-between;
  background-color: #f5f6fa;
`;

const Button = styled.div`
  cursor: pointer;
`;

const Body = styled.div`
  width: 100%;
  display: flex;
  flex-wrap: wrap;
`;

const Day = styled.div`
  width: 14.2%;
  height: 40px;
  display: flex;
  align-items: center;
  justify-content: center;
  cursor: pointer;

  ${props =>
    props.isToday &&
    css`
      border: 1px solid #eee;
    `}

  ${props =>
    props.isSelected &&
    css`
      background-color: #eee;
    `}
`;

export function Calendar() {
  const DAYS = [31, 28, 31, 30, 31, 30, 31, 31, 30, 31, 30, 31];
  const DAYS_LEAP = [31, 29, 31, 30, 31, 30, 31, 31, 30, 31, 30, 31];
  const DAYS_OF_THE_WEEK = ['MON', 'TUE', 'WED', 'THU', 'FRI', 'SAT', 'SUN'];
  const MONTHS = ['JAN', 'FEB', 'MAR', 'APR', 'MAY', 'JUN', 'JUL', 'AUG', 'SEP', 'OCT', 'NOV', 'DEC'];

  const today = new Date();
  const [date, setDate] = useState(today);
  const [day, setDay] = useState(date.getDate());
  const [month, setMonth] = useState(date.getMonth());
  const [year, setYear] = useState(date.getFullYear());
  const [startDay, setStartDay] = useState(getStartDayOfMonth(date));

  useEffect(() => {
    setDay(date.getDate());
    setMonth(date.getMonth());
    setYear(date.getFullYear());
    setStartDay(getStartDayOfMonth(date));
  }, [date]);

  function getStartDayOfMonth(date: Date) {
    return new Date(date.getFullYear(), date.getMonth(), 1).getDay();
  }

  function isLeapYear(year: number) {
    return (year % 4 === 0 && year % 100 !== 0) || year % 400 === 0;
  }

  const days = isLeapYear(date.getFullYear()) ? DAYS_LEAP : DAYS;

  return (
    <Frame>
      <Header>
        <Button onClick={() => setDate(new Date(year, month - 1, day))}>Prev</Button>
        <div>
          {MONTHS[month]} {year}
        </div>
        <Button onClick={() => setDate(new Date(year, month + 1, day))}>Next</Button>
      </Header>
      <Body>
        {DAYS_OF_THE_WEEK.map(d => (
          <Day key={d}>
            <strong>{d}</strong>
          </Day>
        ))}
        {Array(days[month] + (startDay - 1))
          .fill(null)
          .map((_, index) => {
            const d = index - (startDay - 2);
            return (
              <Day
                key={index}
                isToday={d === today.getDate()}
                isSelected={d === day}
                onClick={() => setDate(new Date(year, month, d))}
              >
                {d > 0 ? d : ''}
              </Day>
            );
          })}
      </Body>
    </Frame>
  );
}

Explanation

Initialize Calendar Component

Initialization of the component is rather simple. Firstly, import the necessary libraries, and then, create a function component called Calendar.

Inside of the component, let's return an empty div for now and add in some constants which are

DAYS: an array of numbers of days in every month for a normal year
DAYS_LEAP: an array of numbers of days in every month for a leap year
DAYS_OF_THE_WEEK: an array of names of days of the week
MONTHS: an array of names of months

import * as React from 'react';
import { useState, useEffect } from 'react';
import styled, { css } from 'styled-components';

export function Calendar() {
  const DAYS = [31, 28, 31, 30, 31, 30, 31, 31, 30, 31, 30, 31];
  const DAYS_LEAP = [31, 29, 31, 30, 31, 30, 31, 31, 30, 31, 30, 31];
  const DAYS_OF_THE_WEEK = ['MON', 'TUE', 'WED', 'THU', 'FRI', 'SAT', 'SUN'];
  const MONTHS = ['JAN', 'FEB', 'MAR', 'APR', 'MAY', 'JUN', 'JUL', 'AUG', 'SEP', 'OCT', 'NOV', 'DEC'];

  // Will be implemented below

  return (
    <div />
  );
}

Identify Component Layout

Now let's decide what the layout of a calendar component is. Since we are building a basic calendar component, we only need a header with a title current month and year, a previous month button and a next month button.

As for the body part, it is consisted of 2 parts, which are one row of days of the week and multiple rows of actual days.

Now, let's create these parts using styled components and put them above the calendar function component.

const Frame = styled.div`
  width: 400px;
  border: 1px solid lightgrey;
  box-shadow: 2px 2px 2px #eee;
`;

const Header = styled.div`
  font-size: 18px;
  font-weight: bold;
  padding: 10px 10px 5px 10px;
  display: flex;
  justify-content: space-between;
  background-color: #f5f6fa;
`;

const Button = styled.div`
  cursor: pointer;
`;

const Body = styled.div`
  width: 100%;
  display: flex;
  flex-wrap: wrap;
`;

const Day = styled.div`
  width: 14.2%;
  height: 40px;
  display: flex;
  align-items: center;
  justify-content: center;
  cursor: pointer;

  ${props =>
    props.isToday &&
    css`
      border: 1px solid #eee;
    `}

  ${props =>
    props.isSelected &&
    css`
      background-color: #eee;
    `}
`;

Notice that:

I use 14.2% as the width of the Day component, because there can only be 7 days in a week / row and 100% / 7 is approximately 14.2%.
For Day styled component, I will check 2 props isToday and isSelected to show a grey border if the day is today, or a grey background if it is selected

Use React Hooks to Manage Date / Month / Year as States

A calendar must have a current day, month and year displayed. They are considered as states to the component. Hence, we use useState react hook to manage these states. The initial values of them are generated from today's date by default (You may also make the default value of date come from a prop of this component for further extensibility).

Besides current day, month and year, you also need startDay to identify the first day of the month is which day of the week (Monday, Tuesday or others). After you know which day it is, it's much easier for you to identify the positions of all the days in the calendar.

After creating all the states, we also need to manage updates of them. We should make date variable as an entry point for calculations of day, month, year and startDay. Therefore, we can use useEffect react hook to update day, month, year and startDay with a dependency of date, so that later, when we click any day in the calendar, we can call setDate() to update date and trigger the rest of the states to update too.

const today = new Date();
const [date, setDate] = useState(today);
const [day, setDay] = useState(date.getDate());
const [month, setMonth] = useState(date.getMonth());
const [year, setYear] = useState(date.getFullYear());
const [startDay, setStartDay] = useState(calculateStartDayOfMonth(date));

useEffect(() => {
  setDay(date.getDate());
  setMonth(date.getMonth());
  setYear(date.getFullYear());
  setStartDay(calculateStartDayOfMonth(date));
}, [date]);

Get Start Day of the Month

As mentioned above, we need to get the start day of the month, which is rather simple and straightforward.

function getStartDayOfMonth(date: Date) {
  return new Date(date.getFullYear(), date.getMonth(), 1).getDay();
}

Check If It's in a Leap Year

We also needs to check if we are currently in a leap year, so that we can show correct number of days in February.

I extracted a picture from Wikipedia for better illustration of determination of a leap year.

It's quite clear that, if a year is a leap year, the year is divisible by 4 and by 400 but not by 100.

For example,

2020 is a leap year because it is divisible by 4
2010 is not a leap year because it is not divisible by 4
2000 is a leap year because it is divisible by 400
1900 is not a leap year. Although 1900 is divisible by 4 but it is also divisible by 100

(It's better to write a unit test for it!!)

function isLeapYear(year: number) {
  return (year % 4 === 0 && year % 100 !== 0) || (year % 400 === 0);
}

Build the Calendar with TSX!

Finally, we can complete the component by adding the render part.

The 2 buttons in the headers trigger setDate() when being clicked. And it will then trigger useEffect() callback and then update day, month, year and startDay, where month and day are displayed in the title of the header, day is used to determine if the day is the current selected day and start day to compute how many empty blocks it should have before the 1st day of the month.

const days = isLeapYear(date.getFullYear()) ? DAYS_LEAP : DAYS;

return (
  <Frame>
    <Header>
      <Button onClick={() => setDate(new Date(year, month - 1, day))}>Prev</Button>
      <div>
        {MONTHS[month]} {year}
      </div>
      <Button onClick={() => setDate(new Date(year, month + 1, day))}>Next</Button>
    </Header>
    <Body>
      {DAYS_OF_THE_WEEK.map(d => (
        <Day key={d}>
          <strong>{d}</strong>
        </Day>
      ))}
      {Array(days[month] + (startDay - 1))
        .fill(null)
        .map((_, index) => {
          const d = index - (startDay - 2);
          return (
            <Day
              key={index}
              isToday={d === today.getDate()}
              isSelected={d === day}
              onClick={() => setDate(new Date(year, month, d))}
            >
              {d > 0 ? d : ''}
            </Day>
          );
        })}
    </Body>
  </Frame>
);

Conclusion

Today I shared how to create a simple react calender with styled component. It's not as difficult as imagined because the only critical part, I think, is to know you need to determine what is the day of the week for the first day of the week. If you can do that, you can determine all the positions of the days. The rest works are just grooming your components to make it more appealing.

Thank you for reading!!

Featured image is credited to Bich Tran from Pexels

Compare for Loop and forEach Function in JavaScript

Zhiyue Yi — Sat, 04 Jan 2020 04:42:25 +0000

Visit my Blog for the original post: Compare for Loop and forEach Function in JavaScript

Introduction

I found an interesting discussion in a pull request for rxjs project.

The PR author would like to refactor this part of code

if (_infiniteTimeWindow) {
  for (let i = 0; i < len && !subscriber.closed; i++) {
    subscriber.next(<T>_events[i]);
  }
} else {
  for (let i = 0; i < len && !subscriber.closed; i++) {
    subscriber.next((<ReplayEvent<T>>_events[i]).value);
  }
}

into the following format

if (this._infiniteTimeWindow) {
  _events.forEach(event => {
    if (!subscriber.closed) {
      subscriber.next(<T>event);
    }
  });
} else {
  _events.forEach(event => {
    if (!subscriber.closed) {
      subscriber.next((<ReplayEvent<T>>event).value);
    }
  });
}

So basically, the author would like to refactor the for loop by using forEach() in array utility functions.

As we know, JavaScript / TypeScript has a set of powerful array utility functions including forEach(), map(), reduce() and so on. Those utility functions greatly improve our productivity in array operations by using functional programming paradigm and they are clearer to read and easier to understand.

I believe the above refactored codes also intend to achieve a better readability and maintainability, but the member of rxjs library rejects the changes and claim that it is

removing optimizations that we had done on purpose

Is that really true? To prove that using a for loop is more efficient than forEach(), I did the following experiment.

Experiment: Comparison with Simple Value Addition and Assignment

The following codes are for comparison between for loop and forEach() using an array of 20 consisting of millions items simple value addition and assignment where the execution times are printed.

const list = Array(20000000).fill(0);
const list1 = [];
const list2 = [];

// 20 millions records with a for loop
console.time("for loop");
for (let i = 0; i < list.length; i++) {
  list1[i] = i + 1;
}
console.timeEnd("for loop");

// 20 millions records with forEach()
console.time("forEach()");
list.forEach((_, i) => {
  list2[i] = i + 1;
});
console.timeEnd("forEach()");

// Sanity check if the list1 and list2 are with the same calculation results
console.log(
  list1.every((item, index) => item === list2[index]) &&
    list1.length === list2.length
);

I run the codes for 5 times and get the following results.

	for	forEach()
1	408.801ms	629.787ms
2	410.799ms	629.338ms
3	409.691ms	631.505ms
4	390.361ms	612.205ms
5	390.503ms	618.609ms

So the result is very clear that for loop performs better than forEach(). Although there are 20 million records, the operations are simple, only value addition and assignment. What if the operations are complexer such as demonstrated in rxjs, every subscriber is notified and certain following actions are triggered? It will become a big difference. So, when you are working on a library, it's critical to think about the performance, even if for loop looks "more ugly" than forEach()

Besides the performance, what are the other differences?

Break Loops

If you want to exit the loop based on certain conditions, can forEach() do that? The answer is yes, but it's more troublesome and less straight forward compared to for.

In for loop, it's easy to break the loop by

const list = [1, 2, 3, 4, 5];

for (let i = 0; i < list.length; i++) {
  if (list[i] > 3) {
    break;
  }
  console.log(list[i]);
}

// Only 1, 2, 3 are printed.

However, in forEach(), you cannot directly use break as SyntaxError: Illegal break statement is thrown. It's because break keyword can only be used in a for loop, while a forEach() accepts a function as a parameter and break keyword is NOT allowed in a function.

const list = [1, 2, 3, 4, 5];

list.forEach(item => {
  if (item > 3) {
    break;
  }
  console.log(item);
});
// SyntaxError: Illegal break statement

You can still use a hack way to achieve the break of loop, by using a try-catch block (inspired by HERE).

const list = [1, 2, 3, 4, 5];

try {
  list.forEach(item => {
    if (item > 3) {
      throw Error();
    }
    console.log(item);
  });
} catch (e) {}

// Only 1, 2, 3 are printed

Or another hack way is using some(), because once the condition in the callback function is fulfilled, it will stop checking the rest of the items

const list = [1, 2, 3, 4, 5];

list.some(item => {
  console.log(item);
  return item > 2; // 3 is changed to 2 because the condition checking happens after the console.log()
});
// Only 1, 2, 3 are printed

However, neither of the ways looks pretty as they are not straight forward nor intuitive.

try-catch block is meant for catching errors, but there is actually no error at all.
some() is conceptually not meant for breaking a loop, but it just happens to have the same functionality of break.

Therefore, it takes extra time for developers to figure out the outcome of these pieces of codes, which is also likely to cause careless mistakes and confusions.

Conclusion

In this article, we have discussed the differences of for loop and forEach().

To summarize, I would recommend to use for loop when

You have to break in the loop
You have a strict requirement on performance

If you don't have the above 2 conditions, it's actually better to use forEach() because it looks clear and concise and is better to comprehend.

Create a Simple Breadcrumb in Angular

Zhiyue Yi — Mon, 30 Dec 2019 08:27:12 +0000

NOTE: This article has been archived since it was written in 2018. Now this solution may not work with the latest Angular version. You may continue reading if you would like to see the idea behind it, but may not want to follow the implementation as it is already outdated. Thanks!

Visit my Blog for the original post: Create a Simple Breadcrumb in Angular

Recently, I am building an enterprise resource planning (ERP) platform for my company. The system is required to be flexible to hold different individual modules. In this platform, user navigation should be clear and concise so that the users would conveniently know what location they are at while performing tasks on the platforms.

For example, a hierarchy like Dashboard -> IT HelpDesk -> Issue Log -> New can be provided as a reference of locations. And most importantly, users can navigate back to different level of pages conveniently. So I built a breadcrumb component to cater that need.

Demo for static link:

Demo for dynamic link (123 is a dynamic ID):

Configure the Routes

Af first, you need to configure your route correctly.

Take Dashboard -> IT HelpDesk -> Issue Log -> New as an example. Below code snippet shows a basic route structure.



{
    path: '',
    component: LoginComponent,
}, {
    path: 'dashboard',
    component: DashboardComponent,
    children: [
        {
            path: 'it-helpdesk',
            component: ItHelpdeskComponent,
            children: [
                {
                    path: 'issue-log',
                    children: [
                        {
                            path: '',
                            component: IssueLogListComponent
                        },
                        {
                            path: 'new',
                            component: IssueLogDetailComponent
                        },
                        {
                            path: ':id',
                            component: IssueLogDetailComponent
                        }
                    ]
                }
            ]
        }
    ]
}

In order to use breadcrumb, we need to get their names from this route configuration, as in issue-log route is represented as Issue Log in the breadcrumb. Then we use data attribute in Route to store its display names. Hence, we modify the route configuration as below.



{
    path: '',
    component: LoginComponent,
}, {
    path: 'dashboard',
    component: DashboardComponent,
    data: {
        breadcrumb: 'Dashboard',
    },
    children: [
        {
            path: 'it-helpdesk',
            component: ItHelpdeskComponent,
            data: {
                breadcrumb: 'IT Helpdesk'
            },
            children: [
                {
                    path: 'issue-log',
                    data: {
                        breadcrumb: 'Issue Log'
                    },
                    children: [
                        {
                            path: '',
                            component: IssueLogListComponent
                        },
                        {
                            path: 'new',
                            component: IssueLogDetailComponent,
                            data: {
                                breadcrumb: 'New'
                            }
                        },
                        {
                            path: ':id',
                            component: IssueLogDetailComponent,
                            data: {
                                breadcrumb: ''
                            }
                        }
                    ]
                },
            ]
        }
    ]
}

Notice that the route issue-log/:id has no breadcrumb data yet. That is because this route contains dynamic parameters. We will automate the display text later when building the breadcrumb.

Breadcrumb Component

HTML

The HTML part is rather simple. Just use ol and li to list out all the breadcrumbs with *ngFor

breadcrumb.component.html



<ol class="breadcrumb">
  <li *ngFor="let breadcrumb of breadcrumbs">
    <span [routerLink]="breadcrumb.url" routerLinkActive="router-link-active">
      {{ breadcrumb.label }}
    </span>
  </li>
</ol>

SCSS

The CSS is not complicated either. Take note that when a breadcrumb is hovered, it should be dimmed.

breadcrumb.component.scss



.breadcrumb {
  background: none;
  font-size: 0.8em;
  margin: 0;
  a,
  span {
    color: darkgrey;
  }
  a:hover,
  span:hover {
    color: dimgrey;
    text-decoration: none;
  }
  li {
    list-style: none;
    float: left;
    margin: 5px;
  }
  li:last-child {
    margin-right: 20px;
  }
  li::after {
    content: "->";
    color: darkgrey;
  }
  li:last-child::after {
    content: "";
  }
}

TypeScript

The most important part is the TypeScript part.

Interface

The first thing to do is to create an interface to standardize the data structure of a breadcrumb.

breadcrumb.interface.ts



export interface IBreadCrumb {
  label: string;
  url: string;
}

Component

Then we can start to build our breadcrumb component. The basic code structures are as below.



import { Component, OnInit } from '@angular/core';
import { ActivatedRoute, Router, NavigationEnd } from '@angular/router';
import { IBreadCrumb } from '../../../interfaces/breadcrumb.interface';
import { filter, distinctUntilChanged } from 'rxjs/operators';

@Component({
  selector: 'app-breadcrumb',
  templateUrl: './breadcrumb.component.html',
  styleUrls: ['./breadcrumb.component.scss']
})
export class BreadcrumbComponent implements OnInit {
  public breadcrumbs: IBreadCrumb[]

  constructor(
    private router: Router,
    private activatedRoute: ActivatedRoute,
  ) {
    this.breadcrumbs = this.buildBreadCrumb(this.activatedRoute.root);
  }

  ngOnInit() {
    // ... implementation of ngOnInit
  }

  /**
   * Recursively build breadcrumb according to activated route.
   * @param route
   * @param url
   * @param breadcrumbs
   */
  buildBreadCrumb(route: ActivatedRoute, url: string = '', breadcrumbs: IBreadCrumb[] = []): IBreadCrumb[] {
    // ... implementation of buildBreadCrumb
  }
}

As you can see, we have 2 functions need to be implemented.

ngOnInit() is the function triggered right when the component is created. In this function, we will get the current route and start to build breadcrumb from its root.

buildBreadCrumb() is the function we actually build a breadcrumb. It's a recursive function to recursively loop the child of route object from the root to leaf, such as Dashboard all the way to Issue Log.

buildBreadCrumb()

Label and Path First, let's get the label and path of a single breadcrumb. Note that routeConfig could be null if the current route is on the root. Therefore, it must be checked before assign route.routeConfig.data.breadcrumb and route.routeConfig.path to variables, otherwise, exceptions will be thrown.



let label =
  route.routeConfig && route.routeConfig.data
    ? route.routeConfig.data.breadcrumb
    : "";
let path =
  route.routeConfig && route.routeConfig.data ? route.routeConfig.path : "";

Handling Dynamic Parameters Second, we need to handle dynamic route such as :id. Take a look at this route.



{
    path: 'issue-log/:id',
    component: IssueLogDetailComponent
    data: {
        breadcrumb: ''
    }
}

The breadcrumb is previously left blank because the route is dynamic. I can only know the ID at runtime.

The activated route contains the actual ID. Hence, we shall dynamically attach the actual ID to the breadcrumb by taking the last route part and checking if it starts with :. If so, it is a dynamic route, then we get the actual ID from route.snapshot.params with its parameter name paramName.



const lastRoutePart = path.split("/").pop();
const isDynamicRoute = lastRoutePart.startsWith(":");
if (isDynamicRoute && !!route.snapshot) {
  const paramName = lastRoutePart.split(":")[1];
  path = path.replace(lastRoutePart, route.snapshot.params[paramName]);
  label = route.snapshot.params[paramName];
}

Generate Next URL

In every recursive loop of route, the path is fragment and a complete path is not available, such as issue-log instead of dashboard/it-helpdesk/issue-log. Therefore, a complete path needs to be re-build and attach to the breadcrumb in the current level.



const nextUrl = path ? `${url}/${path}` : url;

const breadcrumb: IBreadCrumb = {
  label: label,
  url: nextUrl
};

Add Route with Non-empty Label and Recursive Calls

In your application, there may be some routes which does not have breadcrumb set and these routes should be ignored by the builder.

Next, if the current route has children, that means that this route is not the leaf route yet and we need to continue to make a recursive call the build next-level route.



const newBreadcrumbs = breadcrumb.label
  ? [...breadcrumbs, breadcrumb]
  : [...breadcrumbs];
if (route.firstChild) {
  //If we are not on our current path yet,
  //there will be more children to look after, to build our breadcumb
  return this.buildBreadCrumb(route.firstChild, nextUrl, newBreadcrumbs);
}
return newBreadcrumbs;

Full Picture of buildBreadCrumb()



/**
 * Recursively build breadcrumb according to activated route.
 * @param route
 * @param url
 * @param breadcrumbs
 */
buildBreadCrumb(route: ActivatedRoute, url: string = '', breadcrumbs: IBreadCrumb[] = []): IBreadCrumb[] {
    //If no routeConfig is avalailable we are on the root path
    let label = route.routeConfig && route.routeConfig.data ? route.routeConfig.data.breadcrumb : '';
    let path = route.routeConfig && route.routeConfig.data ? route.routeConfig.path : '';

    // If the route is dynamic route such as ':id', remove it
    const lastRoutePart = path.split('/').pop();
    const isDynamicRoute = lastRoutePart.startsWith(':');
    if(isDynamicRoute && !!route.snapshot) {
      const paramName = lastRoutePart.split(':')[1];
      path = path.replace(lastRoutePart, route.snapshot.params[paramName]);
      label = route.snapshot.params[paramName];
    }

    //In the routeConfig the complete path is not available,
    //so we rebuild it each time
    const nextUrl = path ? `${url}/${path}` : url;

    const breadcrumb: IBreadCrumb = {
        label: label,
        url: nextUrl,
    };
    // Only adding route with non-empty label
    const newBreadcrumbs = breadcrumb.label ? [ ...breadcrumbs, breadcrumb ] : [ ...breadcrumbs];
    if (route.firstChild) {
        //If we are not on our current path yet,
        //there will be more children to look after, to build our breadcumb
        return this.buildBreadCrumb(route.firstChild, nextUrl, newBreadcrumbs);
    }
    return newBreadcrumbs;
}

ngOnInit()

Finally, we need to implement ngOnInit() to trigger to start building the breadcrumbs.

Breadcrumb build should start when a router change event is detected. To detect it, we use RxJs to observe the changes.



ngOnInit() {
    this.router.events.pipe(
        filter((event: Event) => event instanceof NavigationEnd),
        distinctUntilChanged(),
    ).subscribe(() => {
        this.breadcrumbs = this.buildBreadCrumb(this.activatedRoute.root);
    })
}

The above code snippet indicates that the router events are observed with a filter on the event type to be NavigationEnd and a distinct change.

That means if the route is changing and the new value is different from the previous value, then the breadcrumb will start to build. The results of recursive function will be stored in this.breadcrumb, which will be an array as below.



[

  {

    label: "Dashboard",

    url: "/dashboard"

  },

  {

    label: "IT Helpdesk",

    url: "/dashboard/it-helpdesk"

  },

  {

    label: "Issue Log",

    url: "/dashboard/it-helpdesk/issue-log"

  },

  {

    label: "plfOR05NXxQ1",

    url: "/dashboard/it-helpdesk/issue-log/plfOR05NXxQ1"

  }

];

Conclusion

Breadcrumbs implement a rather simple algorithm, but I think what makes it confusing is its configurations. As developers, you need to know where the configurations should be done and the features Angular provide. With good understanding of Angular, you can implement some components easily as most of the tools you need have been provided by Angular.

You may refer to the full code here: GitHub

Thanks for reading~