Forem: koraflux

Typescript advanced bits: function overloading, never and unknown types

koraflux — Thu, 10 Nov 2022 15:29:34 +0000

Typescript is a powerful tool that helps build reliable products, develop codebases that scale, and improve the developer experience. While it's quite popular nowadays, some aspects are sometimes overlooked.

As a massive fan of Typescript, I want to draw your attention to some of them and talk a bit about how they work, what could be the potential use cases and what benefits they bring. In this article, we'll be looking at function overloading as well as unknown & never types.

Function overloading

Sometimes you may find yourself in a situation where you want a function that needs to work with more than one set of parameters and produce results of different types. Usually, to achieve this, we can use optional parameters and unions. But in some cases, this does not let us describe how parameters and return types are associated concisely enough. So we lose on readability and quality of hints from our IDE. This is where function overloading can help us.

Function overloading in Typescript is a fantastic feature that lets you define multiple function signatures one after another, describing what the function will return depending on what parameters are passed.

To do this, we write two kinds of signatures - overloading signatures and implementation signatures. Overloading signatures does not have an implementation (function body) and just defines the typings. It's important to remember that the implementation signature should be compatible with all the overloading signatures.

Let's look at an example from an imaginary car-renting app. We need a universal function for getting a car booking price. It accepts some information about the car and returns a single price or an array of prices, depending on parameters. Also, if a callback is passed, then it will be called with the price, and in this case, the function will return. Depending on what parameters are passed, it calls two different functions to retrieve the price from the backend (that part is simplified for explanatory purposes). This is what it may look like:

const getCarPricesByCarParams = (
    carType: string,
    city: string,
    distance?: number)
: number[] => {
  return [500, 1000, 1500]
}

const getPriceByCarId = (carId: string):number => {
  return 1000
}

function getBookingPrice(carId: string): number
function getBookingPrice(
    carId: string,
    callback: (price: number) => void)
: void
function getBookingPrice(
    carType: string,
    city: string,
    distance: number)
: number[]
function getBookingPrice(
    carIdOrType: string,
    callbackOrCity?: ((price: number) => void) | string,
    distance?: number)
: number | void | number[] {
  if (typeof callbackOrCity === 'string') {
    // we're returning a number[] type
    return getCarPricesByCarParams(
  carIdOrType,
  callbackOrCity,
  distance)
}
  if (typeof callbackOrCity === 'function') {
    const price = getPriceByCarId(carIdOrType)
    callbackOrCity(1)
    // we're not returning anything here
    // (so function has void return type)
    return
  }
  // we're returning a number type
  return 1000
}

This approach is helpful when the function is complex and returns multiple types. Function overloading enables us to establish strict relationships between parameter types and returned types. If your function gets this complex, a good way to deal with it might be as well splitting it into multiple functions.

Another alternative to function overloading is using Union types in parameters. It's a good idea to experiment with both approaches to identify what feels right for your specific case.

Unknown type

Apart from well-known and straightforward primitive types like string, number, and boolean, the typescript type system has some types that could confuse new developers. Those are never and unknown. Let's look at those types, what they mean and how they can help us.

Unknown type represents a set of all possible values of every possible type. If we declare a variable of this type, any value can be assigned to it. According to set theory that Typescripts heavily relies on in its type system, unknown represents a top type (another top type is any). It means it can describe any possible value.

A good way to think about unknown is that it's a more typesafe version of any. The difference with any is that if we type something as any Typescript permits us to do anything with it. For example, access any properties as if they exist. If you declare a variable of unknown type, Typescript won't let you use it (i.e. access nested properties, call methods or perform operations) unless you narrow it down to a more specific type. And this is much more typesafe.

For this, you can use type guards with typeof, instanceof or other type narrowing techniques or assertions. Using generally makes your code less typesafe, so other type guarding techniques are preferable in most cases.

let someValue: unknown

// TS will complain about the following:

someValue.doSomething();   // error
someValue.someOtherValue   // error
someValue();               // error

// But if we narrow the type down, 
// TS will understand what it is and let us use it.

if (typeOf someValue === 'string') {
  console.log(someValue.toUpperCase());
}

A good way to significantly improve the reliability of your app is via improving type-safety by moving away from using any to unknown. One relevant example could be when you type your backend responses and when stringifying JSON to using unknown combined with some sort of runtime type checking. It can be done either by using built-in functionality like type guards or using an external library like io-ts, zod or yup.

Never type

