Constructors & new

One recipe, many objects

An object literal is the curly-brace way to write one object, like { name: "Ada" }. It is great when you need just one object.

But apps often need many objects with the same shape. Think of many users, many books, or many items in a shopping cart. Each one has the same property names, but different values.

A constructor function is a function that makes these objects for you. You write it once. Then you call it again for each new object. Constructor functions are an older JavaScript pattern, and you still see them in a lot of code.

You call a constructor with the word new, like new User("Ada"). In short, this is what happens:

• JavaScript makes a new, empty object.
• Inside the constructor, this means that new object.
• The constructor writes properties onto this.
• new gives the finished object back to you.

This lesson uses two things you already know. The first is functions, from Declaring & calling functions. The second is methods, where this is the object before the dot.

A constructor function is a normal function. The only difference is how you call it: with new.

By habit, its name starts with a capital letter: User, Book, Task. JavaScript does not need the capital. It is a sign for people who read the code: "call this with new."

function User(name) {
  this.name = name;
  this.role = "learner";
}

const ada = new User("Ada");
const grace = new User("Grace");
console.log(ada.name, grace.name);
console.log(ada === grace);

• Line 1 starts the User constructor. It takes one input, name.
• Lines 2 and 3 write two properties onto this: name and role.
• On line 6, new makes a new, empty object. Then it runs User with this set to that object. So the object in ada gets its own name and role.
• Line 7 calls the same constructor again. This makes a second, different object, for Grace.
• Line 8 prints Ada Grace. Line 9 prints false, because they are two different objects.

function Task(title) {
  this.title = title || "Untitled";
}

const task = new Task("");
console.log(task.title);

A constructor can also check an input before it stores it. On line 2, title || "Untitled" means: use title, but if it is empty, use "Untitled" instead.

Line 5 passes an empty title, so the task's title becomes "Untitled". That value is stored on this one task only.

Three things to remember from this section:

• ada.name is "Ada" and grace.name is "Grace". Each object keeps its own values.
• ada === grace is false. Each new call makes a separate object.
• You can't use an arrow function with new. Arrow functions can't be constructors, and they don't have their own this.

Here is what new User("Ada") does, in four steps. These steps are for a constructor function like User. (A class that extends another class follows slightly different steps. A later lesson covers that.)

1. Make a new, empty object.
2. Link that object to User.prototype, an object where shared methods live. You'll see what the link does below.
3. Run User with this set to the new object.
4. Give back the new object. The one exception: if User returns its own object, new gives back that object instead.

Step 2, the link, is easy to miss. This code shows what it does.

function User(name) {
  this.name = name;
}
User.prototype.describe = function () {
  return this.name + " is here";
};

const ada = new User("Ada");
console.log(ada.describe());
console.log(Object.hasOwn(ada, "describe"));

• Line 4 puts a describe method on User.prototype. It does not put it on ada.
• Line 10 uses Object.hasOwn(ada, "describe"). It asks: is describe stored on ada itself? The answer is false.
• Yet line 9, ada.describe(), still works and prints Ada is here.

Why does line 9 work? When JavaScript can't find a property on the object itself, it follows the link to User.prototype and looks there.

The replay below copies the four steps by hand, in a small function called createWith. It is only a model to help you see the steps. In real code, you just use new. It uses a few tools you may not have seen yet:

• ...args collects the extra inputs into an array called args.
• Object.create(proto) makes a new, empty object linked to proto. That is steps 1 and 2.
• Constructor.apply(obj, args) runs the function with this set to obj, and passes in the values from args. That is step 3.
• Lines 4 to 6 are step 4. If the constructor returned an object or a function, give that back. If not, give back obj.
• Object.getPrototypeOf(x) tells you which object x is linked to.
• x instanceof User checks whether x is linked to User.prototype.

The last three lines compare createWith(User, "Ada") with real new User("Ada"). Both objects have the same name and the same link, so all three lines print true.

