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