never is a primitive type in Typescript representing a bottom type. It is used to describe a type that should never occur. This could be a return type of function that throws an error unconditionally or a state that you want to avoid.

One particularly helpful use case is using it as a way to ensure that all the variations of a particular data structure are handled.

For example, imagine we are building a car renting app, and we have a function that should handle all car types, returning a description for each of them. So we can add a simple shouldNotBeReached helper using never type, and rest assured that once the new car type is added to the codebase, the Typescript will let us know that it needs to be handled.

const shouldNotBeReached = (value: never): never { 
  throw new Error('This should not be reached')
}

type CarType = 'Hedgeback' | 'Sports'

const getCarTypeDescription = (carType: CarType) => {
  switch (carType) {
    case 'Hedgeback': 
       return 'So basically it is a two or four-door car with a tailgate that flips upwards'
    case 'Sports': 
      return 'Well, it is a car designed for getting somewhere really fast and look cool in the process'
   default: 
      return shouldNotBeReached(carType) 
  }
}

Later on, we may want to add some other kind of cars to our app, let's say an SUV. It's easy to forget to update all the functions dealing with this type. To avoid this, we'll add a simple function to the default case of the switch statement. It will make sure Typescript reminds us to handle that new car type.

Conclusion

In this article, we explored three advanced Typescript features along with some use cases. Function overloading can be helpful when working with functions that can accept different sets of parameters and return different types depending on that. Using unknown and never types helps us write more robust and typesafe code and avoid bugs.

Building hotkeys in React apps

koraflux — Tue, 08 Nov 2022 13:08:01 +0000

Introduction

Using hotkeys is a great way to let your web app users get more done faster.

It works even better for power users and complex internal applications where your users spend a lot of time, like systems for content editing, monitoring systems or support tools.

In this article, first, we'll look at some design aspects to keep in mind when implementing hotkeys in an app and ways to make hotkeys convenient for the end user. Then we will do basic hotkeys implementation and look at how to add hotkeys to React application.

Hotkey Integration Preparations

Stick to three hotkey development guidelines:

Discoverability: familiarise your users with hotkeys. Use onboarding, walkthroughs, labels or tooltips to help users learn about your hotkeys system
Memorability: hotkeys and key combos need to be simple and memorable
Compatibility: avoid situations where your hotkeys conflict with existing system-wide or browser shortcuts

1. Make a Plan

Define a list of actions demanding hotkey implementation. It is helpful to pursue a structured approach, starting with mapping out the user stories in your application and defining app sections. Then split your user stories into actions ranked by importance and usage frequency. Leveraging user feedback and analytics can be very helpful here. All the actions could be divided in two big groups:

Global actions include navigation between app parts and launching important functionality. Generally, it makes sense to implement it on the top level of the app (e.g. as a react wrapper component or context).
Contextual actions, such as controlling modal windows or popups, should be implemented at the relevant component level (modal window, multi-step form, etc.).

2. Pick the Hotkeys

Think of the hotkeys and key combos. Remember that they should be memorable and non-conflicting with browser or OS hotkeys.

Keep context and users in mind. What OS they are using, other running apps, preferred browser hotkeys, such as native browser search for content-rich websites.
Steer clear of the overloaded classic key combos
Ctrl + N, Ctrl + O, Ctrl + S, Ctrl + P, Ctrl + W & Ctrl + C, Ctrl + Z, Ctrl + F
Alt + F1, F2, F3…
Decide if you want to use
- Single hotkeys
- Combinations or
- Sequences - keep in mind that they should not conflict with single hotkeys

Settling on one approach will simplify hotkeys for the users.

Single-key hotkeys are easier to use and remember, especially if they're assigned to actions corresponding with key letters. However, this allows for accidental keypresses and a smaller number of possible hotkeys. There are more options with combinations, but some of them will be already used by OS and browser hotkeys.

The sequences approach works for assigning lots of actions, giving you the biggest freedom of options and number of available combos. For example, it’s used in Gmail. But if you pick this route, avoid using single hotkeys since that will lead to conflicts and a poor UX. You can override browser hotkeys by calling event.preventDefault() but think twice before you do it as it can be super annoying to your users sometimes.

After deciding what hotkeys you will assign to your actions, go to your app and try to use them as if they are already there. This will put you in users' shoes and let you identify what works well and what could be improved.

3. Think About Informing the User

Find a way to implement hotkey information in your design. Some of the frequently used tools include:

Labels

Tooltips

