DEV Community: Davor Tvorić

Decoupling Deployment From Release With Feature Toggles

Davor Tvorić — Wed, 06 Dec 2023 09:47:41 +0000

Deploying new features is a nerve-racking task, but it must be done.

Here’s an issue we’ve all faced or will inevitably face in our careers. Allow me to set the scene…

You’ve finished your work on some features, fixed some bugs, etc. You’re feeling good because some features were a bit more complicated. You decide it’s high time to let your users experience these changes. You bundle up all your teams’ changes and deploy them to the production server. A couple of hours later, disaster strikes! There’s a critical bug on a feature you’ve worked on. Now, you have to revert to the old version of the application or deploy a new one, but without your changes.

As these situations can have a huge impact, reacting quickly is key. Unfortunately, developers usually learn how to handle this situation once it happens, so it only prolongs the agony.

Deploying and releasing at the same time isn’t such an uncommon practice because, at the beginning of a project, you want your users to see the changes immediately. Many projects continue using this process, but as the project grows, it makes sense to decouple the deployment of the code and the release process (activating changes to users).

Even if this hasn’t happened to you yet, we can all agree that it’s a very stressful situation, and establishing a process for handling this is something you want to do ahead of time.

But how much ahead of time are we talking about here?

Feature toggles (aka feature flags)

There are many ways to handle these types of outages, and it’s important to establish a rollback procedure. In addition to that, we also use something called feature toggles. It’s not something unique to us, but it’s a pretty sweet thing to have in your toolbox. For those unfamiliar with feature toggles, it’s a mechanism that allows you to turn a feature on or off for a user without needing to deploy the whole application. It’s really simple, but it’s huge!

Although it’s called a “feature toggle”, it doesn’t necessarily mean that you have to use them for features only. You can use them basically for anything. Whether it’s A/B testing, refactoring a part of the screen, or navigating a user to a different page entirely! I’m sure you can think of a couple of more examples that would be useful to you.

This also allows us to oversee which users can access a certain change. This is helpful when trying to collect feedback or just observing how users interact with something you’ve developed. Once you’ve established your feature toggle system, you don’t need to put in continuous work to keep it going. It’s also a great way to manage the lifecycle of the change by progressively rolling it out to your canary, beta, and all users!

You gain a lot more control over who sees what, and the best part is that turning toggles on or off can be done by anyone! Someone like a product manager or customer support person could decide to turn a toggle on because it’s just something that the customer needs. After a feature has been fully developed, the toggle can be globally released to all customers, and everyone can enjoy the stable version.

The number of annoyed users will decrease, and valuable feedback on changes will increase.

It’s also worth mentioning that you can base your whole QA process on the toggles. We can test a change by turning a toggle on, gathering feedback, and then turning the toggle off. When you have such fine-grained control, testing on production isn’t a big deal! We also use these toggles in other environments, so you can isolate a change to a specific set of users on any server.

It’s a win-win for everyone!

Okay, but what about development?

The main question that’s probably going around in your head is how the feature toggles affect the development of a feature.

Feature toggles do complicate things a bit when writing code, but if you spend some time on planning, it can be done elegantly in most cases. You must be careful to add every change behind the toggle so nothing leaks when the toggle isn’t turned on. Other people working on the feature must also be aware of using the toggle since it probably will span through multiple files and can sometimes be forgotten.

Sometimes, it’s not that complicated, but you gain a lot. As I’ve already mentioned, it can be used for basically anything, and complexity may increase, but it really is worth it:

The added complexity isn’t such a big drawback. You’re getting a lot more out of feature toggles, and if that means that developers have to be a bit more careful when writing and reviewing code, so be it. It’s much less stressful for a developer when they know a feature can be turned off if it’s causing problems. This doesn’t mean we approve of sloppy code, but sometimes, these things happen.

To conclude, feature toggles (once established) don’t affect the development process as much, but they offer a lot in return.

Alleviating the downsides

The first one does introduce technical debt, but if we create a task for deleting a toggle after it’s been globally released, we can be sure that it will be deleted as soon as possible. The person who created the toggle is responsible for deleting it, which is a great way to handle this efficiently. In any case, deleting a toggle usually takes significantly less time than developing it!

As for the other issue, there are two ways to handle this. We can do either of these two:

Release the first toggle globally and delete its references in the code if the feature is ready to be released or
Merge the toggles and consider them to be the same feature from now on

It’s not an ideal situation, but it can happen. The solution mostly depends on the state of the features, so it’s impossible to determine the best way without knowing all the facts. Either way, both solutions can simplify things for development.

Decisions, decisions

For us, implementing feature toggles was a no-brainer. Considering all of the benefits like the control, progressive rollouts, and others, it seriously outweighs the downsides it introduces. Even the downsides can be managed to an extent.

It’s important that everyone in the company understands the whole process and embraces why we’re doing it in such a way. It’s an essential part of a company like ours since every department is involved in the release process of product updates. Once people are aware of this, building an admin system to control this is up to you and your company’s needs.

Here’s an example of our own. We call it the “Backoffice”:

THERE ARE ~200 ACTIVE FEATURE TOGGLES IN OUR CODEBASE

As a developer, I’m grateful we can release features quickly and stress-free, knowing we have some wiggle room.

