0
# Object.values
1

2
Object.values is an ES2017 spec-compliant shim for the `Object.values` method that works across all JavaScript environments. It provides a polyfill/shim that extracts enumerable property values from objects into an array, following the ECMAScript specification precisely while maintaining compatibility with legacy environments (ES3+).
3

4
## Package Information
5

6
- **Package Name**: object.values
7
- **Package Type**: npm
8
- **Language**: JavaScript (ES3+)
9
- **Installation**: `npm install object.values`
10

11
## Core Imports
12

13
```javascript
14
var values = require('object.values');
15
```
16

17
## Basic Usage
18

19
```javascript
20
var values = require('object.values');
21

22
var obj = { a: 1, b: 2, c: 3 };
23
var result = values(obj); // [1, 2, 3]
24

25
// Auto-shim for global usage
26
require('object.values/auto');
27
var result2 = Object.values(obj); // [1, 2, 3]
28
```
29

30
## Architecture
31

32
Object.values follows the es-shim API pattern with multiple entry points:
33

34
- **Main API**: Direct function usage for extracting values
35
- **Polyfill Detection**: Feature detection to use native implementation when available
36
- **Global Shimming**: Optional installation of Object.values on the global Object
37
- **Auto-shimming**: Immediate global installation for convenience
38
- **Implementation Access**: Direct access to the core algorithm
39

40
## Capabilities
41

42
### Main Function
43

44
Extract enumerable property values from objects in the same order as `for...in` iteration.
45

46
```javascript { .api }
47
/**
48
 * Extract enumerable property values from an object
49
 * @param {any} O - Object to extract values from
50
 * @returns {Array} Array of enumerable property values
51
 * @throws {TypeError} If O cannot be converted to object
52
 */
53
function values(O);
54
```
55

56
**Usage Examples:**
57

58
```javascript
59
var values = require('object.values');
60

61
// Basic object
62
values({ a: 1, b: 2, c: 3 }); // [1, 2, 3]
63

64
// Mixed property types
65
values({ x: 'hello', y: 42, z: true }); // ['hello', 42, true]
66

67
// Array (returns array values, not indices)
68
values([10, 20, 30]); // [10, 20, 30]
69

70
// String (returns array of characters)
71
values('abc'); // ['a', 'b', 'c']
72

73
// Empty object
74
values({}); // []
75

76
// With symbol properties (symbols are ignored)
77
var obj = { a: 1, b: 2 };
78
if (typeof Symbol === 'function') {
79
  var sym = Symbol('test');
80
  obj[sym] = 'ignored';
81
}
82
values(obj); // [1, 2] - symbol properties are omitted
83

84
// Duplicate values are preserved
85
values({ a: 1, b: 1, c: 2 }); // [1, 1, 2]
86

87
// Property order follows for...in iteration order
88
var orderedObj = { b: 2, a: 1 };
89
orderedObj[0] = 'first';
90
orderedObj.c = 3;
91
values(orderedObj); // ['first', 2, 1, 3] - maintains property order
92
```
93

94
### Polyfill Function
95

96
Get the appropriate Object.values implementation (native or polyfill).
97

98
```javascript { .api }
99
/**
100
 * Get the best available Object.values implementation
101
 * @returns {Function} Native Object.values if spec-compliant, otherwise polyfill
102
 */
103
function getPolyfill();
104
```
105

106
**Usage:**
107

108
```javascript
109
var getPolyfill = require('object.values/polyfill');
110
var objectValues = getPolyfill();
111

112
// Use the returned function
113
objectValues({ a: 1, b: 2 }); // [1, 2]
114
```
115

116
### Shim Installation
117

118
Install Object.values on the global Object if missing or non-compliant.
119

120
```javascript { .api }
121
/**
122
 * Install Object.values on global Object if needed
123
 * @returns {Function} The installed polyfill function
124
 */
125
function shimValues();
126
```
127

128
**Usage:**
129

130
```javascript
131
var shimValues = require('object.values/shim');
132
var polyfill = shimValues();
133

134
// Object.values is now available globally
135
Object.values({ a: 1, b: 2 }); // [1, 2]
136
```
137

138
### Implementation Access
139

140
Direct access to the core Object.values implementation.
141

142
```javascript { .api }
143
/**
144
 * Core Object.values implementation (bypasses native detection)
145
 * @param {any} O - Object to extract values from
146
 * @returns {Array} Array of enumerable property values
147
 * @throws {TypeError} If O cannot be converted to object
148
 */
149
function implementation(O);
150
```
151

152
**Usage:**
153

154
```javascript
155
var implementation = require('object.values/implementation');
156
implementation({ a: 1, b: 2 }); // [1, 2]
157
```
158

159
### Auto-shimming
160

161
Automatically installs the shim when the module is required.
162

163
```javascript
164
// Simply requiring this module installs the shim
165
require('object.values/auto');
166

167
// Object.values is now available globally
168
Object.values({ a: 1, b: 2 }); // [1, 2]
169
```
170

171
## Properties on Main Export
172

173
The main export function includes additional properties for flexible usage:
174

175
```javascript { .api }
176
// Main export has these attached properties:
177
values.getPolyfill; // Function reference: returns appropriate implementation
178
values.implementation; // Function reference: direct access to core algorithm
179
values.shim; // Function reference: installs global shim
180
```
181

182
**Usage:**
183

184
```javascript
185
var values = require('object.values');
186

187
// Use attached properties
188
var polyfill = values.getPolyfill();
189
var result1 = values.implementation({ a: 1 });
190
values.shim(); // Install globally
191
```
192

193
## Entry Points Summary
194

195
- `object.values` - Main function with attached properties (most common)
196
- `object.values/polyfill` - Get best available implementation
197
- `object.values/shim` - Install global shim function
198
- `object.values/implementation` - Direct core implementation
199
- `object.values/auto` - Automatic global shimming
200

201
## Behavior Specifications
202

203
### Property Selection
204

205
- **Enumerable Only**: Only enumerable properties are included (non-enumerable properties are omitted)
206
- **Own Properties**: Inherited properties are ignored
207
- **Symbol Properties**: Symbol properties are omitted
208
- **Order**: Values appear in same order as `for...in` iteration
209
- **Dynamic Changes**: Properties deleted or made non-enumerable during iteration are handled per ES specification
210

211
### Type Coercion
212

213
- **Objects**: Processed directly
214
- **Primitives**: Converted to objects first (strings become character arrays)
215
- **null/undefined**: Throws TypeError (following ES spec)
216

217
### Error Handling
218

219
```javascript
220
// These will throw TypeError:
221
values(null);      // TypeError
222
values(undefined); // TypeError
223

224
// These work (primitives are converted to objects):
225
values(42);        // [] (Number object has no enumerable properties)
226
values('abc');     // ['a', 'b', 'c']
227
values(true);      // [] (Boolean object has no enumerable properties)
228
```