buy the book to support the author.

Chapter 17. Objects and Inheritance

There are several layers to object-oriented programming (OOP) in JavaScript:

• Layer 1: Object-orientation with single objects (covered in Layer 1: Single Objects)
• Layer 2: Prototype chains of objects (described in Layer 2: The Prototype Relationship Between Objects)
• Layer 3: Constructors as factories for instances, similar to classes in other languages (discussed in Layer 3: Constructors—Factories for Instances)
• Layer 4: Subclassing, creating new constructors by inheriting from existing ones (covered in Layer 4: Inheritance Between Constructors)

Each new layer only depends on prior ones, enabling you to learn JavaScript OOP incrementally. Layers 1 and 2 form a simple core that you can refer back to whenever you are getting confused by the more complicated layers 3 and 4.

Layer 1: Single Objects

Roughly, all objects in JavaScript are maps (dictionaries) from strings to values. A (key, value) entry in an object is called a property. The key of a property is always a text string. The value of a property can be any JavaScript value, including a function. Methods are properties whose values are functions.

Kinds of Properties

There are three kinds of properties:

• Properties (or named data properties)
• Normal properties in an object—that is, mappings from string keys to values. Named data properties include methods. This is by far the most common kind of property.
• Accessors (or named accessor properties)
• Special methods whose invocations look like reading or writing properties.Normal properties are storage locations for property values; accessors allow you to compute the values of properties. They are virtual properties, if you will. See Accessors (Getters and Setters) for details.
• Internal properties
• Exist only in the ECMAScript language specification. They are not directly accessible from JavaScript, but there might be indirect ways of accessing them. The specification writes the keys of internal properties in brackets. For example, [[Prototype]] holds the prototype of an object and is readable via Object.getPrototypeOf().

Object Literals

JavaScript’s object literals allow you to directly create plain objects (direct instances of Object). The following code uses an object literal to assign an object to the variable jane. The object has the two properties: name and describe. describe is a method:

var jane = {
    name: 'Jane',
 
    describe: function () {
        return 'Person named '+this.name;  // (1)
    },  // (2)
};

• Use this in methods to refer to the current object (also called the receiver of a method invocation).
• ECMAScript 5 allows a trailing comma (after the last property) in an object literal. Alas, not all older browsers support it. A trailing comma is useful, because you can rearrange properties without having to worry which property is last.

You may get the impression that objects are only maps from strings to values. But they are more than that: they are real general-purpose objects. For example, you can use inheritance between objects (see Layer 2: The Prototype Relationship Between Objects), and you can protect objects from being changed. The ability to directly create objects is one of JavaScript’s standout features: you can start with concrete objects (no classes needed!) and introduce abstractions later. For example, constructors, which are factories for objects (as discussed in Layer 3: Constructors—Factories for Instances), are roughly similar to classes in other languages.

Dot Operator (.): Accessing Properties via Fixed Keys

The dot operator provides a compact syntax for accessing properties. The property keys must be identifiers (consult Legal Identifiers).If you want to read or write properties with arbitrary names, you need to use the bracket operator (see Bracket Operator ([]): Accessing Properties via Computed Keys).

The examples in this section work with the following object:

var jane = {
    name: 'Jane',
 
    describe: function () {
        return 'Person named '+this.name;
    }
};

Getting properties

The dot operator lets you “get” a property (read its value). Here are some examples:

> jane.name  // get property `name`
'Jane'
> jane.describe  // get property `describe`
[Function]

Getting a property that doesn’t exist returns undefined:

> jane.unknownProperty
undefined

Calling methods

The dot operator is also used to call methods:

> jane.describe()  // call method `describe`
'Person named Jane'

Setting properties

You can use the assignment operator (=) to set the value of a property referred to via the dot notation. For example:

> jane.name = 'John';  // set property `name`
> jane.describe()
'Person named John'

If a property doesn’t exist yet, setting it automatically creates it. If a property already exists, setting it changes its value.

Deleting properties

The delete operator lets you completely remove a property (the whole key-value pair) from an object. For example:

> var obj = { hello: 'world' };
> delete obj.hello
true
> obj.hello
undefined

If you merely set a property to undefined, the property still exists and the object still contains its key:

> var obj = { foo: 'a', bar: 'b' };
 
> obj.foo = undefined;
> Object.keys(obj)
[ 'foo', 'bar' ]

If you delete the property, its key is gone, too:

> delete obj.foo
true
> Object.keys(obj)
[ 'bar' ]

delete affects only the direct (“own,” noninherited) properties of an object. Its prototypes are not touched (see Deleting an inherited property).

Tip

Use the delete operator sparingly. Most modern JavaScript engines optimize the performance of instances created by constructors if their “shape” doesn’t change (roughly: no properties are removed or added). Deleting a property prevents that optimization.

The return value of delete

delete returns false if the property is an own property, but cannot be deleted. It returns true in all other cases. Following are some examples.

As a preparation, we create one property that can be deleted and another one that can’t be deleted (Getting and Defining Properties via Descriptors explains Object.defineProperty()):

var obj = {};
Object.defineProperty(obj, 'canBeDeleted', {
    value: 123,
    configurable: true
});
Object.defineProperty(obj, 'cannotBeDeleted', {
    value: 456,
    configurable: false
});

delete returns false for own properties that can’t be deleted:

> delete obj.cannotBeDeleted
false

delete returns true in all other cases:

> delete obj.doesNotExist
true
> delete obj.canBeDeleted
true

delete returns true even if it doesn’t change anything (inherited properties are never removed):

