minewt

!Travis CI badge

A tiny newtype implementation for TypeScript.

Thanks to MayMoonsley for the very punny name
:3

Motivation

Type aliases are a very common tool in TypeScript for type abstraction. They
make it easy to assign names to more complex types, and can even be used for
some degree of type-level programming. However, sometimes, something like the
following crops up:

``typescript
type Dollars = number;
`

The name Dollars is now an _alias_ for number; now, instead of writing
pay(amount: number), we can write pay(amount: Dollars). However, this does
not create a new type; it is not a compile error to pass in any old number into
pay. At best, it serves as documentation for programmers reading the code, but
it doesn't provide any type safety.

Another approach is to take the Java route, and make a new object to wrap
numbers:

`typescript
class Dollars {
constructor(public readonly amount: number) {}
}
`

Now, we can convert to and from this new type via the constructor and field:

`typescript
const dollars: Dollars = new Dollars(3);
const amount: number = dollars.amount;
`

This has the type safety we want; Dollars is a distinct type from number!
Unfortunately, this creates a new object for every Dollars we have, and incurs
a boxing penalty. What we really want is to create a type with the same _runtime
representation_ as number, but create it as a distinct type, with neither
assignable to the other.

A newtype is the best of both worlds. A newtype:

* is a distinct type from its underlying type
* has the same runtime representation as its underlying type

After compilation, a newtype will be exactly the same as its underlying type;
all values of type Dollars will be numbers at runtime. It's safe to cast
between the two, since they have exactly the same representation. This makes
newtypes a kind of _zero-cost abstraction_.

Usage

To create the type and the wrapper:

`typescript
// Create the newtype itself
type Dollars = Newtype;

// Create the newtype wrapper function
const Dollars = newtype();
`

To wrap and unwrap values:

`typescript
// Wrap underlying type in newtype
const dollars: Dollars = Dollars(3);
// Unwrap newtype into underlying type
const amount: number = unwrap(dollars);

// A newtype creates a distinct type:
const x: Dollars = 3; // Error! Type '3' is not assignable to type 'Dollars'
`

To query the underlying representation type, use NewtypeRepr:

`typescript
type T = NewtypeRepr; // 'number'
`

You can also lift functions over the underlying type to functions over the
wrapped type using liftN and liftN2 (higher-arity lifting functions are easy
to define if necessary):

`typescript
function add(x: number, y: number): number {
return x + y;
}

const x: Dollars = ...;
const y: Dollars = ...;

const addDollars = liftN2(add);

const sum = addDollars(x, y);
`

It's even possible to make newtypes that are assignable to other newtypes, using
intersection types with &:

`typescript
type A = Newtype;
const A = newtype();

// B extends A
type B = Newtype & A;
const B = newtype();

const x: A = A(0); // okay
const y: A = B(0); // okay
const z: B = A(0); // compile error: Type 'A' is not assignable to type 'B'
`

Comparisons and Alternatives

minewt is very lightweight, and doesn't provide any specific newtype
implementations.

$3

* newtype-ts: uses a similar approach,
but heavier weight, as it's tightly integrated with functional optics as
part of the fp-ts community

$3

Another solution is to use tag types, which are a different zero-cost
abstraction with a somewhat similar purpose to newtypes. You can use tag types
to add information to a type, such as refinement information:

`typescript
function isEmail(str: string): str is string & Email {
// ...
}
``

Multiple tags can also be added to a single type. In contrast to newtypes, tag
types have a slightly different goal. Tag types are mostly geared towards
validation, like the example above, and adding tags is mostly done via type
predicates. Tags can generally be added to any type.

Some neat libraries that implement tag types:

* taghiro: implements tag types, and also
ships with many useful tags