Problem: Union properties don't narrow

declare function assertType<T>(arg: T);

interface Circle {
  kind: 'circle';
}
interface Square {
  kind: 'square';
}

interface House<TDoor> {
  door: TDoor;
}

declare const house: House<Circle | Square>;

if (house.door.kind === 'circle') {
  // Argument of type 'House<Circle | Square>' is not assignable to parameter of
  // type 'House<Circle>'.
  //                        👇👇👇
  assertType<House<Circle>>(house);
}

Solution 1: Narrow the property by itself, then reconstruct

declare const house: House<Circle | Square>;

const { door } = house;

if (door.kind === 'circle') {
  assertType<House<Circle>>({ door });
}

Solution 2: Union property to union the whole thing

declare function assertType<T>(arg: T);

type Shape = Circle | Square;

interface House<TDoor extends Shape = Shape> {
  kind: TDoor['kind'];
  door: TDoor;
}

declare const house: House<Circle> | House<Square>;

// Still does not work
if (house.door.kind === 'circle') {
  // Argument of type 'House<Circle> | House<Square>' is not assignable to parameter of
  // type 'House<Circle>'.
  //                        👇👇👇
  assertType<House<Circle>>(house);
}

// Using the new property we added does work though!
if (house.kind === 'circle') {
  assertType<House<Circle>>(house);
}

Related TypeScript issue: https://github.com/Microsoft/TypeScript/issues/27272

Problem: Discriminated union definitions are verbose

// So verbose! 👎 Too much boilerplate for a one-off use case.

interface Circle {
  kind: 'circle';
}

interface Square {
  kind: 'square';
}

type Shape = Circle | Square;

const data: Shape = { kind: 'circle' };

Solution: Skip defining types

// More pragmatic

type Shape2 = { kind: 'circle' } | { kind: 'square' };

const data2: Shape2 = { kind: 'circle' };

/* --- */

// Most pragmatic! 👍 Don't bother defining the types at all. We'll still get
// type errors if we mess up.
const data3 = { kind: 'circle' as const };

Problem: Pulling a property off a union is verbose

Solution: Define more propery types to allow direct property access

type Result<T> = { kind: 'ok'; value: T } | { kind: 'err'; msg: string };

declare const result: Result<number>;

// So verbose! 🤮 (More of my code looks like this than would ideal)
const value = result.kind === 'ok' ? result.value : undefined;

/* --- */

type Result2<T> =
  | { kind: 'ok'; value: T; msg?: undefined }
  | { kind: 'err'; value?: undefined; msg: string };

declare const result2: Result2<number>;

// Much better! 😌
const value2 = result2.value;

declare const result3: Result2<{ nested: string }>;

// And it works with optional chaining! 🎊
const value3 = result3.value?.nested;

Discriminated Unions

https://www.typescriptlang.org/docs/handbook/unions-and-intersections.html

// In TypeScript, discriminated unions are a union with a "discriminate".
// In the below example, "kind" is the discriminate.

export type Animal =
  | { kind: 'sheep' }
  | { kind: 'cat', breed: 'house' | 'wild' }
  | { kind: 'human', greeting: string }

export function speak(animal: Animal) {
  switch (animal.kind) {
		case 'cat':
      return animal.breed === 'domestic' ? 'meow' : 'ROAR';
    case 'sheep':
      return 'baa';
    case 'human':
      return animal.greeting;
    default
      assertNever(animal);
  }
}

• Simple use cases results in brief code
• Natural pattern is to switch in consuming code, which can become verbose when there is a large number of functions that access many variants.
• Callers of speak have full knowledge of the data in each animal.
• Caller of speak need to import the the type Animal, and the function separately.
• Logic for each variant lives alongside similar logic for other variants
• Naturally organizes functions near their consumers. Because of this:
  • speak is more likely it will get deleted when it is no longer used.
  • When code splitting, only required functions are be included ¹
• Because Animal doesn't control its own data, we likely won't be organizing many tests around Animal. Instead, many test will be against individual functions, or against callers of those functions.

Possible file layout

Polymorphism

https://www.typescriptlang.org/docs/handbook/interfaces.html

// Could also be a class
interface Animal {
  speak(): string;
}

class Sheep implements Animal {
  speak() {
    return 'baa';
  }
}

function createCat(breed: 'house' | 'wild'): Animal {
	return {
		breed,
    speak() {
      return this.breed === 'house' ? 'meow' : 'ROAR';
    }
  };
}

class Human implements Animal {
	constructor(
    private greeting: string;
  ) {};
  speak() {
    return this.greeting;
  }
}