> delete obj.toString
true
> obj.toString // still there
[Function: toString]

Unusual Property Keys

While you can’t use reserved words (such as var and function) as variable names, you can use them as property keys:

> var obj = { var: 'a', function: 'b' };
> obj.var
'a'
> obj.function
'b'

Numbers can be used as property keys in object literals, but they are interpreted as strings. The dot operator can only access properties whose keys are identifiers. Therefore, you need the bracket operator (shown in the following example) to access properties whose keys are numbers:

> var obj = { 0.7: 'abc' };
> Object.keys(obj)
[ '0.7' ]
> obj['0.7']
'abc'

Object literals also allow you to use arbitrary strings (that are neither identifiers nor numbers) as property keys, but you must quote them. Again, you need the bracket operator to access the property values:

> var obj = { 'not an identifier': 123 };
> Object.keys(obj)
[ 'not an identifier' ]
> obj['not an identifier']
123

Bracket Operator ([]): Accessing Properties via Computed Keys

While the dot operator works with fixed property keys, the bracket operator allows you to refer to a property via an expression.

Getting properties via the bracket operator

The bracket operator lets you compute the key of a property, via an expression:

> var obj = { someProperty: 'abc' };
 
> obj['some' + 'Property']
'abc'
 
> var propKey = 'someProperty';
> obj[propKey]
'abc'

That also allows you to access properties whose keys are not identifiers:

> var obj = { 'not an identifier': 123 };
> obj['not an identifier']
123

Note that the bracket operator coerces its interior to string. For example:

> var obj = { '6': 'bar' };
> obj[3+3]  // key: the string '6'
'bar'

Calling methods via the bracket operator

Calling methods works as you would expect:

> var obj = { myMethod: function () { return true } };
> obj['myMethod']()
true

Setting properties via the bracket operator

Setting properties works analogously to the dot operator:

> var obj = {};
> obj['anotherProperty'] = 'def';
> obj.anotherProperty
'def'

Deleting properties via the bracket operator

Deleting properties also works similarly to the dot operator:

> var obj = { 'not an identifier': 1, prop: 2 };
> Object.keys(obj)
[ 'not an identifier', 'prop' ]
> delete obj['not an identifier']
true
> Object.keys(obj)
[ 'prop' ]

Converting Any Value to an Object

It’s not a frequent use case, but sometimes you need to convert an arbitrary value to an object. Object(), used as a function (not as a constructor), provides that service. It produces the following results:

Here are some examples:

> Object(null) instanceof Object
true
 
> Object(false) instanceof Boolean
true
 
> var obj = {};
> Object(obj) === obj
true

The following function checks whether value is an object:

function isObject(value) {
    return value === Object(value);
}

Note that the preceding function creates an object if value isn’t an object.You can implement the same function without doing that, via typeof (see Pitfall: typeof null).

You can also invoke Object as a constructor, which produces the same results as calling it as a function:

> var obj = {};
> new Object(obj) === obj
true
 
> new Object(123) instanceof Number
true

Tip

Avoid the constructor; an empty object literal is almost always a better choice:

var obj = new Object(); // avoid
var obj = {}; // prefer

this as an Implicit Parameter of Functions and Methods

When you call a function, this is always an (implicit) parameter:

• Normal functions in sloppy mode
• Even though normal functions have no use for this, it still exists as a special variable whose value is always the global object (window in browsers; see The Global Object):

> function returnThisSloppy() { return this }
> returnThisSloppy() === window
true

• Normal functions in strict mode
• this is always undefined:

> function returnThisStrict() { 'use strict'; return this }
> returnThisStrict() === undefined
true

• Methods
• this refers to the object on which the method has been invoked:

> var obj = { method: returnThisStrict };
> obj.method() === obj
true

In the case of methods, the value of this is called the receiver of the method call.

Calling Functions While Setting this: call(), apply(), and bind()

Remember that functions are also objects. Thus, each function has methods of its own. Three of them are introduced in this section and help with calling functions. These three methods are used in the following sections to work around some of the pitfalls of calling functions. The upcoming examples all refer to the following object, jane:

var jane = {
    name: 'Jane',
    sayHelloTo: function (otherName) {
        'use strict';
        console.log(this.name+' says hello to '+otherName);
    }
};

Function.prototype.call(thisValue, arg1?, arg2?, …)

The first parameter is the value that this will have inside the invoked function; the remaining parameters are handed over as arguments to the invoked function. The following three invocations are equivalent:

jane.sayHelloTo('Tarzan');
 
jane.sayHelloTo.call(jane, 'Tarzan');
 
var func = jane.sayHelloTo;
func.call(jane, 'Tarzan');

For the second invocation, you need to repeat jane, because call() doesn’t know how you got the function that it is invoked on.

Function.prototype.apply(thisValue, argArray)

The first parameter is the value that this will have inside the invoked function; the second parameter is an array that provides the arguments for the invocation. The following three invocations are equivalent:

jane.sayHelloTo('Tarzan');
 
jane.sayHelloTo.apply(jane, ['Tarzan']);
 
var func = jane.sayHelloTo;
func.apply(jane, ['Tarzan']);

For the second invocation, you need to repeat jane, because apply() doesn’t know how you got the function that it is invoked on.

apply() for Constructors explains how to use apply() with constructors.

Function.prototype.bind(thisValue, arg1?, …, argN?)

This method performs partial function application—meaning it creates a new function that calls the receiver of bind() in the following manner: the value of this is thisValue and the arguments start with arg1 until argN, followed by the arguments of the new function. In other words, the new function appends its arguments to arg1, …, argN when it calls the original function.Let’s look at an example:

