DEV Community

Typescript Nominal Type: The Right Way

Acid Coder on June 28, 2023

In case you don't know what RighFminal typing Typescript is a structural typing language, but it is possible to mimic the behavior of nominal typi...

Read full post

Ivan Kleshnin • Jul 10 '24 • Edited

Does not look like a proper solution:

class Thing {
  protected x?: never
}

type Test = boolean | Thing

let t1: Test = new Thing() // OK: allowed
let t2: Test = {}          // BAD: allowed
let t3: Test = 3424234     // OK: disallowed
let t4: Test = "3424"      // OK: disallowed

console.log(Object.keys(t1)) // BAD: x affects Object.keys / for-in loops
console.log(t2)
console.log(t3)
console.log(t4)

Acid Coder • Aug 6 '24

not sure i understand this

let t2: Test = {} is expected because x is supposed to be not exist

Ivan Kleshnin • Jul 10 '24 • Edited

Do this instead:

const brand = Symbol("brand")

class Thing {
  protected readonly [brand]: undefined
}

Symbols are enumerable by default but Object.keys and for-in work only with string props.
So it fixes all the above issues.

If you also want to prevent Object.assign copies, add this:

constructor() {
  Object.defineProperty(this, brand, {enumerable: false, configurable: false, writable: false})
}

Acid Coder • Apr 28 • Edited

no, dont mess with the runtime

the purspose is to hide the type while making it an nominal type, the result of your original example is actually correct and is expected

dphuang2 • Jun 28 '23

Have you looked at zod brand?

github.com/colinhacks/zod#brand

Acid Coder • Jun 28 '23 • Edited

I think zod brand is a very smart solution

but it has 2 problems

import { z, BRAND } from "zod";
const Cat = z.object({ name: z.string() }).brand<"Cat">();
type Cat = z.infer<typeof Cat>;

const cat = Cat.parse({ name: "simba" }); // or const cat = { name: "simba" } as Cat;
const catBrand = cat[BRAND];
type U = typeof catBrand; // { Cat: true }
console.log(catBrand); // undefined

still can access cat[BRAND]
type of cat[BRAND] and value of cat[BRAND] mismatched

1 is unsatisfying but overall is not a problem, because nobody is going to do that
2 is an easy fix, just add optional modifier, although it still mislead some to believe it may return { Cat: true }

overall I think zod solution is practically perfect

Acid Coder • Jun 28 '23 • Edited

update:

I missed one point:

to assign Cat type to a variable, you either do

const cat = { name: "simba" } as Cat;

since we want to avoid type assertion if possible

then we are left with:

const cat = Cat.parse({ name: "simba" });

which is slightly unintuitive

ideally, we want

const cat: Cat = { name: "simba" }

but this will error using zod method because it is missing symbol properties

peerreynders • Jun 29 '23 • Edited

In general TypeScript requires a runtime assertion in the absence of a compile time type assertion.

// Don't export this from the module
declare const validCat: unique symbol;

type Cat = {
  name: string;
  [validCat]: true;
};

function assertValidCat(
  maybeCat: Record<PropertyKey, unknown>
): asserts maybeCat is Cat {
  const entries = Object.entries(maybeCat);
  if (
    entries.length === 1 &&
    entries[0][0] === 'name' &&
    entries[0][1] === 'simba'
  )
    return;

  throw new Error('Not a Cat');
}

// outside of module

const catMaybe = { name: 'simba' }; // const catMaybe: { name: string }

assertValidCat(catMaybe);

const catDefinitely = catMaybe; // const catDefinitely: Cat, const catMaybe: Cat
console.log(Object.keys(catDefinitely).length); // 1

Playground

You can even do this to primitive types

type Cat = string & {
  [validCat]: true;
};

Assertion Functions

Source

A type predicate can be used to a similar end.

In a sense the fact that

const ab:AB = {a:1, b:2};

even works is no better than

const ab = {a:1, b:2} as AB;

Acid Coder • Aug 6 '24 • Edited

avoid type assertion because it is prone to error

playground

peerreynders • Aug 7 '24

You've missed the point.

Typescript's assignability has edge cases that may surprise some people, perhaps the most infamous one is that assignments are not subject to excess property checks.

So it could be argued:

type AB = { a: number; b: number; x: never };

// For nominal typing this assignment should
// ideally error as the literal isn't branded to begin with.
const ab: AB = { a: 1, b: 2 };

Compare that to

declare const validAB: unique symbol;
declare const validBA: unique symbol;

type AB = {
  a: number;
  b: number;
  [validAB]: true;
};

type BA = {
  a: number;
  b: number;
  [validBA]: true;
};

// https://www.typescriptlang.org/docs/handbook/release-notes/typescript-3-7.html#assertion-functions
function assertAB(
  maybeAB: Record<PropertyKey, unknown>
): asserts maybeAB is AB {
  const keys = Object.keys(maybeAB);
  if (
    keys.length === 2 &&
    typeof maybeAB['a'] === 'number' &&
    typeof maybeAB['b'] === 'number'
  )
    return;

  throw new Error('Not an AB type');
}

// const ab: AB = {a:1, b:2}
// error: Property '[validAB]' is missing in type '{ a: number; b: number; }' but required in type 'AB'.(2741)

// const ba: BA = {a:1, b:2}
// error: Property '[validBA]' is missing in type '{ a: number; b: number; }' but required in type 'BA'.(2741)

const ab = { a: 1, b: 2 };
// unbranded:  const ab: { a: number; b: number; }

assertAB(ab);
// now branded: const ab: AB
// … and IntelliSense only shows properties `a` and `b`

// const ba: BA = ab;
// error: Property '[validBA]' is missing in type 'AB' but required in type 'BA'.(2741)

console.log(ab);

playground