• Scales cleanly to large numbers of variants
• Callers of speak only need to import Animal, or nothing at all.
• Information is hidden from callers of speak.
• Animal related logic can be more easily be stubbed out when testing other code.
• Logic for each variant lives alongside that variants definition
• Naturally organisms logic near type definitions. Because of this:
  • Tests naturally become written around Animal, and its functions.
  • Harder to delete/detect unused code
  • When code splitting, more unused methods will be included in bundles ¹
• Allows for easy dependency injection

Possible file layout

Polymorphic Discriminated Unions

interface IAnimal {
	kind: string;
  speak(): string;
}

class Sheep implements Animal {
	kind = 'sheep' as const;
  speak() {
    return 'baa';
  }
}

interface Cat extends IAnimal {
  kind: 'cat';
  breed: 'house' | 'wild';
}

function createCat(breed: Cat['breed']): Cat {
	return {
    kind: 'cat';
		breed,
    speak() {
      return this.breed === 'house' ? 'meow' : 'ROAR';
    }
  };
}

class Human implements Animal {
  kind: 'human' as const;
	constructor(
    private greeting: string;
  ) {};
  speak() {
    return this.greeting;
  }
}

export type Animal = Sheep | Cat | Human;

• Well suited for cases were most logic should live near the type definitions, but we need to get access to concrete data outside of the definitions occasionally.
• Most complex. Easiest to make a mess of things with.

Notes

• Both patterns work fine with both mutable and functional styles. Don't sleep on using classes just because you're writing functionally.

TLDR

Gatsby's more barebones approach to styling and layout match my taste better than Next.js's more filled-in blog template. Gatsby's plugins make it easy to add functionality, and Next.js doesn't have anything comparable. I'd recommend Gatsby to people picking between the two, but I'm not reverting my switch to Next.js any time soon.

Gatsby

https://gatsby-starter-blog-demo.netlify.app/

It was real easy to get started with Gatsby. I felt comfortable deploying the starter mostly it as-is, and the plugins made it real easy to add functionality. I used the gatsby-remark-prismjs plugin to add syntax highlighting to my code blocks.

The starter wasn't 100% to my liking though. To understand everything in the starter you need to know GraphQL, which I don't. I opted to ignore the query under each page and pray they didn't break.

I also really wanted types, which wasn't included out of the box. I was able to add TypeScript types to the JavaScript code easily enough, but much of the logic is in the plugins and GraphQL, so I didn't end up with much type coverage.

Next.js

https://next-blog-starter.now.sh/

Next.js's starter blog needed more tweaks before I was ready to use it. The most glaring issue was that the example wouldn't start.

next
ready - started server on http://localhost:3000
error - ./styles/index.css (./node_modules/css-loader/dist/cjs.js??ref--5-oneOf-6-1!./node_modules/next/dist/compiled/postcss-loader/cjs.js??ref--5-oneOf-6-2!./styles/index.css)
Error: PostCSS plugin postcss-nested requires PostCSS 8.

The starter looks to be make for a blog with multiple contributors, meaning I had to delete a bunch of stuff, and it is missing and RSS feed. (Although it does have have a link to a RSS feed in its head 🤔)

Adding code block syntax highlighting was a real hassle. Maybe I just don't know what to search for? I Eventually I ended up looking through the source code for gatsby-remark-prismjs, and didn't see anything Gatsby specific. In fact, it's not Gatsby-not-specific enough that I was able to use it with Next.js! The only price I appear to be paying is a new warning on yarn install.

warning " > gatsby-remark-prismjs@3.10.0" has unmet peer dependency "gatsby@^2.0.0".

You think they'd take a pull request to remove the Gatsby dependency? 🤔

Out of the box Tailwind CSS is used for styling. Tailwind had been getting a lot of good press recently, so it seems like a good choice? if I didn't already have styles from the Gatsby version of my blog I likely would have kept it around.

Pros and Cons

Gatsby

• 👍 Out of the box the template was a good fit for my needs
• 👍 Rich plugin ecosystem makes it easy to enhance your blog with new functionality
• 👎 Requires learning GraphQL to take full advantage of its capabilities
• 👎 No out-of-the-box TypeScript option
• 🤷‍♂️ Typography.js is used for styles out of the box

Next.js

• 👍 Both JavaScript and TypeScript variations
• 👎 Doesn't have anything to match Gatsby's rich plugin ecosystem
• 👍 getStaticProps makes it easy to use existing Node knowledge to add data non-javascript stuff built time
• 👍 Tailwind CSS is used for styles out of the box
• 👎 I got a build error when starting the example for the first time

Reasons to RTFM

• Less likely to be outdated
• Less likely to be incorrect
• Provides more context
• Documentation gets easier to read the more time is spent with it
• You’re learning while you’re searching