1function createWith(Constructor, ...args) {2  const obj = Object.create(Constructor.prototype);Run3  const result = Constructor.apply(obj, args);4  return result !== null && (typeof result === "object" || typeof result === "function")5    ? result6    : obj;7}8 9function User(name) {10  this.name = name;11}12 13const real = new User("Ada");14const model = createWith(User, "Ada");15console.log(real.name === model.name);16console.log(Object.getPrototypeOf(real) === Object.getPrototypeOf(model));17console.log(model instanceof User);

Inside a function written with the function keyword, you can read new.target. It tells you how the function was called:

• Called with new, new.target is the function itself.
• Called without new, new.target is undefined.

function showCall() {
  console.log(new.target ? "constructor call" : "plain call");
}

showCall();
new showCall();

• Line 2 uses condition ? a : b. It means: if the condition is true, use a. If not, use b.
• Line 5 calls showCall() without new, so it prints "plain call".
• Line 6 calls it with new, so it prints "constructor call".

The code inside the function is the same both times. Only new.target changes.

A constructor can use this to catch a missing new. It has two choices:

• Fix the call: if (!new.target) return new SafeUser(name). The ! means "not", so this line runs when new was left out. It calls the function again, this time with new.
• Stop with an error: throw a TypeError, so the mistake shows up right away. Exercise 4 practices this.

The replay below uses the first choice. Pick the call on line 8, then step through it.

1function SafeUser(name) {2  if (!new.target) {3    return new SafeUser(name);4  }5  this.name = name;6}7 8const ada = SafeUser("Ada");Run9console.log(ada.name);

Most constructors don't have a return line. They write to this, and new gives back that object.

But a constructor can return something. Then one unusual rule applies:

• If it returns an object, that object takes the place of the object new made.
• If it returns a primitive, new ignores it. A primitive is a simple value that is not an object: a number, a string, a boolean, null, undefined, a symbol, or a bigint.

function ReturnsObject() {
  this.name = "built";
  return { name: "replacement" };
}

function ReturnsPrimitive() {
  this.name = "built";
  return "ignored";
}

console.log(new ReturnsObject().name);
console.log(new ReturnsPrimitive().name);

• Line 3 returns an object. So line 11 prints replacement, not built.
• Line 8 returns a string. new ignores it, so line 12 prints built.

function Ticket(code) {
  this.code = code;
  return 0;
}

console.log(new Ticket("A1").code);

Line 3 returns 0, a number. new ignores it and keeps the ticket it made, so line 6 prints A1.

The table sums up the rule. Read each row as: "when the constructor does this, new gives back that."

You will rarely need this rule in your own constructors. But it helps you read unusual library code and answer quiz puzzles. A quick check:

• The constructor returns an object or a function: you get that instead.
• It returns a number, string, boolean, null, or undefined: you get the object new made.

You can put a method inside the constructor, with this.greet = function () { ... }. That works. But then each new call makes a brand-new copy of the function, and every object carries its own copy. That uses more memory. And two copies are never equal: === says false.

The better place is the prototype, like User.prototype. A method there is written once, and every object made by new User can use it.

function CopiedMethodUser(name) {
  this.name = name;
  this.greet = function () {
    return "Hi, " + this.name;
  };
}

function SharedMethodUser(name) {
  this.name = name;
}
SharedMethodUser.prototype.greet = function () {
  return "Hi, " + this.name;
};

const copiedA = new CopiedMethodUser("Ada");
const copiedB = new CopiedMethodUser("Grace");
const sharedA = new SharedMethodUser("Ada");
const sharedB = new SharedMethodUser("Grace");
console.log(copiedA.greet === copiedB.greet);
console.log(sharedA.greet === sharedB.greet);
console.log(sharedA.greet());