function func() {
    console.log('this: '+this);
    console.log('arguments: '+Array.prototype.slice.call(arguments));
}
var bound = func.bind('abc', 1, 2);

The array method slice is used to convert arguments to an array, which is necessary for logging it (this operation is explained in Array-Like Objects and Generic Methods). bound is a new function. Here’s the interaction:

> bound(3)
this: abc
arguments: 1,2,3

The following three invocations of sayHelloTo are all equivalent:

jane.sayHelloTo('Tarzan');
 
var func1 = jane.sayHelloTo.bind(jane);
func1('Tarzan');
 
var func2 = jane.sayHelloTo.bind(jane, 'Tarzan');
func2();

apply() for Constructors

Let’s pretend that JavaScript has a triple dot operator (…) that turns arrays into actual parameters. Such an operator would allow you to use Math.max() (see Other Functions) with arrays. In that case, the following two expressions would be equivalent:

Math.max(...[13, 7, 30])
Math.max(13, 7, 30)

For functions, you can achieve the effect of the triple dot operator via apply():

> Math.max.apply(null, [13, 7, 30])
30

The triple dot operator would also make sense for constructors:

new Date(...[2011, 11, 24]) // Christmas Eve 2011

Alas, here apply() does not work, because it helps only with function or method calls, not with constructor invocations.

Manually simulating an apply() for constructors

We can simulate apply() in two steps.

• Step 1
• Pass the arguments to Date via a method call (they are not in an array—yet):

new (Date.bind(null, 2011, 11, 24))

The preceding code uses bind() to create a constructor without parameters and invokes it via new.

• Step 2
• Use apply() to hand an array to bind(). Because bind() is a method call, we can use apply():

new (Function.prototype.bind.apply(
         Date, [null, 2011, 11, 24]))

The preceding array contains null, followed by the elements of arr. We can use concat() to create it by prepending null to arr:

var arr = [2011, 11, 24];
new (Function.prototype.bind.apply(
         Date, [null].concat(arr)))

A library method

The preceding manual workaround is inspired by a library method published by Mozilla. The following is a slightly edited version of it:

if (!Function.prototype.construct) {
    Function.prototype.construct = function(argArray) {
        if (! Array.isArray(argArray)) {
            throw new TypeError("Argument must be an array");
        }
        var constr = this;
        var nullaryFunc = Function.prototype.bind.apply(
            constr, [null].concat(argArray));
        return new nullaryFunc();
    };
}

Here is the method in use:

> Date.construct([2011, 11, 24])
Sat Dec 24 2011 00:00:00 GMT+0100 (CET)

An alternative approach

An alternative to the previous approach is to create an uninitialized instance via Object.create() and then call the constructor (as a function) via apply(). That means that you are effectively reimplementing the new operator (some checks are omitted):

Function.prototype.construct = function(argArray) {
    var constr = this;
    var inst = Object.create(constr.prototype);
    var result = constr.apply(inst, argArray); // (1)
 
    // Check: did the constructor return an object
    // and prevent `this` from being the result?
    return result ? result : inst;
};

Warning

The preceding code does not work for most built-in constructors, which always produce new instances when called as functions. In other words, the step in line (1) doesn’t set up inst as desired.

Pitfall: Losing this When Extracting a Method

If you extract a method from an object, it becomes a true function again. Its connection with the object is severed, and it usually doesn’t work properly anymore. Take, for example, the following object, counter:

var counter = {
    count: 0,
    inc: function () {
        this.count++;
    }
}

Extracting inc and calling it (as a function!) fails:

> var func = counter.inc;
> func()
> counter.count  // didn’t work
0

Here’s the explanation: we have called the value of counter.inc as a function. Hence, this is the global object and we have performed window.count++. window.count does not exist and is undefined. Applying the ++ operator to it sets it to NaN:

> count  // global variable
NaN

How to get a warning

If method inc() is in strict mode, you get a warning:

> counter.inc = function () { 'use strict'; this.count++ };
> var func2 = counter.inc;
> func2()
TypeError: Cannot read property 'count' of undefined

The reason is that when we call the strict mode function func2, this is undefined, resulting in an error.

How to properly extract a method

Thanks to bind(), we can make sure that inc doesn’t lose the connection with counter:

> var func3 = counter.inc.bind(counter);
> func3()
> counter.count  // it worked!
1

Callbacks and extracted methods

In JavaScript, there are many functions and methods that accept callbacks. Examples in browsers are setTimeout() and event handling. If we pass in counter.inc as a callback, it is also invoked as a function, resulting in the same problem just described. To illustrate this phenomenon, let’s use a simple callback-invoking function:

function callIt(callback) {
    callback();
}

Executing counter.count via callIt triggers a warning (due to strict mode):

> callIt(counter.inc)
TypeError: Cannot read property 'count' of undefined

As before, we fix things via bind():

> callIt(counter.inc.bind(counter))
> counter.count  // one more than before
2

Warning

Each call to bind() creates a new function. That has consequences when you’re registering and unregistering callbacks (e.g., for event handling). You need to store the value you registered somewhere and use it for unregistering, too.

Pitfall: Functions Inside Methods Shadow this

You often nest function definitions in JavaScript, because functions can be parameters (e.g., callbacks) and because they can be created in place, via function expressions. This poses a problem when a method contains a normal function and you want to access the former’s this inside the latter, because the method’s this is shadowed by the normal function’s this (which doesn’t even have any use for its own this).In the following example, the function at (1) tries to access the method’s this at (2):

