DEV Community: Alex Jarvis

Figurative Literals: Sharpen your Strings

Alex Jarvis — Mon, 14 Mar 2022 13:04:35 +0000

Recently, I decided to brush off an old project and tune it up with some modern day Typescript know-how. In my weeks-long dice-driven fugue state, I stumbled on some Typescript features that I hadn't had a chance to use before, and I think they're neat.

this is the second article in the series - check out the first article on overloading.

Revisiting the Strange Program

In a previous blog post, I showed how leveraging Typescript overloads can help us keep our code in line, and help anyone who might be consuming our code use it the way we intended.

Our task was to write a program that could accept a number or string, reject non-number-like strings, and then add 2 to given value. Then - for some reason - it needs to return the same type of value as was passed in. Here's that code:

export function addTwo(baseNumber: string): string
export function addTwo(baseNumber: number): number
export function addTwo(baseNumber: string | number) {
  const baseNumberValue = Number(baseNumber)

  if (Number.isNaN(baseNumberValue)) {
    throw new TypeError('baseNumber must be number or number-like string')
  }

  const numericTotal = baseNumberValue + 2

  return typeof baseNumber === 'string' ? String(numericTotal) : numericTotal
}

and in action:

addTwo(2) // 4
addTwo('6') // '8'
addTwo('Four') // Runtime TypeError 'baseNumber must be number or number-like string'
addTwo('Foo') // Runtime TypeError 'baseNumber must be number or number-like string'
addTwo({}) // Nonsense! Fails to compile before you run it.

That works, but I don't love that TypeError. This feels like the kind of thing that we could solve before runtime, something that Typescript could yell at us about when we try to pass in any value that would result in an error. That way, consumers would have a clearer idea of what this function really needs in their editor, just like if you passed in a random value ({} above).

Template Literals to the Rescue

Turns out, Typescript has a clean solution for us: template literals.

Template literals share their syntax with the template literals in javascript, but by using types instead of values. This means that we can construct sub-types out of the content of strings, allowing a deeply integrated piece of documentation right there for us. Typescript could always use specific strings as type values; this is just allowing a little more dynamism.

Before we tackle the solution for addTwo, let's look at a more complicated template literal. Let's imagine a situation where we write a function that spits out simple messages to the console, and we want to make sure the messages are always appropriately enthusiastic.

We might construct a type like this:

type ExcitedMessage = `${string} ${string}!`
export function sayHello(message: ExcitedMessage) {
  console.log(message)
}

Let's break down ExcitedMessage. Use use backticks and string interpolation syntax to wrap two familiar types, string, and then end it with a !. This means thatExcitedMessage will match any string that contains a string, a space, a string, and an exclamation mark.

const foo: ExcitedMessage = 'Hello Greg!' // Good
const bar: ExcitedMessage = 'Ach Hans!' // Good
const baz: ExcitedMessage = 'Unintended Consequences!' // Good
const luhrmann: ExcitedMessage = 'Help!' // Bad - Type '"Help!"' is not assignable to type '`${string} ${string}!`

We can get more flexible, too. We can use union types to optionally allow a comma:

type ExcitedMessage = `${string}${',' | ''} ${string}!`
const foo: ExcitedMessage = 'Hello Greg!' // Good
const bar: ExcitedMessage = 'Ach, Hans!' // Good
const baz: ExcitedMessage = 'Panic; Disco!' // Bad!

So how can we leverage them inside of addTwo?

Getting Number Strings

We just wrap a number type inside of a template literal - it's kind of magical.

type NumberString = `${number}`

export function addTwo(baseNumber: NumberString): NumberString
export function addTwo(baseNumber: number): number
export function addTwo(baseNumber: NumberString | number) {
  const baseNumberValue = Number(baseNumber)

  const numericTotal = baseNumberValue + 2

  return typeof baseNumber === 'string' ? String(numericTotal) : numericTotal
}

By specifying that we don't accept a string - we accept a NumberString - we no longer need to check for NaN inside of our code - we can be certain that Typescript will fail to compile if the given string is not number-like.

addTwo(2) // 4
addTwo('6') // '8'
addTwo('Four') // Nonsense! Fails to compile before you run it.

We've just moved an error report from run-time to compile-time - or dev time, if our editor is Typescript-aware.

The Power of Documentation

With these tricks, we've built a powerful suggestion system to ourselves and to future devs. This is really why I love writing Typescript; confidence that those who touch this code in the future might have a helpful computer friend that helps them understand what I intended to communicate.

And that's good, because this function is so odd out of context I'd likely assume it was an accident otherwise.

type NumberString = `${number}`

export function addTwo(baseNumber: NumberString): NumberString
export function addTwo(baseNumber: number): number
export function addTwo(baseNumber: NumberString | number) {
  const numericTotal = Number(baseNumber) + 2

  return typeof baseNumber === 'string' ? String(numericTotal) : numericTotal
}

For a real-life example of these ideas in action, check out my dice rolling library, randsum. Happy Typing!

Learn more about how The Gnar builds software.

Overloading Functions for Type Harmony

Alex Jarvis — Tue, 22 Feb 2022 22:20:38 +0000

A Strange Program

Let's imagine that you have been asked to write a very interesting, if a little curious, program. Your task is to write a program that will take either a number (4), or a number-like string ("4"). It's then going to add 2 to that number, and return the total. Stranger still, the type of the return value must match the type of the value that you put into the system in the first place.

