Tag types

[zpdDG4gta8XKpMCd]

Problem

• There is no straight way to encode a predicate (some checking) about a value in its type.

Details

There are situations when a value has to pass some sort of check/validation prior to being used. For example: a min/max functions can only operate on a non-empty array so there must be a check if a given array has any elements. If we pass a plain array that might as well be empty, then we need to account for such case inside the min/max functions, by doing one of the following:

• crashing
• returning undefined
• returning a given default value

This way the calling side has to deal with the consequences of min/max being called yet not being able to deliver.

function min<a>(values: a[], isGreater: (one: a, another: a) => boolean) : a {
   if (values.length < 1) { throw Error('Array is empty.'); }
   // ...
}
var found;
try {
   found = min([]);
} catch (e) {
   found = undefined;
}

Solution

A better idea is to leverage the type system to rule out a possibility of the min function being called with an empty array. In order to do so we might consider so called tag types.

A tag type is a qualifier type that indicates that some predicate about a value it is associated with holds true.

const enum AsNonEmpty {} // a tag type that encodes that a check for being non-empty was passed

function min<a>(values: a[] & AsNonEmpty) : a {
   // only values that are tagged with AsNonEmpty can be passed to this function
   // the type system is responsible for enforcing this constraint
   // a guarantee by the type system that only non-empty array will be passed makes
   // implementation of this function simpler because only one main case needs be considered
   // leaving empty-case situations outside of this function
}

min([]); // <-- compile error, tag is missing, the argument is not known to be non-empty
min([1, 2]); // <-- compile error, tag is missing again, the argument is not know to be non-empty

it's up to the developer in what circumstances an array gets its AsNonEmpty tag, which can be something like:

// guarntee is given by the server, so we always trust the data that comes from it
interface GuaranteedByServer {
    values: number[] & AsNonEmpty;
}

Also tags can be assigned at runtime:

function asNonEmpty(values: a[]) : (a[] & AsNonEmpty) | void {
    return values.length > 0 ? <a[] & AsNonEmpty> : undefined;
}

function isVoid<a>(value: a | void) : value is void {
  return value == null;
}

var values = asNonEmpty(Math.random() > 0.5 ? [1, 2, 3] : []);
if (isVoid(values)) {
   // there are no  elements in the array, so we can't call min
   var niceTry = min(values); // <-- compile error; 
} else {
    var found = min(values); // <-- ok, tag is there, safe to call
}

As was shown in the current version (1.6) an empty const enum type can be used as a marker type (AsNonEmpty in the above example), because

• enums might not have any members and yet be different from the empty type
• enums are branded (not assignable to one another)

However enums have their limitations:

• enum is assignable by numbers
• enum cannot hold a type parameter
• enum cannot have members

A few more examples of what tag type can encode:

• string & AsTrimmed & AsLowerCased & AsAtLeast3CharLong
• number & AsNonNegative & AsEven
• date & AsInWinter & AsFirstDayOfMonth

Custom types can also be augmented with tags. This is especially useful when the types are defined outside of the project and developers can't alter them.

• User & AsHavingClearance

ALSO NOTE: In a way tag types are similar to boolean properties (flags), BUT they get type-erased and carry no rutime overhead whatsoever being a good example of a zero-cost abstraction.

UPDATED:

Also tag types can be used as units of measure in a way:

• string & AsEmail, string & AsFirstName:

var email = <string & AsEmail> 'aleksey.bykov@yahoo.com';
var firstName = <string & AsFirstName> 'Aleksey';
firstName = email; // <-- compile error

• number & In<Mhz>, number & In<Px>:

var freq = <number & In<Mhz>> 12000;
var width =   <number & In<Px>> 768;
freq = width; // <-- compile error

function divide<a, b>(left: number & In<a>, right: number & In<b> & AsNonZero) : number & In<Ratio<a, b>> {
     return <number & In<Ratio<a, b>>> left  / right;
}

var ratio = divide(freq, width); // <-- number & In<Ratio<Mhz, Px>>

[mhegazy]

A few thoughts, in the typescript compiler we have used brands to achieve a similar behavior, see: https://github.com/Microsoft/TypeScript/blob/master/src/compiler/types.ts#L485; #1003 could make creating tags a little bit cleaner. A nominal type would be far cleaner solution (#202).

[zpdDG4gta8XKpMCd]

one more use case just came across:

var scheduled = setTimeout(function() { }, 1000);
clearInterval(scheduled); // <-- runtime bug

with type tag this situation could have been avoided

declare function setTimeout(act: () => void, delay: number) : number & AsForTimeout;
declare function clearInterval(scheduled: number & AsForInterval);
var scheduled = setTimeout(function() { }, 1000);
clearInterval(scheduled); // <-- compile error

[jovdb]

With Typescript 2 you can now simulate the behavior you want:

declare class MinValue<T extends number> {
    private __minValue: T;
}

// MinValue type guard
function hasMinValue<T extends number>(value: number, minValue: T): value is number & MinValue<T> {
    return value >= minValue;
}

// Use it
function delay(fn: Function, milliSeconds: number & MinValue<0>) { }

const delayInMs = 200;
delay(() => { }, delayInMs); // error: number not assignable to MinValue<0>

if (hasMinValue(delayInMs, 0)) {
    delay(() => { }, delayInMs); // OK
}

if (hasMinValue(delayInMs, 100)) {
    delay(() => { }, delayInMs); // error: MinValue<100> not assignable to MinValue<0>
}

with this concept, you can also create Ranges:

// MaxValue 
declare class MaxValue<T extends number> {
    private __maxValue: T;
}

// MaxValue type guard
function hasMaxValue<T extends number>(value: number, maxValue: T): value is number & MaxValue<T> {
    return value <= maxValue;
}

// RangeValue
type RangeValue<TMin extends number, TMax extends number> = MinValue<TMin> & MaxValue<TMax>; 

// RangeValue type guard
function inRange<TMin extends number, TMax extends number>(value: number, minValue: TMin, maxValue: TMax): value is number & RangeValue<TMin, TMax> {
    return value >= minValue && value >= maxValue;
}

// Range example
//-----------------
type Opacity = RangeValue<0, 1>;
function setTransparency(opacity: number & Opacity) {
   // ...
}


const opacity = 0.3;
setTransparency(opacity); // error: 'number' not assignable to MinValue<0>

if (inRange(opacity, 0, 1)) { 
    setTransparency(opacity); // OK
}

if (inRange(opacity, 0, 3)) { 
    setTransparency(opacity); // error: MinValue<0> & MaxValue<3> not assignable to MinValue<0> & MaxValue<1>
}