As for you, I hope I’ve shown you why it’s a good idea to think about something like this if you don’t use a similar mechanism. If you need a bit more convincing, you can read more about it in an article by Martin Fowler! Even if you’re not in a position to make your feature toggle system, there are a lot of external tools and libraries that might help you implement the same!

Check yo' project structure before you wreck yo' project structure

Davor Tvorić — Mon, 04 Apr 2022 09:48:50 +0000

I gotta admit, when it came to structuring a frontend project, I didn't really know why people considered it that important. I've mostly been working on smaller projects either alone or with 2-3 people. The projects' structure didn't matter all that much because they were abandoned as soon as we were finished with the project. With this kind of experience you might get lulled into the feeling that the default setup is all that you need.
I realized there's a lot more than meets the eye when I started working on an existing project that was a couple of years old. Just imagine being plopped in a foreign structure where you have to think about every little detail and question yourself constantly!
I started thinking a lot more about where I'd place a function, partial or a simple object. By just spending some time thinking about what would be the most logical solution, I've (hopefully) improved mine and everyone else's developer experience.

The catch is that I still have a lot to learn. I'm sure there's some things I haven't even considered because they're manageable at the time. But I don't see that as a bad thing, since that's something that could probably be improved. That's why I think it's important that you review how you structure your projects once in a while.

In this article, I'll explain why we've had the idea for a standard project structure within our team. My experience is related to frontend, but you might find something interesting even if you work in something else! But if you're in need of an actual structure, I'll be showing that in some other post.

How can you condense complex project structures into a single template?

Our projects' structure can vary a lot depending on the length of the project, the complexity, the features, and a number of other factors. However, I think we can make a generic structure which would work great in most cases. Now you're probably thinking, what about existing projects? It might be really complex (and inefficient) to change the whole structure in an existing project, but who says that you have to change absolutely everything? If you're going to work on a project for some time, why not make it easier for yourself if it's possible? After all, you've probably gathered a lot of knowledge throughout the years and could surely improve on the parts you designed at the beginning of the project.

Tackling this problem might not even be as complicated as you might think. Just writing down and explaining each folder/file will give you insight about your current situation.
From there you can easily see whether the decisions you made make sense! When I did this, it really felt like a game of Sudoku. When it seems like there's nothing else that can be done, you stumble upon a couple of smaller things here and there and, suddenly, a huge playing field opens up. That's my method for handling larger and older projects that are in time for a tune up.

Many projects, even more factors, but not enough resources

I work in an agency, but we work on projects of varying lengths. Some are done in a month's time and some are worked on for years. We're not limited to one technology, so that's also another factor. That's just a couple of things, but our structures can be wildly different. This means that each time you switch projects you have to get used to a different structure, as well. By not having a defined standard within the team, it meant that new projects would succumb to the same fate. That's more cognitive load that you don't want to have.
To counter that, we've researched which structure would fit us the best. Most of our focus was on scalability, readability, and extendibility. That's a lot of -bilitys, but in simpler terms we wanted to make sure that the project structure we made is easy to understand, use and improve. Sounds really simple, but to find something concrete on the Internet proved to be somewhat of a tough task. We were defining this structure for our frontend projects where the technologies are relatively young. Therefore, there's a lot of resources that show their ideas on really small examples with little experience in larger projects. It also doesn't help that only some use actual architectural patterns that are commonly used in software development.
We did manage to find some resources that really helped us out:

Contemporary Front-end Architectures by Harshal Patil
Infinum Frontend Handbook
How to structure frontend application by Michal Zalecki
Folders-by-feature structure
Container component

There's a lot to learn from each resource, but we didn't use every single thing from them. Each part was discussed and made sure that it really worked for us. It helped that we could decide as a team because each of us had some experience in something the others didn't, so it's important not to dismiss anyone's opinion.
After defining a structure, there's two last steps that were incredibly important and made everything click:

Explain each segment so that someone with less experience can understand it with relative ease
Just by using your explanation from the last step, create a smaller app to test out your structure

These steps were vital to adding most of the finishing touches. If we hadn't done them, we would have shot our own leg when we started a new project. It makes sense testing out what you did, but it is tempting to skip this part since you've already done the majority of the work. It will also help you to objectively look at the work you've done. Don't forget that everything can be improved!

Final words

Following this plan we came up with a concise CRA template (and Vue template) with a detailed README. Now we're able to preserve the same project structure throughout multiple projects and relieve ourselves of the cognitive load when switching to other projects.
This does not mean that our work is over, but it should be less of a hassle to have a great foundation and improve everything from here.

And if that doesn't sound great, I don't know what does!

How to work as a solo frontend developer

Davor Tvorić — Mon, 08 Nov 2021 07:45:25 +0000

Working in a team is great. You can progress really fast and learn a lot from your colleagues. Having another set of eyes to proof check your work is a godsend because it can prevent silly things being deployed to production.
But, sometimes, life happens and you have to work alone on a project. Be it a specific technology, budget reasons or something entirely else, it doesn't really matter. Working alone doesn't mean it'll suck or be really stressful if you keep yourself in check.

I worked on a couple of projects as a solo frontend developer, but I rarely had the feeling like I couldn't do it or that I maybe didn't learn as much as I could have. If you "act" like there is a whole team involved (or that someone new will be joining you on the project), that can force you not to take shortcuts and do everything properly.

Don't be lazy

Avoid shortcuts

