Suggestion: Units of measure

[dsherret]

This feature request is similar to units of measure in F#.

For example:

const metres = 125<m>;
const seconds = 2<s>;
let speed: number<m/s>;

speed = metres / seconds; // valid
speed = metres / seconds / 10<s>; // error -- cannot convert m/s**2 to m/s

(Moved from work item 1715 on Codeplex.)

Proposal

Last Updated: 2016-06-09
Copied from: https://github.com/dsherret/Units-of-Measure-Proposal-for-TypeScript

---

Overview

Units of measure is a useful F# feature that provides the optional ability to create tighter constraints on numbers.

TypeScript could benefit from a similar feature that would add zero runtime overhead, increase type constraints, and help decrease programmer error when doing mathematical calculations that involve units. The feature should prefer explicity.

Defining Units of Measure

Units of measure should probably use syntax similar to type aliases (#957). More discussion is needed on this, but for the purpose of this document it will use the following syntax:

type measure <name> [ = measure expression ];

The optional measure expression part can be used to define a new measures in terms of previously defined measures.

Example Definitions

type measure m;
type measure s;
type measure a = m / s**2;

Units of measure can be defined in any order. For example, a in the example above could have been defined before m or s.

Circular Definitions

Circular definitions are NOT allowed. For example:

type measure a = b;
type measure b = a; // error

Use with Number

Units of measure can be defined on a number type in any of the following ways:

type measure m;

// 1. Explicitly
let distance: number<m> = 12<m>;
// 2. Implictly
let distance = 12<m>;
// 3. Using Number class
let distance = new Number(10)<s>;

TODO: Maybe we shouldn't use the <m> syntax because it might conflict with jsx files.

Detailed Full Example

type measure m;
type measure s;
type measure a = m / s**2;

let acceleration = 12<a>,
 time = 10<s>;

let distance = 1/2 * acceleration * (time ** 2); // valid -- implicitly typed to number<m>
let avgSpeed = distance / time; // valid -- implicitly typed to number<m/s>

time += 5<s>; // valid
time += 5; // error -- cannot convert number to number<s>
time += distance; // error -- cannot convert number<m> to number<s>

// converting to another unit requires asserting to number then the measure
time += (distance as number)<s>; // valid

acceleration += 12<m / s**2>; // valid
acceleration += 10<a>; // valid
acceleration += 12<m / s**2> * 10<s>; // error -- cannot convert number<m/s> to number<a>

Use With Non-Unit of Measure Number Types

Sometimes previously written code or external libraries will return number types without a unit of measure. In these cases, it is useful to allow the programmer to specify the unit like so:

type measure s;

let time = 3<s>;

time += MyOldLibrary.getSeconds(); // error -- type 'number' is not assignable to type 'number<s>'
time += MyOldLibrary.getSeconds()<s>; // valid

Dimensionless Unit

A dimensionless unit is a unit of measure defined as number<1>.

let ratio = 10<s> / 20<s>; // implicitly typed to number<1>
let time: number<s>;

time = 2<s> * ratio; // valid
time = time / ratio; // valid
time = (ratio as number)<s>; // valid
time = 2<s> + ratio; // error, cannot assign number<1> to number<s>
time = ratio; // error, cannot assign number<1> to number<s>
time = ratio<s>; // error, cannot assert number<1> to number<s>

Scope

Works the same way as type.

External and Internal Modules

Also works the same way as type.

In addition, if an external library has a definition for meters and another external library has a definition for meters then they should be able to be linked together by doing:

import {m as mathLibraryMeterType} from "my-math-library";
import {m as mathOtherLibraryMeterType} from "my-other-math-library";

type measure m = mathLibraryMeterType | mathOtherLibraryMeterType;

TODO: The above needs more thought though.

Definition File

Units of measure can be defined in TypeScript definition files ( .d.ts) and can be used by any file that references it. Defining units of measure in a definition file is done just the same as defining one in a .ts file.

Compilation

The units of measure feature will not create any runtime overhead. For example:

type measure cm;
type measure m;

let metersToCentimeters = 100<cm / m>;
let length: number<cm> = 20<m> * metersToCentimeters;

Compiles to the following JavaScript:

var metersToCentimeters = 100;
var length = 20 * metersToCentimeters;

Math Library

Units of measure should work well with the current existing Math object.

Some examples:

Math.min(0<s>, 4<m>); // error, cannot mix number<s> with number<m> -- todo: How would this constraint be defined?

let volume = Math.pow(2<m>, 3)<m**3>;
let length = Math.sqrt(4<m^2>)<m>;

[danquirk]

Definitely love this feature in F#. Would need to pick some syntax for how you define these and make sure we're not too at risk for future JS incompatibility with whatever is picked.

[basarat]

👍

[electricessence]

Not sure if this should be in TypeScript. You can use classes to manage this:
https://github.com/electricessence/TypeScript.NET/blob/master/System/TimeSpan.ts
https://github.com/electricessence/Open.Measuring/blob/master/Measurement.ts

[dsherret]

You could, but using a class is a lot of overhead for doing calculations while ensuring type. It's also much more code to maintain and it's barely readable when doing complex calculations.

A units of measure feature adds no runtime overhead and—in my opinion—it would make the language much more attractive.

[zpdDG4gta8XKpMCd]

Meanwhile in order to simulate units of measure, thank to the dynamic nature of JavaScript, you can use interfaces and the trick to get nominal types

interface N<a> { 'i am a number measured in': a }
function numberOf<a>(value: number): N<a> { return <any>value; }
function add<a>(one: N<a>, another: N<a>) : N<a> { return <any>one + <any>another; }
interface Ft { 'i am a foot ': Ft }
interface M { 'i am a meter ': M }
var feet = numberOf<Ft>(2);
var meters = numberOf<M>(3);
feet = meters; // <-- a problem

unfortunately due to 'best common type' resolution (which hopefully is going to be fixed) the following wont be prevented:

var huh = add(feet, meters);

however this will be

var huh = add<Ft>(feet, meters); // <-- problem

[dsherret]

Some suggested syntax:

declare type m;
declare type s;
declare type a = m/s^2;

var acceleration = 12<a>,
 time = 10<s>;

var distance = 1/2 * acceleration * time * time; // distance is implicitly typed as number<m>

This could also allow for tiny types like so:

declare type email;

function sendEmail(email: string<email>, message : string) {
 // send the email in here
}

var myEmail = "david@email.com"<email>;
sendEmail(myEmail, "Hello!"); // valid
sendEmail("some string", "Hello!"); // invalid

Some outstanding questions I can think of:

1. Should this feature be allowed on types other than number? Maybe it should be allowed on just number and string?
2. If it's allowed on additional types, how does this feature work with a type that has generics? (Side note: when would this even be useful?)

[zpdDG4gta8XKpMCd]

David Sherret (@dsherret), unit measures are meant for primitive types for better type safety, more complex custom structures (including generics) don't need it, however standard built-in complex types might benefit from it too, so:

1. yes, for all primitive types including number, boolean and string (undefined, void, and null might have it too)
2. yes for standard types, sometimes it seems useful to assign a unit to an instance of Date for example

[dsherret]

Aleksey-Bykov ah yeah, I forgot about how it could be useful for boolean too. Date makes sense to me as well because you can't extend dates. Other than that, I don't see much use for it with anything else (including undefined, void, and null).

So:

• String
• Number
• Boolean
• Date

[dsherret]

I have started to write a proposal for this feature. Please offer your suggestions and criticisms. I've tried to make it similar to F#:

https://github.com/dsherret/Units-of-Measure-Proposal-for-TypeScript

I'm not at all familiar with the typescript compiler so I don't know how much of an impact this feature would have on it.

[saschanaz]

David Sherret (@dsherret), I think declare type m syntax would be able to cover other features such as typedef (#308). How about declare type m extends number, to get compatibility with potential other features? :D

Or, even without declare.

/* 
Types defined by this syntax can extend only one of the primitive types, or, only `number` for this feature.
`m` and `s` should be treated as two different types, both derived from `number`.
`m` and `s` should also be discriminated against `number`.
*/
type m extends number;
type s extends number;

/* Mathematic operators in type definition creates new type. */
type a = m / s ^ 2;
// Note: Wouldn't caret here be confusing, as it still works as a XOR operator in other lines?
var acceleration = <a>12;
var time = <s>10;

time += <s>5; // Valid
time += 5; // Error, not compatible
/* ... */

[dsherret]

Caret

I thought using caret might be confusing because it's usually used as the XOR operator, but to me the benefit of readability outweighs the potential confusion.

// This seems more readable to me:
type V = (kg * m^2) / (A * s^3);
// than this:
type V = (kg * m * m) / (A * s * s * s)

However, yeah it might cause some confusion when it's actually used in a statement:

var area = 10<m^2> + 20<m^2>;

Though I think the caret being within the angle brackets makes it fairly obvious that it's not the XOR operator, though I know some people would definitely think that on first glance. It is nicer than writing this:

var area = 10<m*m> + 20<m*m>;

and I think only allowing that would cause some people to write definitions like so (which I think would look gross in the code):

type m2 = m * m;
type m3 = m2 * m;

Definition

I thought using the declare keyword at the front was just a good way to piggy back on ambient definitions in order to avoid conflicts with any potential JS changes in the future; however, I think the chances of there being a type keyword is really low. Your shortening makes sense to me.

Here's some other alternatives I can think of:

type number<m>;
type string<email>;
// -- or
type m : number;
type email : string;

Before or after

I think doing this:

var distance = 100<m> + 20<m/s> * 10<s>;

...is more readable when visualizing the mathematics and aligns more with F#.

Doing this makes more sense with the statement type s extends number, but it's not as readable:

var distance = <m>100 + <m/s>20 * <s>10;

I don't know... I guess we can keep coming up with ideas for all of this.

[dsherret]

By the way, do you think it might be confusing to even referencing units of measure and tiny types as "types" (even though it's done in F#). Usually in javascript, when I think of a type, it's something I can use in plain javascript like: var t = new TypeName();. I think it might be good to separate this from the idea of typedefs.