var obj = {
    name: 'Jane',
    friends: [ 'Tarzan', 'Cheeta' ],
    loop: function () {
        'use strict';
        this.friends.forEach(
            function (friend) {  // (1)
                console.log(this.name+' knows '+friend);  // (2)
            }
        );
    }
};

This fails, because the function at (1) has its own this, which is undefined here:

> obj.loop();
TypeError: Cannot read property 'name' of undefined

There are three ways to work around this problem.

Workaround 1: that = this

We assign this to a variable that won’t be shadowed inside the nested function:

loop: function () {
    'use strict';
    var that = this;
    this.friends.forEach(function (friend) {
        console.log(that.name+' knows '+friend);
    });
}

Here’s the interaction:

> obj.loop();
Jane knows Tarzan
Jane knows Cheeta

Workaround 2: bind()

We can use bind() to give the callback a fixed value for this—namely, the method’s this (line (1)):

loop: function () {
    'use strict';
    this.friends.forEach(function (friend) {
        console.log(this.name+' knows '+friend);
    }.bind(this));  // (1)
}

Workaround 3: a thisValue for forEach()

A workaround that is specific to forEach() (see Examination Methods) is to provide a second parameter after the callback that becomes the this of the callback:

loop: function () {
    'use strict';
    this.friends.forEach(function (friend) {
        console.log(this.name+' knows '+friend);
    }, this);
}

Layer 2: The Prototype Relationship Between Objects

The prototype relationship between two objects is about inheritance: every object can have another object as its prototype. Then the former object inherits all of its prototype’s properties.An object specifies its prototype via the internal property [[Prototype]]. Every object has this property, but it can be null. The chain of objects connected by the [[Prototype]] property is called the prototype chain (Figure 17-1).

Figure 17-1. A prototype chain.

To see how prototype-based (or prototypal) inheritance works, let’s look at an example (with invented syntax for specifying the [[Prototype]] property):

var proto = {
    describe: function () {
        return 'name: '+this.name;
    }
};
var obj = {
    [[Prototype]]: proto,
    name: 'obj'
};

The object obj inherits the property describe from proto. It also has a so-called own (noninherited, direct) property, name.

Inheritance

obj inherits the property describe; you can access it as if the object itself had that property:

> obj.describe
[Function]

Whenever you access a property via obj, JavaScript starts the search for it in that object and continues with its prototype, the prototype’s prototype, and so on. That’s why we can access proto.describe via obj.describe. The prototype chain behaves as if it were a single object. That illusion is maintained when you call a method: the value of this is always the object where the search for the method began, not where the method was found. That allows the method to access all of the properties of the prototype chain. For example:

> obj.describe()
'name: obj'

Inside describe(), this is obj, which allows the method to access obj.name.

Overriding

In a prototype chain, a property in an object overrides a property with the same key in a “later” object: the former property is found first. It hides the latter property, which can’t be accessed anymore.As an example, let’s override the method proto.describe() in obj:

> obj.describe = function () { return 'overridden' };
> obj.describe()
'overridden'

That is similar to how overriding of methods works in class-based languages.

Sharing Data Between Objects via a Prototype

Prototypes are great for sharing data between objects: several objects get the same prototype, which holds all shared properties. Let’s look at an example. The objects jane and tarzan both contain the same method, describe(). That is something that we would like to avoid by using sharing:

var jane = {
    name: 'Jane',
    describe: function () {
        return 'Person named '+this.name;
    }
};
var tarzan = {
    name: 'Tarzan',
    describe: function () {
        return 'Person named '+this.name;
    }
};

Both objects are persons. Their name property is different, but we could have them share the method describe. We do that by creating a common prototype called PersonProto and putting describe into it (Figure 17-2).

Figure 17-2. The objects jane and tarzan share the prototype PersonProto and thus the property describe.

The following code creates objects jane and tarzan that share the prototype PersonProto:

var PersonProto = {
    describe: function () {
        return 'Person named '+this.name;
    }
};
var jane = {
    [[Prototype]]: PersonProto,
    name: 'Jane'
};
var tarzan = {
    [[Prototype]]: PersonProto,
    name: 'Tarzan'
};

And here is the interaction:

> jane.describe()
Person named Jane
> tarzan.describe()
Person named Tarzan

This is a common pattern: the data resides in the first object of a prototype chain, while methods reside in later objects. JavaScript’s flavor of prototypal inheritance is designed to support this pattern: setting a property affects only the first object in a prototype chain, whereas getting a property considers the complete chain (see Setting and Deleting Affects Only Own Properties).

Getting and Setting the Prototype

So far, we have pretended that you can access the internal property [[Prototype]] from JavaScript. But the language does not let you do that. Instead, there are functions for reading the prototype and for creating a new object with a given prototype.

Creating a new object with a given prototype

This invocation:

Object.create(proto, propDescObj?)

creates an object whose prototype is proto. Optionally, properties can be added via descriptors (which are explained in Property Descriptors). In the following example, object jane gets the prototype PersonProto and a mutable property name whose value is 'Jane' (as specified via a property descriptor):

var PersonProto = {
    describe: function () {
        return 'Person named '+this.name;
    }
};
var jane = Object.create(PersonProto, {
    name: { value: 'Jane', writable: true }
});

Here is the interaction:

> jane.describe()
'Person named Jane'

But you frequently just create an empty object and then manually add properties, because descriptors are verbose:

var jane = Object.create(PersonProto);
jane.name = 'Jane';

Reading the prototype of an object

This method call:

Object.getPrototypeOf(obj)