It's really easy to skip a couple of steps when working alone because, honestly, is anyone going to notice? The answer should be yes, you'll notice it!
Opening a pull request that will be merged to master immediately might seem illogical, but having everything consistent will surely help you out in the long run. On top of that, you might notice something wrong when you're doing a once-over.

Keep your code neat

Keeping your code neat is something you also shouldn’t skimp out on. Linters, prettiers and everything else should be setup as if you were in a team!

Be your own QA

Writing tests is a no-brainer. It's always a great relief knowing that stuff works even after a refactor. Not having to constantly think about that will allow you to focus on more important things! That shouldn't change even if you're working alone.

Documentation!

It might be boring, but if you don't do it, nobody will. At a first glance, it doesn't seem important since you're the only one that will be reading it. I can tell you that I know for a fact that the future you will thank you for it. It's unrealistic to expect you'll remember every little detail, even though you've written everything yourself. Having a good documentation means that some of the mental burden can be relieved because you can refer to it at any time.
Heck, something might even change within the project and your new teammate will be even faster with the onboarding.

Ask for help

Collaborate with other frontend developers

I have the benefit that there are other brilliant teammates on other projects. They might not know the domain of my project, but they can offer technical help if you explain it to them. Try to make it easy for them to understand it, and I’m sure that you’ll get new insights. The same goes for asking for help online. Just because you're alone on the project doesn't mean that you have to do everything by yourself.
If you have work colleagues, it's not a bad idea to assign them on a pull request once in a while. You might be surprised how tunnel-visioned you can get!

Learn about the domain from backend

If there's a backend, I'm sure you can discuss domain issues with them, as well. They probably know a lot and it's a good idea to double-check with them. You might learn about something you weren't aware of!

Improve wherever you can

Now that you're alone on the project, you can do anything to improve your development experience. If there is a task that needs to be automated, why wouldn't you automate it? If you can get the budget for it, you'll save time and you'll learn something new. This is a great opportunity to make up for not learning from your teammates. Something that a senior colleague always set up can now be done by you. It might seem daunting if it's out of your comfort zone, but hey, how else are you going to learn?
From personal experience, these situations taught me some skills I would rarely have the time to research in other projects.

By sticking to these tips, I've been able to maximise my learning and do quality work as much as I could. Not having a teammate doesn't mean that you really have to be isolated from everything else. And, who knows, you might even get someone working on a project by your side so you want to be proud of what you're capable of doing all on your own, right?

Try to avoid comments (most of the time)

Davor Tvorić — Mon, 31 May 2021 13:36:50 +0000

Writing down a comment when you're coding might seem like you're going to help yourself or someone that might stumble upon your code, but, in reality, it might cause confusion and make your code less readable. If you're just starting out with coding, you sometimes feel that you need to comment every line to get your point across. That's probably not the case most of the time and you're probably just adding unnecessary noise to your code.

Code explanation

If possible, try to use the time you would spend on writing a comment on coming up with better naming or clearer code structures. Take a look at this

// check if employee can receive overtime pay
if (employee.isFullTime && employee.workHours > 160)

Instead of relying on the comment to explain the condition, it would be much wiser to create a function with a clear name that does this check

const isEmployeeEligibleForOvertimePay = (employee) => {
    return employee.isFullTime && employee.workHours > 160;
}

if (isEmployeeEligibleForOvertimePay(employee))

It's now possible to reuse this small piece of code, as well as not have any doubts what this condition does. This might be a much larger condition, but a name might be sufficient enough to be aware what it's doing.

Of course, there is a case where it's very difficult to come up with a meaningful name or it's just not possible. In that case a comment would be helpful, but you should have that as a last resort.

Outdated comments

function insertData(data) {
    store.user.insert(data); // updates the current user data
}

If you've been working on some older projects, something like this might've popped up. You can see that some data is being inserted, but the comment says otherwise. The comment might be right, although someone could have forgotten to delete it. This causes you to doubt the code and you're forced to check what's really going on in the insert method.

To prevent this, it's probably better to rename the functions to better represent their functionality and delete the unnecessary comment.
This is something that might happen with any comment. If someone forgets to update the comment after a couple of changes, another person can't be sure what's right or not. It's not a critical mistake and nothing will break because of this, but you might spend a couple of minutes/hours until you find out the truth.

Redundant comments

// checks whether the student lives in a dorm
if (student.livesInDorm)

I think we can all agree that these kinds of comments are totally unnecessary. You might feel better that you've written a couple lines of comments, but this doesn't help anyone when it's obvious what's happening

Separators

// ---------------
// VARIABLES
// ---------------
$blue: #1257ab;

This could be debated, but I think that the file structure should mandate where something belongs. By having these kinds of comments, you're just breaking up the flow of the code and not adding much value. If this is something that occurs a lot, having a defined standard with vertical formatting might have a much more appealing look.

Some people are more of a visual type, so separators can come in handy to visualize the various parts of a file, but I would still stay away from them.

Commented code

Nowadays, there's probably very little reason to keep commented out code in your codebase, especially if you're using a version control system. Anyone that will come upon the commented code won't be bothered to delete it because they haven't written in in the first place.
That will just perpetuate the old code into newer versions until it won't even work if you comment it out.

Do yourself a favour and delete the commented code. If you'll really need it, you can get it from your VCS' history.

Conclusion

Having comments in your codebase is something that requires constant attention. When you update a function, you must make sure you've updated its comment as well. That's why most of the comments you write go stale and just confuse you next time you bump into them.
By spending more time on naming your variables and functions, extracting a piece of code and adding vertical or horizontal formatting, you might even avoid the need for comments.

