TypeScript Literal Types and as const, with Examples

A literal type is a type with exactly one value: "up" is a type whose only member is the string "up", and 404 is a type whose only member is the number 404. On their own they are not very useful. Joined into a union, they give you a variable that accepts a fixed set of values and nothing else.

type Direction = "up" | "down" | "left" | "right";

function move(dir: Direction, steps: number) {
  console.log(`moving ${dir} by ${steps}`);
}

move("up", 3);
move("left", 1);

// @ts-expect-error: Argument of type '"north"' is not assignable to parameter of type 'Direction'.
move("north", 1);

Without the @ts-expect-error comment, the last call is a compile-time error (TS2345). With it, the program compiles and the call still runs and prints moving north by 1: literal types exist only for the compiler, and at runtime the value is an ordinary string.

String, Number and Boolean Literals

Any string, number, bigint or boolean value can be written as a type. The compiler then accepts only that exact value.

let method: "GET" = "GET";
let code: 404 = 404;
let ok: true = true;
let big: 10n = 10n;

type Port = 80 | 443 | 8080;
const port: Port = 443;

boolean itself is just the union true | false, which is why narrowing a boolean with if (flag) leaves false in the else branch.

Unions of Literals

The common use is a union that lists every allowed value. Inside the function the compiler narrows the union as you check it, so each branch knows exactly which value it has.

type Size = "sm" | "md" | "lg";

function padding(size: Size): number {
  if (size === "sm") return 4;
  if (size === "md") return 8;
  return 16; // size is "lg" here
}

const sizes: Size[] = ["sm", "md", "lg"];
console.log(sizes.map(padding)); // [ 4, 8, 16 ]

A union of string literals is the usual TypeScript alternative to an enum. It costs nothing at runtime, the values are plain strings you can log and send over JSON, and a typo is a compile error. More on the trade-offs in enums.

Widening: let vs const

When TypeScript infers a type from a literal, it looks at whether the value can change. A const variable can never be reassigned, so it keeps the literal type. A let variable can, so its type is widened to the general type.

const a = "hello"; // type: "hello"
let b = "hello";   // type: string
b = "bye";         // fine, b is a string

const n = 42;      // type: 42
let m = 42;        // type: number

let c = a;         // type: string (copying a literal into a let widens it)

console.log(a, b, n, m, c); // hello bye 42 42 hello

Hover over each name in the editor to see the inferred type. If you want a let that only holds certain values, annotate it: let mode: "light" | "dark" = "light".

Why Object Properties Widen

Properties of an object literal are mutable, so they widen too, even when the object is stored in a const. This is the most common way to meet literal types by accident:

// This does not compile: req.method is string, not "GET" | "POST"
function send(url: string, method: "GET" | "POST") {
  console.log(method, url);
}

const req = { url: "/users", method: "GET" };
send(req.url, req.method);

The compiler reports:

index.ts(7,15): error TS2345: Argument of type 'string' is not assignable to parameter of type '"GET" | "POST"'.

req is inferred as { url: string; method: string } because code later could run req.method = "DELETE". There are three fixes:

type Method = "GET" | "POST";

function send(url: string, method: Method) {
  console.log(method, url);
}

// 1. Annotate the object (or the property)
const r1: { url: string; method: Method } = { url: "/users", method: "GET" };

// 2. as const on the whole object: every property becomes readonly and literal
const r2 = { url: "/posts", method: "POST" } as const;

// 3. as const on one property only
const r3 = { url: "/tags", method: "GET" as const };

send(r1.url, r1.method);
send(r2.url, r2.method);
send(r3.url, r3.method);

A fourth option is satisfies, which checks the object against a type while keeping its literal property types.

as const

as const is a const assertion. Put it after an expression and the compiler infers the narrowest type it can:

• string, number and boolean values keep their literal types
• object properties become readonly
• array literals become readonly tuples with a fixed length

const config = {
  env: "production",
  retries: 3,
  hosts: ["a.example.com", "b.example.com"],
} as const;
// type: { readonly env: "production"; readonly retries: 3;
//         readonly hosts: readonly ["a.example.com", "b.example.com"] }

// @ts-expect-error: Cannot assign to 'env' because it is a read-only property.
config.env = "staging";

const point = [3, 4] as const; // type: readonly [3, 4]
const [x, y] = point;
console.log(config.retries, x + y); // 3 7

The assertion is compile-time only. The emitted JavaScript is the same object literal with as const removed, so nothing stops other code from mutating it at runtime. If you need a runtime guarantee, call Object.freeze as well.

A Union Type from an as const Array

A frequent pattern is to keep the allowed values in one array, which you can loop over at runtime, and derive the union type from it. (typeof arr)[number] means "the type of any element of arr".

const ROLES = ["admin", "editor", "viewer"] as const;
type Role = (typeof ROLES)[number]; // "admin" | "editor" | "viewer"

function isRole(value: string): value is Role {
  return (ROLES as readonly string[]).includes(value);
}

for (const input of ["editor", "owner"]) {
  console.log(input, isRole(input)); // editor true, then owner false
}

Without as const, ROLES would be string[] and Role would be plain string. The cast to readonly string[] in isRole is needed because includes on a tuple of literals only accepts those literals, and the point of the function is to test a string that might not be one. The same object pattern works for key/value maps: const Status = { Active: "active", Banned: "banned" } as const, then type Status = (typeof Status)[keyof typeof Status].

const Type Parameters

A generic function normally widens the literals you pass it. Since TypeScript 5.0 you can mark a type parameter const, which makes the compiler infer the argument as if it had as const on it, without asking the caller to write it.

function plain<T>(value: T) {
  return value;
}

function exact<const T>(value: T) {
  return value;
}

const a = plain({ kind: "circle", sizes: [1, 2] });
// type: { kind: string; sizes: number[] }

const b = exact({ kind: "circle", sizes: [1, 2] });
// type: { readonly kind: "circle"; readonly sizes: readonly [1, 2] }

console.log(a.kind === b.kind); // true

This is mostly a tool for library authors: route definitions, builders and schema helpers use it so callers get precise types from plain literals.

The Meanings of const

The keyword const shows up in four different places in TypeScript code:

None of them freezes an object at runtime. const obj = { a: 1 } still allows obj.a = 2; only reassigning obj itself is an error.