Type-safe refinements (type guards) in TypeScript (moved to https://github.com/karol-majewski/refinements)

safe-type-guards.ts

namespace Refinement {
  class Hit<T> {
    constructor(readonly value: T) {}
  }
  
  class Miss {}

  type Result<T> = Hit<T> | Miss;

  export function hit<T> (value: T) {
    return new Hit(value);
  }

  export const miss = new Miss();

  export function create<T, U extends T>(refine: (candidate: T) => Result<U>): (candidate: T) => candidate is U {
    return (candidate): candidate is U => refine(candidate) instanceof Hit;
  }
}

Usage:

class Cat {
  meow(): void {}
}

class Dog {
  bark(): void {}
}

type Pet = Cat | Dog;

const isCat = Refinement.create(
  (pet: Pet) => pet instanceof Cat
    ? Refinement.hit(pet)
    : Refinement.miss
)

console.log(
  isCat(new Cat()), // true ✅
  isCat(new Dog()) // false ✅
)

With regular type guards, it's easy to make a mistake. The body of user-defined type guards is not type-checked.

class Cat {
  meow(): void {}
}

class Dog {
  bark(): void {}
}

type Pet = Cat | Dog;

const isCat = (pet: Pet): pet is Cat =>
  pet instanceof Dog; // Bad!

console.log(
  isCat(new Cat()), // false ⛔️
  isCat(new Dog()) // true ⛔️
)

The implementation of isCat is incorrect, but TypeScript doesn't care.

TypeGuard.create solves that problem.

This approach is used by fp-ts:

https://gcanti.github.io/fp-ts/modules/Option.ts.html#getrefinement

Type guards use cases: use for filter and discrimination.