TypeScript Exclamation Mark: The Non-Null Assertion (!)

An exclamation mark after an expression, value!, is the non-null assertion operator. It removes null and undefined from the type, so a number | undefined can be used as a number. It is a promise to the compiler, not a check: nothing happens at runtime.

const prices = new Map<string, number>([
  ["tea", 2.5],
  ["coffee", 3.2],
]);

const tea = prices.get("tea");         // number | undefined
const coffee = prices.get("coffee")!;  // number

console.log(coffee.toFixed(2)); // 3.20
console.log(tea!.toFixed(2));   // 2.50: ! works on any expression

Without the !, tea.toFixed(2) is error TS18048, 'tea' is possibly 'undefined'. With it, the code compiles because you told the compiler the key exists.

What x! Does at Runtime: Nothing

The ! is erased from the output. The compiled JavaScript for prices.get("coffee")! is just prices.get("coffee"). If the assertion is wrong, the error appears later, at the first place the missing value is used:

const prices = new Map<string, number>([["tea", 2.5]]);

try {
  const juice = prices.get("juice")!; // compiles: the ! silences the check
  console.log(juice.toFixed(2));      // TypeError at runtime
} catch (e) {
  console.log((e as Error).message);
}

The program prints Cannot read properties of undefined (reading 'toFixed'). The crash happens on the line after the !, and in real code it can be much further away: the undefined may be stored in an object and blow up in a different file. That distance is why ! is risky.

Definite Assignment: let x!: T

The same symbol in a declaration means something related. TypeScript tracks whether a variable is assigned before it is read, and it cannot follow an assignment made inside another function:

// This does not compile: TypeScript cannot see the assignment inside init()
let config: { port: number };

function init() {
  config = { port: 8080 };
}

init();
console.log(config.port);

index.ts(9,13): error TS2454: Variable 'config' is used before being assigned.

let config!: { port: number }; is a definite assignment assertion: "this will be assigned before any read". It fixes the error, with the same catch as x!: if init() is ever skipped, the read gets undefined. Restructuring is usually better, for example const config = init(); with init returning the object.

Class Properties: prop!: T

With strictPropertyInitialization (part of strict), every class property must be initialized in its declaration or in the constructor. Otherwise you get TS2564: Property 'socket' has no initializer and is not definitely assigned in the constructor. When a property is set later by a method or a framework, prop!: T tells the compiler to accept it:

class Connection {
  url: string;
  socket!: { send(msg: string): string }; // set in open(), not in the constructor

  constructor(url: string) {
    this.url = url;
  }

  open() {
    this.socket = { send: (msg) => `sent "${msg}" to ${this.url}` };
  }
}

const c = new Connection("ws://example.com");
console.log(c.socket);            // undefined: declared but not set yet
c.open();
console.log(c.socket.send("hi")); // sent "hi" to ws://example.com

The first console.log shows the gap: the type says socket is always there, but before open() it is undefined. Calling c.socket.send at that point compiles and throws. If the property can really be missing, declare it socket?: ... and check it, or create the object in the constructor. The main place prop! is standard practice is a framework that fills a property after construction: Angular's @ViewChild(...) child!: ChildDirective (set before ngAfterViewInit runs), or ORM entity classes whose columns the library fills when it loads a row (MikroORM's documentation writes @Property() title!: string).

Safer Alternatives

Most ! can be replaced by something the compiler checks, or by a check that fails loudly at the right place:

function must<T>(value: T | null | undefined, what: string): T {
  if (value == null) throw new Error(`missing ${what}`);
  return value;
}

function assertDefined<T>(value: T, what: string): asserts value is NonNullable<T> {
  if (value == null) throw new Error(`missing ${what}`);
}

const env = new Map([["PORT", "8080"]]);

const port = must(env.get("PORT"), "PORT"); // string
console.log(Number(port) + 1);              // 8081

const host = env.get("HOST");
try {
  assertDefined(host, "HOST");
  console.log(host.toUpperCase()); // host is string after the assertion
} catch (e) {
  console.log((e as Error).message); // missing HOST
}

Both helpers narrow the type like ! does, but a wrong assumption produces missing HOST on the spot instead of a TypeError somewhere else. assertDefined is an assertion function (asserts value is ...): after the call, the compiler treats host as a string. More patterns in type guards.

The Other Exclamation Marks

! means different things depending on where it sits:

Only the first two are erased at compile time. !value and !!value run at runtime and return a boolean.