Repository files navigation

Note: This proposal was split out of the broaderObject Property Counting effort.For the wider discussion and a more general API that counts different kinds of own properties, see the parent proposal:https://github.com/tc39/proposal-object-property-count

• Stage: 2
• Champions:Ruben Bridgewater,Jordan Harband
• Authors:Ruben Bridgewater,Jordan Harband

You can browse the spec text athttps://tc39.es/proposal-object-keys-length/ or view thesource.

Object.keysLength(target) returns the number of an object’s own enumerable string-keyed properties — precisely the same set of properties returned byObject.keys(target), but without allocating the intermediate array. In other words:

Object.keysLength(obj)===Object.keys(obj).length;

This narrowly scoped API addresses the single most common “count properties” pattern in the wild:Object.keys(obj).length.

Developers frequently writeObject.keys(obj).length to determine how many own enumerable string-keyed properties an object has. While clear, this forces the engine to create an array of keys only to immediately take its.length, incurring avoidable allocation and garbage-collection overhead. This cost can be significant on hot paths and in frameworks and libraries that perform this check repeatedly.

Providing a built-in that returns the same information without producing an intermediate array:

• avoids needless allocation and GC pressure,
• makes intent explicit and readable, and
• enables engines to optimize the common case directly.

This proposal intentionally focuses on the exact semantics ofObject.keys (own, enumerable, string-keyed properties). Broader counting needs (e.g., including symbols or non-enumerables, or choosing among key types) are covered by the parent proposal,Object.propertyCount.

Object.keysLength(target)

• Parameters:target — coerced withToObject (likeObject.keys). Passingnull orundefined throws aTypeError.
• Return value: a non-negative integer equal toObject.keys(target).length.

Seethe spec for the precise algorithm.

Basic objects:

Object.keysLength({});// 0Object.keysLength({a:1,b:2});// 2Object.keysLength(/./.exec('a'));// 4 ('0', 'index', 'input', 'groups')

Objects without a prototype:

consto={__proto__:null};o.x=1;Object.keysLength(o);// 1

Arrays and sparse arrays (counts present indices only):

Object.keysLength([,,3]);// 1 (only index "2" exists)consta=[];a[10]='x';Object.keysLength(a);// 1

Symbols are not counted (matchingObject.keys):

consts=Symbol('s');constobj={a:1,[s]:2};Object.keysLength(obj);// 1

Non-enumerable properties are not counted:

constobj={a:1};Object.defineProperty(obj,'hidden',{value:true,enumerable:false});Object.keysLength(obj);// 1Object.keysLength([]);// 0

Primitives are coerced likeObject.keys:

Object.keysLength('abc');// 3 (indices "0","1","2")Object.keysLength(42);// 0

Error cases:

Object.keysLength(null);// throws TypeErrorObject.keysLength(undefined);// throws TypeError

Object.keysLength is a focused subset of the largerObject.propertyCount proposal. WhileObject.keysLength is fixed to matchObject.keys semantics (own, enumerable, string-keyed properties),Object.propertyCount explores a flexible API that can also count symbols and/or non-enumerables via options. If your use case needs those capabilities, see the parent proposal:https://github.com/tc39/proposal-object-property-count.

The patternObject.keys(obj).length is ubiquitous in production codebases across frameworks and libraries (e.g., React, Angular, Vue, Lodash, Node.js, Storybook, VS Code, and many more). This API makes that common intent fast without changing semantics.

• Spec text:https://tc39.es/proposal-object-keys-length/
• Spec source:spec.emu
• Parent proposal:https://github.com/tc39/proposal-object-property-count