• Lines 3 to 5 make a new greet function inside each CopiedMethodUser object.
• Lines 11 to 13 put one greet function on SharedMethodUser.prototype.
• Line 19 prints false: the two copied objects hold two different functions.
• Line 20 prints true: the two shared objects use the same function.
• Line 21 prints Hi, Ada.

function User(name) {
  this.name = name;
}
User.prototype.sayHi = function () {
  return "Hi, " + this.name;
};

console.log(new User("Asha").sayHi());

Line 4 puts sayHi on User.prototype. Line 8 makes a user and calls sayHi() on it, which prints Hi, Asha.

This works because of step 2 of new: the link. Take sharedA.greet(). JavaScript looks for greet on sharedA itself and doesn't find it. So it follows the link to SharedMethodUser.prototype and finds greet there.

Inside greet, this is sharedA, the object before the dot. So one shared function can still greet each user by name. The prototype lessons later show this lookup in full.

The table compares three places to write a method. Read each row as: "if I write the method here, this is what happens."

JavaScript comes with its own constructors too. They are called built-in constructors. For example:

• new Date() makes a Date object for the current date and time.
• new Map() makes a Map: a collection of keys and values. A later lesson covers it.

But three built-ins are traps when you use them with new: new Number(5), new String("x"), and new Boolean(false). Each one makes a wrapper object: an object with a primitive value inside it. Code that expects a plain number, string, or boolean can then go wrong.

console.log(typeof new String("x"));
console.log(Boolean(new Boolean(false)));
console.log(typeof "x");
console.log(Boolean(false));

• Line 1 prints object, not string.
• Line 2 prints true, even though the wrapper holds false.
• Lines 3 and 4 show the plain values for comparison. They print string and false.

The worst trap is new Boolean(false). The value inside is false. But the wrapper itself is an object, and every object counts as true in an if. Values that count as true are called truthy. So if (new Boolean(false)) runs its block.

Use plain values instead: 5, "x", and false. To convert a value, call Number(value), String(value), or Boolean(value) without new. Called that way, they give back plain values.

console.log(String(5));
console.log(Boolean(""));
console.log(typeof String(5));

Line 1 turns the number 5 into the string "5". Line 2 prints false, because an empty string counts as false. Line 3 prints string: the result is a plain string, not an object.

Where you’ll use this

You will meet constructors in three places:

• Older code and some libraries still use constructor functions.
• Built-in objects such as Date, Map, Set, URL, and many browser objects are made with new.
• Classes use the same steps, with neater syntax.

function CartItem(name, price, quantity) {
  if (!new.target) return new CartItem(name, price, quantity);
  this.name = name;
  this.price = price;
  this.quantity = quantity;
}

CartItem.prototype.total = function () {
  return this.price * this.quantity;
};

const apples = new CartItem("Apples", 2, 3);
console.log(apples.total());

• Line 2 is a new.target guard. If someone forgets new, it calls the constructor again with new.
• Lines 3 to 5 store the item's name, price, and quantity on this.
• Lines 8 to 10 put one shared total method on the prototype. It multiplies the price by the quantity.
• Line 12 makes 3 apples at 2 each. Line 13 prints 6.

Constructors aren't the only way to make objects. Object literals, functions that return objects (called factory functions), and classes are all useful too.

Constructors are still worth learning. They explain the common new Something() code, and they prepare you for prototypes and classes.

Common misconceptions

Read each snippet carefully. Your first try counts, and every choice explains why it is right or wrong.

Key takeaways

• A constructor function is a normal function that you call with new. By habit, its name starts with a capital letter.
• new makes an empty object, links it to Constructor.prototype, runs the function with this set to that object, and gives the object back.
• new.target is undefined when you forget new, and the function itself when you use new. A constructor can use it to catch the mistake.
• If a constructor returns an object, you get that object instead. If it returns a primitive, new ignores it.
• Put shared methods on the prototype (or in a class, later). Don't use new with Number, String, or Boolean.

Up next: Object.keys, values & entries.