0
# Invert KV
1

2
Invert KV is a utility function for inverting the key/value pairs of JavaScript objects. It transforms object keys into values and values into keys, supporting both regular properties and symbol properties with robust error handling.
3

4
## Package Information
5

6
- **Package Name**: invert-kv
7
- **Package Type**: npm
8
- **Language**: JavaScript with TypeScript definitions
9
- **Installation**: `npm install invert-kv`
10

11
## Core Imports
12

13
```javascript
14
import invertKeyValue from "invert-kv";
15
```
16

17
The package is ES module only (no CommonJS support).
18

19
## Basic Usage
20

21
```javascript
22
import invertKeyValue from "invert-kv";
23

24
// Basic object inversion
25
invertKeyValue({foo: 'bar', hello: 'world'});
26
//=> {bar: 'foo', world: 'hello'}
27

28
// Handles string and number keys
29
invertKeyValue({foo: 'bar', 1: 'one'});
30
//=> {bar: 'foo', one: '1'}
31

32
// Supports symbols
33
const sym = Symbol('test');
34
invertKeyValue({foo: sym, unicorn: 'rainbow'});
35
//=> {[sym]: 'foo', rainbow: 'unicorn'}
36
```
37

38
## Capabilities
39

40
### Key-Value Inversion
41

42
Inverts the key/value pairs of an object, creating a new object where the original keys become values and the original values become keys.
43

44
```typescript { .api }
45
/**
46
 * Invert the key/value of an object
47
 * @param object - The object to invert (must be non-null object)
48
 * @returns A new object with inverted key/value pairs
49
 * @throws TypeError if input is not an object or is null
50
 */
51
function invertKeyValue<T extends Record<PropertyKey, PropertyKey>>(
52
  object: T
53
): {[P in keyof T as T[P]]: keyof T extends number ? Exclude<keyof T, number> | string : P};
54
```
55

56
The function:
57
- Processes both regular object properties (string/number keys) and symbol properties
58
- Creates a new object without mutating the original
59
- Throws `TypeError` with message "Expected an object" for invalid inputs (null, undefined, or non-objects)
60
- Supports any PropertyKey type for both keys and values (string, number, symbol)
61

62
**Usage Examples:**
63

64
```javascript
65
import invertKeyValue from "invert-kv";
66

67
// String properties
68
invertKeyValue({foo: 'bar', '🦄': '🌈'});
69
//=> {bar: 'foo', '🌈': '🦄'}
70

71
// Mixed string and number properties
72
invertKeyValue({name: 'Alice', 1: 'first', 2: 'second'});
73
//=> {Alice: 'name', first: '1', second: '2'}
74

75
// Symbol properties
76
const mySymbol = Symbol('myKey');
77
invertKeyValue({regularKey: mySymbol, anotherKey: 'value'});
78
//=> {[mySymbol]: 'regularKey', value: 'anotherKey'}
79

80
// Symbols as keys
81
const keySymbol = Symbol('keySymbol');
82
invertKeyValue({[keySymbol]: 'symbolValue', normalKey: 'normalValue'});
83
//=> {symbolValue: keySymbol, normalValue: 'normalKey'}
84

85
// Error handling
86
try {
87
  invertKeyValue(null);
88
} catch (error) {
89
  console.log(error.message); // "Expected an object"
90
}
91

92
try {
93
  invertKeyValue("not an object");
94
} catch (error) {
95
  console.log(error.message); // "Expected an object"
96
}
97
```
98

99
## Types
100

101
```typescript { .api }
102
/**
103
 * Generic type-safe version with mapped types
104
 */
105
function invertKeyValue<T extends Record<PropertyKey, PropertyKey>>(
106
  object: T
107
): {[P in keyof T as T[P]]: keyof T extends number ? Exclude<keyof T, number> | string : P};
108
```
109

110
The TypeScript definition provides:
111
- Generic constraint `T extends Record<PropertyKey, PropertyKey>` ensuring both keys and values are valid PropertyKey types
112
- Complex mapped type that preserves type relationships after inversion
113
- Special handling for numeric keys which become string values in the result
114
- Full type safety for the inversion operation