returns the prototype of obj. Continuing the preceding example:

> Object.getPrototypeOf(jane) === PersonProto
true

Checking whether one object a prototype of another one

This syntax:

Object.prototype.isPrototypeOf(obj)

checks whether the receiver of the method is a (direct or indirect) prototype of obj. In other words: are the receiver and obj in the same prototype chain, and does obj come before the receiver? For example:

> var A = {};
> var B = Object.create(A);
> var C = Object.create(B);
> A.isPrototypeOf(C)
true
> C.isPrototypeOf(A)
false

Finding the object where a property is defined

The following function iterates over the property chain of an object obj. It returns the first object that has an own property with the key propKey, or null if there is no such object:

function getDefiningObject(obj, propKey) {
    obj = Object(obj); // make sure it’s an object
    while (obj && !{}.hasOwnProperty.call(obj, propKey)) {
        obj = Object.getPrototypeOf(obj);
        // obj is null if we have reached the end
    }
    return obj;
}

In the preceding code, we called the method Object.prototype.hasOwnProperty generically (see Generic Methods: Borrowing Methods from Prototypes).

The Special Property proto

Some JavaScript engines have a special property for getting and setting the prototype of an object: proto. It brings direct access to [[Prototype]] to the language:

> var obj = {};
 
> obj.__proto__ === Object.prototype
true
 
> obj.__proto__ = Array.prototype
> Object.getPrototypeOf(obj) === Array.prototype
true

There are several things you need to know about proto:

• proto is pronounced “dunder proto,” an abbreviation of “double underscore proto.” That pronunciation has been borrowed from the Python programming language (as suggested by Ned Batchelder in 2006). Special variables with double underscores are quite frequent in Python.
• proto is not part of the ECMAScript 5 standard. Therefore, you must not use it if you want your code to conform to that standard and run reliably across current JavaScript engines.
• However, more and more engines are adding support for proto and it will be part of ECMAScript 6.
• The following expression checks whether an engine supports proto as a special property:

Object.getPrototypeOf({ __proto__: null }) === null

Setting and Deleting Affects Only Own Properties

Only getting a property considers the complete prototype chain of an object. Setting and deleting ignores inheritance and affects only own properties.

Setting a property

Setting a property creates an own property, even if there is an inherited property with that key. For example, given the following source code:

var proto = { foo: 'a' };
var obj = Object.create(proto);

obj inherits foo from proto:

> obj.foo
'a'
> obj.hasOwnProperty('foo')
false

Setting foo has the desired result:

> obj.foo = 'b';
> obj.foo
'b'

However, we have created an own property and not changed proto.foo:

> obj.hasOwnProperty('foo')
true
> proto.foo
'a'

The rationale is that prototype properties are meant to be shared by several objects. This approach allows us to nondestructively “change” them—only the current object is affected.

Deleting an inherited property

You can only delete own properties. Let’s again set up an object, obj, with a prototype, proto:

var proto = { foo: 'a' };
var obj = Object.create(proto);

Deleting the inherited property foo has no effect:

> delete obj.foo
true
> obj.foo
'a'

For more information on the delete operator, consult Deleting properties.

Changing properties anywhere in the prototype chain

If you want to change an inherited property, you first have to find the object that owns it (see Finding the object where a property is defined) and then perform the change on that object. For example, let’s delete the property foo from the previous example:

> delete getDefiningObject(obj, 'foo').foo;
true
> obj.foo
undefined

Iteration and Detection of Properties

Operations for iterating over and detecting properties are influenced by:

• Inheritance (own properties versus inherited properties)
• An own property of an object is stored directly in that object. An inherited property is stored in one of its prototypes.
• Enumerability (enumerable properties versus nonenumerable properties)
• The enumerability of a property is an attribute (see Property Attributes and Property Descriptors), a flag that can be true or false. Enumerability rarely matters and can normally be ignored (see Enumerability: Best Practices).

You can list own property keys, list all enumerable property keys, and check whether a property exists. The following subsections show how.

Listing Own Property Keys

You can either list all own property keys, or only enumerable ones:

• Object.getOwnPropertyNames(obj)returns the keys of all own properties of obj.
• Object.keys(obj)returns the keys of all enumerable own properties of obj.

Note that properties are normally enumerable (see Enumerability: Best Practices), so you can use Object.keys(), especially for objects that you have created.

Listing All Property Keys

If you want to list all properties (both own and inherited ones) of an object, then you have two options.

Option 1 is to use the loop:

for («variable» in «object»)
    «statement»

to iterate over the keys of all enumerable properties of object. See for-in for a more thorough description.

Option 2 is to implement a function yourself that iterates over all properties (not just enumerable ones). For example:

function getAllPropertyNames(obj) {
    var result = [];
    while (obj) {
        // Add the own property names of `obj` to `result`
        result = result.concat(Object.getOwnPropertyNames(obj));
        obj = Object.getPrototypeOf(obj);
    }
    return result;
}

Checking Whether a Property Exists

You can check whether an object has a property, or whether a property exists directly inside an object:

• propKey in obj
• Returns true if obj has a property whose key is propKey. Inherited properties are included in this test.
• Object.prototype.hasOwnProperty(propKey)
• Returns true if the receiver (this) has an own (noninherited) property whose key is propKey.

Warning

Avoid invoking hasOwnProperty() directly on an object, as it may be overridden (e.g., by an own property whose key is hasOwnProperty):

> var obj = { hasOwnProperty: 1, foo: 2 };
> obj.hasOwnProperty('foo')  // unsafe
TypeError: Property 'hasOwnProperty' is not a function