Even though I've shown the types of comments you should avoid, there are cases where it's a good idea to leave a comment (but not that many!).

leaving a warning on a complicated feature that can't be managed with proper names is always a good idea
documentation/legal comments in public code

Why you shouldn't mix levels of abstraction in your functions

Davor Tvorić — Mon, 11 Jan 2021 16:30:28 +0000

For some time now, I was convinced I could be writing more readable code. Because of a high paced tempo that is working in an agency, I had an excuse not to invest more time in readability. Or so I thought.

You can come up with all sorts of excuses to assure yourself that your code is good enough and that someone else will understand it perfectly in a couple of months. That won't help you out when you actually get stuck in a trap you set up yourself. Okay, this sounds really dramatic, but I hope you get the point!
By writing clean code, you'll be helping someone continue writing code after you, but you'll help yourself as well. The main problem for me is that I can recognize good code, but when I start coding, all of that falls apart because I'm not sure what really makes code good.

One of the concepts I've picked up is the level of abstraction (in your functions). Take a look at this piece of code:

function createUser(username, password) {
    if (username.trim().length <= 2) {
        console.error('Username too short.');
        return;
    }

    if (password.length <= 6 || password.length > 30) {
        console.error('Password must be longer than 6 characters and shorter than 30');
        return;
    }

    const user = {
        username,
        password
    };
    database.insert(user);
}

It's nothing too complex, right? You can pretty easily determine what this function is doing and what validations it's checking. But we can make it even easier to read for other developers.
This is an example of mixing levels of abstraction which we should remedy, if possible. The thing why this might seem a bit off is because we're having some low-level checks (length of username and password) and some high-level functions which handle inserting some data in a database. To make this function more readable, we should try to even out the levels of abstraction.

function createUser(username, password) {
    try {
        validateUserData(username, password)
    } catch(error) {
        showErrorMessage(error);
        return;
    }

    const user = {
        username,
        password
    };
    database.insert(user);
}

function validateUserData(username, password) {
    if (!isUsernameValid(username)) {
        throw new Error('Username too short');
    }

    if (!isPasswordValid(password)) {
        throw new Error('Password must be longer than 6 characters and shorter than 30');
    }
}

function isUsernameValid(username) {
    return username.trim().length > 2;
}

function isPasswordValid(password) {
    return password.length > 6 && password.length <= 30;
}

function showErrorMessage(message) {
    console.error(message);
}

Even though this is a bit more code, I think it's pretty obvious what the function is doing just by reading the function names. You don't have to delve deeper in the code and increase your cognitive load to understand what the function should be doing.
Splitting the function this way gave us the opportunity to write even better tests because we can easily focus on edge cases for any function.
You can imagine what this method could do on a more complex function!

I would argue that this would definitely be worth the time you spent splitting this function up. You will be quicker to find bugs and won't have to spend an absurd amount of time re-familiarizing yourself with the code you wrote half a year ago!

My journey to mastering React

Davor Tvorić — Mon, 14 Sep 2020 10:23:09 +0000

Let’s go back a couple of years, to a much different state in the world. When people didn’t have to stand so far apart and could freely attend social gatherings. When things in Javascript were… Kinda the same? We’re going back to the time I started learning React which, ultimately, ended abruptly. Fast forward a few years to today. I have once again started learning React, but this time I’m sticking to it. I’ll try to point out my mistakes and why it didn’t work out the first time.

To give a bit of context, I have been working with Vue for a while now and I am still quite pleased with it. I picked Vue after I made a project in Angular 2, which didn’t really stick. Since there is a bit of a “rivalry” between Vue and React, I was apt to defend Vue instead of learning and trying to improve a cumbersome process or pattern that might have appeared in Vue. I hope this article will help to motivate you if you’re in the same state of mind.

The incentive

The first time I had a go with React was in a state where I thought Vue was a gift to humanity. Anything that was done in it was as it should be and nothing needed any changes. But since React was so popular, I thought I’d give it a go and see why so many people are developing their apps with it.
I started out with this tutorial. Everything made sense, but I just didn’t like how everything clicked together. I remember thinking “why would you do this like that, in Vue you could do this...” which really isn’t the point. An interesting observation in software development is that there are always multiple ways to solve a problem. When you’re aware of that, instead of defending your solution, you can learn from someone else’s suggestion. And you can learn a lot.
That wasn’t the case that day, obviously. After a couple of days, my will to learn React dissolved and I was left with the confirmation of my doubts. Vue is just better.

Some time passed, I’ve learned a thing or two, read a couple of books and I’ve gotten a new job at Bornfight. I was assigned to the Vue team. We had, and still do, a Vue and a React team. After a few bigger projects, we realised that it would probably be beneficial to use a single frontend framework in our Javascript team, instead of two. Knowledge sharing would be much easier and we would have a more specialized team to handle new projects. My colleagues suggested that we should use React. I agreed to that, even though it meant that I had to learn React. It made much more sense than Vue since it was easier to hire new people and the library is still more popular as it was a couple of years ago.