Underlined letters in buttons corresponding to hotkeys

Hotkey maps
For the best discoverability and memorability, it’s great to add a hotkey map, i.e. a page or a modal window with the list of all available actions in the app.

If there are many hotkeys, a search with a filter may be added on top of the map. Here are some examples of hotkey maps:

By the way, in all the examples above, users can see those hotkey maps by hitting a '?' key. You can consider following this best practice as well.

As a result, you have a list of hotkeys and informational design elements to get users up to speed. Now we can move on to implementation.

For internal app interfaces, which users think of as their main work tools, consider making hotkeys customisable so that users can reassign the keys. This could be useful for the most advanced users.

Implementing Hotkeys in React

Let’s dive into how hotkeys can be implemented in a React app, look into possible improvements and go over some popular hotkeys libraries that could be helpful to build hotkeys system for your app.

Adding Hotkeys

This is what the most basic TypeScript hotkey implementation looks like. All hotkeys implementations are based on event listener, attached either to the document object or a specific DOM node.

We can use keydownevent to track keyboard presses by the user. Note that we’ve added a check for the event.repeat property to neutralise double clicks.

You can always check out all keyboardevents properties on MDN.

export const setupHotkeys = () => {
 document.addEventListener("keydown", (event: KeyboardEvent) => {
   if (event.repeat) {
     return;
   }
   if (event.ctrlKey && event.key === "l") {
     // do what you want to do when CTRL + L is pressed 
   }
 });
};

Hotkeys in a React App

Now let’s implement basic hotkeys as a hook for a React app.

We are using the useLayoutEffect hook and useRef hooks to recall the most up to date callback to avoid bugs. Here is a very nice article explaining how useLayoutEffect hook works just in case.

We’re also using the useEffect callback to attach the listener. Please note that we are removing the event listener in a function that gets returned by the useEffect hook. (Here is the documentation for useEffect hook). We do this to ensure we don’t leave the listener attached when the component is removed from dom - this is needed to avoid memory leaks.

export const useHotkeys = (
 key: string,
 callback: (event: KeyboardEvent) => void
) => {
 const callbackRef = useRef(callback);

 useLayoutEffect(() => {
   callbackRef.current = callback;
 });

 useEffect(() => {
   const handler = (event: KeyboardEvent) => {
     if (event.key === key) {
       callbackRef.current(event);
     }
   };

   document.addEventListener("keydown", handler);

   return () => document.removeEventListener("keydown", handler);
 }, [key]);
};

Let’s now implement support for combos.

We start by adding an additional parameter, like a combination key or a modifier - Alt, Ctrl, Shift, and the meta key (Windows logo key or the Mac command key). To support the combination, we’ll add an additional check in the handler so that the app reacts only when the key is pressed in a combination with a modifier key.

type CombinationKey = "alt" | "ctrl" | "meta" | "shift";

export const useHotkeys = (
 key: string,
 combinationKey: null | CombinationKey,
 callback: (event: KeyboardEvent) => void
) => {
 const callbackRef = useRef(callback);

 useLayoutEffect(() => {
   callbackRef.current = callback;
 });

 useEffect(() => {
   const handler = (event: KeyboardEvent) => {
     if (
       (!combinationKey || event[`${combinationKey}Key`]) &&
       event.key === key
     ) {
       callbackRef.current(event);
     }
   };

   document.addEventListener("keydown", handler);
   return () => document.removeEventListener("keydown", handler);
 }, [key, combinationKey]);
};

React Libraries for Hotkeys

There are lots of hotkey development libraries for React apps, one of the most popular ones being react-hotkeys-hook.

An example of how hotkey implementation works in this library:

import { useHotkeys } from 'react-hotkeys-hook'

export const Component = () => {
 useHotkeys('ctrl+j', () => {/* do something */});

 return (
   /* some jsx */
   )
}

Here’s some other hotkey libraries to check out:

https://github.com/jaywcjlove/react-hotkeys
https://gitlab.com/iamnautilusjungle/mousetrap-react
Hotkey functionality can also be implemented using other libraries, such as Blueprint.js: https://blueprintjs.com/docs/#core/hooks/use-hotkeys

Conclusion

We looked at some ways of building and implementing hotkey systems in React apps. When developing hotkeys, our priority should always be usability and comfort. Well-designed hotkeys can save tons of time for your users and make them happy so it's worth considering hotkeys in your app.

If you found this interesting and want to know more, here are some cool articles on this topic that I've used while researching: