0
# Lodash MapKeys
1

2
Lodash MapKeys provides the `mapKeys` function for creating objects with transformed keys while preserving the original values. It's the complement to `mapValues`, enabling key transformation through various iteratee types including functions, property paths, and custom transformations.
3

4
## Package Information
5

6
- **Package Name**: lodash
7
- **Package Type**: npm
8
- **Language**: JavaScript
9
- **Installation**: `npm install lodash`
10
- **Specific Function**: mapKeys (from lodash utility library)
11

12
## Core Imports
13

14
```javascript
15
import { mapKeys } from "lodash";
16
```
17

18
For full lodash import:
19

20
```javascript
21
import _ from "lodash";
22
// Use as _.mapKeys()
23
```
24

25
CommonJS:
26

27
```javascript
28
const { mapKeys } = require("lodash");
29
```
30

31
## Basic Usage
32

33
```javascript
34
import { mapKeys } from "lodash";
35

36
// Transform keys using a function
37
const result = mapKeys({ a: 1, b: 2 }, function(value, key) {
38
  return key + value;
39
});
40
// => { 'a1': 1, 'b2': 2 }
41

42
// Transform keys using property path
43
const data = { user1: { name: 'alice' }, user2: { name: 'bob' } };
44
const byName = mapKeys(data, 'name');
45
// => { 'alice': { name: 'alice' }, 'bob': { name: 'bob' } }
46

47
// Use with thisArg for context binding
48
const context = { prefix: 'key_' };
49
const prefixed = mapKeys({ a: 1, b: 2 }, function(value, key) {
50
  return this.prefix + key;
51
}, context);
52
// => { 'key_a': 1, 'key_b': 2 }
53
```
54

55
## Capabilities
56

57
### Object Key Transformation
58

59
Creates an object with the same values as the input object and keys generated by running each own enumerable property through an iteratee function.
60

61
```javascript { .api }
62
/**
63
 * Creates an object with the same values as `object` and keys generated by 
64
 * running each own enumerable property of `object` through `iteratee`.
65
 * 
66
 * @param {Object} object - The object to iterate over
67
 * @param {Function|Object|string} [iteratee=_.identity] - The function invoked per iteration
68
 * @param {*} [thisArg] - The `this` binding of `iteratee`
69
 * @returns {Object} Returns the new mapped object
70
 */
71
function mapKeys(object, iteratee, thisArg);
72
```
73

74
**Parameters:**
75

76
- `object` (Object): The object to iterate over. Can also be an array (treated as object with index keys)
77
- `iteratee` (Function|Object|string, optional): The function invoked per iteration. Defaults to `_.identity`
78
  - **Function**: `(value, key, object) => newKey` - Custom transformation function
79
  - **String**: Property path to extract nested value as key (uses `_.property` style)
80
  - **Object**: Uses `_.matches` style predicate for transformation
81
  - **Omitted**: Uses `_.identity` which converts values to string keys
82
- `thisArg` (*, optional): The `this` binding of `iteratee`
83

84
**Returns:** 
85
- `Object`: Returns the new mapped object with transformed keys
86

87
**Usage Examples:**
88

89
```javascript
90
import { mapKeys } from "lodash";
91

92
// Function iteratee - custom key transformation
93
const users = { user1: 'Alice', user2: 'Bob' };
94
const result1 = mapKeys(users, (value, key) => `${key}_${value.toLowerCase()}`);
95
// => { 'user1_alice': 'Alice', 'user2_bob': 'Bob' }
96

97
// String iteratee - property path extraction
98
const data = {
99
  item1: { id: 'x', name: 'First' },
100
  item2: { id: 'y', name: 'Second' }
101
};
102
const byId = mapKeys(data, 'id');
103
// => { 'x': { id: 'x', name: 'First' }, 'y': { id: 'y', name: 'Second' } }
104

105
// Array input (treated as object with index keys)
106
const array = ['foo', 'bar'];
107
const arrayResult = mapKeys(array, (value, index) => `item_${index}`);
108
// => { 'item_0': 'foo', 'item_1': 'bar' }
109

110
// Context binding with thisArg
111
const transformer = {
112
  suffix: '_transformed',
113
  transform: function(value, key) {
114
    return key + this.suffix;
115
  }
116
};
117
const contextResult = mapKeys(
118
  { a: 1, b: 2 }, 
119
  transformer.transform, 
120
  transformer
121
);
122
// => { 'a_transformed': 1, 'b_transformed': 2 }
123

124
// No iteratee - uses identity (converts values to keys)
125
const identityResult = mapKeys({ a: 1, b: 2 });
126
// => { '1': 1, '2': 2 }
127

128
// Nested property access
129
const complexData = {
130
  user1: { profile: { username: 'alice123' } },
131
  user2: { profile: { username: 'bob456' } }
132
};
133
const byUsername = mapKeys(complexData, 'profile.username');
134
// => { 'alice123': { profile: { username: 'alice123' } }, 'bob456': { profile: { username: 'bob456' } } }
135
```
136

137
### Type Behavior
138

139
**Input Types:**
140
- **Object**: Standard object with enumerable properties
141
- **Array**: Treated as object with numeric index keys (0, 1, 2, etc.)
142
- **Null/Undefined**: Returns empty object `{}`
143

144
**Key Generation:**
145
- Keys are always converted to strings (JavaScript object key behavior)
146
- Duplicate generated keys will overwrite previous entries
147
- Non-enumerable properties are ignored
148
- Only own properties are processed (not inherited)
149

150
**Iteratee Function Signature:**
151
```javascript
152
function iteratee(value, key, object) {
153
  // value: the property value
154
  // key: the property key (string or number for arrays)
155
  // object: the original object being iterated
156
  // return: the new key for this property
157
}
158
```
159

160
## Error Handling
161

162
The `mapKeys` function handles various edge cases gracefully:
163

164
- **Invalid iteratee**: Falls back to identity transformation
165
- **Non-objects**: Empty or falsy inputs return empty object `{}`
166
- **Circular references**: Processes enumerable properties without infinite loops
167
- **Property access errors**: String iteratees that reference non-existent paths return `undefined` keys
168

169
## Related Functions
170

171
- `_.mapValues` - Maps values instead of keys (companion function)
172
- `_.transform` - More flexible object transformation utility
173
- `_.keyBy` - Creates object with keys from iteratee results (similar use case)
174
- `_.invert` - Swaps keys and values of an object