Home

Awesome

Object.values / Object.entries

ECMAScript Proposal, specs, and reference implementation for Object.values/Object.entries

Spec drafted by @ljharb.

This proposal is currently at stage 4 of the process, and will be included in ES 2017.

Designated TC39 reviewers: @wycats @littledan @rwaldron

Engine Implementations

Previous discussions

Rationale

It is a very common use case to need the own values of an object - for example, when using an object as a hash filter. Many libraries have a “values” function: lodash/underscore, jQuery, Backbone, etc.

It is also useful to obtain an array of key/value pairs (what the spec calls “entries”) from an object, for the purposes of iteration or serialization. With the advent of the Map constructor accepting an iterable of entries, and its associated entries iterator (WeakMap also accepts iterable entries in its constructor), it becomes very compelling to want to quickly convert a plain object to a Map, via passing an array of entries into new Map.

We already have the precedent of Object.keys returning an array of own keys, and matched triplets of keys/values/entries iterators on Map/Set/Array. As such, per discussions on es-discuss and in at least one previous TC39 meeting, this proposal seeks to add Object.values and Object.entries to ECMAScript. Like Object.keys, they would return arrays. Their ordering would match Object.keys ordering precisely, such that the indices of all three resulting arrays would reflect the same key, value, or entry on the object.

Spec

You can view the spec in markdown format or rendered as HTML. Note: there's been a small bit of spec refactoring to ensure that Object.{keys,values,entries} share the same key ordering.

Iterators or Arrays?

Consistency with Object.keys is paramount in this proposal‘s opinion. A follow-on proposal for an iterator, however, could likely be Reflect.ownValues and Reflect.ownEntries, which would complete the triplet with Reflect.ownKeys, providing an array of both string-valued and symbol-valued properties. However, this proposal is focused on Object.values/Object.entries, and the existence of either the Object or Reflect forms should not preclude the existence of the other. In addition, the current precedent for returning iterators from keys/values/entries currently only applies to methods on prototypes - and in addition, “Object is special” seems to be something many accept. Also, arrays are themselves iterable already.