To be honest, I was really excited about this opportunity. I have learned a lot throughout the time and I was confident that would assist me a bunch. Over the years I started to appreciate other approaches and realized that there was no rivalry between Vue and React, not really. React introduced hooks which Vue adopted in Vue 3, for instance. Both of these solutions have their pros and cons and you just have to weigh out your needs and pick your technology based on that. Armed with that knowledge and a healthy outlook on things, I started learning instead of judging. I also had a purpose and a necessity to learn React.

The process

The way I went on about learning React was pretty much the same. I did the same tutorial, but this time I learned both React and Vue. Possessing a bit more in-depth knowledge than I did the first time helped me out a lot. If I didn’t understand something, I could easily find the terminology and search for an explanation online. At the same time, I questioned some of my own methods and used the inspiration to improve my problem-solving skills.
After the tutorial, I wasn’t even thinking that this was nearly enough. I bought this course and continued developing. To solidify my React foundations, I also watched these two tutorials:

As you can see, I am more of a visual learner. I feel like I get more out of watching videos and coding aside. This doesn’t mean that I haven’t gone through the detailed documentation or read some amazing articles at React Resources. I was in awe when I first saw this site and what it offered. It offers a lot of resources in one place and I wholeheartedly recommend this, as well as all of the other resources I mentioned.

This was the moment I felt ready to delve in my own project. I was certain I would avoid most of the basic mistakes people make and I also had a great idea about what to make. And no, it wasn’t a to do app!

The problem

The way I see it, you won’t learn much if you’re prejudiced, don’t have any will to learn something new or you don’t have a goal to work towards. The first time I tried to learn React, I think I ticked all of those boxes. I was too proud to admit something I did wasn’t optimal, I really wasn’t willing to learn React and with those things combined, there really wasn’t a final goal I wanted to achieve. Nowadays, I don’t think there’s anything wrong with admitting that you could have done something better and genuinely improving where it’s necessary. I gave up too easily and I learned nothing useful.

Today, I still think I am far from a master, but I believe that I learned a lot about React and frontend development in general. I am still learning, reading articles and working on React projects. I’ll probably do this for a while and I hope I’ll love doing this as much as I love doing it now. There are countless ways to improve your code and yourself and this is just one of the ways. My future steps will include working on a personal project. It’s nothing complex, but I love reading books and this combines some of my favourite things into one.

The thing I also missed the first time was someone experienced with React to help me out. I could have asked someone for an explanation on any of the numerous platforms and someone would surely help, but I was too shy to do it. Now I get the much-needed help (and PR reviews) from my colleagues here at Bornfight. I realise how invaluable this is, so if you have any questions about React, feel free to email me at davor.tvoric@bornfight.com. I can’t offer that much help, but I can try to help you figure out a solution or review a piece of code you’ve written!

Summary

To sum everything up, I would say that you must be willing to get your hands dirty. You can learn something by reading an article or watching a video, but the real knowledge comes from learning from your mistakes. Reading about a solution and trying to implement it yourself have a vastly different experience between them. Even if it’s something simple, I’m certain that it’s worth doing, just for the sake of doing.
Having someone proof your ideas and nudging you in the right direction is of tremendous help.
If you’re in a similar spot like me, have a go at the resources I mentioned before and feel free to comment on my personal project. Any bit helps and if it benefits us both, why not?

Thanks for reading and stay tuned for the next post where I will make the same (simple) app in both Vue and React. I will compare the differences and show how each of them handles the same problems in their own way!

Component diagram for frontend apps

Davor Tvorić — Mon, 17 Aug 2020 09:54:40 +0000

Hey everyone!

I've had an idea about using component diagrams in my frontend project workflow. This idea works best with frameworks that rely on components (Vue, React, Angular, Svelte...). I messed with this on a personal project and I really like the benefits it provides, but I would like to hear your opinions or experiences that I might have missed.

Here's a brief example:
Before the start of a project, but after you have some sort of a broad idea of what the project will look like, you create a diagram that looks like this.

This example shows just two components, but the idea is that every component is noted here and that it shows the relationship and the props that get passed down from a parent component.

I have a feeling this would give you a much better idea of what your components will look like at the beginning of the project and keep everyone on the same page. I think it would even help to onboard new developers at a quicker rate.

This would have to be stored somewhere at a repository level so it's easy to access (for developers) and it would have to be maintained throughout the project. This is where it might fail. I imagined this as a guide, so something may be implemented differently during the development stage, but the diagram must be updated with the new information, to keep it up to date. Someone might forget or feel lazy and not update it which renders the diagram useless. I haven't thought of any way to prevent this, so I was hoping someone else might have a suggestion.

Have you ever done something similar? Is the diagram showing too much/little information? If you have any opinions, please share them down below!

Improve your Javascript code in PhpStorm

Davor Tvorić — Mon, 20 Apr 2020 09:53:39 +0000

Lately, I've been looking for a simple way to check the complexity of my Javascript code. In my opinion, it should prevent you from doing crazy stuff, while maintaining a level of readability.

I found out that there are many ways that you could do this, but I was searching for a solution that would be simple to implement. That way I would get the grips with what really makes a difference when checking your complexity. After that, I could proceed with testing different options and having something that could be implemented on a team level.

Some Google searches later, I found out about Code Inspections in PhpStorm (as well as WebStorm). It ticked all of my boxes because it was simple, didn't require any installation and had a ton of options.

Now, there are a whole lot of different checks (and levels of severity) you can set, so I won't be going through them all. You can check all of those over at JetBrains. Some of the rules might be even coverable with ESLint and/or Prettier, but I will list all of them here. It's worth noting that this isn't a final list since I have only started using this tool.

