DEV Community: Charles Szilagyi

End-to-end Type Safety in Clean Architecture

Charles Szilagyi — Fri, 22 May 2020 10:23:56 +0000

Let's create a completely type-safe web application in a Clean Architecture using a couple of modern libraries. Such systems are orders of magnitude more reliable than the untyped counterparts. Plus, they are easier to understand, maintain and refactor. Tech: TypeScript, GraphQL, MongoDB, React.

💡 The sample code is on Github: https://github.com/thekarel/best-practices-example

End to End Type Safety

In this post I show you how to build a full-stack web application that is type-safe across all layers of the architecture: from the domain models to the services, repositories, the HTTP transport layer (GraphQL) and client-side UI. It's more than just typing up every interface in the codebase: in this example, all significant interfaces and types are derived from higher-order ones - usually from the domain modules.

There is only a single source of truth for types

This means that changes to high-level interfaces cascade through the whole stack. The type checker will be able to spot a mismatch in any one of the layers.

Benefits

The practical benefits are pretty significant:

The linter warns you of potential bugs before you even run a test or let alone build the app
You need to write far fewer unit tests than otherwise because the whole codebase relies on interconnected type definitions.
The codebase is easier to understand as the same interfaces are repeated (maybe with slight modifications)
Since everything is typed the code is self-documenting
When you change the code - fix, refactor or improve - you get instant feedback about the health of your codebase in the IDE or by running tsc.

Experience shows that even large refactoring can be successfully done on such codebase, solely based on static type checking. Of course, it is not a substitute for End-to-end tests.

All in all, I think such stack eliminates some significant sources of bugs that would otherwise exist because the codebase complexity exceeds a limit. We're incapable of remembering every data shape, type and interface. Apart from fewer bugs, you'd also benefit from higher confidence and faster development throughput. Win-win?

Clean Architecture TL;DR

The architecture of this example follows Clean Architecture principles.

This, in a nutshell, means that:

The app is sliced into layers, starting from the deepest: domain (entities), services (use cases), transport (GraphQL in this case), repository (abstraction over MongoDB), UI (React, closest to the user)
There is a strictly unidirectional dependency arrow: layers that are deeper in the stack can never refer to any code in outer layers

The second rule implies that the domain module will never import or refer to anything defined in other layers. The services receive "tools" to get and save data (etc.) via dependency injection. The repository can know about domain entities (but not much else). The transport layer is a smart cookie and knows about the domain, services and repositories (this is the dependency injection root). The UI, ideally, is limited to the GraphQL types, and maybe the domain entities.

The original Clean Architecture diagram. Image from https://blog.cleancoder.com/uncle-bob/2012/08/13/the-clean-architecture.html

Head over to https://thekarel.gitbook.io/best-practices/the-big-picture/architecture for a detailed treatment.

Tech Stack

Reminder: there is a complete example available at https://github.com/thekarel/best-practices-example

The technologies and libraries I use are the following:

I assume you are relatively familiar with most of these tools already. I'll focus on two libraries that are probably not so widely used and also highlight a couple of essential solutions.

Let's look at each layer one by one and see how this stack hangs together.

Layers

Domain

Technically this is the simplest slice of the stack. The entities are pure TypeScript interfaces. For example, an Order looks like this:

import {Cupcake} from '../cupcake/Cupcake'

export interface Order {
  id: string
  customerName: string
  deliveryAddress: string
  items: Cupcake[]
}

The corresponding Cupcake is

import {Feature} from './Feature'
import {Kind} from './Kind'

export interface Cupcake {
  kind: Kind
  features: Feature[]
  name: string
}

The critical fact is that all subsequent layers will refer back to these definitions in some shape or form.

Services

The Service layer, also known as Use Cases defines the possible operations on our entities. In this example, these include creating and reading Orders.

The domain entities are very abstract, but you might be thinking: creating an order is a concrete operation and must be able to talk to a database etc. This fact seems to contradict the dependency arrow rule mentioned above.

Dependency Arrow Rule: Layers that are deeper in the stack can never refer to any code in outer layers

The solution is to define dependency interfaces in the Service layer. For example, the OrderService defines an OrderRepository interface. This way the service itself will not have to know anything about the way orders are stored, but can dictate the shape of data going in and coming out of a repository - the rest is an implementation detail, from this point of view:

import {Order} from '@cupcake/domain'

export interface OrderRepository {
  connect(): Promise<void>
  save(order: Order): Promise<void>
  load(id: string): Promise<Order | undefined>
  all(): Promise<Order[]>
}

In terms of end to end type safety, please note how the save method takes a domain Order and similarly how the load method returns one. This ensures that we can use different storage methods without breaking the contract (see below).

The domain interfaces reappear in similar ways across the whole stack.

Repository

As hinted above, the repository is a data persistence abstraction. Since it implements a higher-level interface definition, we can use different storage strategies in our app depending on the circumstances. Compare the following two repository implementations: one saves into memory, the other into a real database:

OrderRepositoryMemory

import {OrderRepository} from '@cupcake/services'
import {Order} from '@cupcake/domain'

export class OrderRepositoryMemory implements OrderRepository {
  private orders: Map<string, Order> = new Map()

  async connect() {
    return
  }

  async save(order: Order) {
    this.orders.set(order.id, order)
  }

  async load(id: string) {
    return this.orders.get(id)
  }

  async all() {
    return Array.from(this.orders.values())
  }
}

OrderRepositoryMongo

import {Order} from '@cupcake/domain'
import {OrderRepository} from '@cupcake/services'
import {Collection, MongoClient} from 'mongodb'

export class OrderRepositoryMongo implements OrderRepository {
  client: MongoClient
  dbName = 'cupcakes'
  collectionName = 'cupcakes'
  collection?: Collection<Order>

  constructor(private readonly url: string) {
    this.client = new MongoClient(this.url, {useUnifiedTopology: true})
  }

