How do you emulate nominal typing in TypeScript?

Question

I have many functions in my project that take an number as parameter; half the time this number is an index into an array, the other half of the time, it is a cursor position (a point between two entries in an array). This causes confusion, even with naming conventions.

I would like to enforce that the functions below are taking the intended nominal types.

class Index extends Number {}
class CursorPosition extends Number {}

function getElement(i: Index) {}
function getRange(p1: CursorPosition, p2: CursorPosition) {}

const myIndex: Index = 6;
const myPosition: CursorPosition = 6;

getElement(1); // would like this to fail at compile time
getRange(2, 3); // would like this to fail at compile time
getElement(myPosition); // would like this to fail at compile time
getRange(myIndex, myIndex); // would like this to fail at compile time

getElement(myIndex); // would like this to pass at compile time
getRange(myPosition, myPosition); // would like this to pass at compile time

I understand that typescript uses structural typing, and this is why this does no occur "out of the box".

Also, I have considered both boxing my variables and adding a arbitray propery:

class myNum extends Number { 
  l: "1";
}

or using a cast.

class myNum { 
  arb: "arbitrary property value";
}

const mn2: myNum = <any>8;

function getElement2(a: any[], i: myNum) {
  return a[<any>i];
}

getElement2([], mn2);
getElement2([], 6);

Any better ideas?

Answer 1

You can use branded types:

type Index =  Number & { __type: 'Index'}
type CursorPosition =  Number & { __type: 'CursorPosition'}


function getElement(i: Index) {}
function getRange(p1: CursorPosition, p2: CursorPosition) {}

function indexFromNumber(n: number) :Index {
    return n as any;
}

function cursorPositionFromNumber(n: number): CursorPosition {
    return n as any;
}

const myIndex: Index = indexFromNumber(6);
const myPosition: CursorPosition = cursorPositionFromNumber(6);

getElement(1); // error
getRange(2, 3);  // error
getElement(myPosition);  // error
getRange(myIndex, myIndex); // error

getElement(myIndex); // ok 
getRange(myPosition, myPosition); //ok 

You need to define a helper function to create instances of the type or use type assertions ( const myIndex = 1 as any as Index), but the call site will give errors if you pass a simple number.

This article has a bit more of a discussion on the topic. Also the typescript compiler uses this approach for paths