Instead, it is better to call it generically (see Generic Methods: Borrowing Methods from Prototypes):

> Object.prototype.hasOwnProperty.call(obj, 'foo')  // safe
true
> {}.hasOwnProperty.call(obj, 'foo')  // shorter
true

Examples

The following examples are based on these definitions:

var proto = Object.defineProperties({}, {
    protoEnumTrue: { value: 1, enumerable: true },
    protoEnumFalse: { value: 2, enumerable: false }
});
var obj = Object.create(proto, {
    objEnumTrue: { value: 1, enumerable: true },
    objEnumFalse: { value: 2, enumerable: false }
});

Object.defineProperties() is explained in Getting and Defining Properties via Descriptors, but it should be fairly obvious how it works: proto has the own properties protoEnumTrue and protoEnumFalse and obj has the own properties objEnumTrue and objEnumFalse (and inherits all of proto’s properties).

Note

Note that objects (such as proto in the preceding example) normally have at least the prototype Object.prototype (where standard methods such as toString() and hasOwnProperty() are defined):

> Object.getPrototypeOf({}) === Object.prototype
true

The effects of enumerability

Among property-related operations, enumberability only influences the for-in loop and Object.keys() (it also influences JSON.stringify(), see JSON.stringify(value, replacer?, space?)).

The for-in loop iterates over the keys of all enumerable properties, including inherited ones (note that none of the nonenumerable properties of Object.prototype show up):

> for (var x in obj) console.log(x);
objEnumTrue
protoEnumTrue

Object.keys() returns the keys of all own (noninherited) enumerable properties:

> Object.keys(obj)
[ 'objEnumTrue' ]

If you want the keys of all own properties, you need to use Object.getOwnPropertyNames():

> Object.getOwnPropertyNames(obj)
[ 'objEnumTrue', 'objEnumFalse' ]

The effects of inheritance

Only the for-in loop (see the previous example) and the in operator consider inheritance:

> 'toString' in obj
true
> obj.hasOwnProperty('toString')
false
> obj.hasOwnProperty('objEnumFalse')
true

Computing the number of own properties of an object

Objects don’t have a method such as length or size, so you have to use the following workaround:

Object.keys(obj).length

Best Practices: Iterating over Own Properties

To iterate over property keys:

• Combine for-in with hasOwnProperty(), in the manner described in for-in. This works even on older JavaScript engines. For example:

for (var key in obj) {
    if (Object.prototype.hasOwnProperty.call(obj, key)) {
        console.log(key);
    }
}

• Combine Object.keys() or Object.getOwnPropertyNames() with forEach() array iteration:

var obj = { first: 'John', last: 'Doe' };
// Visit non-inherited enumerable keys
Object.keys(obj).forEach(function (key) {
    console.log(key);
});

To iterate over property values or over (key, value) pairs:

• Iterate over the keys, and use each key to retrieve the corresponding value. Other languages make this simpler, but not JavaScript.

Accessors (Getters and Setters)

ECMAScript 5 lets you write methods whose invocations look like you are getting or setting a property. That means that a property is virtual and not storage space. You could, for example, forbid setting a property and always compute the value returned when reading it.

Defining Accessors via an Object Literal

The following example uses an object literal to define a setter and a getter for property foo:

var obj = {
    get foo() {
        return 'getter';
    },
    set foo(value) {
        console.log('setter: '+value);
    }
};

Here’s the interaction:

> obj.foo = 'bla';
setter: bla
> obj.foo
'getter'

Defining Accessors via Property Descriptors

An alternate way to specify getters and setters is via property descriptors (see Property Descriptors). The following code defines the same object as the preceding literal:

var obj = Object.create(
    Object.prototype, {  // object with property descriptors
        foo: {  // property descriptor
            get: function () {
                return 'getter';
            },
            set: function (value) {
                console.log('setter: '+value);
            }
        }
    }
);

Accessors and Inheritance

Getters and setters are inherited from prototypes:

> var proto = { get foo() { return 'hello' } };
> var obj = Object.create(proto);
 
> obj.foo
'hello'

Property Attributes and Property Descriptors

Tip

Property attributes and property descriptors are an advanced topic. You normally don’t need to know how they work.

In this section, we’ll look at the internal structure of properties:

• Property attributes are the atomic building blocks of properties.
• A property descriptor is a data structure for working programmatically with attributes.

Property Attributes

All of a property’s state, both its data and its metadata, is stored in attributes. They are fields that a property has, much like an object has properties. Attribute keys are often written in double brackets. Attributes matter for normal properties and for accessors (getters and setters).

The following attributes are specific to normal properties:

• [[Value]] holds the property’s value, its data.
• [[Writable]] holds a boolean indicating whether the value of a property can be changed.

The following attributes are specific to accessors:

• [[Get]] holds the getter, a function that is called when a property is read. The function computes the result of the read access.
• [[Set]] holds the setter, a function that is called when a property is set to a value. The function receives that value as a parameter.

All properties have the following attributes:

• [[Enumerable]] holds a boolean. Making a property nonenumerable hides it from some operations (see Iteration and Detection of Properties).
• [[Configurable]] holds a boolean. If it is false, you cannot delete a property, change any of its attributes (except [[Value]]), or convert it from a data property to an accessor property or vice versa. In other words, [[Configurable]] controls the writability of a property’s metadata. There is one exception to this rule—JavaScript allows you to change an unconfigurable property from writable to read-only, for historic reasons; the property length of arrays has always been writable and unconfigurable. Without this exception, you wouldn’t be able to freeze (see Freezing) arrays.

