Object

Nearly allobjectsin JavaScript are instances ofObject;a typical object inherits properties (including methods) fromObject.prototype,although these properties may be shadowed (a.k.a. overridden). The only objects that don't inherit fromObject.prototypeare those withnullprototype,or descended from othernullprototype objects.

Changes to theObject.prototypeobject are seen byallobjects 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.prototypeis the only object in the core JavaScript language that hasimmutable prototype— the prototype ofObject.prototypeis alwaysnulland not changeable.

You should avoid calling anyObject.prototypemethod directly from the instance, 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 fromObject.prototypemay 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 bynull-prototype objects.All modern JavaScript utilities for working with objects arestatic.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 throughtype conversionand 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.
• ThepropertyIsEnumerable()andhasOwnProperty()methods can be replaced with theObject.getOwnPropertyDescriptor()andObject.hasOwn()static methods, respectively.
• TheisPrototypeOf()method can usually be replaced withinstanceof,if you are checking theprototypeproperty of a constructor.

In case where a semantically equivalent static method doesn't exist, or if you really want to use theObject.prototypemethod, you should directlycall()theObject.prototypemethod on your target object instead, to prevent the object from having an overriding property that produces unexpected results.

constobj={
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(){
returnfalse;
},
};

obj.propertyIsEnumerable("foo");// false; unexpected result
Object.prototype.propertyIsEnumerable.call(obj,"foo");// true; expected result

There isn't any method in an Object itself to delete its own properties (such asMap.prototype.delete()). To do so, one must use thedeleteoperator.

Almost all objects in JavaScript ultimately inherit fromObject.prototype(seeinheritance and the prototype chain). However, you may createnull-prototype objects usingObject.create(null)or theobject initializer syntaxwith__proto__: null(note: the__proto__key in object literals is different from the deprecatedObject.prototype.__proto__property). You can also change the prototype of an existing object tonullby callingObject.setPrototypeOf(obj, null).

constobj=Object.create(null);
constobj2={__proto__:null};

An object with anullprototype can behave in unexpected ways, because it doesn't inherit any object methods fromObject.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 ofObject.prototype.toString()often makes debugging intractable:

constnormalObj={};// create a normal object
constnullProtoObj=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.

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 thetoStringmethod back to the null-prototype object by assigning it one:

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 whichtoString()is on the object's prototype, thetoString()method here is an own property ofnullProtoObj.This is becausenullProtoObjhas no (null) prototype.

You can also revert a null-prototype object back to an ordinary object usingObject.setPrototypeOf(nullProtoObj, Object.prototype).

In practice, objects withnullprototype are usually used as a cheap substitute formaps.The presence ofObject.prototypeproperties will cause some bugs:

constages={alice:18,bob:27};

functionhasPerson(name){
returnnameinages;
}

functiongetAge(name){
returnages[name];
}

hasPerson("hasOwnProperty");// true
getAge("toString");// [Function: toString]

Using a null-prototype object removes this hazard without introducing too much complexity to thehasPersonandgetAgefunctions:

constages=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 fromObject.prototypealso prevents prototype pollution attacks. If a malicious script adds a property toObject.prototype,it will be accessible on every object in your program, except objects that have null prototype.

constuser={};

// 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 producenull-prototype objects, especially those that use objects as ad hoc key-value collections. For example:

• The return value ofObject.groupBy()
• Thegroupsandindices.groupsproperties of the result ofRegExp.prototype.exec()
• Array.prototype[@@unscopables](all@@unscopablesobjects should havenull-prototype)
• import.meta
• Module namespace objects, obtained throughimport * as ns from "module";orimport()

The term "null-prototype object "often also includes any object withoutObject.prototypein its prototype chain. Such objects can be created withextends nullwhen using classes.

Many built-in operations that expect objects first coerce their arguments to objects.The operationcan be summarized as follows:

• Objects are returned as-is.
• undefinedandnullthrow aTypeError.
• Number,String,Boolean,Symbol,BigIntprimitives are wrapped into their corresponding object wrappers.

There are two ways to achieve nearly the same effect in JavaScript.

• Object.prototype.valueOf():Object.prototype.valueOf.call(x)does exactly the object coercion steps explained above to convertx.
• TheObject()function:Object(x)uses the same algorithm to convertx,except thatundefinedandnulldon't throw aTypeError,but return a plain object.

Places that use object coercion include:

• Theobjectparameter offor...inloops.
• Thethisvalue ofArraymethods.
• Parameters ofObjectmethods such asObject.keys().
• Auto-bo xing when a property is accessed on a primitive value, since primitives do not have properties.
• Thethisvalue when calling a non-strict function. Primitives are boxed whilenullandundefinedare replaced with theglobal object.

Unlikeconversion to primitives,the object coercion process itself is not observable in any way, since it doesn't invoke custom code liketoStringorvalueOfmethods.

Object()

Turns the input into an object.

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'sownenumerable 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'sownenumerable 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.groupBy()

Groups the elements of a given iterable according to the string values returned by a provided callback function. The returned object has separate properties for each group, containing arrays with the elements in the group.

Object.hasOwn()

Returnstrueif the specified object has the indicated property as itsownproperty, orfalseif the property is inherited or does not exist.

Object.is()

Compares if two values are the same value. Equates allNaNvalues (which differs from bothIsLooselyEqualused by==andIsStrictlyEqualused 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'sownenumerable 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'sownenumerable string properties.

These properties are defined onObject.prototypeand shared by allObjectinstances.

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 plainObjectinstances, the initial value is theObjectconstructor. Instances of other constructors each inherit theconstructorproperty from their respectiveConstructor.prototypeobject.

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'senumerable ownproperty.

Object.prototype.toLocaleString()

CallstoString().

Object.prototype.toString()

Returns a string representation of the object.

Object.prototype.valueOf()

Returns the primitive value of the specified object.

The following example creates empty objects using thenewkeyword with different arguments:

consto1=newObject();
consto2=newObject(undefined);
consto3=newObject(null);

You can use theObject()constructor to create an object wrapper of a primitive value.

The following examples create variableso1ando2which are objects storingBooleanandBigIntvalues:

// Equivalent to const o1 = new Boolean(true)
consto1=newObject(true);

// No equivalent because BigInt() can't be called as a constructor,
// and calling it as a regular function won't create an object
consto2=newObject(1n);

When altering the behavior of existingObject.prototypemethods, 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, passthisand the arguments (the call state) to the current behavior by callingapply()on the function. This pattern can be used for any prototype, such asNode.prototype,Function.prototype,etc.

constcurrent=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")){
returnthis["-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.
returncurrent.apply(this,args);
}
};

You can read more about prototypes inInheritance and the prototype chain.

• Object initializer