How to define an opaque type in TypeScript?

by

That is because TypeScript type system is “structural”, so any two types with the same shape will be assignable one to each other – as opposed to “nominal”, where introducing a new name like Foo would make it non-assignable to a same-shape Bar type, and viceversa.

There’s this long standing issue tracking nominal typings additions to TS.

One common approximation of opaque types in TS is using a unique tag to make any two types structurally different:

// opaque type module:
export type EUR = { readonly _tag: 'EUR' };
export function eur(value: number): EUR {
  return value as any;
}
export function addEuros(a: EUR, b: EUR): EUR {
  return ((a as any) + (b as any)) as any;
}

// usage from other modules:
const result: EUR = addEuros(eur(1), eur(10)); // OK
const c = eur(1) + eur(10) // Error: Operator '+' cannot be applied to types 'EUR' and 'EUR'.

Even better, the tag can be encoded with a unique Symbol to make sure it is never accessed and used otherwise:

declare const tag: unique symbol;
export type EUR = { readonly [tag]: 'EUR' };

Note that these representation don’t have any effect at runtime, the only overhead is calling the eur constructor.

newtype-ts provides generic utilities for defining and using values of types that behave similar to my examples above.

Branded types

Another typical use case is to keep the non-assignability only in one direction, i.e. deal with an EUR type which is assignable to number:

declare const a: EUR;
const b: number = a; // OK

This can be obtained via so called “branded types”:

declare const tag: unique symbol
export type EUR = number & { readonly [tag]: 'EUR' };

See for instance this usage in the io-ts library.

More Related Contents:

  1. Transform union type to intersection type
  2. Type union not checking for excess properties
  3. ‘any’ vs ‘Object’
  4. Create a global variable in TypeScript
  5. Get an object’s class name at runtime
  6. How to use jQuery with TypeScript
  7. Type definition in object literal in TypeScript
  8. Difference between Variance, Covariance, Contravariance and Bivariance in TypeScript
  9. How do I declare object value type without declaring key type?
  10. Typescript property does not exist on union type
  11. Specify method’s type without converting the method to property
  12. Angular 2 View will not update after variable change in subscribe
  13. Type for “every possible string value except …”
  14. How to combine known interface properties with a custom index signature?
  15. Call a global variable inside module
  16. Obtaining the return type of a function
  17. What does “… resolves to a non-module entity and cannot be imported using this construct” mean?
  18. tsc throws `TS2307: Cannot find module` for a local file
  19. What TypeScript version is Visual Studio Code using? How to update it?
  20. Why does TypeScript track mutation of function static properties?
  21. Array VS Type[] in Typescript
  22. TypeScript filter out nulls from an array
  23. typescript: validate excess keys on value, returned from function
  24. Typescript: Omit a property from all interfaces in a union, but keep the union structure
  25. Declaring abstract method in TypeScript
  26. TypeScript sorting an array
  27. How to extend the ‘Window’ typescript interface
  28. Generic and typeof T in the parameters
  29. How to make “handler” lookup for “dispatcher” style function be typed correctly
  30. Modules vs. Namespaces: What is the correct way to organize a large typescript project?

Leave a Comment