Default values

If you don’t specify attributes, the following defaults are used:

These defaults are important when you are creating properties via property descriptors (see the following section).

Property Descriptors

A property descriptor is a data structure for working programmatically with attributes.It is an object that encodes the attributes of a property. Each of a descriptor’s properties corresponds to an attribute. For example, the following is the descriptor of a read-only property whose value is 123:

{
    value: 123,
    writable: false,
    enumerable: true,
    configurable: false
}

You can achieve the same goal, immutability, via accessors. Then the descriptor looks as follows:

{
    get: function () { return 123 },
    enumerable: true,
    configurable: false
}

Getting and Defining Properties via Descriptors

Property descriptors are used for two kinds of operations:

• Getting a property
• All attributes of a property are returned as a descriptor.
• Defining a property
• Defining a property means something different depending on whether a property already exists:

• If a property does not exist, create a new property whose attributes are as specified by the descriptor. If an attribute has no corresponding property in the descriptor, then use the default value. The defaults are dictated by what the attribute names mean. They are the opposite of the values that are used when creating a property via assignment (then the property is writable, enumerable, and configurable).For example:

> var obj = {};
> Object.defineProperty(obj, 'foo', { configurable: true });
> Object.getOwnPropertyDescriptor(obj, 'foo')
{ value: undefined,
  writable: false,
  enumerable: false,
  configurable: true }

I usually don’t rely on the defaults and explicitly state all attributes, to be completely clear.

• If a property already exists, update the attributes of the property as specified by the descriptor. If an attribute has no corresponding property in the descriptor, then don’t change it. Here is an example (continued from the previous one):

> Object.defineProperty(obj, 'foo', { writable: true });
> Object.getOwnPropertyDescriptor(obj, 'foo')
{ value: undefined,
  writable: true,
  enumerable: false,
  configurable: true }

The following operations allow you to get and set a property’s attributes via property descriptors:

• Object.getOwnPropertyDescriptor(obj, propKey)
• Returns the descriptor of the own (noninherited) property of obj whose key is propKey. If there is no such property, undefined is returned:

> Object.getOwnPropertyDescriptor(Object.prototype, 'toString')
{ value: [Function: toString],
  writable: true,
  enumerable: false,
  configurable: true }
 
> Object.getOwnPropertyDescriptor({}, 'toString')
undefined

• Object.defineProperty(obj, propKey, propDesc)
• Create or change a property of obj whose key is propKey and whose attributes are specified via propDesc. Return the modified object. For example:

var obj = Object.defineProperty({}, 'foo', {
    value: 123,
    enumerable: true
    // writable: false (default value)
    // configurable: false (default value)
});

• Object.defineProperties(obj, propDescObj)
• The batch version of Object.defineProperty(). Each property of propDescObj holds a property descriptor. The keys of the properties and their values tell Object.defineProperties what properties to create or change on obj. For example:

var obj = Object.defineProperties({}, {
    foo: { value: 123, enumerable: true },
    bar: { value: 'abc', enumerable: true }
});

• Object.create(proto, propDescObj?)
• First, create an object whose prototype is proto. Then, if the optional parameter propDescObj has been specified, add properties to it—in the same manner as Object.defineProperties. Finally, return the result. For example, the following code snippet produces the same result as the previous snippet:

var obj = Object.create(Object.prototype, {
    foo: { value: 123, enumerable: true },
    bar: { value: 'abc', enumerable: true }
});

Copying an Object

To create an identical copy of an object, you need to get two things right:

• The copy must have the same prototype (see Layer 2: The Prototype Relationship Between Objects) as the original.
• The copy must have the same properties, with the same attributes as the original.

The following function performs such a copy:

function copyObject(orig) {
    // 1. copy has same prototype as orig
    var copy = Object.create(Object.getPrototypeOf(orig));
 
    // 2. copy has all of orig’s properties
    copyOwnPropertiesFrom(copy, orig);
 
    return copy;
}

The properties are copied from orig to copy via this function:

function copyOwnPropertiesFrom(target, source) {
    Object.getOwnPropertyNames(source)  // (1)
    .forEach(function(propKey) {  // (2)
        var desc = Object.getOwnPropertyDescriptor(source, propKey); // (3)
        Object.defineProperty(target, propKey, desc);  // (4)
    });
    return target;
};

These are the steps involved:

• Get an array with the keys of all own properties of source.
• Iterate over those keys.
• Retrieve a property descriptor.
• Use that property descriptor to create an own property in target.

Note that this function is very similar to the function _.extend() in the Underscore.js library.

Properties: Definition Versus Assignment

The following two operations are very similar:

• Defining a property via defineProperty() and defineProperties() (see Getting and Defining Properties via Descriptors).
• Assigning to a property via =.

There are, however, a few subtle differences:

• Defining a property means creating a new own property or updating the attributes of an existing own property. In both cases, the prototype chain is completely ignored.
• Assigning to a property prop means changing an existing property. The process is as follows:

• If prop is a setter (own or inherited), call that setter.
• Otherwise, if prop is read-only (own or inherited), throw an exception (in strict mode) or do nothing (in sloppy mode). The next section explains this (slightly unexpected) phenomenon in more detail.
• Otherwise, if prop is own (and writable), change the value of that property.
• Otherwise, there either is no property prop, or it is inherited and writable. In both cases, define an own property prop that is writable, configurable, and enumerable. In the latter case, we have just overridden an inherited property (nondestructively changed it). In the former case, a missing property has been defined automatically. This kind of autodefining is problematic, because typos in assignments can be hard to detect.

