TypeScript Reference ยท Primitive and Special Types
TypeScript String, Number and Boolean wrapper types
Know the difference between string and String, number and Number, boolean and Boolean in TypeScript, and why the capitalized wrapper types should be avoided.
TypeScript has two kinds of names for the basic value types. The lowercase ones, string, number and boolean, describe the primitive values you use every day. The capitalized ones, String, Number and Boolean, describe the wrapper objects that JavaScript creates with new String("x"), plus the methods shared by all strings, numbers or booleans.
You almost never want the wrapper types. A primitive is assignable to its wrapper type, but a wrapper type is not assignable to the primitive. That one-way relationship produces confusing errors, so style guides ban the capitalized names in annotations.
let a: string = "text"; // use this let b: String = "text"; // legal, but avoid
Try it
Press Run (or Ctrl + Enter) to see the result here.
Program input ยท what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or readFileSync(0)), it gets the next line from this box.
Press Run (or Ctrl + Enter) to see the result here.
Program input ยท what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or readFileSync(0)), it gets the next line from this box.
Syntax
let x: string; let X: String; let y: number; let Y: Number; let z: boolean; let Z: Boolean;
| Type | Meaning |
|---|---|
string, number, boolean |
Primitive values. Use these in annotations. |
String, Number, Boolean |
Interfaces for the wrapper objects and the shared methods (toUpperCase, toFixed, valueOf). |
Edge cases:
Number("42"),String(7)andBoolean(x)called withoutneware conversion functions and return primitives. That use is fine.new Boolean(false)is a truthy object, a classic bug.typeof new String("a")is"object", so type guards ontypeof v === "string"do not see wrapper objects.BigIntandSymbolfollow the same pattern (bigintandsymbolare the primitives).
Usage notes
- Use lowercase in annotations. Linters flag the capitalized forms (
@typescript-eslint/no-wrapper-object-types). - Conversion functions are fine.
Number(str),String(n)andBoolean(v)are idiomatic. Avoid onlynewwith them. - Methods work on primitives.
"abc".toUpperCase()works because JavaScript temporarily wraps the primitive; you do not need the wrapper type. - Equality.
new String("a") === "a"isfalse, butnew String("a") == "a"istrue. Primitives avoid the issue. - Why the asymmetry? A primitive has every member of its wrapper interface, so it can be used where a wrapper is expected. A wrapper object is a different kind of value, so it cannot be used where a primitive is expected.
- Template literal types and string helper types work with
string, notString.
Related
string,number,boolean,Objectand{}- Lessons: Primitive types, Type compatibility