It's easy to get in a habit of immediately looking up ready-made solutions; never slowing down to more deeply understand our problems, and our tools. Not only can ready-made solutions create shallow knowledge, total time spend can be longer if few people have had the same problem, or if we're not knowledgeable enough to know what to look for.

Stack Overflow is still great, but it’s not the first resource I would reach for.

More great reading material

• Source code: Will make you a better developer
• Patch notes: May have better information on the latest features than the docs
• Repo issues: The best way to find solutions to project/library specific problems

I'm a huge fan of the JavaScript pattern where one replaces a switch:

function handle(event) {
  switch (event.kind) {
    case 'goblins_are_coming':
      repelMonsters(event);
    case 'family_is_coming':
      stockFridge(event);
  }
}

with an object:

const eventHandlers = {
  goblins_are_coming: repelMonsters,
  family_is_coming: stockFridge,
};

The second method really shines when we don't want to specify the kinds of events we are handling in the same file.

import familyEventHandlers from './familyEventHandlers';

export default const eventHandlers = {
  goblins_are_coming: repelMonsters,
  ...familyEventHandlers,
};

The pattern doesn't work in TypeScript very well

Assume this is written above the rest of the TypeScript examples:

interface GoblinEvent {
  kind: 'goblins_are_coming';
  smell: number;
}

interface FamilyEvent {
  kind: 'family_is_coming';
  notice: number;
}

type OurEvent = GoblinEvent | FamilyEvent;

declare const repelMonsters: (event: GoblinEvent) => void;
declare const stockFridge: (event: FamilyEvent) => void;

TypeScript plays fine with the first JavaScript example.

function handle(event: FamilyEvent | GoblinEvent) {
  switch (event.kind) {
    case 'goblins_are_coming':
      repelMonsters(event);
    case 'family_is_coming':
      stockFridge(event);
  }
}

But can't make sense of the second one.

const eventHandlers = {
  goblins_are_coming: repelMonsters,
  family_is_coming: stockFridge,
};

declare const e: OurEvent;

eventHandlers[e.kind](e);

This ☝ produces this 👇 error message.

Argument of type 'OurEvent' is not assignable to parameter of type 'GoblinEvent & FamilyEvent'.
  Type 'GoblinEvent' is not assignable to type 'GoblinEvent & FamilyEvent'.
    Property 'notice' is missing in type 'GoblinEvent' but required in type 'FamilyEvent'.ts(2345)

Here's the great (terrible?) hack to make it work

function handle<P extends OurEvent, T extends P['kind']>(
  payload: P,
  stuff: { [K in T]: (arg0: P) => void },
) {
  stuff[payload.kind](payload);
}

handle(e, eventHandlers);

No type errors! 🎊

... but with a catch.

This works because the interface is still generic when accessed. To keep this compiling, the object must preserve it's mapped typings as long as the event is generic.

That is to say, the following produces a type error:

function handleWrapper<P extends OurEvent>(payload: P) {
  handle(payload, eventHandlers);
}

TLDR:

Check this out:

function handle<P extends OurEvent, T extends P['kind']>(
  payload: P,
  stuff: { [K in T]: (arg0: P) => void },
) {
  stuff[payload.kind](payload);
}

async function seriousBusinessLogic(pickAColor) {
  const favorite = await pickAColor('Pick your favorite', [
    'steelblue',
    'darkgoldenrod',
    'olivedrab',
  ]);

  const leastFavorite = await pickAColor(
    'Please pick your least favorite of these colors',
    ['aquamarine', 'darksalmon', 'rebeccapurple'],
  );

  alert(`You picked ${favorite}, and ${leastFavorite}`);
}

The most immediate benefit is not splitting the above code into multiple parts. We can keep the dispatching logic and the resulting effects in the same block as they should be; as well as chaining multiple requests together easily and naturally.

Promises also let us keep this business logic hidden inside of a component when we need to call into outside components to get our answer. Suppose this question could be best answered using the ui of an already mounted component, and this was a regular callback that didn't return a promise. The component that needs the question answered would need to set a flag inside of itself and then wait for the answer to come down as a prop. But, other components that ask the same question may also receive the prop, and because the answer is stateful we would need to call another callback to clear the answer prop.

This could all be avoided by moving all this logic and state into a higher component, but, that defeats our original goal of isolation. On the other hand, if the question can be answered by a modal inside of the current class we should likely just do that.

I've used this trick successfully in these situations:

• The question was being asked a lot. We could just render a modal in the current context whenever we need to and be done with it; but creating a service to answer a frequent question saves a large amount of time.
• The question could only be answered by other components. Other components need to be interacted with by the user to get the question answered or other components have state inside of them that we don't want to pass around.