Object
The Object
type represents one of JavaScript's data types. It is used to store various keyed collections and more complex entities. Objects can be created using the Object()
constructor or the object initializer / literal syntax.
Description
Nearly all objects in JavaScript are instances of Object
; a typical object inherits properties (including methods) from Object.prototype
, although these properties may be shadowed (a.k.a. overridden). The only objects that don't inherit from Object.prototype
are those with null
prototype, or descended from other null
prototype objects.
Changes to the Object.prototype
object are seen by all objects through prototype chaining, unless the properties and methods subject to those changes are overridden further along the prototype chain. This provides a very powerful although potentially dangerous mechanism to override or extend object behavior. To make it more secure, Object.prototype
is the only object in the core JavaScript language that has immutable prototype — the prototype of Object.prototype
is always null
and not changeable.
Object prototype properties
You should avoid calling any Object.prototype
method, especially those that are not intended to be polymorphic (i.e. only its initial behavior makes sense and no descending object could override it in a meaningful way). All objects descending from Object.prototype
may define a custom own property that has the same name, but with entirely different semantics from what you expect. Furthermore, these properties are not inherited by null
-prototype objects. All modern JavaScript utilities for working with objects are static. More specifically:
valueOf()
,toString()
, andtoLocaleString()
exist to be polymorphic and you should expect the object to define its own implementation with sensible behaviors, so you can call them as instance methods. However,valueOf()
andtoString()
are usually implicitly called through type conversion and you don't need to call them yourself in your code.__defineGetter__()
,__defineSetter__()
,__lookupGetter__()
, and__lookupSetter__()
are deprecated and should not be used. Use the static alternativesObject.defineProperty()
andObject.getOwnPropertyDescriptor()
instead.- The
__proto__
property is deprecated and should not be used. TheObject.getPrototypeOf()
andObject.setPrototypeOf()
alternatives are static methods. - The
propertyIsEnumerable()
andhasOwnProperty()
methods can be replaced with theObject.getOwnPropertyDescriptor()
andObject.hasOwn()
static methods, respectively. - The
isPrototypeOf()
method can usually be replaced withinstanceof
, if you are checking theprototype
property of a constructor.
In case where a semantically equivalent static method doesn't exist, or if you really want to use the Object.prototype
method, you should directly call()
the Object.prototype
method on your target object instead, to prevent the object from having an overriding property that produces unexpected results.
js
const obj = {
foo: 1,
// You should not define such a method on your own object,
// but you may not be able to prevent it from happening if
// you are receiving the object from external input
propertyIsEnumerable() {
return false;
},
};
obj.propertyIsEnumerable("foo"); // false; unexpected result
Object.prototype.propertyIsEnumerable.call(obj, "foo"); // true; expected result
Deleting a property from an object
There isn't any method in an Object itself to delete its own properties (such as Map.prototype.delete()
). To do so, one must use the delete operator.
null-prototype objects
Almost all objects in JavaScript ultimately inherit from Object.prototype
(see inheritance and the prototype chain). However, you may create null
-prototype objects using Object.create(null)
or the object initializer syntax with __proto__: null
(note: the __proto__
key in object literals is different from the deprecated Object.prototype.__proto__
property). You can also change the prototype of an existing object to null
by calling Object.setPrototypeOf(obj, null)
.
js
const obj = Object.create(null);
const obj2 = { __proto__: null };
An object with a null
prototype can behave in unexpected ways, because it doesn't inherit any object methods from Object.prototype
. This is especially true when debugging, since common object-property converting/detecting utility functions may generate errors, or lose information (especially if using silent error-traps that ignore errors).
For example, the lack of Object.prototype.toString()
often makes debugging intractable:
js
const normalObj = {}; // create a normal object
const nullProtoObj = Object.create(null); // create an object with "null" prototype
console.log(`normalObj is: ${normalObj}`); // shows "normalObj is: [object Object]"
console.log(`nullProtoObj is: ${nullProtoObj}`); // throws error: Cannot convert object to primitive value
alert(normalObj); // shows [object Object]
alert(nullProtoObj); // throws error: Cannot convert object to primitive value
Other methods will fail as well.
js
normalObj.valueOf(); // shows {}
nullProtoObj.valueOf(); // throws error: nullProtoObj.valueOf is not a function
normalObj.hasOwnProperty("p"); // shows "true"
nullProtoObj.hasOwnProperty("p"); // throws error: nullProtoObj.hasOwnProperty is not a function
normalObj.constructor; // shows "Object() { [native code] }"
nullProtoObj.constructor; // shows "undefined"
We can add the toString
method back to the null-prototype object by assigning it one:
js
nullProtoObj.toString = Object.prototype.toString; // since new object lacks toString, add the original generic one back
console.log(nullProtoObj.toString()); // shows "[object Object]"
console.log(`nullProtoObj is: ${nullProtoObj}`); // shows "nullProtoObj is: [object Object]"
Unlike normal objects, in which toString()
is on the object's prototype, the toString()
method here is an own property of nullProtoObj
. This is because nullProtoObj
has no (null
) prototype.
In practice, objects with null
prototype are usually used as a cheap substitute for maps. The presence of Object.prototype
properties will cause some bugs:
js
const ages = { alice: 18, bob: 27 };
function hasPerson(name) {
return name in ages;
}
function getAge(name) {
return ages[name];
}
hasPerson("hasOwnProperty"); // true
getAge("toString"); // [Function: toString]
Using a null-prototype object removes this hazard without introducing too much complexity to the hasPerson
and getAge
functions:
js
const ages = Object.create(null, {
alice: { value: 18, enumerable: true },
bob: { value: 27, enumerable: true },
});
hasPerson("hasOwnProperty"); // false
getAge("toString"); // undefined
In such case, the addition of any method should be done cautiously, as they can be confused with the other key-value pairs stored as data.
Making your object not inherit from Object.prototype
also prevents prototype pollution attacks. If a malicious script adds a property to Object.prototype
, it will be accessible on every object in your program, except objects that have null prototype.
js
const user = {};
// A malicious script:
Object.prototype.authenticated = true;
// Unexpectedly allowing unauthenticated user to pass through
if (user.authenticated) {
// access confidential data
}
JavaScript also has built-in APIs that produce null
-prototype objects, especially those that use objects as ad hoc key-value collections. For example:
- The return value of
Array.prototype.group()
- The
groups
andindices.groups
properties of the result ofRegExp.prototype.exec()
Array.prototype[@@unscopables]
(all@@unscopables
objects should havenull
-prototype)import.meta
- Module namespace objects, obtained through
import * as ns from "module";
orimport()
The term "null
-prototype object" often also includes any object without Object.prototype
in its prototype chain. Such objects can be created with extends null
when using classes.
Object coercion
Many built-in operations that expect objects first coerce their arguments to objects. The operation can be summarized as follows:
- Objects are returned as-is.
undefined
andnull
throw aTypeError
.Number
,String
,Boolean
,Symbol
,BigInt
primitives are wrapped into their corresponding object wrappers.
The best way to achieve the same effect in JavaScript is through the Object()
constructor. Object(x)
converts x
to an object, and for undefined
or null
, it returns a plain object instead of throwing a TypeError
.
Places that use object coercion include:
- The
object
parameter offor...in
loops. - The
this
value ofArray
methods. - Parameters of
Object
methods such asObject.keys()
. - Auto-boxing when a property is accessed on a primitive value, since primitives do not have properties.
- The
this
value when calling a non-strict function. Primitives are boxed whilenull
andundefined
are replaced with the global object.
Unlike conversion to primitives, the object coercion process itself is not observable in any way, since it doesn't invoke custom code like toString
or valueOf
methods.
Constructor
Object()
-
Turns the input into an object.
Static methods
Object.assign()
-
Copies the values of all enumerable own properties from one or more source objects to a target object.
Object.create()
-
Creates a new object with the specified prototype object and properties.
Object.defineProperties()
-
Adds the named properties described by the given descriptors to an object.
Object.defineProperty()
-
Adds the named property described by a given descriptor to an object.
Object.entries()
-
Returns an array containing all of the
[key, value]
pairs of a given object's own enumerable string properties. Object.freeze()
-
Freezes an object. Other code cannot delete or change its properties.
Object.fromEntries()
-
Returns a new object from an iterable of
[key, value]
pairs. (This is the reverse ofObject.entries
). Object.getOwnPropertyDescriptor()
-
Returns a property descriptor for a named property on an object.
Object.getOwnPropertyDescriptors()
-
Returns an object containing all own property descriptors for an object.
Object.getOwnPropertyNames()
-
Returns an array containing the names of all of the given object's own enumerable and non-enumerable properties.
Object.getOwnPropertySymbols()
-
Returns an array of all symbol properties found directly upon a given object.
Object.getPrototypeOf()
-
Returns the prototype (internal
[[Prototype]]
property) of the specified object. Object.hasOwn()
-
Returns
true
if the specified object has the indicated property as its own property, orfalse
if the property is inherited or does not exist. Object.is()
-
Compares if two values are the same value. Equates all
NaN
values (which differs from bothIsLooselyEqual
used by==
andIsStrictlyEqual
used by===
). Object.isExtensible()
-
Determines if extending of an object is allowed.
Object.isFrozen()
-
Determines if an object was frozen.
Object.isSealed()
-
Determines if an object is sealed.
Object.keys()
-
Returns an array containing the names of all of the given object's own enumerable string properties.
Object.preventExtensions()
-
Prevents any extensions of an object.
Object.seal()
-
Prevents other code from deleting properties of an object.
Object.setPrototypeOf()
-
Sets the object's prototype (its internal
[[Prototype]]
property). Object.values()
-
Returns an array containing the values that correspond to all of a given object's own enumerable string properties.
Instance properties
These properties are defined on Object.prototype
and shared by all Object
instances.
Object.prototype.__proto__
Deprecated-
Points to the object which was used as prototype when the object was instantiated.
Object.prototype.constructor
-
The constructor function that created the instance object. For plain
Object
instances, the initial value is theObject
constructor. Instances of other constructors each inherit theconstructor
property from their respectiveConstructor.prototype
object.
Instance methods
Object.prototype.__defineGetter__()
Deprecated-
Associates a function with a property that, when accessed, executes that function and returns its return value.
Object.prototype.__defineSetter__()
Deprecated-
Associates a function with a property that, when set, executes that function which modifies the property.
Object.prototype.__lookupGetter__()
Deprecated-
Returns the function bound as a getter to the specified property.
Object.prototype.__lookupSetter__()
Deprecated-
Returns the function bound as a setter to the specified property.
Object.prototype.hasOwnProperty()
-
Returns a boolean indicating whether an object contains the specified property as a direct property of that object and not inherited through the prototype chain.
Object.prototype.isPrototypeOf()
-
Returns a boolean indicating whether the object this method is called upon is in the prototype chain of the specified object.
Object.prototype.propertyIsEnumerable()
-
Returns a boolean indicating whether the specified property is the object's enumerable own property.
Object.prototype.toLocaleString()
-
Calls
toString()
. Object.prototype.toString()
-
Returns a string representation of the object.
Object.prototype.valueOf()
-
Returns the primitive value of the specified object.
Examples
Constructing empty objects
The following example creates empty objects using the new
keyword with different arguments:
js
const o1 = new Object();
const o2 = new Object(undefined);
const o3 = new Object(null);
Using Object to create Boolean objects
The following examples store Boolean
objects in o
:
js
// equivalent to const o = new Boolean(true)
const o = new Object(true);
js
// equivalent to const o = new Boolean(false)
const o = new Object(Boolean());
Object prototypes
When altering the behavior of existing Object.prototype
methods, consider injecting code by wrapping your extension before or after the existing logic. For example, this (untested) code will pre-conditionally execute custom logic before the built-in logic or someone else's extension is executed.
When modifying prototypes with hooks, pass this
and the arguments (the call state) to the current behavior by calling apply()
on the function. This pattern can be used for any prototype, such as Node.prototype
, Function.prototype
, etc.
js
const current = Object.prototype.valueOf;
// Since my property "-prop-value" is cross-cutting and isn't always
// on the same prototype chain, I want to modify Object.prototype:
Object.prototype.valueOf = function (...args) {
if (Object.hasOwn(this, "-prop-value")) {
return this["-prop-value"];
} else {
// It doesn't look like one of my objects, so let's fall back on
// the default behavior by reproducing the current behavior as best we can.
// The apply behaves like "super" in some other languages.
// Even though valueOf() doesn't take arguments, some other hook may.
return current.apply(this, args);
}
};
Warning: Modifying the prototype
property of any built-in constructor is considered a bad practice and risks forward compatibility.
You can read more about prototypes in Inheritance and the prototype chain.
Specifications
Specification |
---|
ECMAScript Language Specification # sec-object-objects |
Browser compatibility
BCD tables only load in the browser