DEV Community: Aziz

Multitasking like a pro with the WIP commit

Aziz — Wed, 31 Jan 2024 08:02:29 +0000

Intro

Multitasking sucks and should be an exception 99% of the time for coding work. But alas, life does what it wants, so sometimes when coding, you have to urgently put your current work away to work on something else.

You may already know of the popular git stash command but did you know there’s an arguably better way?

In this article, I talk about the The WIP (work in progress) commit and the git commands that enable it, why it’s more flexible than other choices, and also some aliases with cool names.

The WIP Commit Sales Pitch

You’re working on some branch and have some unstaged changes. Imagine the following scenarios:

You want to share your progress with a colleague to collaborate on a tough issue you’re stuck on.
A sudden high priority production bug arises and you need to work on it ASAP while you delegate your current branch to someone else.
The feature you’re working on is unfinished but you’re done for the day so you want to push your work to your branch to keep it safe in the cloud.
You want to simply transfer your current work to a different machine to continue working there.

The common thing between all of these is that you need to save your work somewhere right now. You don’t care about commit messages, pre-commit hooks, CI pipelines, or anything else.

Well, guess what? The WIP commit removes all of that from your way and allows you to truly just send it and forget it.

Here’s the command for it:



git add -A; git rm $(git ls-files --deleted) 2> /dev/null; git commit --no-verify --no-gpg-sign --message "--wip-- [skip ci]"

Yeah, it’s pretty terrifying. The cool part is, some smart people on the internet thought of it for us so we don’t have to worry about it. The command comes from the ohmyzsh git plugin aliases.

If you’re curious, here’s a breakdown of what each part of the command does:

Demo & Usage

There are three aliases you should know:

gwip
gunwip
gunwipall

You can use the gwip alias to stage everything and create a WIP commit in one go. Here’s a demo:

Note that you still have to git push it manually if you want to track it remotely. If you have pre-push hooks, you can skip those with git push --no-verify. Use this power wisely.

Likewise, you can use gunwip to unwip (soft reset) the last WIP commit you’ve made. Here’s a demo:

Finally, you can use gunwipall which unwips (soft resets) all WIP commits you have in your current branch if you happened to have more than one.

Why?

Relevant work is stored in the relevant branch
WIP commits are gone when you delete the branch, so you don’t have a list of rotting old stashes.
No copy-pasting of files like with apply
Your work is saved on the cloud

Why not git stash?

Although git stash is another really handy command, stashing doesn’t work for this use case for a few reasons:

It’s only local to your machine
It’s not associated with any branches as it’s stored in your stash list
Applying a stash which is not at the top of your list complicates your command.
Your stash list can get messy with forgotten stashes (be honest with yourself, how many do you have right now?)

Why not patch?

Patches solve pretty much the same issue, but they aren’t as useful as gwip for the following reasons:

They’re not associated with a branch.
They involve copy-pasting
You have to track them manually. You’re not able to push a patch, otherwise it would be called a commit.
Did I mention they involve copy-pasting?

Setting it up

Using Ohmyzsh

If you’re using Ohmyzsh, you can edit your .zshrc file’s plugins to include git like so:

Afterwards, you’ll want to run source ~/.zshrc or quit your terminal and open it up again for changes to take effect. By the way, the git plugin for OMZ includes a ton of really helpful aliases that you’d do yourself a favor by checking out its docs.

If you’re not using OMZ, simply read the next section about setting it up manually with aliases.

Manually

Add the following to your .zshrc or .bashrc file:



alias gwip='git add -A; git rm $(git ls-files --deleted) 2> /dev/null; git commit --no-verify --no-gpg-sign --message "--wip-- [skip ci]"'

alias gunwip='git rev-list --max-count=1 --format="%s" HEAD | grep -q "\--wip--" && git reset HEAD~1'

# Similar to `gunwip` but recursive "Unwips" all recent `--wip--` commits not just the last one
function gunwipall() {
  local _commit=$(git log --grep='--wip--' --invert-grep --max-count=1 --format=format:%H)

  # Check if a commit without "--wip--" was found and it's not the same as HEAD
  if [[ "$_commit" != "$(git rev-parse HEAD)" ]]; then
    git reset $_commit || return 1
  fi
}

Now reload your config file using source ~/.zshrc (or .bashrc or whatever you’re using) and you should now have the aliases ready for use.

Conclusion

WIP commits make everyone’s lives easier by allowing you to simply send it and forget it. I hope you find it useful. Let me know your opinion!

Vim for the VS Code User: Part 2 - Language Support

Aziz — Mon, 03 Jul 2023 06:02:29 +0000

Last time I showed you how to setup vim with a basic config which you can extend to make vim exactly how you like it.

In this article, we'll setup LSP support, Autocomplete, and Syntax Highlighting.

Before You Start

It's important to know what plugin is taking care of what responsibility so you can customize things to your own taste later. I'll explain each functionality and how it's achieved in an abstract way in this section.

To summarize, there are 3 independent concepts you should know about:

LSP is different from Syntax Highlighting is different from Autocomplete!

And to achieve the functionality we need, we'll use the following plugins:

lsp-zero (and its dependencies)
mason
nvim-lspconfig
nvim-cmp
treesitter

Language Server Protocol

LSP stands for language server protocol. Here's what the LSP does:

Autocomplete options (but not the menu itself)
Diagnostics
Code actions (refactor, extract function, etc.)
Import management
Other (depends on language & specific LSP)

Syntax Highlighting

Syntax highlighting is how you get all the pretty colors in your code.

Autocomplete

Gives you completion options based on where your cursor currently is and what you're typing with the help of your LSP.

With that out of the way, let's get to setting everything up.

Setting Up Syntax Highlighting

Install nvim-treesitter. I'll do it with Packer (refer to 1st article):

-- packer.lua
return require("packer").startup(
    function(use)

      -- ... other plugins ...

      use("nvim-treesitter/nvim-treesitter", {run = ":TSUpdate"})
    end
)

Then run :so followed by :PackerSync to install it.

Next, create a configuration for it using whatever method you like. I did it by creating a file under ~/.config/nvim/after/plugin/treesitter.lua

require "nvim-treesitter.configs".setup {
    -- A list of parser names, or "all" (customize according to taste)
    ensure_installed = {"javascript", "typescript", "rust", "lua", "vim", "vimdoc", "query"},

    -- Install parsers synchronously (only applied to `ensure_installed`)
    sync_install = false,

    -- Automatically install missing parsers when entering buffer
    auto_install = true,

    highlight = {
        enable = true,

        -- Set this to `true` if you depend on 'syntax' being enabled (like for indentation).
        -- Using this option may slow down your editor, and you may see some duplicate highlights.
        -- Instead of true it can also be a list of languages
        additional_vim_regex_highlighting = false
    }
}

Above is my own personal configuration. You can mess around with yours to make it do whatever you like. Check the docs for more info.

With that, you're done! Now this plugin will automatically install whatever's necessary to highlight your code without you needing to do a thing!

LSP Zero (Autocomplete & Language Support)

Add the following to your packer file:

use {
    "VonHeikemen/lsp-zero.nvim",
    branch = "v2.x",
    requires = {

        -- LSP Support
        {"neovim/nvim-lspconfig"}, -- Required

        {
            -- Optional
            "williamboman/mason.nvim",
            run = function()
                pcall(vim.cmd, "MasonUpdate")
            end
        },

        {"williamboman/mason-lspconfig.nvim"}, -- Optional

        -- Autocompletion
        {"hrsh7th/nvim-cmp"}, -- Required
        {"hrsh7th/cmp-nvim-lsp"}, -- Required
        {"L3MON4D3/LuaSnip"} -- Required
    }
}

Then run :so followed by :PackerSync to install all the added plugins.

If all goes well, you should be ready to setup your config.

I set mine up under ~/.config/nvim/after/lsp.lua as the following:

local lsp = require("lsp-zero")

lsp.preset("recommended")

-- navigating completions in the autocomplete popup
local cmp = require("cmp")
local cmp_select = {behavior = cmp.SelectBehavior.Select}
local cmp_mappings =
    lsp.defaults.cmp_mappings(
    {
        -- prev item in menu
        ["<C-p>"] = cmp.mapping.select_prev_item(cmp_select),

        -- next item in menu
        ["<C-n>"] = cmp.mapping.select_next_item(cmp_select),

        -- confirm current selection
        ["<C-y>"] = cmp.mapping.confirm({select = true}),

        -- misc
        ["<C-Space>"] = cmp.mapping.complete()
    }
)

-- assigning previously defined mappings
lsp.setup_nvim_cmp(
    {
        mappings = cmp_mappings
    }
)