Inherited Read-Only Properties Can’t Be Assigned To

If an object, obj, inherits a property, foo, from a prototype and foo is not writable, then you can’t assign to obj.foo:

var proto = Object.defineProperty({}, 'foo', {
    value: 'a',
    writable: false
});
var obj = Object.create(proto);

obj inherits the read-only property foo from proto. In sloppy mode, setting the property has no effect:

> obj.foo = 'b';
> obj.foo
'a'

In strict mode, you get an exception:

> (function () { 'use strict'; obj.foo = 'b' }());
TypeError: Cannot assign to read-only property 'foo'

This fits with the idea that assignment changes inherited properties, but nondestructively. If an inherited property is read-only, you want to forbid all changes, even nondestructive ones.

Note that you can circumvent this protection by defining an own property (see the previous subsection for the difference between definition and assignment):

> Object.defineProperty(obj, 'foo', { value: 'b' });
> obj.foo
'b'

Enumerability: Best Practices

The general rule is that properties created by the system are nonenumerable, while properties created by users are enumerable:

> Object.keys([])
[]
> Object.getOwnPropertyNames([])
[ 'length' ]
 
> Object.keys(['a'])
[ '0' ]

This is especially true for the methods of the built-in instance prototypes:

> Object.keys(Object.prototype)
[]
> Object.getOwnPropertyNames(Object.prototype)
[ hasOwnProperty',
  'valueOf',
  'constructor',
  'toLocaleString',
  'isPrototypeOf',
  'propertyIsEnumerable',
  'toString' ]

The main purpose of enumerability is to tell the for-in loop which properties it should ignore. As we have seen just now when we looked at instances of built-in constructors, everything not created by the user is hidden from for-in.

The only operations affected by enumerability are:

• The for-in loop
• Object.keys() (Listing Own Property Keys)
• JSON.stringify() (JSON.stringify(value, replacer?, space?))

Here are some best practices to keep in mind:

• For your own code, you can usually ignore enumerability and should avoid the for-in loop (Best Practices: Iterating over Arrays).
• You normally shouldn’t add properties to built-in prototypes and objects. But if you do, you should make them nonenumerable to avoid breaking existing code.

Protecting Objects

There are three levels of protecting an object, listed here from weakest to strongest:

• Preventing extensions
• Sealing
• Freezing

Preventing Extensions

Preventing extensions via:

Object.preventExtensions(obj)

makes it impossible to add properties to obj. For example:

var obj = { foo: 'a' };
Object.preventExtensions(obj);

Now adding a property fails silently in sloppy mode:

> obj.bar = 'b';
> obj.bar
undefined

and throws an error in strict mode:

> (function () { 'use strict'; obj.bar = 'b' }());
TypeError: Can't add property bar, object is not extensible

You can still delete properties, though:

> delete obj.foo
true
> obj.foo
undefined

You check whether an object is extensible via:

Object.isExtensible(obj)

Sealing

Sealing via:

Object.seal(obj)

prevents extensions and makes all properties “unconfigurable.” The latter means that the attributes (see Property Attributes and Property Descriptors) of properties can’t be changed anymore. For example, read-only properties stay read-only forever.

The following example demonstrates that sealing makes all properties unconfigurable:

> var obj = { foo: 'a' };
 
> Object.getOwnPropertyDescriptor(obj, 'foo')  // before sealing
{ value: 'a',
  writable: true,
  enumerable: true,
  configurable: true }
 
> Object.seal(obj)
 
> Object.getOwnPropertyDescriptor(obj, 'foo')  // after sealing
{ value: 'a',
  writable: true,
  enumerable: true,
  configurable: false }

You can still change the property foo:

> obj.foo = 'b';
'b'
> obj.foo
'b'

but you can’t change its attributes:

> Object.defineProperty(obj, 'foo', { enumerable: false });
TypeError: Cannot redefine property: foo

You check whether an object is sealed via:

Object.isSealed(obj)

Freezing

Freezing is performed via:

Object.freeze(obj)

It makes all properties nonwritable and seals obj. In other words, obj is not extensible and all properties are read-only, and there is no way to change that. Let’s look at an example:

var point = { x: 17, y: -5 };
Object.freeze(point);

Once again, you get silent failures in sloppy mode:

> point.x = 2;  // no effect, point.x is read-only
> point.x
17
 
> point.z = 123;  // no effect, point is not extensible
> point
{ x: 17, y: -5 }

And you get errors in strict mode:

> (function () { 'use strict'; point.x = 2 }());
TypeError: Cannot assign to read-only property 'x'
 
> (function () { 'use strict'; point.z = 123 }());
TypeError: Can't add property z, object is not extensible

You check whether an object is frozen via:

Object.isFrozen(obj)

Pitfall: Protection Is Shallow

Protecting an object is shallow: it affects the own properties, but not the values of those properties. For example, consider the following object:

var obj = {
    foo: 1,
    bar: ['a', 'b']
};
Object.freeze(obj);

Even though you have frozen obj, it is not completely immutable—you can change the (mutable) value of property bar:

> obj.foo = 2; // no effect
> obj.bar.push('c'); // changes obj.bar
 
> obj
{ foo: 1, bar: [ 'a', 'b', 'c' ] }

Additionally, obj has the prototype Object.prototype, which is also mutable.

Layer 3: Constructors—Factories for Instances

A constructor function (short: constructor) helps with producing objects that are similar in some way. It is a normal function, but it is named, set up, and invoked differently. This section explains how constructors work. They correspond to classes in other languages.