How would we go about writing something like that? Maybe something like this:

export function addTwo(baseNumber: string | number): string | number {
  const baseNumberValue = Number(baseNumber)

  if (Number.isNaN(baseNumberValue)) {
    throw new TypeError('baseNumber must be number or number-like string')
  }

  const numericTotal = baseNumberValue + 2

  return typeof baseNumber === 'string' ? String(numericTotal) : numericTotal
}

Running the program, we see that it works:

addTwo('2') // '4'
addTwo(2) // 4
addTwo(2) // 4

What happens if we try to use this elsewhere? Then we get into trouble.

For instance, this line will not work:

addTwo(2) + 4 // Type Error: Operator '+' cannot be applied to types 'string | number' and 'number'.

This is because the return type of addTwo is a union type - just like the baseNumber argument. That means that Typescript lacks the understanding that we contextually know just by reading the code: if it's a string coming in, it's a string coming out.

Enter: Overloads

By re-defining the function signature above the function, we can let Typescript know that there are more specific ways of calling this particular function. This is called "overloading" the function - giving a function more than one function signature. We can construct the overload like so:

export function addTwo(baseNumber: string): string
export function addTwo(baseNumber: number): number
export function addTwo(baseNumber: string | number) {
  const baseNumberValue = Number(baseNumber)

  if (Number.isNaN(baseNumberValue)) {
    throw new TypeError('baseNumber must be number or number-like string')
  }

  const numericTotal = baseNumberValue + 2

  return typeof baseNumber === 'string' ? String(numericTotal) : numericTotal
}

The first two changes are the overloads, which spell out the consequences of using one type versus the other. On top of the obvious compiler usability benefits, I really like how this spells it out to any developers who might come across this very odd little function in the future.

On top of that, we've also made a change to the implementation function signature by removing the explicit type returns. While I generally like being explicit about return types, this is one instance where being too explicit hurts us.[1]

A Little Bit of a Tangent (About Overloads and Return Types) but stick with me here

By explicitly returning the type from this overloaded function's implementation signature, we are clobbering our local Typescript's ability to help us catch problems. Externally, the implementation signature isn't broadcast to any consumers - only the overload signatures are. However, if we aren't careful, we can make a liar out of ourselves.

Let's imagine our function, with explicit return values in our implementation signature:

+ export function addTwo(baseNumber: string): string
+ export function addTwo(baseNumber: number): number
+ export function addTwo(baseNumber: string | number): string | number {
- export function addTwo(baseNumber: string | number) {
  const baseNumberValue = Number(baseNumber)

  if (Number.isNaN(baseNumberValue)) {
    throw new TypeError('baseNumber must be number or number-like string')
  }

  const numericTotal = baseNumberValue + 2

  return typeof baseNumber === 'string' ? String(numericTotal) : numericTotal
}

and now, let's imagine that we accidentally flip the script on that ternary condition on the end - we delete it, and accidentally screw up our cases. Now, we return a string for a number, and a number for a string.

This:

return typeof baseNumber === 'string' ? String(numericTotal) : numericTotal

Becomes This:

return typeof baseNumber === 'number' ? String(numericTotal) : numericTotal

Ideally, we'd want Typescript to scream at us - "Hey! Your code can never match these type signatures - stop!" but it never does. This is because internally - when writing the function, in our editors - Typescript looks to the implementation signature for its return data. It is only about to get as specific as its explicit return value allows, and even though we've swapped the cases on the logic gate, it still reads as number | string. This stinks for us, but it stinks extra hard for anyone consuming this function. Because of our explicit-type-clobbering, we've actually made Typescript tell a lie, and it will result in an error that we won't find until runtime.

This is Typescript. We are better than that.

By removing the explicit return, we let the overloads take full responsibility for reporting their validity to us, the developer. This makes sense, if you think about it - explicit return types are for communicating what Typescript can't assume on its own (or for being friendly to future developers and clear with intent for yourself). You are still explicitly returning a type value here - you're just doing it in the overloads, which is the only thing that gets broadcast to consumers of the function anyway!

Highway to the Overload

By leveraging specificity in our Typescript, we can nudge and shove future developers towards a deeper understanding of the impact of our code, and let Typescript make sure that we aren't bumping into things along the way.

addTwo(2) + 4 // 8 - no Type errors here!
addTwo('2') + ' Letter Word' // '4 Letter Word'
addTwo('2') + 4 // Type Error - no go, Buster

Sometimes, the best documentation is the kind that reads you.

And I like our little function! It's strange - and I can't for the life of me imagine what practical use it could have - but I like it, and I wouldn't change a thing.

export function addTwo(baseNumber: string): string
export function addTwo(baseNumber: number): number
export function addTwo(baseNumber: string | number) {
  const baseNumberValue = Number(baseNumber)

  if (Number.isNaN(baseNumberValue)) {
    throw new TypeError('baseNumber must be number or number-like string')
  }

  const numericTotal = baseNumberValue + 2

  return typeof baseNumber === 'string' ? String(numericTotal) : numericTotal
}

...
...
...

Okay. Maybe a few things. Next up: Let's get rid of that TypeError with the power of template literals!

[1] This section is true as of Typescript 4.5.4.

Learn more about how The Gnar builds software.