To enable Code Inspection rules, you can go to Preferences/Settings->Editor->Inspections->Javascript. You can also set it on a project or a global level.

Assignment issues
- Assignment used as condition
- Nested assignment
- Variable is assigned to itself
Potentially confusing code constructs
- Confusing sequence of '+' or '-'
- Magic number
- Nested conditional expression
- Overly complex arithmetic expression
- Overly complex boolean expression
- Statement with empty body
- Unnecessary 'block' statement
- Use of 'caller' property
Validity issues
- 'this' expression which references the global object
- Attempt to assign to const or readonly variable
- Expression statement which is not assignment or call
- Function with inconsistent returns
- Referencing 'arguments' outside of function
- Reserved word used as name
Async code and promises
- All of the options
Data flow
- Redundant local variable
Probable bugs
- Comparison with NaN
- Division by zero
- Infinite loop statement
- Infinite recursion
- Possibly incorrect target of indexed property access
- Potentially invalid constructor usage
- Potentially invalid reference to 'this' from closure
- Result of object allocation ignored
- Suspicious usage of 'bind' with arrow function
- Typeof comparing with non-standard value
Control flow issues
- 'if' statement with identical branches
- 'if' statement with too many branches
- Conditional expression with identical branches
- Constant conditional expression
- Duplicate condition in 'if' statement
- Object is 'null' or 'undefined'
- Redundant 'if' statement
- Redundant conditional expression
- Tail recursion
- All of the unecessary and unreachable rules
Try statement issues
- All of the options
Function metrics
- All of the options
General
- All of the options except non-strict mode used
ECMAScript 6 migration aids
- All of the options
Potentially undesirable code constructs
- 'with' statement
- Comma expression

And that's it! It's a long list, but I think it really helps out during development. Although most of the stuff is how you usually write code, it's good not to have the mental burden of having to think about it constantly.
Do you have any recommendations of rules or even other tools to use? I would love to see what other people are using!

What happens under the hood when you declare ref() in Vue 3?

Davor Tvorić — Mon, 23 Mar 2020 11:40:14 +0000

Over the last weekend, I've decided to take a look at Vue 3. VueMastery provided a free weekend for their courses, so it was a perfect chance to get started (although a bit too late from my side). I watched Vue 3 Reactivity and Vue 3 Essentials.

I was positively surprised, to say the least! The main reason for that is because I've never read or written such abstract code. I mostly took Vue (and other libraries) for granted, unless I specifically needed to understand something. I decided to change this for the composition API. To see how the fundamentals work was an eye-opener, I never realized such things were possible in Javascript.

Learning about tracking effects, triggering them, using object accessors, proxies and more taunted me to find out even more. That's why I made my mind up on writing this article. I'll try to explain most of the things that happen in Vue 3 (following the current source code) when you declare a ref(). I think it's done in a really clever way and an opportunity to improve your understanding of the language. I'll also urge you to check out the source code. Doing this, you can learn so much, but achieve a deeper understanding of the library you're using!

The implementation

We're going to take a look at the ref.ts file first. I have stripped some of the type declarations that aren't that useful to us at the moment.

const convert = <T extends unknown>(val: T): T =>
  isObject(val) ? reactive(val) : val

export function ref(value?: unknown) {
  return createRef(value)
}

export function shallowRef<T = any>(): Ref<T | undefined>
export function shallowRef(value?: unknown) {
  return createRef(value, true)
}

function createRef(value: unknown, shallow = false) {
  if (isRef(value)) {
    return value
  }
  if (!shallow) {
    value = convert(value)
  }
  const r = {
    _isRef: true,
    get value() {
      track(r, TrackOpTypes.GET, 'value')
      return value
    },
    set value(newVal) {
      value = shallow ? newVal : convert(newVal)
      trigger(
        r,
        TriggerOpTypes.SET,
        'value',
        __DEV__ ? { newValue: newVal } : void 0
      )
    }
  }
  return r
}

As you can see, when you call ref(), the createRef function gets called. Here we have some pretty standard stuff, checking if it already is a ref and converting an object to a reactive (this will always be false since the 'shallow' argument is not passed).

Now we have some pretty cool stuff! We declare an object called r with an '_isRef' property and some object accessors. By declaring a get and a set function for a single property, we can declare what happens when you're trying to get the value or update the value. By doing that, we can add our own logic, for instance, to add reactivity to our objects. As you can see, the return value is the object we created, which is why we have to call .value on a ref variable. In Vue 2, this is done with the Object.defineProperty().

Our getters and setters are looking very slim, but the whole magic happens in the track() and trigger() functions. We will see how it all fits together in the effect.ts file. Since there is a bit more to comprehend, I'll split the two functions into their own blocks.

export function track(target: object, type: TrackOpTypes, key: unknown) {
  if (!shouldTrack || activeEffect === undefined) {
    return
  }
  let depsMap = targetMap.get(target)
  if (depsMap === void 0) {
    targetMap.set(target, (depsMap = new Map()))
  }
  let dep = depsMap.get(key)
  if (dep === void 0) {
    depsMap.set(key, (dep = new Set()))
  }
  if (!dep.has(activeEffect)) {
    dep.add(activeEffect)
    activeEffect.deps.push(dep)
    if (__DEV__ && activeEffect.options.onTrack) {
      activeEffect.options.onTrack({
        effect: activeEffect,
        target,
        type,
        key
      })
    }
  }
}

This is what fascinated me, which might say that I have a really low threshold of what impresses me.
In the track() function, we pass in the target object, a tracking type and a key. From our targetMap, we get our depsMap. The targetMap is just a map of our tracked reactive objects and their depsMap (dependencies map). A depsMap contains each of the object's properties and their dependency; the exact effect that needs to get re-run when a value changes. This might be a lot to get your head around, so I'll show you a quick example.

|       targetMap     |
|-----------|---------|
| health    | depsMap |
| damage    | depsMap |

Health and damage are our objects which properties we are tracking (which makes it reactive). Now, each object has a depsMap:

|    depsMap (health)    |
|------------------|-----|
| baseAmount       | dep |
| currentAmount    | dep |
| bonusAmount      | dep |

Each of the properties is represented here and they all have a value of dep. 'dep' represents a set of functions that get run if that specific property changes. For instance:

() => {totalHealth = health.baseAmount + health.bonusAmount}

BaseAmount and bonusAmount will have the same function (effect) written in 'dep'. If either of those change, this function will be run and 'totalHealth' will contain the right value.

This is basically what happens in the track function, with the addition that it creates a new Map or Set if a depsMap or dep doesn't already exist. After I've explained how this works, I'm sad to inform you that none of this code gets executed when we just declare an instance of ref. This is because there is no effect to be tracked, so it just gets returned on the first line. But this will happen if you add a dependency to a property.

export function trigger(
  target: object,
  type: TriggerOpTypes,
  key?: unknown,
  newValue?: unknown,
  oldValue?: unknown,
  oldTarget?: Map<unknown, unknown> | Set<unknown>
) {
  const depsMap = targetMap.get(target)
  if (depsMap === void 0) {
    // never been tracked
    return
  }
  const effects = new Set<ReactiveEffect>()
  const computedRunners = new Set<ReactiveEffect>()
  if (type === TriggerOpTypes.CLEAR) {
    // collection being cleared
    // trigger all effects for target
    depsMap.forEach(dep => {
      addRunners(effects, computedRunners, dep)
    })
  } else if (key === 'length' && isArray(target)) {
    depsMap.forEach((dep, key) => {
      if (key === 'length' || key >= (newValue as number)) {
        addRunners(effects, computedRunners, dep)
      }
    })
  } else {
    // schedule runs for SET | ADD | DELETE
    if (key !== void 0) {
      addRunners(effects, computedRunners, depsMap.get(key))
    }
    // also run for iteration key on ADD | DELETE | Map.SET
    if (
      type === TriggerOpTypes.ADD ||
      (type === TriggerOpTypes.DELETE && !isArray(target)) ||
      (type === TriggerOpTypes.SET && target instanceof Map)
    ) {
      const iterationKey = isArray(target) ? 'length' : ITERATE_KEY
      addRunners(effects, computedRunners, depsMap.get(iterationKey))
    }
  }
  const run = (effect: ReactiveEffect) => {
    scheduleRun(
      effect,
      target,
      type,
      key,
      __DEV__
        ? {
            newValue,
            oldValue,
            oldTarget
          }
        : undefined
    )
  }
  // Important: computed effects must be run first so that computed getters
  // can be invalidated before any normal effects that depend on them are run.
  computedRunners.forEach(run)
  effects.forEach(run)
}

Now that we know how targetMap, depsMap and deps are generated, it's a lot easier to understand triggers.
If the object has been tracked, we find our depsMap from our targetMap and get the value. If you remember, depsMap's value is deps which contains all the effects for a specific property. With the addRunnders() function, we add all of the effects to the effects or computedRunners sets, depending on the fact whether they are computed or not.
After all of that, we run each effect for our computed properties first and then for effects. This is what makes the reactivity work after you update a single property on a tracked object.

And that's the basic behaviour of our refs, calling track() and trigger() when getting or setting a property. I hope it has been clear enough and that I haven't made any wrong assumptions. There is a lot to comprehend here, but the main point is that you have gotten the gist of the refs' reactivity and how it all actually works.

I've pasted the links to the files I've been looking at, so you can take a closer look and see for yourself that it's not that complicated. It's also a really good learning material for patterns that you might not know!

Handling nested data in Vue with Vuex ORM

Davor Tvorić — Mon, 24 Feb 2020 08:01:45 +0000

I’ve recently started working on a fairly complex application regarding the structure and the amount of data I get from our API. A lot of the data is meant to be reused and some of them reference the same relationships. This meant that I would, most likely, get tangled up with having some of the data not properly updated.

A while back, a colleague suggested to me to try out Vuex ORM. He reasoned that it should help a lot with nested data and act as a single source of truth. Its job is to map the data you receive from the back-end, after all.
I was convinced, so I’ve read the documentation, tried it out and all I can say is that it made my life a whole lot simpler! In addition to storing the data, I was amazed by how easy it is to get the specific data (and its relationships), format it and filter it by using the query builder. I also realized that a lot of these features would not be properly utilized if you had a simple application in mind. The additional complexity might not be worth it.

I won’t bore you with the basics of Vuex ORM because you can read all about them in the documentation. However, I will show you how I’m currently using it and which features have proved to be really useful.

The whole plugin is really simple to set up. The only additional thing I had to think about is JSON:API. It turned out that it wasn’t so difficult because the community around Vuex ORM was busy with making all sorts of additional features for Vuex ORM. I have used a JSON:API normalizing library that was compatible with Vuex ORM. I have opted out of using their Axios plugin because I needed more control over the data I was receiving. So, in the response interceptor, I added the JSON:API normalizer.

import JsonApiResponseConverter from 'json-api-response-converter';
.
.
.
appAxios.interceptors.response.use(async (response) => {
       if (response.headers['content-type'] && 
           response.headers['content-type'].includes('application/vnd.api+json')) {
           response.data = new JsonApiResponseConverter(response.data).formattedResponse;
       }
   return response;
});

That was pretty much it. Now I could go on and create my models and actually use the library.

After I’ve written a few models, I realized that I was creating a non-orthogonal system. If I’ve wanted to switch some parts of the application in the future, it would prove to be a nearly impossible task. That’s why I’ve decided to separate the concerns in my application and make less of a rigid structure. This is what I came up with and what I’m currently using.

The folder structure

├── src/
│   ├── API/ - contains the files that handle API calls
│   ├── models/ - contains the files that define the ORM models
│   ├── repositories/ - contains the files that act like getters for the ORM

All of this could have been written inside the ORM model, but I found out that the files tend to grow a lot and the code gets a bit messy. You will see my point in the examples.

Example

models/OfferItem.ts

export default class OfferItem extends Model {
    public static entity = 'offerItem';

    // defines all of the fields and relationships on a model
    public static fields() {
        return {
            id: this.attr(null),
            formData: this.attr([]),
            offerItemType: this.string(''),
            price: this.number(''),
            priceDetails: this.attr([]),
            priceDate: this.string(''),
            createdAt: this.string(''),
            updatedAt: this.string(''),
            offer_id: this.attr(null),
            // simple inverse one-to-one relationship
            product_id: this.attr(null),
            product: this.belongsTo(Product, 'product_id'),
            material_id: this.attr(null),
            material: this.belongsTo(ProductCatalogue, 'material_id'),
            offer: this.belongsTo(Offer, 'offer_id'),
        };
    }

    // all of the methods that can be done with the model
    // i.e. fetch all, search, delete, update, etc.
    // we use the API layer here, not in the components
    public static async getById(offerItemId: string) {
        let offerItem;
        try {
            offerItem = await OfferItemAPI.getById(offerItemId);
        } catch (e) {
            return Promise.reject(e);
        }

        this.insertOrUpdate({
            data: offerItem.data,
            insertOrUpdate: ['product', 'offer'],
        });

        return Promise.resolve();
    }

    public static async updateExisting(
        formData: ChecklistFieldEntry[],
        offerItemId: string,
        offerItemType: string) {
        let offerItem;
        try {
            offerItem = await OfferItemAPI.updateExisting(
                offerItemId, 
                formData, 
                offerItemType);
        } catch (e) {
            return Promise.reject(e);
        }

        this.insertOrUpdate({
            data: offerItem.data,
            insertOrUpdate: ['product', 'offer', 'material'],
        });

        return Promise.resolve();
    }
}

api/OfferItemsAPI.ts

import OfferItem from '@/models/OfferItem';

export default class OfferItemAPI {
    // makes the actual call to the back-end
    public static async updateExisting(offerItemId: string, formData: ChecklistFieldEntry[], offerItemType: string) {
        const request = {
            data: {
                type: 'offer_items',
                id: offerItemId,
                attributes: {
                    offerItemType,
                    formData,
                },
            },
        };

        let offerItem;
        try {
            offerItem =
                await ApiController.patch(ApiRoutes.offerItem.updateExisting(offerItemId), request) as AxiosResponse;
        } catch (e) {
            return Promise.reject(e);
        }

        return Promise.resolve(offerItem);
    }

public static async updateExistingMaterial(offerItemId: string, formData: ChecklistFieldEntry[]) {
        const request = {
            .
            .
            .
        };

        let offerItem;
        try {
            offerItem =
                await ApiController.patch(ApiRoutes.offerItem.updateExisting(offerItemId), request) as AxiosResponse;
        } catch (e) {
            return Promise.reject(e);
        }

        return Promise.resolve(offerItem);
    }
}

repositories/OfferItemsRepository.ts

import OfferItem from '@/models/OfferItem';

// using the query builder, we can easily get the specific data
// we need in our components
export default class OfferItemRepository {
    public static getById(offerItemId: string) {
        return OfferItem.query().whereId(offerItemId).withAll().first();
    }
}

Even with a smaller example, you can see that the complexity would only grow with having everything in just one file.

The next step of this is to use it properly and keep the layers separate. The API layer is never used inside of a component, the component can only communicate with the model and the repository.

Concerns

Even though this has been a great help, I have run into some issues that have been bugging me.

Model interfaces

When you define a model and want to use the properties you set it, Typescript will argue that the properties you are using do not exist. I'm assuming this has to do with the facts they are nested in the "fields" property. Not a major issue, but you would have to write an additional interface to escape the errors.

json-api-response-converter

The library suggested by Vuex ORM has some issues when handling cyclical JSON. I have chosen to use jsona instead. The switch was relatively simple because of the way the libraries handle deserialization.

Conclusion

Even though there are some smaller nuances with the library I've run into, I would still urge you to try it out on your complex Vue projects. It's a great benefit to not worry about the data you have and just focus on the business logic of your application.