ts-opaque

ts-opaque

Easy-to-use library that implements opaque types in TypeScript!

Installation

Install ts-opaque through npm:

$ npm install ts-opaque

Motivation

An opaque type, in TypeScript, is a type whose true structure is obfuscated to the compiler at compile-time. These types can make your code more type safe, secure, easier to refactor, and faster!

While Flow has an opaque keyword for creating opaque types, TypeScript does not; this package is my solution.

Usage

import Opaque from "ts-opaque";

interface User {
  readonly id: Opaque<number, User>;
  name: string;
}

interface Post {
  readonly id: Opaque<number, Post>;
  readonly authorId: User["id"];
  title: string;
  body: string;
}

let myUser: User = {
  // Error, type 'number' is not assignable to type 'Opaque<number, User>'
  id: 1,
  name: "John Doe",
};

myUser = {
  id: 1 as User["id"],
  name: "John Doe",
};

let myPost: Post = {
  // Error, type 'number' is not assignable to type 'Opaque<number, Post>'
  id: 1,
  // Error, type 'number' is not assignable to type 'Opaque<number, User>'
  authorId: 1,
  title: "ts-opaque",
  body: "It's a pretty cool package.",
};

myPost = {
  id: 1 as Post["id"],
  authorId: myUser.id,
  title: "ts-opaque",
  body: "It's a pretty cool package.",
};

There are other types and helper function ts-opaque exports as well! Check out the API below.

API

• Opaque - Create an opaque type.

Helper Types

• BaseType - Get the base type of an opaque type.
• BrandType - Get the brand type of an opaque type.

Helper Functions

• create - Cast a value to an opaque type.
• widen - Widen an opaque type to its base type.

Related Works

Others have made fantastic packages to implement opaque types in TypeScript. While these implementations are flawless in their functionality, ts-opaque brands its opaque types with symbol keys, hiding them directly from your IDE's intellisense or its equivalent. ts-opaque is also distributed with helper functions and types to manipulate and use opaque types easily. Spread some love to these works:

• ts-brand
• type-fest

License

This package is available as open source under the terms of the MIT License.