  async connect() {
    await this.client.connect()

    this.collection = this.client.db(this.dbName).collection<Order>(this.collectionName)
  }

  async save(order: Order) {
    if (!this.collection) {
      throw new Error('Connect first')
    }

    await this.collection.insert(order)
  }

  // etc
}

Look at the example codebase to see how different repositories are injected

Another equally important fact to note is that all type definitions are picked up from the domain and services layers.

Probably the most significant feature in the type safety context is the fact that we enforce the database documents' shape to match the domain entities:

this.collection = this.client.db(this.dbName).collection<Order>

This is to ensure the primary rule of persistence in Clean Architecture:

A repository takes a domain entity and returns a domain entity or a list of entities

The type-safety of the database layer itself is an important fact: it guarantees that the data entering our system (from the outside world) will match the expected domain shape. In other words, we ensure that everything inside the application boundaries is of known shape.

GraphQL

The example codebase uses GraphQL as the transport layer solution.

GraphQL types are sometimes defined using the "GraphQL schema language", for example:

type Customer {
  name: String!
  address: String!
}

Using the schema language has one serious disadvantage: it's not possible to refer to domain types using GraphQL's schema. It's time to look at...

TypeGraphQL

TypeGraphQL allows us to define GraphQL schemas using TypeScript classes. Using implements we can then refer back to domain interfaces. For example, this is how a Cupcake interface looks like in the example Graph:

import {Cupcake as DomainCupcake, Order as DomainOrder} from '@cupcake/domain'
import {Field, ID, ObjectType} from 'type-graphql'
import {Cupcake} from '../cupcake/Cupcake'

@ObjectType()
export class Order implements DomainOrder {
  @Field(() => ID)
  id!: string

  @Field()
  customerName!: string

  @Field()
  deliveryAddress!: string

  @Field(() => [Cupcake])
  items!: DomainCupcake[]
}

