Methods of primitives — JavaScript Codex

You can write "hello".toUpperCase() and get back "HELLO". That looks like you called a method on an object. But a string is a primitive, not an object. So how does a plain value suddenly grow methods? That trick is what this chapter is about, and understanding it clears up a whole class of confusing behavior later on.

Start with the two kinds of thing you’re dealing with.

A primitive:

Is a single value of a primitive type.
Comes in 7 types: string, number, bigint, boolean, symbol, null, and undefined.

An object:

Can hold many values, stored as named properties.
Is created with {}, for example {name: "Maya", age: 30}. Objects come in other shapes too — functions, for instance, are objects.

The headline feature of objects is that a property can hold a function. When it does, we call that property a method:

let maya = {
  name: "Maya",
  sayHi: function() {
    alert("Hi buddy!");
  }
};

maya.sayHi(); // Hi buddy!

Here maya is an object with a method sayHi. Call it with maya.sayHi() and it runs.

object maya

name“Maya”

sayHifunction

primitive str

“Hello”

An object bundles data and behavior under one name; a primitive is just one value.

JavaScript ships with many built-in objects already — ones for dates, errors, HTML elements, and more. Each carries its own set of properties and methods.

That power isn’t free. Objects are heavier than primitives. Each one needs extra machinery behind the scenes to track its properties, which costs memory and time.

A primitive that acts like an object

Whoever designed JavaScript ran into a genuine conflict:

People want to do a lot with strings and numbers — uppercase a string, round a number, and so on. Reaching for those operations as methods (str.toUpperCase()) feels natural.
Primitives need to stay fast and small. Making every string a full object would defeat the point.

The resolution is a little odd, but it works cleanly:

Primitives stay primitive. One value, nothing bolted on.
The language still lets you reach for methods and properties on strings, numbers, booleans, symbols, and bigints.
To make step 2 possible, when you access a property, JavaScript builds a temporary object wrapper that carries the value and the relevant methods, runs what you asked, then throws the wrapper away.

Each primitive type gets its own wrapper, and each provides a different set of methods: String, Number, Boolean, Symbol, and BigInt.

Take the string method str.toUpperCase(), which returns an uppercased copy of the string:

let str = "Hello";

alert( str.toUpperCase() ); // HELLO

Nothing surprising in the output. The interesting part is what happens between the dot and the call:

str is a primitive. The moment you touch a property on it, a temporary String wrapper object is created that knows the value "Hello" and carries methods like toUpperCase().
That method runs on the wrapper and returns a brand-new string, which alert shows.
The wrapper is destroyed. str is still the same lightweight primitive it always was.

primitive

str = “Hello”

→ .toUpperCase()

temporary String wrapper

value: “Hello”

toUpperCase() …

→

returns new string

“HELLO”

then: wrapper destroyed · str still just “Hello”

The wrapper lives only for the duration of one property access, then it's gone.

So you get object-style methods while the value stays a lean primitive.

Engines don’t take this literally. The specification describes a wrapper being created and destroyed, but a real engine will often skip building the object entirely and just do the work directly — as long as the observable result matches what the spec says. You get the convenience with none of the object overhead in practice.

Numbers have their own methods. For example, toFixed(n) rounds a number to n digits after the decimal point and returns the result as a string:

let n = 1.23456;

alert( n.toFixed(2) ); // 1.23

There are many more of these. The Numbers and Strings chapters go through the useful ones in detail.

Don't call the String/Number/Boolean constructors with new

Some languages, Java among them, let you deliberately build a wrapper object around a primitive with syntax like new Number(1) or new Boolean(false).

JavaScript keeps that syntax around for historical reasons, but you should avoid it. It creates real objects, and that breaks assumptions in several spots.

Watch what happens to typeof:

alert( typeof 0 ); // "number"

alert( typeof new Number(0) ); // "object"!

And an object is always truthy in a condition, no matter what value it wraps. So this runs the branch even though the wrapped number is 0:

let zero = new Number(0);

if (zero) { // zero is an object, so it's truthy
  alert( "zero is truthy!?!" );
}

Calling those same functions without new is a different story, and it’s genuinely useful. Without new, String, Number, and Boolean convert a value to the matching primitive type:

let num = Number("123"); // convert a string to a number (primitive)

That’s normal, everyday conversion code. The problem is strictly the new keyword.

null and undefined have no methods

null and undefined are the exceptions. Neither has a wrapper object, so neither provides any methods or properties. You could call them the most primitive of the primitives.

Try to read a property off one and you get a TypeError:

alert(null.test); // error

This is exactly why Cannot read properties of null (reading 'test') is one of the errors you’ll meet most often — it usually means a value you expected to be a string or object was actually null or undefined.

has methods

string → String
number → Number
bigint → BigInt
boolean → Boolean
symbol → Symbol

no methods

null
undefined

accessing a property throws

Five primitive types get wrappers and methods; two get nothing.

A property you set on a primitive vanishes

Because the wrapper is temporary, writing to it has no lasting effect. Consider:

let str = "Hello";

str.test = 5; // (*)

alert(str.test); // undefined

At line (*) a wrapper is created, test is set on that wrapper, and then the wrapper is immediately discarded — taking test with it. On the next line a fresh wrapper is created that knows nothing about test, so you read back undefined. (In strict mode the assignment itself throws; in non-strict mode it silently does nothing useful.) Primitives can’t store custom properties. If you need to attach data to something, you need an actual object.

Summary

Every primitive except null and undefined comes with a set of handy methods. The Numbers and Strings chapters cover the ones you’ll use.
Under the hood these methods run through a temporary wrapper object, but engines optimize the pattern so aggressively that calling them costs you effectively nothing.
null and undefined have no methods at all — reaching for a property on either one throws a TypeError.
You can build wrapper objects yourself with new Number(...) and friends, but don’t: the result is a truthy object, not a primitive, and it will surprise you.