TypeScript as: Type Assertions and Casting Explained

value as Type is a type assertion: it tells TypeScript to treat value as Type. People call it a cast, but it is only an instruction to the compiler. It is erased from the JavaScript output, converts nothing and checks nothing at run time.

interface Config {
  port: number;
  host: string;
}

const text = '{"port": 8080, "host": "localhost"}';

// JSON.parse returns any; the assertion gives the result a useful type
const config = JSON.parse(text) as Config;

console.log(config.port + 1);            // 8081
console.log(config.host.toUpperCase());  // LOCALHOST

This is the typical use: you know more about a value than the compiler can (here, the shape of some JSON), and you say so. If you are wrong, nothing warns you. The next sections show what that means and when a runtime check is the better choice.

as and the Angle-Bracket Syntax

There are two spellings of the same assertion:

const someValue: unknown = "hello";
const a = someValue as string;   // as syntax
const b = <string>someValue;     // angle-bracket syntax, same meaning

The angle-bracket form is not allowed in .tsx files, where <string> would read as a JSX tag. Use as everywhere and the question never comes up. Assertions bind loosely, so wrap them in parentheses when you continue the expression: (value as string).length.

Assertions Do Not Convert Values

This is the part that causes real bugs. An assertion changes what the compiler believes about a value, not the value itself:

const input: unknown = "42";

const asserted = input as number;  // compiles: unknown can be asserted to anything
const converted = Number(input);   // an actual conversion

console.log(asserted + 1);   // 421 (string concatenation: it is still "42")
console.log(converted + 1);  // 43
console.log(typeof asserted, typeof converted); // string number

The compiler believes asserted is a number, so asserted + 1 type-checks as arithmetic. At run time it is still the string "42" and JavaScript concatenates. To change a value's type, convert it: Number(x), String(x), Boolean(x), BigInt(x), new Date(x). The string to number page compares the conversion functions.

What the Compiler Allows

as is not unlimited. TypeScript allows x as T when one type is assignable to the other: widening ("a" as string, dog as Animal) and narrowing (animal as Dog, unknown as User) are both fine. When the types do not overlap at all, it refuses:

// This does not compile: string and number do not overlap.
const input = "42";
const n = input as number;

console.log(n);

The compiler reports index.ts(3,11): error TS2352: Conversion of type 'string' to type 'number' may be a mistake because neither type sufficiently overlaps with the other. If this was intentional, convert the expression to 'unknown' first. The message itself names the escape hatch: input as unknown as number. That double assertion compiles, and it is exactly as wrong at run time as the example above. When you feel the need for it, the right fix is usually a conversion (Number(input)) or a different type.

The overlap rule is loose for objects. An object literal that has some of the properties is accepted, which is how as quietly lets incomplete objects through:

interface User {
  name: string;
  email: string;
}

const draft = { name: "Ada" } as User; // compiles: email is missing
const empty = {} as User;              // compiles too

console.log(draft.name);               // Ada
console.log(typeof draft.email);       // undefined, although the type says string
console.log(empty.name?.length);       // undefined

An annotation (const draft: User = { name: "Ada" }) or satisfies User would report the missing email (TS2741). Use as on an object literal only when you really intend to fill it in later, and prefer building the complete object.

as const Is Different

as const looks like an assertion but does the opposite of loosening: it makes a literal as narrow as possible. Strings stay literal types, arrays become readonly tuples, and object properties become readonly.

const sizes = ["small", "medium", "large"] as const;
type Size = (typeof sizes)[number]; // "small" | "medium" | "large"

const point = { x: 1, y: 2 } as const; // { readonly x: 1; readonly y: 2 }

function isSize(value: string): value is Size {
  return (sizes as readonly string[]).includes(value);
}

console.log(isSize("medium"), isSize("huge")); // true false
console.log(point.x + point.y);                // 3

It is safe, because it describes the literal exactly rather than claiming something the compiler cannot see. (The sizes as readonly string[] inside isSize is a widening assertion, also safe: it lets includes accept any string.) See literal types for more.

When a Type Guard Is the Better Tool

as is a claim; a type guard is a check. At a boundary where data comes from outside your code (JSON, fetch, localStorage, user input, a message), the claim can be false, and an assertion turns a clear error at the boundary into a confusing one somewhere else.

interface Point {
  x: number;
  y: number;
}

function isPoint(v: unknown): v is Point {
  return typeof v === "object" && v !== null &&
    "x" in v && typeof v.x === "number" &&
    "y" in v && typeof v.y === "number";
}

const raw: unknown = JSON.parse('{"x": 3, "y": "4"}');

// With as: compiles, and the bug surfaces later
const p1 = raw as Point;
console.log(p1.x + p1.y); // 34 (a string snuck in)

// With a guard: the bad data is caught where it enters
if (isPoint(raw)) console.log(raw.x + raw.y);
else console.log("invalid point");

A rough guide to the tools that look alike:

Two good uses of as remain: narrowing something the compiler cannot follow (a Map entry you set two lines earlier, a value from an untyped library), and test code that builds partial fixtures. Keep them small and close to the place where you know the claim is true.