Generating the final schema from these classes is trivial (don't worry about the container, it has nothing to do with type-safety):

import {AwilixContainer} from 'awilix'
import {buildSchemaSync} from 'type-graphql'
import {OrderResolver} from './order/OrderResolver'

export const generateSchema = (container: AwilixContainer) =>
  buildSchemaSync({
    resolvers: [OrderResolver],
    container: {
      get: (constructor) => container.build(constructor),
    },
  })

The Graph imports the domain type definitions and turns them into strong guarantees: anyone sending a Cupcake to the server must conform to the domain schema (or the request is rejected). What we achieve with this is significant the same way as it was for the repository: the data coming into our system from the outside world is guaranteed to match our expectations.

The data coming into our system from the outside world is guaranteed to match our expectations

UI

The example app uses a React UI - but any UI library would work.

The crucial question is instead, how do we map from our Graph or domain entities to definitions that are useable in the UI?

Ideally, the UI only knows about the Graph interfaces: these are the "things" that are sent towards the client, and in turn, this is what the client sends back.

Ideally, the UI only knows about the Graph interfaces

GraphQL being what it is, there are other, more intricate questions concerning queries and mutations - it can get complicated quickly. Manually copying all these interfaces from Grap to the UI codebase, and keeping them updated is hopeless.

Hence, we look at the last piece of the puzzle: generating static TypeScript types from GraphQL schemas.

GraphQL Codegen

GraphQL Code Generator is a CLI tool that can generate TypeScript typings out of a GraphQL schema.

The implementation is relatively simple and it only touches the UI project.

First, define a configuration file in ui/codegen.yml\:

schema: http://localhost:8888/
generates:
  src/graphQLTypes.ts:
    hooks:
      afterOneFileWrite:
        - prettier --write
    plugins:
      - typescript
      - typescript-operations
config:
  namingConvention:
    enumValues: keep

Add a command to package.json:

  "scripts": {
    "typegen": "graphql-codegen"
  }

When you know that the GraphQL schema has changed - this is easy in a monorepo - run the typegen command in the UI to generate a local type definition of the Graph types. You commit these to the codebase just like any hand-written code.

Having access to these types enables UI components to refer to the Graph types when making a request or creating a payload:

import {Feature, Kind, MutationCreateOrderArgs, Query} from '../graphQLTypes'

// later
const [fetchOrders, ordersFetchStatus] = useManualQuery<{orders: Query['orders']}>(ordersQuery)
  React.useEffect(() => {
    fetchOrders()
  }, [])


  const dumbOrderArgs: MutationCreateOrderArgs = {
    deliveryAddress: 'New York',
    customerName: 'Mr. Muffin',
    items: [
      {kind: Kind.savoury, features: [Feature.sugarFree], name: 'One'},
      {kind: Kind.sweet, features: [Feature.vegan], name: 'Two'},
      {kind: Kind.sweet, features: [Feature.exclusive], name: 'Three'},
    ],
  }

The End

As with any code example, this is a slight simplification. Life is always a bit different and undoubtedly more challenging. I haven't touched the topic of evolving interfaces (data shapes), for example. Still, I think these ideas and tools provide a solid foundation to build on.

Relying on clean architecture and a type-safe codebase will make the products we make better and our lives more comfortable at the same time.

The more complex you build, the more type safety you need!

Have I missed something? Please let me know!

Using OS X Without the Mouse

Charles Szilagyi — Mon, 18 May 2020 07:40:21 +0000

Moving away from the trackpad or mouse is not a one time toggle though - it's a process that takes time for everyone. Let's get started on macOS and see what tools are out there to help you along your journey.

Learn Keyboard Shortcuts

This one is too obvious, still often overlooked: if you repeatedly reach for the mouse to do a particular action, try to find the relevant shortcut in your app.

For system-wide hotkeys, check out the official Mac keyboard shortcuts.

Browse commands

A powerful key combination you might want to keep in mind is ⌘⇧\: it lets you search all the shortcuts of the current app plus run the commands, or simply navigate the menus with the keyboard.

Use the ⌘⇧\ shortcut to navigate app menus and run commands

CheatSheet

There is a free app called CheatSheet that can show you all the shortcuts available in the current window by holding the command ⌘ key.

You can even print the hotkey list for future reference if you like.

Take it easy

You might be overwhelmed at first, but remember: learning takes time. Don't try to memorise every key combination at once. Just let the ones you often use become second nature, then pick up new ones as you go.

The Scary but Powerful: Vim mode 🙀

Vim is the infamous editor you can't get out of, right? Well, I'm not saying you should use Vim as your primary editor. There are better alternatives nowadays IMO, although it's still the most powerful text editor probably and it's not that hard to pick up.

What I'm suggesting though, is to learn the basic movement and command keys of Vim mode. It's a brilliant, comfortable and efficient way of using the keyboard. It is probably the fastest way to deal with text editing and writing source code. It has been around for 28 years since Vim came out (!), and seems like there are no significantly better alternatives for now.

You can get started with learning just a handful of shortcuts:

Move left, down, up, right: h, j, k, l.
Go to the top of the document: gg (G takes you to the end).
Go to insert mode so you can type any text: i.
Exit insert mode and go back to "navigate" again: ESC.

Don't believe the hype; it's not that difficult 🤓

There are countless more tricks, shortcuts and all sorts of magic you can do with Vim. The main thing to appreciate though is that the modal nature of Vim mode allows you to keep your hands on the home row of the keyboard so that you can touch-type without interruption. You will need to pick up the mouse a lot less often.

As you'll see below, a lot of new solutions borrow from Vim's keybindings. Even Gmail has matching hotkeys!

Vim mode in VS Code

Probably all source code editors and IDEs support Vim mode in some form. I use VS Code nowadays (who knew?) and probably the first extension I have installed was VSCodeVim.

VSCodeVim is a Vim emulator for Visual Studio Code.

Combined with the flexible shortcuts of the IDE itself, VSCodeVim allows me to create and change source code fast - significantly faster than otherwise. The navigation inside and between files is also brilliant.

For a quick overview, check out Using VSCode with the VIM Extension by Richard Bagshaw:

Some of my favourite and most often used features are:

gd jumps to the definition of the symbol (variable, function, import etc.)
gh displays the linter warning/error on the current line.
Jump to the line I'm looking at by using relative line numbers and typing something like 15k (15 lines up).
Being able to change code inside parens, curly braces or an HTML/React tag with ci(, ci{, cit respectively. You can also change the whole block with ca(, ca{ or cat.

Plus, the usual, basic editing tricks:

Adding to the beginning or end of a line with I or A
Adding a new line below or above with o or O.
Copying, deleting or changing the whole line with yy, dd, cc
Finding character in the current line with f, e.g. f( to jump to the next (.

Clicking on Things with Vimac

Vimac is a fantastic app by Dexter Leng that allows you to "Stop using your clunky trackpad/mouse now" on Mac OS.

By pressing a shortcut, you're presented with a "hint" to every interactive element on the screen. Next, you tap the hint keys to simulate a mouse click - without touching the mouse! 🐭

There are modifiers to simulate right-click or ⌘-click, plus you can turn on Vim-like scrolling for lists inside apps.

I strongly encourage you to give this gem a try: https://vimacapp.com.

XEasyMotion

A little tool I'd also recommend and still use for clicking on the screen is XEasyMotion

It opens a crosshair on your screen so you can click on anything you'd like, even if it's not interactive. You move the crosshair with hjkl by the way 😉

Gif from https://github.com/h2ero/XEasyMotion

Clicking on Internet Things with Vimium

Another spiritual successor of Vim is Vimium - The Hacker's Browser.

Vimium works similarly to Vimac, but inside your browser: after installing the extension for Chrome or Firefox you can press a shortcut - f by default - then type the letters of the hints where you'd like to click.

You won't appreciate how easy and comfortable browsing becomes until you give Vimium a try!

Productivity apps

Of course, there are many power tools out there designed to help simplify your life and make you faster. Here are some of my favourites.

Launchbar

Launchbar is an application, file, folder (etc.) launcher with fuzzy search, an elegantly simple interface and a staggering amount of features.

After pressing the designated shortcut, you can start typing the name of the "thing" you'd like to open. Launchbar can naturally open applications, files or folders anywhere on your Mac. Plus, there are many other entities you can manage: contacts, calendar events, bookmarks, search engines, songs, calculations, text snippets, data from 3rd party apps and so on. It's a powerful tool 💪!

The features I'm using the most are:

Opening and switching between apps - it can even replace ⌘+TAB!
Opening files and folders: every file and folder takes the same time to open, just press a few (fuzzy) letters
Looking up previous clipboard entries and pasting them again and again
Use ClipMerge to copy multiple things to the clipboard so I can paste them in one go
Inserting pre-defined text snippets, so I don't have to repeat myself over and over again - and it works in any application

I've been using Launchbar for over five years now. These nano-optimisations seem to add up:

Alfred

Thanks to @euperia for drawing my attention to Alfred:

Its like Spotlight on steroids. You can extend it with add-ons to do things like play/pause/skip spotify, generate passwords, perform google searches etc - all without needing to take your hands off the keyboard.

Sounds brilliant!

Keyboard Maestro

Finally, a tool that sports a less impressive UX but allows you to automate anything on your computer: Keyboard Maestro

In their own words:

Automate applications or web sites, text or images, simple or complex, on command or scheduled. You can automate virtually anything.

This one is an advanced tool, and the possibilities are truly limitless - at least I couldn't find the limits yet. Just to highlight a few things you can achieve:

Remap keys
Record interactions with an app or website and replay it
Fill out forms
Click on images on the screen
Replay activity for screencasting :)

Check out a few tips and use cases in this video:

Desktop managers

The way macOS manages windows is just plain annoying. By default, new apps appear at random places, overlapping each other, forcing you to move them manually. We can do better than that!

Rectangle

When on a smaller screen, I've used Spectacle for a very long time. This little tool allows you to snap windows to edges or corners of the screen, or to make them centred or full-screen (and so on), with keyboard shortcuts.

Recently it was announced that Spectacle is not maintained anymore and apparently Rectangle is a great replacement:

With Rectangle, you can optimise the screen real-estate, de-clutter your desktop and quickly snap new apps to your preferred location, all without touching the mouse. A highly recommended tool!

Amethyst

When working on a large display, like a 34" ultra-wide monitor, I've found even manual window snapping is sub-optimal. So at the moment, I'm running Amethyst - a tiling window manager for macOS.

Essentially, when you run a tiling window manager, instead of manually managing the windows, they are positioned automatically on the screen in tiles (surprise!), so they never overlap.

You can then use keyboard shortcuts to move them around, change the focus etc.

While it takes a little getting used to such a desktop, I've found it to be more comfortable so far than having to worry about manually positioning windows repeatedly.

Do you have any #mouseless tips and tricks you'd share? Let me know!

Debug anything: React in TypeScript with Parcel 📦

Charles Szilagyi — Mon, 11 May 2020 06:14:56 +0000

Get the code

You can skip ahead if you already have a React, TypeScript and Parcel project. Otherwise, let's check out the example code:

git clone git@github.com:thekarel/debug-anything.git
cd debug-anything/parcel
yarn # or npm i

Code structure

The application itself is elementary: you'll see a list of fake blog post titles, clicking on a title will fetch the body of the post and display it above the list.

The code in this folder is, as usual, kept as simple as possible so that we can focus our attention on the debugger. In a production app, we'd use a human-friendly folder structure. The entry point is index.html which pulls in index.tsx and runs the basic React app.

You should focus on the following files:

Post.ts # The Post interface type
Posts.tsx # The post-list React component 
index.html # The entry-point
index.tsx # The React app
postRepository.ts # Data fetching module

Less than 100 lines altogether, so don't expect anything revolutionary 😉

Parcel

You might be wondering where is the Webpack or Babel configuration file? Well, there's none! Since Parcel is a zero-configuration bundler, we can just tell it to compile the code, and it Just Works all the time. I find it easier to work with than other solutions like Create React App as it's so simple and fast.

In this example, we can bundle the whole React app, written in TypeScript, by simply pointing Parcel to index.html - and that's all the plumbing we need. One less thing to worry about. Deserves a star ⭐️ on GitHub 👍

Note: this example code uses Parcel 2 alpha 3.

Dev server

Let's start the dev server with yarn start or npm start:

╰─$ yarn start 
yarn run v1.22.4
$ parcel index.html
ℹ️ Server running at http://localhost:1234
✨ Built in 548ms

Make sure you can visit http://localhost:1234

The "app" fetches the list of posts on start, then grabs the selected post's title from the server.

Configure the debugger

What we'd like to achieve in terms of debugging, is to be able to set breakpoints in VS Code, launch a debug browser and step through the initial list fetch and subsequent remote requests.

To make this as easy and comfortable as possible, we'll take advantage of the launch.json configuration file. It's actually all prepared for you 😌

Let's look at .vscode/launch.json and focus on the React+TS, Parcel section:

{
    "type": "chrome",
    "request": "launch",
    "name": "Debug React, TS, Parcel app in Chrome",
    "url": "http://localhost:1234/",
    "webRoot": "${workspaceFolder}/parcel",
    "pathMapping": {
        "__parcel_source_root": "${workspaceFolder}/parcel"
    },
        "skipFiles": [
        "${workspaceFolder}/parcel/node_modules/**/*.js",
        "<node_internals>/**/*.js"
    ]
},

The config is very similar to our Create React App example, by the way.

The type and request parameters tell VS Code to start debugging in a new Chrome window. It will use an empty profile by the way, without extensions or personal settings.

The name of the launcher will appear in the debug toolbar, plus the status bar of the IDE, after the 1st run:

The url needs to match the address where our dev version is served (http://localhost:1234/ by default).

webRoot: the filesystem path that matches the root of the dev server. It is usually the folder where the entry point is kept - in our case the folder where index.html is. Keep in mind that the example code repo houses multiple small projects. In a single-project repo, "webRoot": "${workspaceFolder}/src" is a good first guess.

pathMapping: this option is required in our case, as Parcel serves up a source-map that makes it look like the original files are under /__parcel_source_root. Without this setting VS Code would be unable to map breakpoint locations in the source to runtime code:

Check your pathMapping if you encounter "Breakpoint set but not yet bound" issues

You can find the correct path in the debug browser by the way. In Chrome, open the dev console and go to Sources:

Finally, we set skipFiles so that the debugger never steps into 3rd party or core Node.js modules. Skipping such files is useful if you want to focus on your codebase and are not interested in spending time looking at library code—a highly recommended tweak.

React + TypeScript debugger in action

Make sure the dev server is running, then launch the debug browser:

Let's add two breakpoints: one inside the fetchBody function, another into the useEffect hook:

Now we can restart the debugger (not the server!) and check the hook's behaviour when the component is mounted first:

Next, we can follow the code flow of fetchBody - note how we never see any core or 3rd party libraries (like Fetch or React internals):

Hopefully, you'll be able to implement a comfortable debug workflow in your React/TypeScript app based on this template ✌️

Have any tips or comments to share? Let me know!

Debug anything: Browser-based React apps

Charles Szilagyi — Mon, 04 May 2020 09:15:45 +0000

Code setup

To speed things up, I've prepared a simple React app we can play with here, so all you need to do is to check out the repo for this series and start the CRA dev server:

git clone git@github.com:thekarel/debug-anything.git
cd debug-anything/react-cra
yarn # npm i
yarn start # npm start

You should see a successful launch message in your console:

Compiled successfully!

You can now view react-cra in the browser.

  Local:            http://localhost:3000
  On Your Network:  http://192.168.0.4:3000

Note that the development build is not optimized.
To create a production build, use yarn build.

Creating a `launch.json`

As discussed before, we need a launch.json for non-trivial use cases - see Debug anything: launch.json & the debug console for more details.

The sample code already contains the launch configuration too. It's pretty straightforward, but let's walk through it line by line, to make sure we understand what's happening. Open .vscode/launch.json:

Let's focus on lines 8 to 12 and go from top to bottom:

{
    "type": "chrome",
    "request": "launch",
    "name": "Debug CRA web app in Chrome",
    "url": "http://localhost:3000",
    "webRoot": "${workspaceFolder}/react-cra"
}

type: this sets the debugger type to chrome, meaning we'll use Chrome browser in this config. Another type we've before used is node - there are many others you can get by installing extensions. There's one for Firefox too 🦊

Each debugger type has its specific configuration, so try to use the handy autocomplete that comes with VS Code.

request: the selected option launch means we'll launch a browser for debugging and it will load the address specified below. It's not very different from what you'd do manually, but Code automates it for you. Another possibility is to attach to an already running debug server, which is not possible here. It's good to know that VS Code will take care of closing Chrome when you stop the debug session.

name: any name you prefer, this will show up in the debug toolbar:

url: the URL the browser will load - this has to match the one where the CRA dev server is running!

webRoot: the path to the project source files. Source maps are not reliable in CRA development mode, unfortunately.

The CRA debug recipe

So how does all this hang together? The debug process is made up of the following steps.

First, you start the dev server in a console with npm start - this can be done in VS Code too by the way.

Next, you launch the debug browser from the debug sidebar, or by pressing F5:

Add breakpoints to your code as usual:

Then interact with the site in the debug browser, but this time with the debug powers enabled 💪 Let's see how a successful fetch looks like in our sample app:

You can restart the session and bring the app back to its original state by using Restart in the toolbar:

You might be wondering if this is any better than opening the page in a "normal" Chrome and using the dev tools? The difference is not huge in this case. One clear benefit, though, is that you get to keep your breakpoints even after you close the browser or quit Code. This applies to watch expressions too! Speaking of which...

Bonus: adding watch expressions

We've seen how to inspect and even edit local variables. Going to the variables section and looking at values works. But if you're dealing with complex objects, repeatedly opening up nested structures gets annoying fast.

VS Code offers a more comfortable solution: you can set watch expressions that will be re-evaluated in each debug step. It's even possible to query nested properties with the dot notation (e.g. post.title).

Make sure the Watch section is open in the debug sidebar and add a few expressions:

Let's try to fetch an existing post and keep an eye on the expressions:

With these expressions, it's easy to inspect the unhappy path too - keep an eye on the error this time:

As you might have guessed, the method we used above applies to any browser-based app. The setup is roughly the following in these cases:

Start the development server
Configure your launch.json to open the app in the debugging browser
Set breakpoints in your source code
Set watch expressions when you repeatedly inspect the same property
Use step commands to inspect the code flow
Restart functions or the whole app

Debug anything: launch.json & the debug console

Charles Szilagyi — Mon, 27 Apr 2020 20:27:43 +0000

Debugging can be an intricate business, and we need a way to store the config for our bespoke setup - ports, paths, arguments, and so on - somewhere. VSCode uses launch.json for fine-grained control and having one will make it possible to start our app or attach to it in complex debug scenarios. Not having a launch.json was a temporary hack, but we'll need one moving forwards. So let's create one!

Make sure our sample code folder is open in VSCode:

launch.json

VSCode has a handy UI to generate a config skeleton. Let's switch to the debug sidebar, click "create a launch.json file" and select Node.js:

VSCode generates a new launch.json file under the .vscode folder in the workspace:

We'll dig deeper into the file format and possible values in the future when we'll look at different real-life scenarios and adapt the configuration as required.

For now, it's enough to observe that the presence of the config enables a launch menu in the debug sidebar which you can use to start the toy server 🧸 quickly:

You can refer to the excellent official documentation on creating the configuration and the possible configuration values if you'd like to understand more about this topic right now.

By the way, I'd suggest saving launch.json to your code repo. Having a shared one enables all team members to take advantage of proper debugging.

Debug Console

Note how the debug console also opened up automatically:

This console allows you to evaluate expressions in the context of the app running in the debugger. It is a pretty amazing and convenient tool! You can inspect any variable in the scope, similar to the debug sidebar. But you can also run any function in scope, or literally run any code you want, even require modules - inside your running app 🤯

Let's see an example. Make sure to add a breakpoint on line 24 and fire off a request:

As demonstrated, you can type in any local variable (or function) name, and you even get auto-completion.

But, as mentioned above, you're not limited to your app's code - you can import any available module:

Have fun exploring the debug console! 🥼

Debug anything: Editing variables and restarting functions

Charles Szilagyi — Mon, 20 Apr 2020 07:14:11 +0000

Previously we've looked at how to start debugging a simple server and the ways you can move around the code in the debugger. Today we'll check out two less prominent features. The first one is the ability to edit variables. The second being the ability to replay a function - to restart a stack frame, to be precise - without restarting the debugger or the application.

While these features might not be super intuitive, they are quite powerful and can save a ton of time. You can try a function buried deep in the call stack with different inputs, without restarting a potentially long and tedious journey.

Let's see how we can use them together to try different scenarios in our usual tiny server app.

Setup

We'll play around with the usual code snippet, go ahead and copy-paste it into an empty file if it's not on your machine yet:

const http = require('http');
const url = require('url');

const hostname = '127.0.0.1';
const port = 3456;
const serverUrl = `http://${hostname}:${port}`

const getNameFromReq = (req) => {
  const {name} = url.parse(req.url, true).query;

  return name
}

const getGreeting = (name) => {
  const greeting = `Hello, ${name}!`

  return greeting
}

const server = http.createServer((req, res) => {
  const name = getNameFromReq(req)
  const greeting = getGreeting(name)

  res.statusCode = 200;
  res.setHeader('Content-Type', 'text/plain');
  res.end(`${greeting}\n`);
});

server.listen(port, hostname, () => {
  console.log(`Server running at ${serverUrl}`);
});

Hello, undefined!

Our toy server assumes there is always a query parameter called name present in the request. If it's missing, the response becomes "Hello, undefined!":

> curl http://127.0.0.1:3456
Hello, undefined!

Let's use the debugger and see how our getGreeting function behaves with different name parameters. The fix is trivial, obviously, but let's play along, we're here to see what the debugger can do. 🤓

Let's put a breakpoint on line 15 and hit the server without a name query argument (e.g. curl http://127.0.0.1:3456).

You should see the debugger kicking in and stopping on line 15.

If you're not confident how to do this, please refer to Part 1, the basics

Make sure the Variables and Call stack sections are both open in the debug sidebar. We'll focus on the local variable name for now, which is undefined:

Let's step over the next line (F10) and observe the return value of getGreeting:

If you need a quick overview of step over, step into and step out, read Part 2, Navigating with steps

Ok, no surprises here: if the name is undefined, the greeting will say Hello, undefined!.

Rewind

Let's re-run this function, this time with a different name. We don't need to fire off another request - we can restart the last stack frame:

And we're back at the beginning of the getGreeting function 👌

Let's now try what would happen if the name was null? We can edit the local variable to fund out:

We can try to set a string value - mind the quotes around the value:

You can override anything local or defined in the closure, including functions:

Keep in mind: once you override functions you'll have to restart the process to get back to the original implementation.

And this is it: you are now able to restart functions in the debugger and edit local and closure values, including strings and functions. Why not play around and see what happens if you restart functions higher up in the stack?

Happy debugging! 🥼

Debug Anything: Navigating with steps

Charles Szilagyi — Tue, 14 Apr 2020 05:28:29 +0000

In the previous episode we've started exploring the VS Code debugger. We've added breakpoints to our tiny codebase and glanced at the local state.

This time we'll learn how to follow the code execution line by line and how to jump in and out of function calls.

Get the code

First, let's change our single-function server into something more complex. We'll add two extra functions: one to get the name from the request and another to generate the greeting.

You can copy-paste this code as index.js in an empty folder.

const http = require('http');
const url = require('url');

const hostname = '127.0.0.1';
const port = 3456;
const serverUrl = `http://${hostname}:${port}`

const getNameFromReq = (req) => {
  const {name} = url.parse(req.url, true).query;

  return name
}

const getGreeting = (name) => {
  const greeting = `Hello, ${name}!`

  return greeting
}

const server = http.createServer((req, res) => {
  const name = getNameFromReq(req)
  const greeting = getGreeting(name)

  res.statusCode = 200;
  res.setHeader('Content-Type', 'text/plain');
  res.end(`${greeting}\n`);
});

server.listen(port, hostname, () => {
  console.log(`Server running at ${serverUrl}`);
});

The code for the series is available at https://github.com/thekarel/debug-anything

Start the debugger

Let's start the debugger: use the debug toolbar or press F5 and select Node.js:

You should be able to visit http://127.0.0.1:3456/?name=Coco as usual and see a greeting.

You can also use curl http://127.0.0.1:3456\?name\=Coco if you're that kind of person

Ok, so far we've only established the server is up and running - let's add a breakpoint. Without a breakpoint, the debugger wouldn't start:

You should have a breakpoint now on line 21:

const name = getNameFromReq(req)

Step by Step

Fire off a request again to http://127.0.0.1:3456/?name=Coco - the debugger will kick in and stop code execution on line 21:

Wonderful. Let's focus on the debug toolbar now:

First of all: names. The buttons from left to right are the following (with the default VS Code shortcut):

Continue / Pause F5
Step Over F10
Step Into F11
Step Out ⇧F11
Restart ⇧⌘F5
Stop ⇧F5

Continue, restart and stop are straightforward and will do what you expect: continue to the next breakpoint, restart the process and stop the process (and the debugger).

Steps are related to function calls on the current line: you can step over a function call, step into it (look inside and debug) or leave it (step out). Step-over also allows you to run the code line by line, even if the line is not a function call.

Step commands only control what you "see" in the debugger. So "stepping out" or "over" a function will still execute all the code as usual. The debugger will just not bore you with the details, and you'll get jor job done quicker.

Continue

Continue will run the code up to the next breakpoint, or the end of the program. One way of debugging is to add multiple breakpoints on relevant lines beforehand and jump between them using continue:

So, Continue is handy if you already know which functions or lines are relevant to you. The debugger will pause at pre-defined locations allowing you to inspect the variables and call stack.

Step Over

You can think of step over as going line-by-line in a function but not following function calls (not stepping in). Use it if you're not interested in the details of the function call on the current line, but only want to see how local variables change over time, for example:

Step over is a great way to walk trough devlarative code.

Step Into

You can use step-into when you arrive on a line that calls an interesting function, and you want to dig deeper. Once you step into a block, you keep debugging as usual (use continue, step commands, etc.).

Observe how we step over getNameFromReq but step into getGreeting:

Step Out

Stepping out is the opposite of stepping in: you can leave a function once you're no longer interested in it. Clicking "Step out" runs the remaining code of the function without you having to keep clicking.

Check out the difference between debugging the two functions - we follow the first one through but step out of the second early:

Now you should have a better understanding of the debugger toolbar, how to focus on what matters and skip the irrelevant bits. The navigation commands not only save you time but make the whole debugging activity more enjoyable! Why not try these in your project as an exercise?

Happy debugging! 🥼

Debug anything: the basics (with GIFs!)

Charles Szilagyi — Tue, 07 Apr 2020 05:22:19 +0000

A debugger allows you to open up your program while it runs, look at the state, variables, pause and observe the data flow step by step. You can even run code snippets and try ideas in the runtime environment. All that without stopping, changing code (adding console.log!) and restarting. You'll fix issues and understand the codebase much faster with a debugger.

We'll start with some suspiciously simple Node.js code, and in the future will look at debugging a browser app, Express server, GraphQL, TypeScript, Serverless, Jest tests, Storybook - but let's clear the basics first! Even if you're not keen on server-side Node.js, I'd still encourage you to go over this introduction.

Get the code

Git repo for the series: https://github.com/thekarel/debug-anything

The code for our first session is super simple - go ahead and copy-paste it to index.js in an empty folder:

const http = require('http');

const hostname = '127.0.0.1';
const port = 3456;
const serverUrl = `http://${hostname}:${port}`

const server = http.createServer((req, res) => {
  const name = 'World'

  res.statusCode = 200;
  res.setHeader('Content-Type', 'text/plain');
  res.end(`Hello, ${name}!\n`);
});

server.listen(port, hostname, () => {
  console.log(`Server running at ${serverUrl}`);
});

Now go ahead and open the folder in VS Code:

To make sure all is well so far, try to run it:

node index.js

... and visit http://127.0.0.1:3456 - you should see Hello, World!.

Make sure you stop the node index.js command now, or you'll get an ugly Error: listen EADDRINUSE error soon 🙀

The code itself is trivial: we run an HTTP server, and respond to every request with "Hello, World!". Impressive, right? But this simple code is enough to learn the basic notions of debugging.

Add a new feature

Let's add a feature to our server: instead of returning the hard-coded message "Hello, World!", we'll pick the name from the query, so hitting http://127.0.0.1:3456?name=Coco will respond with Hello, Coco!.

Also, let's pretend we have no idea how to do it ;) Wouldn't it be nice to be able to run the server, send a request and see where the name Coco shows up? Let's give it a try. Let's start the debugger!

Start the debugger

Make sure index.js is open in VS Code, click the debugger icon, click Run and Debug then Node.js:

Your server is now running in debug mode! Try visiting http://127.0.0.1:3456?name=Coco - you won't see a difference, but it should still return the default message.

Next, let's add a breakpoint to the code which will pause the execution the next time we hit the server URL. You can do that by clicking the line number in the left gutter of the editor:

Try visiting http://127.0.0.1:3456?name=Coco - VS Code will pop into view and pause the server:

Let's find out where the name in the query ends up, so we can return a friendly greeting. Check out the left sidebar: you'll see a section named Variables. Under Local the IDE shows all the vars that are in the local scope of the function. There's one that looks promising: req:

Now that we know that the request query string sits in req.url, with a little help we can go ahead and change the script to

const http = require('http');
const url = require('url'); // 👈

const hostname = '127.0.0.1';
const port = 3456;
const serverUrl = `http://${hostname}:${port}`

const server = http.createServer((req, res) => {
  const {name} = url.parse(req.url, true).query;  // 👈

  res.statusCode = 200;
  res.setHeader('Content-Type', 'text/plain');
  res.end(`Hello, ${name}!\n`);
});

server.listen(port, hostname, () => {
  console.log(`Server running at ${serverUrl}`);
});

Because the code changed, you need to restart the server. It's simple to do with the debugger: you can press ⇧⌘F5 or click the green restart icon:

You can also disable the breakpoint as we don't need it anymore:

Visit http://127.0.0.1:3456?name=Coco and marvel at how much one can achieve with today's technology! 😉

I encourage you to keep exploring the debugger. Next time we'll look at walking through the code line by line using the "step over", "step in" and "step out" functionality.

Happy debugging! 🥼

Declarative programming: correct and easy to understand code

Charles Szilagyi — Mon, 30 Mar 2020 06:20:55 +0000

This article is part of Best Practices - Pragmatic recommendations based on clean coding principles for teams working on TypeScript/JavaScript web application

Maintainable code is simple, discoverable and easy to understand.

How do we write code that others understand easily? By stating our intentions in short, abstract, human language-like expressions and moving the technical details into lower-level modules.

Consider the following code snippet. It is obvious what's supposed to happen without seeing the implementation details, and it's also clear where to look to understand more.

const buyTicket = async ({repository: Repository}, {userId: UserId, concertId: ConcertId}): Promise<Ticket> => {
    const [concert, user] = await Promise.all([
        repository.getConcert(concertId),
        repository.getUser(userId)
    ])

    if (!ticketsAvailableFor(concert)) {
        throw new TicketsNotAvailableError()
    }

    if (!hasFundsFor(user, concert)) {
        throw new NotEnoughFundsError()
    }

    const ticket = new Ticket(concert, user)

    await repository.recordTransaction(user, ticket)

    return ticket
}

This code more or less reads like a recipe in English: get the user and the concert, check if tickets and the money are available - if so, deduct the money and hand over a ticket.

Production code would be more complicated than this example, but the pattern is quite clear:

State your intentions in expressive, human-friendly language
Stay on one level of abstraction inside a module
Start from high-level, domain language and move to low-level, implementation-specific details

Writing declarative code creates building blocks, starting from the top and drilling down to the bottom. You state the most significant, most abstract problem first, then break it down to smaller bits - next go and break down these again and again. At some point down this road, you find ready-made solutions, your existing, reusable code or 3rd party modules.

You can think of declarative programming as writing a specification first (top-level function calls), then implementing these features one by one. It's easy to imagine that the snippet above started as a list of requirements to implement:

const buyTicket = () => {
    // get user
    // get concert

    // check if tickets are still available
    // check if the user has funds

    // create a Ticket
    // create sale transaction

    //return ticket
}

While details in a declarative codebase are not immediately visible, they are still easily accessible. When you need to understand specifics, you should be able to "jump to definition" in your IDE - or open the relevant file, which is straightforward with consistent naming.

The definition of the lower-level code block must also follow the declarative principles - so it's also easy to understand. This pattern repeats like a fractal, from top to bottom, from very abstract to the lowest level.

One function (method) must deal with one level of abstraction. Sticking to the rule of increasing specificity makes reading and changing the program straightforward, as readers don't have to jump between contexts, which is very distracting and drains attention.

Declarative code builds up complex structures from smaller building blocks. In this regard, it's very similar to the compositional nature of functional programming. But using FP is not a requirement; you can use this technique in object-oriented programming or any other/mixed paradigm.

The main goal here is to write something easy to understand for others - and ourselves in the future. But declarative programming has other benefits too: refactoring is more manageable because you've extracted implementation details, so changing "how" we do something doesn't affect the "what". Also, finding the code responsible for a piece of functionality is almost trivial. You might have to go through several modules (more indirection), but the path to follow is always evident. You might have to walk a bit more, but you're guaranteed to get there - and this is key in a product-oriented environment.

The expressive strategy described here works well outside of programming too. You are encouraged to be declarative when recording requirements, writing documentation, describing systems, creating tests, scripts, CI/CD pipelines.

Finally, consider how the opposite of declarative code looks like: everything stares at you at once, from technical details to high-level concepts, from counters and indexes to business entities, all mixed. Such source code is confusing and difficult to follow - and precisely because of that becomes a breeding ground for bugs.

The only problem to solve is the one we have today

Charles Szilagyi — Thu, 26 Mar 2020 10:41:51 +0000

What you need to solve are the problems you have now: dedicate proper focus to these. Produce a correct solution for the task at hand and move on.

Worrying about what might happen in an imaginary scenario leads you down into rabbit holes. It is one of the reasons why people start many things but finish few.

Another reason to refrain from "preemptive" solutions is the lack of information. You will know more about the problem domain later and will be able to come up with a better solution "just in time".

Finally, you limit your future choices by making sub-optimal decisions now.

Don't paint yourself into a corner by making uninformed judgments.

If you keep your application as simple as possible, you'll have a much higher chance to adapt to future changes successfully.

You can't predict the future, and surprises will happen. What you have planned might never arrive, something completely different probably will.

Continue reading The only problem to solve is the one we have today in Best Practices

Simplicity is a developer's best friend

Charles Szilagyi — Mon, 16 Mar 2020 09:36:57 +0000

You need to embrace simplicity if you want to achieve results today and stay successful tomorrow. Long term product quality, performance and development speed all rest on the simplicity of a system.

Run with the minimum that achieves the business goals.

There are two kinds of complexity in any project: the inherent complications of the problem domain and the unnecessary, "incidental" or "accidental" complexity introduced by developers. The domain complexity is more or less fixed and has to be accepted as is. Dealing with it is the primary role of a developer.
Accidental complexity, on the other hand, has to be avoided and minimised at all cost.

Be frugal with code, processes and infrastructure. Everything you add today will have to be looked at and understood by you or someone else in the future. The more complicated your system is, the more resources people dedicate to learning it instead of implementing improvements and new features.

Simple might seem boring at first - but it's the opposite: it's liberating.

Continue reading Simplicity is the best ally in the long run on my Best Practices on GitBook

Paying attention: the mental cost of development

Charles Szilagyi — Mon, 09 Mar 2020 06:24:22 +0000

Writing software requires long periods of uninterrupted concentration. Developers need to consider complex ideas in detail, imagine and experiment with various solutions to discover the one that works. Finding answers often requires research and learning about new concepts. All this is impossible without paying attention.

For this reason, attention is the most precious resource in a software project. Once depleted, no amount of determination, money or time will deliver the desired outcomes. Without focus, all other resources go to waste.

There is no such thing as multitasking. You can do one thing well or many things wrong in parallel.

But, attention is also a very fragile thing. Successful developers work in attention-friendly environments without external interruptions. They also learn how to manage and direct their focus on what's relevant: they are disciplined.

A significant source of distraction is often the codebase and the tooling itself. Teams need to avoid unnecessary complexities in the code and all unproductive practices while writing it. There are some recommendations you can follow.

Of course, there are other things to do in a project than writing code. But all activities must be organized in a way that encourages and supports periods of deep concentration and thinking. Focus and care always manifest in more reliable, performant, refined and more enjoyable products. Your customers will be grateful!

Building up a focus-friendly climate takes effort and care, but it's an essential requirement to achieve anything substantial.

You can find out more about the importance of concentration and focus in my Best Practices on GitBook

DEV Community: Charles Szilagyi

End-to-end Type Safety in Clean Architecture

End to End Type Safety

Benefits

Clean Architecture TL;DR

Tech Stack

Layers

Domain

Services

Repository

OrderRepositoryMemory

OrderRepositoryMongo

GraphQL

TypeGraphQL

UI

GraphQL Codegen

The End

Using OS X Without the Mouse

Learn Keyboard Shortcuts

Browse commands

CheatSheet

Take it easy

The Scary but Powerful: Vim mode 🙀

Vim mode in VS Code

Clicking on Things with Vimac

XEasyMotion

Clicking on Internet Things with Vimium

Productivity apps

Launchbar

Alfred

Keyboard Maestro

Desktop managers

Rectangle

Amethyst

Debug anything: React in TypeScript with Parcel 📦

Get the code

Code structure

Parcel

Dev server

Configure the debugger

React + TypeScript debugger in action

Debug anything: Browser-based React apps

Code setup

Creating a launch.json

The CRA debug recipe

Bonus: adding watch expressions

Debug anything: launch.json & the debug console

launch.json

Debug Console

Debug anything: Editing variables and restarting functions

Setup

Hello, undefined!

Rewind

Debug Anything: Navigating with steps

Get the code

Start the debugger

Step by Step

Continue

Step Over

Step Into

Step Out

Debug anything: the basics (with GIFs!)

Get the code

Add a new feature

Start the debugger

Declarative programming: correct and easy to understand code

The only problem to solve is the one we have today

Simplicity is a developer's best friend

Paying attention: the mental cost of development

Creating a `launch.json`