-- shortcuts for making use of LSPs
lsp.on_attach(
    function(client, bufnr)
        local opts = {buffer = bufnr, remap = false}

        -- go to definition of symbol under cursor
        vim.keymap.set(
            "n",
            "gd",
            function()
                vim.lsp.buf.definition()
            end,
            opts
        )

        -- shows info about current symbol as if you hovered on it
        -- with the cursor (really handy!)
        vim.keymap.set(
            "n",
            "K",
            function()
                vim.lsp.buf.hover()
            end,
            opts
        )

        -- lookup a workspace symbol
        vim.keymap.set(
            "n",
            "<leader>vws",
            function()
                vim.lsp.buf.workspace_symbol()
            end,
            opts
        )

        -- show diagnostic in a floating dialog (like when you hover on a 
        -- a line with a red squiggly under it)
        vim.keymap.set(
            "n",
            "<leader>vd",
            function()
                vim.diagnostic.open_float()
            end,
            opts
        )

        -- go to next diagnostic
        vim.keymap.set(
            "n",
            "[d",
            function()
                vim.diagnostic.goto_next()
            end,
            opts
        )

        -- go to prev diagnostic
        vim.keymap.set(
            "n",
            "]d",
            function()
                vim.diagnostic.goto_prev()
            end,
            opts
        )

        -- show code actions (refactor, inline function, etc..)
        vim.keymap.set(
            "n",
            "<leader>vca",
            function()
                vim.lsp.buf.code_action()
            end,
            opts
        )

        -- show references to symbol under cursor
        vim.keymap.set(
            "n",
            "<leader>vrr",
            function()
                vim.lsp.buf.references()
            end,
            opts
        )

        -- rename current symbol (works across files too!)
        vim.keymap.set(
            "n",
            "<leader>vrn",
            function()
                vim.lsp.buf.rename()
            end,
            opts
        )

        -- show help for current function when in insert mode (helps to see
        -- params of current function for example)
        vim.keymap.set(
            "i",
            "<C-h>",
            function()
                vim.lsp.buf.signature_help()
            end,
            opts
        )
    end
)

-- setup lua language server (with support for nvim)
require("lspconfig").lua_ls.setup(lsp.nvim_lua_ls())

lsp.setup()

The above configuration sets up everything you need for a base you can expand on. I've added a lot of annotations to make it easier to know what does what.

Whenever you add an LSP, autocomplete and everything else will "just work" requiring only minimal configuration most of the time.

For most of your needs, you should consult the lspconfig server configurations page.

Let's add the html and emmet LSPs as a demo.

Step 1: Install it with LspInstall. To do this, simply run the command :LspInstall from a file with the .html extension.

We'll do the same to install support for emmet

Let's do a quick check to see if that worked. Exit your current vim session and open it again so the LSPs are loaded.

Here's a demo of emmet with autocomplete:

And here is what the html lsp gives us:

Step 2: configure LSPs with lspconfig (if necessary)

For the emmet and html LSPs, this isn't necessary (thanks to lsp-zero). You can still do it if you want to customize things to your needs. Refer to the server configurations page in that case.

You can see an example at the bottom of this file in my own neovim config.

What actually happened here though? Let's break it down:

You ran the :LspInstall command which looked up what LSPs are associated with the file you have open
You installed the html and emmet lsps suggested by LspInstall, which in turn installed them using Mason (it's the popup that shows after you select which lsp to install)

If you want to see what LSPs you have installed, you can run the :Mason command.

You can use some basic shortcuts to manage your LSPs from this menu, like i to install an available LSP, X to uninstall one, and / to search for one. You can exit this menu using q.

Conclusion

We setup syntax highlighting with Nvim-Treesitter, and language support, including autocomplete and diagnostics, using lsp-zero, mason, and nvim-cmp.

Here's my own nvim config if you're interested (yes, I will shamelessly link to this every time 🌚):

https://github.com/aziznal/my-neovim-config/

How I Reduced Burnout By Reducing Everything

Aziz — Mon, 19 Jun 2023 17:53:30 +0000

In this article, I talk about my experience with burn out and how I'm making it not a thing for me anymore (I think, I hope).

I aim to be as practical as possible with my explanations and proposed solutions but at the end of the day, your mileage may vary.

⚠️ Disclaimer: Mental health is a sensitive topic. If you need help, seek help. This article is half me ranting, and the other half me sharing my limited experience with burnout.

The Deadly Cycle

I've been a developer for ~5 years. I've been in a professional environment for 3 of those years.

I've found lately that I'm in a constant cycle of high-energy, high-output, partial or complete burnout, regret, rest, then high-energy again and the cycle repeats.

Here's another visualization that'll help me get the point across:

And then it just repeats like this:

This constant change between HOT 🔥 and cold 🧊 is the best way to completely ruin someone's happiness and motivation. Whenever I'm feeling highly motivated, I remember that I'm going to eventually burn out any way so what's the point.

Likewise, when I'm feeling burnt out, I just think to myself that there's no need for any real change in my life as this too will pass and I'll get my motivation back anyway.

I'd gotten so stressed about this that I eventually got completely crippled and became unable to do anything at all. I literally just stared at my monitors.

This is not the way.

The Nitty Gritty (What's Actually Happening)

What do I do in a day? What makes me feel burnt out? Why do I seem not to learn my lesson?

A typical week for me would start with defining some goals for the week. Usually overly optimistic and without consideration to how much spare time or motivation I actually have after company work. You know, the usual stuff.

Naturally, I would spend every day in this week working for my company, constantly interrupted by notifications from my phone, emails, slack, other random bullshit, etc. which would make me work longer than usual in an attempt to get some work done before calling it a day.

This would tire me out completely by the evening and, at that point, nothing short of a high-dose energy supplement would get my energy back up, but that's only pushing my already depleted motivation.

I would reach the end of the week having achieved little or none of what I'd set out to do, stressed about company work since that's also not going as swimmingly as I'd like.
Sometimes, I would be extra motivated for a given day and maybe I'd get a decent amount of my personal goals achieved. A rare occasion though.

I'm happy to say I've put almost all of that completely behind me. I've found something close to a balance.

How? By dumbing it down so my primitive ape brain can wrap itself around it.

Towards a Solution

The end goal is to flatten the mental state wave:

I'm not an expert at this topic, so I won't pretend to be one. All I did was do a little self retrospection.

At the end of the day, my conclusion was that I've got a severe mis-allocation of mental resources and an unhealthy attachment to everyone else's happiness and what others think is right.

The following are the culprits:

Your Attention Span

So, good news, there's this thing called attention a.k.a your ability to focus. Bad news, you have not that much of it.

According to wikipedia, the average adult has 5 hours a day of attention.

As a developer, it's one of your most important resources.

You might think that ~5 hours is actually pretty good, but don't forget to take into account the many interruptions you encounter, and the fact that each interruption means you need 23 minutes to get back into your flow (according to this random link I found on the internet which I totally trust).

So I made it a goal to maximize the amount of uninterrupted attention I have in a day.

This started relatively tame with me placing my phone out of my sight and out of arms reach while working.

Social Media

I've never considered myself a social media user. "I just use reddit", I'd say to myself. Whatever you classify it as, it became a natural reflex for me to open up reddit on my phone within 5 milliseconds of touching my phone. It was terrifying, and it was time and attention consuming. It had to go.

So I quit. Cold turkey. Just like that. I'm never going back. I'm all the happier for it. If the world burns, I'll know it when I see the flames from my window. If it's the second coming of jesus christ, I'll listen to the angels singing outside or something. Basically, important news will make its way to me somehow.

There's nothing that reddit adds to my life that could cancel out the negativity I get from it. That's that.

For those interested, before quitting cold-turkey, I tried app timers. But those can be turned off so it's not very useful to me. I needed to put more friction between me and the app, so I just removed it.

Notifications

Notifications are a crime against humanity. I'm pretty sure everyone has some form of mild PTSD from being subjected to the constant stream of beeps, boops, ring-a-ding-a-lings and buzzes.

So I muted everything 🔇. Not my phone, laptop, tablet, watch, or anything can demand my attention with a notification. If it's important, then I'll probably be called about it. Otherwise, I'll read it on MY time.

To balance things out, I made it a habit to take a look at my notifications whenever I've completed a "session" of work which has a measurable end.

I used to think that good communication meant answering on time and giving your time to people so they feel heard. Screw that.

Good communication should happen when it's time for it, not when you're in the middle of something. Respect your time, and respect the fact that you're expensive for your company. Being interrupted and having to start over better be damn worth it.

As a bonus, I made it a habit to permanently mute any sort of notification that adds nothing to my life. Unsubscribing from marketing emails, hiding shopping apps notifications, etc..

They really add up, so I recommend muting them as soon as you spot them. Eventually, you'll have a feed which only includes things you actually care about.

Simplifying My Workspace

I went down from three monitors to one, sometimes two.

I used to be the kind of guy to dream about when I'd be able to make a setup where I'd be able to have 5 or 6 monitors at the same time (I still kinda do…)

But then I asked myself, "dude, I'm a freaking web developer. WHY do I even need more than 2 monitors, ever?!". And the answer for me is, of course, netflix or spotify. pure distraction.

I'm strictly talking about MY own reasons right now, so if you're enjoying better productivity with your own setup then good for you.

Now I use one monitor when possible, and add another when building a hot-reloadable thing and I don't want to have to mess around with my windows.

Boom. instant wins. I don't know why, but I don't miss my older setup at all. I might even just go down to one monitor permanently. It enables me to focus only on what's on my current monitor and that's all.

Another simplification I did was to change my editor. I really hated how much moving around between the mouse and keyboard I had to do all day, so I learned vim over the last month or so and I'm a happier coder for it. I make it sound simple but it was a painful process honestly. Though it paid out very well in the end.

Final Thoughts

Our poor brains have way too much to filter through nowadays. Give yourself a break.

If you're unable to do the things that you want to do, then there's a good reason for it and you're not the problem, but you need to find a way to adapt your environment to yourself to make the most out of your unique mind.

It's not just about what you do during work. It's about what you do throughout your day that consumes your attention.

If you find yourself constantly in a position where you have to seriously strain yourself to achieve your goals, you need to lighten the load somewhere else in your life, or suffer the very real consequences.

Thank you for reading my article.

Vim for The VS Code User: Part 1 - Initial Setup

Aziz — Mon, 12 Jun 2023 07:25:22 +0000

Ahh vim. For me, it was just a funny meme I saw every once in a while about how people can't seem to exit it.

But then, as most adventures in a dev's life start, I went on the internet while procrastinating from doing my real work and I instead watched a former meth addict and Netflix engineer talking about neovim, its shortcuts, plugins, theming, etc.. and it sort of clicked for me. I tried it and I've been hooked ever since.

In my following article(s), I want to show you how you can get started with vim, specifically Neovim, including avoiding some the mistakes I fell into. This will help you turn your IDE (integrated development environment) into a PDE (Personal development environment)

With this article and the ones I plan on making in this series, you will make vim into a personalized code editing powerhouse custom tailored for exactly your flow and yourself.

Here's a link to my config if you're interested.

Before You Start

For me, the vim roller coaster looked something like this:

The point is to keep pouring in effort and you'll get there, but you'll probably have to push through it at some point.

Once you're used to vim, you'll have a hard time going back to your default editor without at least using vim motions because although you can switch your brain to the old ways again, you won't want to!

Also, I want to mention some important points about things that I was doing wrong, in my opinion, that may help you as well:

Stop using a non-qwerty layout unless you know what you're doing. Switching to the US QWERTY layout was the best thing I did for my coding speed (I used Turkish Q before)
Don't think you need more experience before you start. You are literally as ready as you will ever be right now.
Ease into it. Do things YOUR way at YOUR pace 🫵. Don't stop using your favorite editor cold-turkey. Your productivity will plummet to the ground and you will feel like crap. For starters, you could check out this vim extension for VS code, for example.
Don't use Vimscript. This is my ⚠️ personal opinion ⚠️, but I've had a much easier time using plain old lua which is how you setup your vim config, as I'll show you in an upcoming section.

One last thing: I'm using the words ' vim' and 'neovim' interchangeably here, but I'm strictly talking about neovim in pretty much all instances.

Why Vim?

Here is one good explanation:

Why, oh WHY, do those #?@! nutheads use vi?

My reasons are:

Incredibly fast startup
Clean. Simple. Nothing more than an editor.
Minimal hand movement. I don't even need to move my - hand to the arrow keys.
Tailored exactly to your needs
Unmatched customizability
Brag rights

It's not even funny how much quicker neovim is to start than my VS Code. Maybe I made my VS Code installation a bloated mess of extensions and other crap, or maybe I just want a functional but customized editor that doesn't take half my RAM to edit an HTML file.

Vim's shortcuts are also all close to the center of the keyboard. You don't have to move your hands that much even on the keyboard itself, let alone away from the keyboard to the mouse.

Not to mention the insane amount of customization you can do. I cannot stress this enough, but you will never run out of ways to make vim your own.

Most importantly, you now get to brag (I use arch AND vim btw 😎).

Installing Neovim

There's no better guide than here.

The Modes of Vim

This is probably one of the biggest differences between your conventional text editing environment and vim. I'm not going to go into too much depth about these but you can read about them here. (probably do some more research though)

In a normal text editor, you can just write immediately, and you can use combinations of Ctrl, Shift, Super/Opt, and Alt/Cmd and a key for your shortcuts.

In vim, there are 4 modes you should be familiar with:

Normal: all your keys (yes, including the letters) are shortcuts for text manipulation and many other functions.
Insert: pretty much exactly like a normal text editor.
Visual: Select text and do something with it (copy, paste, delete, format, etc.)
Command: Run a vim command.

You already know how to use Insert, Visual, and probably even Command modes.

VS Code's default is in insert mode, you are in "Visual" mode when selecting any text, and Ctrl+Shift+P opens the command palette which is a sort of command mode in itself.

What makes vim special for me is its Normal mode. Instead of reaching for the bottom left corner of your keyboard, your fingers can stay on the home row of your keyboard.

I won't sugar coat it. It's a slow start to get used to it, but practice makes perfect.

Once you know your way around these modes, it becomes a matter of wanting to do something and your fingers will simply do it.

The Most Basic Motions and Shortcuts

There is not a chance in heehaw that I can list all the shortcuts you will need and use in vim in an article. Instead, I will list some resources where you can get into it yourself.

To get right into the action, you can use vim's built-in interactive tutorial by running the :Tutor command. Try it, it's pretty nice!

I can also recommend the following resources which personally helped me:

http://www.viemu.com/a_vi_vim_graphical_cheat_sheet_tutorial.html (recommend starting with this one ⭐)
https://devhints.io/vim
https://vimsheet.com/
https://vim.rtorr.com/
https://vim.fandom.com/wiki/Tutorial#Vim_tutor

What's a Config?

Your config is how you tell neovim about your plugins, themes, shortcut maps, and so on.

Your config will most likely be found under ~/.config/nvim. It can be split into different files each responsible for configuring a different aspect of vim, like theme.lua for your theme, sets.lua for your settings, etc.

It all starts with one file: init.lua which is loaded automatically when you open vim. This file loads the rest of your config.

An init.lua file is almost like an index.js. You can write your program code in it, or you can write your code in different files and then export the whole thing through this file, which is what we're going to do.

Here's what the inside of your top-level init.lua will look like:

require('yourname')

What's yourname? This is just a namespace where you write your config. It's a convention people follow in their configs to avoid clashes with the built-in neovim config. You can replace yourname with anything within reason.

Next, you want to create a few more things:

a directory called lua
a directory below lua called yourname which has to match what you picked before for that.
an init.lua file under lua/yourname/.

The lua directory means something in the lua programming language so make sure to name it exactly so. Now our top-level init.lua file makes sense, doesn't it? It's importing the init.lua under lua/yourname. Piece of cake.

Here's a cool pic:

So it's basically the top init file calling the init file below it which in turn calls any files you want.

the init file under yourname will typically look like this:

require('sets.lua')
require('remaps.lua')
-- any other files ...

What about the packer.lua file though? Why not load that too?

The reason is that this file is special. It's a config for a plugin manager called Packer which I use to install and manage my plugins. It's sort of like your package.json.

I'll show you how you can basically set up this file with your first plugin so you can get started installing plugins as soon as possible.

Create the packer.lua file under lua/yourname/ and add the following into it:

vim.cmd [[packadd packer.nvim]]

return require("packer").startup(
    function(use)
      -- your plugin installation code will go here
    end
)

To find plugins, I personally just google something like neovim plugin copilot and usually the gets me a github page with instructions I can follow.

So if you want to install the github copilot extension, you would do the following:

vim.cmd [[packadd packer.nvim]]

return require("packer").startup(
    function(use)
        use("zbirenbaum/copilot.lua")
    end
)

Then, run the following commands to install the newly added plugin(s):

:so            -- to load packer into the context
:PackerSync    -- to install the newly added plugin

Remember, you run these commands by clicking shift + semicolon, type the command (without the colon since it would already be there), then press enter.

Many plugins require you to also set them up before you can use them. make sure to refer to the documentation. Here is a link to the documentation for this copilot extension, which requires us to do something before the plugin actually works.

So, let's add the config for the plugin. You'll add this under a new folder called after/plugin.

Just like the lua folder, this folder is special in that everything in it is executed after your own config is loaded.

Add a file called copilot.lua (name is not important) and paste what the docs recommends into it:

require("copilot").setup()

Exit vim and start it up again and you should now have a :Copilot command. To authenticate your account, run :Copilot auth and follow the instructions.

Now you have copilot in neovim!

You've just gone through the basic flow to install a plugin. Remember to read the docs for any given plugin well to avoid unnecessary headaches.

Here's my own config if you're interested.

Other Resources

My own neovim config
Tips for using vim: https://vim.fandom.com/wiki/Best_Vim_Tips
A game for learning vim, in vim: https://github.com/ThePrimeagen/vim-be-good
Collection of Awesome Plugins: https://github.com/rockerBOO/awesome-neovim
Some more popular plugins: https://hannadrehman.com/top-neovim-plugins-for-developers-in-2022

There are so many topics to cover that I plan on splitting it all up over multiple articles. I plan to tackle the following topics:

Theming
Language Servers and Autocomplete
Must-Have plugins
Finding your files
Git

Stay tuned for these and let me know if there is anything in specific that you'd like me to cover.

VS Code Shortcuts to Navigate Your Editor Like Tarzan in The Jungle

Aziz — Sun, 28 May 2023 18:06:59 +0000

No need for a long intro, it's pretty simple: make better programs by focusing on the program instead of the editor.

So whether it's instantly refactoring 50 different lines of code at the same time, finding issues, or changing your view by adding and closing panels, these VS Code shortcuts will help you with navigating your environment rapidly, and jumping around your code with ease.

You might also find my previous articles in this series useful:

Add Cursor to All Matching

Select and edit multiple instances of the same text simultaneously

Maybe this won't increase your code quality, but it'll definitely increase the amount of code you modify at a time, so no one will have the time to even review your code.

Linux / Windows: Ctrl + Shift + L
Mac: Cmd + Shift + L

Next Issue In Project

Instantly navigate to code marked with an issue across your project

VS Code is like your guardian angel. It constantly keeps watch over your spaghetti code and keeps a list of why you should've considered a different career. If you wanna make the voices go away quickly, try this shortcut!

Linux / Windows / Mac: F8

Next Issue In File

Instantly navigate to code marked with an issue but only in the current file

The previous shortcut was great, but it turns out there are wayyy too many issues across your project to even begin to hope to fix them. Most of them are warnings either way so who cares? Why not just stick to the current file!

Linux / Windows: Alt + F8
Mac: Opt + F8

Show Code Actions Menu

Show code actions in context to the code your cursor is on

That little menu in VS Code can have so many wonderful refactoring options. It's there to make your life easier. Also, auto imports. Honestly, mostly auto imports.

Linux / Windows: Ctrl + Dot
Mac: Cmd + Dot

Toggle Left Sidebar

Show or hide the left (or primary) side bar

When your wide screen is not wide enough to see that 3000 character email validation regex, you can hide the side bar completely and see if that helps to understand it. Still no? Well it's a cool shortcut either way.

Linux / Windows: Ctrl + B
Mac: Cmd + B

Toggle Right Panel

Show or hide the right (secondary) side bar

Indeed, there is an entirely hidden section on the right. My mind was blown too when I first discovered this. Now you put your debugger there and see every single variable in your application at once!

Linux / Windows: Ctrl + Alt + B
Mac: Cmd + Opt + B

Toggle File Explorer Panel

Focus on the file explorer panel, then you can navigate with the arrow keys

This one really makes you regret the fact that you nested your components 10 levels deep, doesn't it? Well, at least the icons are pretty.

Linux / Windows: Ctrl + Shift + E
Mac: Cmd + Shift + E

Find Symbol in File

Use fuzzy search to list and find symbols like functions and variables (useful for finding a constructor quickly!)

Why answer the question of why you have 100 methods in your class? This will never come back to haunt you, at least, not now that you know this shortcut!

Linux / Windows: Ctrl + Shift + O
Mac: Cmd + Shift + O

Go to Definition of Highlighted Symbol

Go to definition of the symbol under the cursor. Useful when you're working with unfamiliar code or libraries

Using an API from an npm package abandoned 3 years ago but still has 300 million weekly downloads? Sometimes you gotta get your hands dirty and dig in a bit.

Linux / Windows / Mac: F12

Show Peek of Definition of Highlighted Symbol

Show definition of the symbol under the cursor in a popup window

Got commitment issues? Sneak a peek at the party from a little window like a true introvert.

Linux / Windows: Ctrl + Shift + F12
Mac: Cmd + Shift + F12

Conclusion

With these shortcuts, you'll find yourself getting to the important bits of your code quicker, and with more control over them.

Check out my other articles for even more handy shortcuts:

How To Implement a TypeScript Web App With Clean Architecture

Aziz — Sun, 14 May 2023 13:51:17 +0000

In this guide, I will show you how to write your application using the clean architecture template I created in this article.

Why clean architecture? Because, depending on the size of your app, the “Keep coding and hope nothing breaks” architecture can only take you so far!

“The only way to go fast is to go well.” — Bob Martin

Intro

I think we rely too much on web frameworks when making our applications. While they take care of a lot of the boring stuff, they take away our control of our applications.

I made a project template that takes control away from the framework by isolating different layers of your application into packages.

You'll notice by the end that we don't actually need Angular at all, and we can easily swap it for any other framework, which is the entire point of clean architecture.

Advantages of this architecture

Well-defined boundaries for layers
Faster build and test-run times thanks to caching
Significantly easier time writing tests due to loose coupling
Zero dependence on details like Web Framework, Database, etc
Promotes code reuse

Disadvantages

Some boilerplate code
Requires experience (I explain everything in this article, so don't worry!)

Layers of the architecture

We're going to divide our application into three main layers:

Core: containing our entities, use cases, and repository interface. This is what the application is at its core (hence the name).
Data: containing implementations of repositories for retrieving data from local and remote storage. This is how we get and store data.
Presentation: This layer is how the user sees and interacts with our application. It contains our Angular or React code.

There is a fourth auxiliary layer called DI (dependency injection). This layer's job will be to prevent direct dependencies between presentation and data while at the same time allowing for Presentation to use Data through Core.

The Core layer contains our app logic and defines interfaces for repositories which the Data layer implements. The repositories are used by use cases to do operations on data, but the Core layer doesn't care where the data comes from or how it's saved. It delegates the responsibility (a.k.a concern) to the Data layer, which decides whether the data comes from a local cache or a remote API, etc.

Next, the Presentation layer uses the use cases from the Core layer and allows the user a way to interact with the application. Notice that the Presentation layer does NOT interact with the Data layer because the Presentation doesn't care where data comes from either. The Core is what ties the application layers together.

The diagram below explains the dependencies between and within layers. Notice that, eventually, everything points towards the Core layer.

As for data flow, it all starts at the Presentation when the user might click a button or submits a form. The Presentation calls a use case, a method in the repository that retrieves/stores data is called. This data is retrieved from either a local data source, the remote data source, or maybe even both. The repository returns the result of the call back to the use case, which returns it to the Presentation.

We will implement this data flow by injecting implementations of the repository interface from Data into the Core layer. This way, we keep Core in control, so inversion of control is satisfied. It's satisfying because Data implements what Core has defined as a repository.

General File Structure

Inside our main project, we have a folder named packages which has a folder for each layer of our application. We will start by creating some stuff in Core.

Defining an example application

Let's say we just received the following requirements for an app:

Create an app that displays counters to the user
The user should be able to create/delete counters
The user should be able to increment/decrement a counter by pressing buttons
The user should be able to change the amount of increment/decrement for a counter
The user should be able to assign a label to a counter
The user should be able to filter counters by label
The user's counters should be saved if they close the application and open it again.

From these requirements, we can say the following:

Our main entity is the Counter
Our use cases get all counters, get counters filtered by label, increment, decrement, assign a label, create a counter, and delete counter
We need a way to store data locally, i.e., a local data source

Writing Your First Entity and Use Case

Now we're getting to the fun parts. We start by defining our application's single entity: the counter.

We'll create a new directory under core/src/ named counter, and within it, we'll create another directory called entities, in which we'll create a file called counter.entity.ts:

export class Counter {
    id: string;
    label: string;
    currentCount: number = 0;
    incrementAmount: number = 1;
    decrementAmount: number = 1;
}

Next, we implement our use cases. We start by defining a standard way to interact with our use cases and each use case's dependencies.

We create a use case interface under core/src/base and call it usecase.interface.ts.

export abstract class Usecase<T> {
    abstract execute(...args: any[]): T;
}

Now, whenever we create a new use case, we make it implement Usecase where it must also define its return type. This forces us to be thoughtful about the output of our use cases.

Let's create the CreateCounterUsecase first.

Inside of core, create a folder under src/counter called usecases, and in it, create create-counter.ts.

import { Usecase } from "../../base/usecase.interface";

import { Counter } from "../entities/counter.entity";

export abstract class CreateCounterUsecase implements Usecase<Counter> {
    abstract execute(...args: any[]): Counter;
}

export class CreateCounterUsecaseImpl implements CreateCounterUsecase {
    constructor() {}

    execute(...args: any[]): Counter {
        throw new Error("Method not implemented.");
    }
}

You'll see an interface of the use case, and directly below it, an implementation of that interface. Doing things this way helps us define data flow into/out of use cases and also makes dependency injection a walk in the park.

This use case will need a way to create a counter that persists somewhere so that our users will be able to do things like refresh the page and not lose their counters. For this, we create a repository interface under src/counter/counter-repository.interface.ts.

import { Counter } from "./entities/counter.entity";

export abstract class CounterRepository {
    abstract createCounter(counterInfo: Counter): Counter;
}

Now we add this repository to our create-counter use case's dependencies and call this new method we added. I like to define dependencies in the constructor because it makes it straightforward to provide them when doing dependency injection.

import { Usecase } from "../../base/usecase.interface";
import { CounterRepository } from "../counter-repository.interface";

import { Counter } from "../entities/counter.entity";

export abstract class CreateCounterUsecase implements Usecase<Counter> {
    abstract execute(): Counter;
}

export class CreateCounterUsecaseImpl implements CreateCounterUsecase {
    constructor(private counterRepository: CounterRepository) {}

    execute(): Counter {
        return this.counterRepository.createCounter({
            id: Math.random().toString().substring(2),
            currentCount: 0,
            decrementAmount: 1,
            incrementAmount: 1,
            label: "New Counter",
        });
    }
}

Congratulations! We've just written our first entity, use case, and repository interface!

There's one last thing we need to do, and that is to export our entities, use case, and repository from the core package. I prefer to do this using index.ts files. Here's how we do it.

export * from "./entities/counter.entity";

export * from "./usecases/create-counter";

export * from "./counter-repository.interface";

Under core/src/counter, create a file called index.ts. This file will use the export statement to make everything inside the counter directory available with a very simple import statement.

Whenever we add a new file to counter, and we want to export it, we just add an export statement to this file.

Next, update core/src/index.ts to include the following export statement:

export * from './counter';

We won't need to update this file again unless we add another module next to counter.

Run the following command to build your core package and have it distributed to all the packages that depend on it:

npx lerna run build && npx lerna bootstrap

You only need to run the bootstrap command if it's the first time you're using the template.

Now we're ready for the next step.

Creating Data Sources

We need to implement the repository interface that core has defined. I choose to do this in a package called data. That way, I isolate my business rules in the core package, and the data sources that support them in another.

Under packages/data/src, create a folder called counter and, in it, create a file called counter-repository.impl.ts. The file extension is completely optional. I just like to make the insides of files a bit more explicit using these extensions. It also makes searching for them a bit easier.

import * as core from "core";

export class CounterRepositoryImpl implements core.CounterRepository {
    createCounter(counterInfo: core.Counter): core.Counter {
        throw new Error("Method not implemented.");
    }
}

You'll notice I've imported everything in core as the keyword core. This is also a personal preference. You could use destructured imports to get things from core, but I think it's better to make it more explicit.

Anyways. How should we implement our repository? We need some way to enable the user to persist their session somehow. “Oh, I know!” I hear you say, enthusiastically, “We can just use the browser's built-in local storage!” That is a good solution to get the point across, but there's a tiny problem.

The data package doesn't have access to the browser's storage API because it isn't aware of a browser in the first place. In fact, we want data to be this way. Otherwise, we would have made it dependent on a detail, i.e., the platform it's running on.

Instead, we provide our repo implementation with something called local storage. This is a dependency with an interface we define in data, and an implementation that we can define literally anywhere we want. This local storage dependency will be injected into our repo implementation. We will get to this section soon.

I chose to create this interface under data/src/common as local-storage-service.interface.ts since we'd want to use it in other repositories as well. Here's the interface to our local storage dependency:

export abstract class LocalStorageService {
    abstract get(key: string): string;

    abstract set(key: string, value: string): string;
}

Now we add it as a dependency to our repo implementation, and we implement the createCounter method:

import * as core from "core";

import { LocalStorageService } from "../common/local-storage-service.interface";

export class CounterRepositoryImpl implements core.CounterRepository {
    constructor(private localStorageService: LocalStorageService) {}

    createCounter(counterInfo: core.Counter): core.Counter {
        this.localStorageService.set(counterInfo.id, JSON.stringify(counterInfo));

        return counterInfo;
    }
}

I'm implementing this method as simple as I can for now. The cool part is you can choose to make it anything you want in the future without Presentation or Core having to change anything at all.

Congrats! We've just implemented all we need in data. Now we need to export it as well. Again, let's make use of index files.

Create an index.ts file under data/src/counter.

export * from './counter-repository.impl';

and also one under data/src/common

export * from "./local-storage-service.interface";

Finally, export both of these in the index file under data/src.

export * from "./common";

export * from "./counter";

We export the local storage service interface because we will have it implemented in a place with access to the browser's storage API: Presentation!

But wouldn't that ruin our dependency graph by making data depend on Presentation? In fact, it won't because we're implementing inversion of control. This means that Presentation will indirectly depend on data rather than the other way around. You'll see how this works in the upcoming section.

For now, let's re-build our data package. Run npx lerna run build again.

Dependency Injection (With a Little Help From Angular)

Here's we bring **core** and **data** together. We want to associate the implementations of use cases and repositories with their interfaces.

I do this using a class that generates these objects with their dependencies given to them, for example, a Factory.

Under di/src, create a folder called counter, and within it, create a file called counter.factory.ts:

import * as core from "core";
import * as data from "data";

export class CounterFactory {
    private counterRepository: core.CounterRepository;

    constructor(private localStorageService: data.LocalStorageService) {
        this.counterRepository = new data.CounterRepositoryImpl(this.localStorageService);
    }

    getCreateCounterUsecase(): core.CreateCounterUsecase {
        return new core.CreateCounterUsecaseImpl(this.counterRepository);
    }
}

The CounterFactory class is instantiated with all the dependencies we need to instantiate our repository and use case. We don't expose the repository, only the interface it requires.

We export this factory as well as the local storage service interface it requires by creating an index.ts file under di/src/counter like the following:

import * as data from "data";

export * from "./counter.factory";

export type LocalStorageService = data.LocalStorageService;

and we export this file in the index.ts file under di/src:

export * from "./counter";

Here's how the project dir looks for di:

Run npx lerna run build to build your package. Notice how Lerna doesn't rebuild core and data, but uses a cached version of their previous build since they didn't change. Kinda cool, right?

Now we're ready to move onto Presentation.

We need to make the stuff we just created easily accessible in Presentation. For this, I use Angular's superb dependency injection. Here's how I do it.

With Angular, we could do this directly inside of our app.module file, but I'm going to make things tidier by doing it all in a folder under presentation/src/di, and I'll make a file inside of it called counter.ioc.ts

import * as core from 'core';
import * as di from 'di';

import { Provider } from '@angular/core';

import { LocalStorageServiceImpl } from '../services/local-storage-service';

const localStorageServiceImpl = new LocalStorageServiceImpl();

const counterFactory = new di.CounterFactory(localStorageServiceImpl);

export const CORE_IOC: Provider[] = [
    {
        provide: core.CreateCounterUsecase,
        useFactory: () => counterFactory.getCreateCounterUsecase(),
    },
];

This file instantiates the CounterFactory and provides it with the dependencies it requires. Then, we create a Provider[] using Angular's Provider type and inject our dependencies exactly like we normally do in an Angular application.

Before you panic, here's the LocalStorageServiceImpl file which we create under presentation/src/services (or wherever you think is suitable):

import * as di from 'di';

export class LocalStorageServiceImpl implements di.LocalStorageService {
    get(key: string): string {
        const item = localStorage.getItem(key);

        if (item == null) throw new Error(`Could not find item with key ${key}`);

        return item;
    }

    set(key: string, value: string): void {
        localStorage.setItem(key, value);
    }
}

One last thing (I swear!). We need to include this CORE_IOC provider array in our app.module to make it available in all of our applications.

import { NgModule } from '@angular/core';
import { BrowserModule } from '@angular/platform-browser';

import { AppComponent } from './app.component';

import { CORE_IOC } from 'src/di/counter.ioc';

@NgModule({
    declarations: [AppComponent],

    imports: [BrowserModule],

    providers: [...CORE_IOC],

    bootstrap: [AppComponent],
})
export class AppModule {}

We are officially finished. I knew you could get there!

Keep in mind that a lot of what we've done in the previous steps is stuff we will only do once. You'll see once we get to adding more use cases.

We can get to writing our UI code now.

Creating a UI Component That Interacts With a Use Case

This is your standard Angular coding procedure. We'll create a new component called counter under presentation/src/app.

I'm going to skip over the UI code and just show the controllers and how the use cases are used. You can see the code here if you're interested in it.

I will remove all the code generated by Angular from app.component and add my own. We need a button to create counters for now and a sort of structure to display them. I'll go with a basic scrollable list. Here's what our UI looks like:

I'm going to hook the blue button to a method in our component's controller in app.component.ts:

import { Component } from '@angular/core';

import * as core from 'core';

@Component({
    selector: 'app-root',
    templateUrl: './app.component.html',
    styleUrls: ['./app.component.scss'],
})
export class AppComponent {
    counters: core.Counter[] = [];

    constructor(private createCounterUsecase: core.CreateCounterUsecase) {}

    createCounter(): void {
        const newCounter = this.createCounterUsecase.execute();

        this.counters.push(newCounter);
    }
}

We have a list that stores all our counters and a method for creating a counter that pushes a new counter to the list after calling the use case. We inject the use case into the constructor using Angular's awesome dependency injection. Pretty neat, right?

Now we can press the add-counter button, and we'll see some stuff pop up in the list. (Again, I'm skipping over the actual HTML and CSS since they're not relevant).

Now press the refresh button, and… it's all gone. That's because we need to add a method in our controller that retrieves all the counters when the page loads.

For this, we also need a use case that does this. Let's get working.

We create a new use case under core/counter/usecases named get-all-counters.ts

import { Usecase } from "../../base/usecase.interface";
import { CounterRepository } from "../counter-repository.interface";

import { Counter } from "../entities/counter.entity";

export abstract class GetAllCountersUsecase implements Usecase<Counter[]> {
    abstract execute(): Counter[];
}

export class GetAllCountersUsecaseImpl implements GetAllCountersUsecase {
    constructor(private counterRepository: CounterRepository) {}

    execute(): Counter[] {
        return this.counterRepository.getAllCounters();
    }
}

We add a method to the repo interface for getting all counters:

import { Counter } from "./entities/counter.entity";

export abstract class CounterRepository {
    abstract createCounter(counterInfo: Counter): Counter;

    abstract getAllCounters(): Counter[];
}

Build core with npx lerna run build then implement this method in data's repo implementation:

import * as core from "core";

import { LocalStorageService } from "../common/local-storage-service.interface";

export class CounterRepositoryImpl implements core.CounterRepository {
    get counterIds(): string[] {
        const counterIds = JSON.parse(this.localStorageService.get("counter-ids"));

        /** for app being used for first time */
        if (counterIds == null) [];

        return counterIds.ids;
    }

    set counterIds(newIds: string[]) {
        this.localStorageService.set("counter-ids", JSON.stringify({ ids: newIds }));
    }

    constructor(private localStorageService: LocalStorageService) {
        try {
            this.counterIds;
        } catch (e: unknown) {
            this.counterIds = [];
        }
    }

    createCounter(counterInfo: core.Counter): core.Counter {
        this.localStorageService.set(counterInfo.id, JSON.stringify(counterInfo));

        this.addCounterId(counterInfo.id);

        return counterInfo;
    }

    getAllCounters(): core.Counter[] {
        return this.counterIds.map((id) => this.getCounterById(id));
    }

    private addCounterId(counterId: string): void {
        this.counterIds = [...this.counterIds, counterId];
    }

    private getCounterById(counterId: string): core.Counter {
        return JSON.parse(this.localStorageService.get(counterId));
    }
}

The repository implementation has become a bit complex now. There's probably a better implementation that can be done here (foreshadowing ;)).

Regardless, build data and move on to di, so we update the counter factory to account for our new use case:

import * as core from "core";
import * as data from "data";

export class CounterFactory {
    private counterRepository: core.CounterRepository;

    constructor(private localStorageService: data.LocalStorageService) {
        this.counterRepository = new data.CounterRepositoryImpl(this.localStorageService);
    }

    getCreateCounterUsecase(): core.CreateCounterUsecase {
        return new core.CreateCounterUsecaseImpl(this.counterRepository);
    }

    getGetAllCountersUsecase(): core.GetAllCountersUsecase {
        return new core.GetAllCountersUsecaseImpl(this.counterRepository);
    }
}

This was a lot simpler now that we already have the boilerplate code in place, right?

Finally, we inject our use case using Angular's di:

import * as core from 'core';
import * as di from 'di';

import { Provider } from '@angular/core';

import { LocalStorageServiceImpl } from '../services/local-storage-service';

const localStorageServiceImpl = new LocalStorageServiceImpl();

const counterFactory = new di.CounterFactory(localStorageServiceImpl);

export const CORE_IOC: Provider[] = [
    {
        provide: core.CreateCounterUsecase,
        useFactory: () => counterFactory.getCreateCounterUsecase(),
    },
    {
        provide: core.GetAllCountersUsecase,
        useFactory: () => counterFactory.getGetAllCountersUsecase(),
    },
];

Now we're ready to use this use case in app.component:

import { Component, OnInit } from '@angular/core';

import * as core from 'core';

@Component({
    selector: 'app-root',
    templateUrl: './app.component.html',
    styleUrls: ['./app.component.scss'],
})
export class AppComponent implements OnInit {
    counters: core.Counter[] = [];

    constructor(
        private createCounterUsecase: core.CreateCounterUsecase,
        private getAllCountersUsecase: core.GetAllCountersUsecase
    ) {}

    ngOnInit() {
        this.loadCounters();
    }

    createCounter(): void {
        const newCounter = this.createCounterUsecase.execute();

        this.counters.push(newCounter);
    }

    private loadCounters() {
        this.counters = this.getAllCountersUsecase.execute();
    }
}

We provide the use case in the constructor and then set it to be called in ngOnInit. Now, add a counter by pressing the button and refresh the page; the counters will persist! At least until we reset the browser storage.

So, to recap:

We created the use case in core
We implemented repo methods required by the use case in data
We set up a method to create the factory with its dependencies in di
We used Angular's di to provide the use case throughout the project in presentation
We called the use case!

Steps 1, 2, and 5 are the steps that mean something to us. The rest are glue and make-life-easier solutions.

Adding the rest of the use cases is just rinse and repeat. You can see how I've implemented the rest of them in this repo.

Testing

In this section, I'll provide an example of writing a unit test for the counter-repository implementation in data.

We do this by creating a new file under data/src/tests/counter named counter-repository.test.ts

import { Counter, CounterRepository } from "core";

import { LocalStorageService } from "../../common";
import { CounterRepositoryImpl } from "../../counter";

class MockLocalStorageService implements LocalStorageService {
    private storage = {} as any;

    get(key: string): string {
        return this.storage[key];
    }
    set(key: string, value: string): void {
        this.storage[key] = value;
    }
}

describe("Counter Repository", () => {
    let localStorageService: LocalStorageService;
    let counterRepository: CounterRepository;

    beforeEach(() => {
        localStorageService = new MockLocalStorageService();
        counterRepository = new CounterRepositoryImpl(localStorageService);
    });

    test("Should create a new counter and retrieve it later", () => {
        const newCounter: Counter = {
            id: "1",
            currentCount: 0,
            decrementAmount: 1,
            incrementAmount: 1,
            label: "new counter",
        };

        counterRepository.createCounter(newCounter);

        expect(counterRepository.getAllCounters()).toHaveLength(1);
        expect(counterRepository.getAllCounters()[0]).toStrictEqual(newCounter);
    });
});

Lines 6 to 15 are a basic mock implementation of the local storage service that counter repository implementation requires. We define the body of the test code in lines 17 to 40. Before each test block is run, the counter repository and its dependency are initialized, so we make sure our unit tests are run in a clean environment every time.

I've written a single test that creates a new counter and then sees if it's been stored by calling the method to retrieve all counters. The rest is up to you!

Closing Notes

We've covered quite a bit, and it may seem overwhelming at first. If you have trouble going through it the first time, give it another try and take things slow. Understanding what each layer is actually responsible for will help a lot in getting all the pieces to fall into place!

It's definitely a slower start than you may be used to, but once you get the basic steps, you'll appreciate the ease of knowing who is responsible for what, and which code lives where. Not to mention how much easier testing is made when everything is loosely coupled.

Finally, I would be very glad if someone gave me feedback on how I've done things here. Does it work for you? Is the balance between complexity and practicality good enough? Is there a big problem staring me in the eye that I'm missing? I'm completely open to constructive criticism, so let me have it!

Thank you for reading through this whole thing. I hope you find it very useful, and it brings you joy while programming as much it does for me.

References and Links

The Ultimate Clean Architecture Template for TypeScript Projects

Aziz — Sun, 14 May 2023 13:51:06 +0000

Intro

This is it. You’ve been looking for this all your life. Well, guess what? You’ve found it! The end to your pain, misery, and hours of debugging code written back in the days when you thought your app would be done in three hours. Or when you thought you were only making a demo app that wasn’t worth the effort. Or when you just didn’t know any better.

In this guide, I explain my approach to creating a TypeScript project template that implements clean architecture principles. This will probably work for any type of application that you can think of, including SPAs (Single Page Apps) with Angular, React, Vue, or other frameworks such as React Native or Electron. Basically, if it uses TypeScript, it will work.

Clean architecture is not just about following a couple of rules to make it slightly less painful to write an app. It’s about transforming your work environment to help you enforce proper architecture and dependency rules. You don’t allow yourself to, possibly at some point in the future, be lazy and completely ignore the rules just to make a feature as quickly as you can because it will come back to bite you in the butt.

What is Clean Architecture?

The idea behind Uncle Bob’s clean architecture (which I really recommend you give a read) is a separation of concerns. It allows your code to be independent of frameworks, databases, or UIs. It also makes your code more testable.

The diagram visualizes a core idea of clean architecture: the dependency rule. You’ll notice all the arrows point inwards toward Entities. This means that entities do not depend on anything, but everything depends on them. This is because entities represent your business rules and do not care whether you use Angular, React, Vue, etc.

In short, Enterprise Business Rules is the layer where you implement classes or models that define the core rules of your enterprise/application.

You interact with these Entities using the encompassing layer, which is Use Cases. They dictate data flow to and from entities. They allow the below layers to interact with the entities.

Next, Controllers interact with the use cases to produce output used in Presenters, as you can see in the bottom right section of the diagram. This is where Angular or React components would take place, assuming the role of both Controllers and Presenters.

Finally, you have details such as a database in the outermost layer. It’s implied that you can change these outermost layer details without having to change any of the circles on the inside. That makes sense, right? A Web framework, for example, doesn’t care if you’re using MongoDB, SQL, or even Blockchain. And, of course, use cases or entities are even further away from such tools.

A Detailed Implementation Guide

Before getting started, there are a few things to mention:

First, I divided the application template into four layers: Core, Data, Dependency Injection (DI), and Presentation.

Core: Contains our entities, use cases, and repository interface. This is what the application is at its core (hence the name).
Data: Contains implementations of core repositories for retrieving data from local and remote storage. This is how we get and store data.
DI: Ties Core and Data together, allowing Presentation to depend only on Core directly.
Presentation: This layer is how the user sees and interacts with our application. It would, for example, contain our Angular or React code.

Second, I preferred to use Lerna here because it gave me the least headache. There are alternatives like Yarn or Npm Workspaces, but they weren’t as easy as the current solution for me.

Finally, you may not agree with my approach in some sections, however, the beauty of this architecture is that you can swap anything for anything so long as your app core is unaltered and its dependencies are only towards itself.

Having said that, let’s start.

Creating Project Directories and Root

Create a folder for your project. I just called mine root
Inside this folder, create a folder named packages. Inside of that create three folders: core, data, and di.

You should now have something like the following:

Next, we have to initialize all of these. Inside of each root, core, data, di, do the following commands:

run npm init -y
create a tsconfig.json file. Use the configurations provided below.

For root tsconfig.json:

{
    "compilerOptions": {
         "module": "commonjs",
         "sourceMap": true,
         "allowSyntheticDefaultImports": true,

         "emitDecoratorMetadata": true,
         "experimentalDecorators": true,

         "noImplicitAny": true,
         "noImplicitOverride": true,
         "noImplicitReturns": true,
         "forceConsistentCasingInFileNames": true
    }
}

For core and data tsconfig.json:

{
    "extends": "../../tsconfig.json",

    "include": ["src/**/*.ts"],

    "exclude": ["node_modules"],

    "compilerOptions": {
        "baseUrl": ".",
        "rootDir": ".",

        "module": "ES2020",
        "target": "ES2020",
        "moduleResolution": "node",

        "outDir": "build/",

        "declaration": true,
        "declarationMap": true,
        "sourceMap": true,

        "plugins": [
            {
                "name": "@rollup/plugin-typescript"
            }
        ]
    }
}

For di tsconfig.json:

{
    "extends": "../../tsconfig.json",

    "include": ["src/**/*.ts"],

    "exclude": ["node_modules"],

    "compilerOptions": {
        "baseUrl": ".",
        "rootDir": ".",

        "module": "ES2020",
        "target": "ES2020",
        "moduleResolution": "node",

        "lib": ["ES6", "DOM"],

        "experimentalDecorators": true,
        "emitDecoratorMetadata": true,

        "declaration": true,
        "declarationMap": true,
        "sourceMap": true,

        "outDir": "build/",

        "plugins": [
            {
                "name": "@rollup/plugin-typescript"
            }
        ]
    }
}

Finally, we create presentation. You can do this one however you want. I just use the angular CLI to create it because it’s the framework I prefer. To initialize a project with the Angular CLI, run ng new in the packages dir and go through the steps according to your taste.

I also added .gitignore files to all packages as well as root to ignore node_modules and build by adding a /node_modules and a /build entry.

After all of that, you should have the following:

Configuring Core, Data, and DI

Next, we configure core, data, and di. They all follow the same initial configuration. So follow these next steps for all of them (or just do this for core, then copy and paste everything into data and di):

First, create a folder called src and add a file called index.ts in it. This file will be what exposes everything we want to export out of our package. Inside of src, create a folder called tests. This will contain all our unit tests for this package.

There are a few scripts and devDependencies we need to add to package.json. You can copy and paste the following (change the name of the package for data and di):

{
    "name": "core",
    "version": "1.0.0",
    "description": "",
    "scripts": {
        "build": "tsc --project tsconfig.build.json && npm run rollup",
        "build:watch": "nodemon -e ts --exec \"npm run build\" --ignore build/** --ignore tests/**",
        "rollup": "rollup -c",
        "test": "jest",
        "test:watch": "jest --watch"
    },
    "author": "",
    "license": "ISC",
    "devDependencies": {
        "@rollup/plugin-typescript": "^8.3.3",
        "@types/jest": "^28.1.6",
        "@types/node": "^18.0.0",
        "jest": "^28.1.3",
        "nodemon": "^2.0.19",
        "rollup": "^2.77.0",
        "rollup-plugin-dts": "^4.2.2",
        "ts-jest": "^28.0.7",
        "typescript": "^4.7.4",
        "tslib": "^2.4.0"
    },
    "main": "build/src/index.js",
    "types": "build/src/index.d.ts"
}

Notice the types property at the end of the file. This is necessary to allow this package to be importable and useable in other packages.

Here’s an explanation for each of those scripts:

build: builds your project, resulting in a build folder that contains index.d.ts which is going to enable this package to be imported into other packages.
build:watch: causes the project to rebuild on every change to the code
rollup: bundles your project’s types after the build. This is necessary to create an index.d.ts that includes correct declarations and exports.
test: runs all unit tests in your package
test:watch: reruns your tests on every relevant change. (see jest docs for more info)

Here’s an explanation for the devDependencies:

rollup, rollup-plugin-dts, and @rollup/plugin-typescript: a module bundler that is used to fix index.d.ts files into something more useful for our use case.
jest and ts-jest: for writing and running unit tests
nodemon: allows us to run a command whenever the code changes. See the build:watch script.
The rest are dependencies of TypeScript.

We need to add a couple more config files for rollup and jest. These files go at the same level as package.json. Here they are:

rollup.config.js:

import typescript from '@rollup/plugin-typescript';
import dts from 'rollup-plugin-dts';

import tsConfig from './tsconfig.json';

const config = [
    {
        input: "src/index.ts",
        output: [{ file: "build/src/index.js", sourcemap: true }],
        plugins: [
            typescript(
                {
                    sourceMap: tsConfig.compilerOptions.sourceMap
                }
            )
        ]
    },
    {
        input: 'build/src/index.d.ts',
        output: [{ file: "build/src/index.d.ts", "format": "es" }],
        plugins: [
            dts(
                {
                    compilerOptions: {
                        baseUrl: tsConfig.compilerOptions.baseUrl
                    }
                }
            )
        ]
    },
]

export default config;

jest.config.js

module.exports = {
    transform: { '^.+\\.ts?$': 'ts-jest' },
    testEnvironment: 'node',
    testRegex: '.*\\.(test)?\\.(ts)$',
    moduleFileExtensions: ['ts', 'js'],
};

One last thing: We don’t want our build to contain tests, so make a new file next to tsconfig.json called tsconfig.build.json. This is the file used in our build script in package.json. Its contents are the following:

{
    "extends": "./tsconfig.json",

    "exclude": ["node_modules", "src/tests"],
}

That’s it!

Each of your packages should look like this now:

We can do a test build of our packages now. To make things happen in the build, add any exports to your package’s index.ts file. For example: export const Foo = 1;

Now, run npm install && npm run build in each core, data, and di.

After this runs correctly, see that the build results are correct in your build/src/index.ts and build/src/index.d.ts files.

The project’s packages are ready now.

Setting Up the Mono Repo Configuration

Right now, we just have five non-related packages (root, core, data, di, and presentation). We need the root to act as the container for the other packages. To do this, we will use Lerna.

First, copy and paste the following config to your root package.json:

{
    "name": "root",
    "license": "ISC",
    "scripts": {
        "prestart": "npm install && lerna bootstrap",
        "start": "lerna run start",
        "test": "lerna run test",
        "build": "lerna run build",
        "graph": "nx graph"
    },
    "devDependencies": {
        "lerna": "^5.1.8",
        "nx": "^14.4.3",
        "tslib": "^2.4.0"
    }
}

Here’s a breakdown of the scripts:

prestart: This script automatically runs when you run npm start. It makes sure all dependencies for all packages are present and configured correctly.
start: Runs the start script for all packages under the packages directory.
test and build: same as start
graph: Creates an interactive dependency graph so you can visualize your project dependencies.

The dependencies for Lerna and NX are required because our scripts use these.

Next, there are a few config files for Lerna and NX, named lerna.json, and nx.json, respectively.

{
    "packages": ["packages/*"],
    "useNx": true,
    "version": "0.0.0"
}

{
    "tasksRunnerOptions": {
        "default": {
            "runner": "nx/tasks-runners/default",
            "options": {
                "cacheableOperations": ["build", "test"]
            }
        }
    },
    "targetDefaults": {
        "build": {
            "dependsOn": ["^build"]
        },
        "start": {
            "dependsOn": ["^build"]
        }
    }
}

You’ll notice in nx.json that we have a property named cacheableOperations. This makes it so that only packages with changes are rebuilt/retested. As your project grows, you will be more grateful for this feature.

Another thing you’ll notice is the targetDefaults containing two entries: one for start and one for build. The config in here makes it so that if package A depends on package B, then package A’s start will only run after package B’s build, and so on and so forth. If it’s not obvious right now, you’ll see why this is necessary in the next section.

Setting up dependencies between packages

There’s one last step, and we’re done. We still haven’t told data, presentation, and di that they depend on core. We’ll do that next.

Inside of data/package.json, add the following property above devDependencies: dependencies: { "core": "*" }

Inside of di/package.json, add the following property above devDependencies: dependencies: { "core": "*", "data": "*" }

Inside of presentation/package.json, add the following property above devDependencies: dependencies: { "core": "*", "di": "*" }

NX and Lerna are smart enough to make sure core, data, and di are built before presentation starts because presentation depends on those other packages.

We are officially finished! Run npm start in root and watch the magic happen.

If you encounter any errors, remove all package-lock.json and node_modules from all folders, then run npm start again.

Here’s the finished implementation of all of the above instructions.

How Do I Use This Masterpiece of a Mono Repo?

You can read my article that explains how to use this template step by step. You can find the link here.

Why I Did Things the Way That I Did

I’ve been trying to find a good approach to do this for a while. I’ve considered the quickest approach by dumping everything under one package and trusting myself to respect the rules because I’m a good programmer (or so I like to believe), but that wasn’t good enough for me.

I needed something that made sure the rules weren’t being broken. By rules, I’m, of course, talking about the dependency rules. We cannot allow entities to be dependent on a database, nor can we allow entities to be dependent on UI code. I tried to solve this by including some scripts that would throw errors when dependencies were made between the wrong things (using dependency-cruiser), but it was way too finicky. And it would show errors too late.

So, I decided to divide each application layer into its own package. Complete with its own package.json and tsconfig.json and a configured bundler. I put all these layers together using Lerna and NX. This way, a package can never depend on something it shouldn’t, “accidentally” or otherwise, without it being present in its package.json dependencies. It has become a work of art, if I do say so myself.

Extras

I recommend you utilize VS Code workspaces when working with a mono repo such as the one we just made.

When you use VS Code workspaces, you can fully use syntax highlighting and workspace-specific extensions by allowing VS Code to treat each VS Code separately from the rest.

VS Code only cares about the tsconfig.json file in the root of your project. That means it completely disregards each of the tsconfig.json files in each of our packages, causing false positives to appear in your problems section. Workspaces save you from that.

Thank you for reading!

References and Links

TypeScript Runtime Type Checking

Aziz — Mon, 24 Apr 2023 20:15:56 +0000

Intro

Typescript is the best thing to happen to Javascript since the Great Callback Pyramid crumbled.

We got types, autocomplete, compile-time issue catching, and the world was finally at peace, until someone decided to use instanceof (yes it was me).

You see, even though we got all of the aforementioned goodies, there are still a few quirks of the typescript type system that may fly under the radar since they don't arise often, especially when you're writing relatively simple applications.

In this article, I want to dive into the topic of objects. Specifically, the different ways an object can be instantiated, why they matter, and how the instanceof operator can be used / misused.

I'll back everything up with a practical example about error handling, and show you how we can get the flexibility of typescript's structured typing system with the power of runtime object type checks.

An Example Use case

You're a frontend dev and you've been asked to implement error handling for an application. Let's say for this application that the types of errors you need to handle are:

authentication errors
backend errors
any uncaught errors that don't fit into the previous two types.

Let's see how we would implement something for that.

1. What if we only used typescript?

Like a good developer, we start things simple by creating a type for each of our errors:

type AuthError = { reason: string };

type BackendError = { reason: string };

type UnknownError = { reason: string };

Right out of the gate, we have a few major issues:

To typescript, these are all the same thing
To javascript, these don't even exist
Code Repetition

Let's move on to something better.

2. What if we used classes?

Good idea! After all, classes are also available during runtime which solves the second issue.

class AuthError {
    constructor(public reason: string) {}
}

class BackendError {
    constructor(public reason: string) {}
}

class UnknownError {
    constructor(public reason: string) {}
}

We still have two issues. These are still the same thing for typescript, and we're still repeating ourselves.

The code repeating issue is simple enough to take care of. We can make a super class and have the others extend it:

class CustomError {
    constructor(public reason: string) {}
}

class AuthError extends CustomError {}

class BackendError extends CustomError {}

class UnknownError extends CustomError {}

The code above is perfectly valid. Though typescript can't tell the difference, maybe we don't need it do! After all, we can use instanceof and the following code works perfectly fine:

function handleError(error: CustomError) {
    if (error instanceof AuthError) {
        // do something
    } else if (error instanceof BackendError) {
        // do something
    } else if (error instanceof UnknownError) {
        // do something
    }
}

Great! Now we took care of all issues we mentioned before, but the article is not finished yet. Uh oh. Something is about to change your view about something in javascript.

The issue is hidden in how instanceof works.

In the simplest terms, someObject instanceof SomeClass returns true if someObject was created by or inherits from SomeClass's constructor, meaning there has to be a new keyword in their somewhere. Big deal, so what? We'll just throw our errors like this:

throw new AuthError('Session is expired or something');

Okay. fair enough, except that this is the wild untamed land of javascript, where you could also do this:

throw { reason: 'Session is expired or something' };

Zero warnings. Zero errors. But that's the not even the worst part. You've just lost the ability to check this at runtime:

const errorObj: AuthError = { reason: 'Session is expired or something' };

console.log(errorObj instanceof AuthError); // -> False

instanceof does NOT work when you don't use instantiate objects with the new keyword.

Even though this is a rather unlikely issue, I've personally lost faith in instanceof. Whenever an issue happens in this area of the code, a little voice in my head will keep telling me "What if it's because of that really rare bug you read about once?"

We need a different approach. One that saves us from the quirks of javascript, and allows typescript to truly shine.

3. Back to types again

Introducing tags! A tag is simply a property with constant value which placed in a type, allowing us to confidently narrow the type of a given object during both compile-time and runtime.

Here's how we could define our errors now:

type AuthError = {
    reason: string,
    errorType: 'auth-error', // <- tag
};

type BackendError = {
    reason: string,
    errorType: 'backend-error', // <- tag
};

type UnknownError = {
    reason: string,
    errorType: 'unknown-error', // <- tag
};

type CustomError = AuthError | BackendError | UnknownError;

Interestingly, CustomError is now on the bottom of our hierarchy instead of at the top. Using the | (union) operator, we tell typescript that a CustomError is one of any of the given types. We are able to narrow which one it is exactly using the tag.

Here's how the handleError function can be re-written:

function handleError(error: CustomError) {
    switch (error.errorType) {
        case 'auth-error':
            // ...
        case 'backend-error':
            // ...
        default:
            // ...
    }
}

The coolest part? Typescript is helping you along every step of the way, and is fully aware of exactly the type of error you're handling.

Note that for this to work, the tag needs to have the same name for all the types (errorType in the above example).

If you're interested in how to print the types this way (using // ^?) check out this extension (I'm not affiliated, just think it's awesome).

Now it wouldn't even matter if we rawdog it and throw objects directly. Typescript would get mad and force us to add a tag:

// ERROR: Property 'errorType' is missing in type '{ reason: string; }' but required in type 'AuthError'.
const errorObject: AuthError = {
    reason: string;
};

throw errorObject;

Conclusion

In conclusion, this article underscores the importance of understanding Typescript and Javascript type systems explained with an error handling example.

Through a step-by-step exploration, we discovered that using tags is a powerful, reliable solution. This approach takes advantage of Typescript's structured typing system and allows for runtime object type checks, resulting in more robust and maintainable code.

By mastering these nuances, we can fully harness Typescript's potential while avoiding language pitfalls.

For more insight into typescript, I highly recommend the Effective Typescript book by Dan Vanderkam.

VS Code Shortcuts To Code Like You're Playing a Piano

Aziz — Fri, 13 Jan 2023 18:06:02 +0000

I’ll be honest, being fast while programming is half the reason I even code anymore (Jk. Unless...). Anyway, I’ve found the thing that made me become a lot quicker was divorcing my hand from the mouse. Think about it, every time you have to move the mouse, you have to do these things:

Move your hand from the keyboard to the mouse (ouch, my shoulders)
Find where that dagnabbin’ cursor went to
Physically move the cursor to where you need and click
Move your hand back to the keyboard (again, ouch, my shoulders)

Here are my top shortcuts that will make you feel like you’re playing the piano while you’re coding:

Multiple Cursors

Quickly create multiple cursors to change multiple sections of code

What’s the quickest way to increase your code output? Simple! Add more cursors!! Now you can write infinitely more code in the same time! More code = more better!

Linux: Ctrl + Shift + Arrow Up / Arrow Down
Windows: Ctrl + Alt + Arrow Up / Arrow Down
Mac: Cmd + Opt + Arrow Up / Arrow Down

Select Next

Select the next occurrence of whatever you have currently selected

You want to change that one string in multiple places, and you knew you should’ve set it as a variable somewhere and reused it, but here we are anyway. Do you use an overkill find and replace or put your hand on the forbidden device known as the mouse? Blasphemy!

Linux / Windows: Ctrl + D
Mac: Cmd + D

Undo Select Next

Rollback the last select-next by one step

You have discovered the power of select next, but perhaps too early. If you see yourself going mad with power and next-selecting things you shouldn’t have, this one is for you!

Linux / Windows: Ctrl + U
Mac: Cmd + U

Scroll the Screen Without Moving The Cursor

Keep your cursor in place while scrolling up and down in your code

Sometimes you want to hide the crappy code you wrote above so you can focus on a brighter future. “I will refactor it later,” you say. A lie. but you already knew that. So, why face the facts when you can scroll, scroll, scroll your shame away?

Linux / Windows: Ctrl + Up Arrow / Down Arrow
Mac: Ctrl + Fn + Up Arrow / Down Arrow

Jump Word

Move your cursor one word at a time instead of one char at a time

Your days of holding the right or left arrows for what feels like an eternity are over. One click, one word. Elegant.

Linux / Windows: Ctrl + Left Arrow / Right Arrow
Mac: Opt + Left Arrow / Right Arrow

Select Word

Jump one word and select it at the same time

Maybe that word has done you something wrong. Who knows. Regardless, you can show it who’s boss by selecting it in one go and nuking it to oblivion (or whatever your mastermind has in plan).

Linux / Windows: Ctrl + Shift + Left Arrow / Right Arrow
Mac: Opt + Shift + Left Arrow / Right Arrow

Jump To End or Beginning

Instantly go to the beginning or end of code on your current line

You wake up in the morning, turn your workstation on, and open your code editor. You find your cursor at the end of a line, but you need it at the beginning. Sigh, you say to yourself, “Guess I’ll get some things done while that’s happening.”

You place a rock on your left arrow and go on with your day. You shower, grab a cup of coffee, decide for two hours what music playlist you’re listening to for the day, go through ten meaningless corporate meetings, and then return to your code editor.

You remove the rock off your left arrow, and to your rejoice, you have finally reached the beginning of the line. Save yourself an eternity by using this shortcut.

Linux / Windows: End / Home
Mac: Cmd + Left Arrow / Right Arrow

Select Till End or Beginning

Instantly select all code until the beginning or end of your current line

People throughout history have done much with power they’ve accumulated over their lives. Genghis Khan, Attila the Hun, Spider Man, etc. These people have used their power in various destructive ways. None of it compares to what this shortcut allows you to do. Use it wisely.

Linux / Windows: Shift + End / Home
Mac: Cmd + Shift + Left Arrow / Right Arrow

Expand / Shrink Selection

Expand the scope of your selection to include more / less scope (i.e string, function, etc.)

Only the cool kids use this one.

Linux / Windows: Alt + Shift + Left Arrow / Right Arrow
Mac: Ctrl + Shift + Left Arrow / Right Arrow

Show / Hide Terminal / Go back to code

Toggle terminal focus / visibility and move focus back to your code

Sneak a peek at your failing build every once in a while. Yup, still failing. Let’s just close that real quick.

Linux / Windows: Ctrl + J for terminal, Ctrl + 1 for code
Mac: Cmd + J for terminal, Cmd + 1 for code

Split Terminal

Split the terminal into two or more panes visible at the same time

Studies show that people with more terminals on at a given time are better hackers. It’s just a fact. Accept it. Embrace it.

Linux / Windows: Ctrl + Shift + 5
Mac: Ctrl + Cmd + Opt + * (star)

Conclusion

I solemnly swear I have not touched my mouse during the making of these demos.

You’ll know you’re starting to become better when you see dust building up on your mouse. Also, don’t forget to buy the loudest mechanical RGB keyboard you can find. That’ll scare away the mouse users!

What’s your favorite / most used shortcut?