0
# Lowercase Keys
1

2
Lowercase Keys is a utility function that creates a new object with all keys converted to lowercase while preserving the original values. It's designed as a lightweight, zero-dependency utility for data normalization and consistent key formatting.
3

4
## Package Information
5

6
- **Package Name**: lowercase-keys
7
- **Package Type**: npm
8
- **Language**: JavaScript (ES modules) with TypeScript definitions
9
- **Installation**: `npm install lowercase-keys`
10

11
## Core Imports
12

13
```javascript
14
import lowercaseKeys from 'lowercase-keys';
15
```
16

17
**Note**: This package is ES modules only and requires Node.js 12.20.0+.
18

19
## Basic Usage
20

21
```javascript
22
import lowercaseKeys from 'lowercase-keys';
23

24
// Basic transformation
25
const result = lowercaseKeys({FOO: true, bAr: false});
26
console.log(result);
27
// => {foo: true, bar: false}
28

29
// With mixed case keys
30
const data = lowercaseKeys({
31
  UserName: 'alice',
32
  EMAIL_ADDRESS: 'alice@example.com',
33
  isActive: true
34
});
35
console.log(data);
36
// => {username: 'alice', email_address: 'alice@example.com', isactive: true}
37
```
38

39
## Capabilities
40

41
### Object Key Transformation
42

43
Converts all keys of an object to lowercase while preserving the original values and their types.
44

45
```javascript { .api }
46
/**
47
 * Lowercase the keys of an object.
48
 * @param {Record<string, T>} object - The input object whose keys should be lowercased
49
 * @returns {Record<string, T>} A new object with the keys lowercased
50
 */
51
function lowercaseKeys<T>(object: Record<string, T>): Record<string, T>;
52
```
53

54
**Parameters:**
55
- `object` (`Record<string, T>`): Input object with string keys and values of any type
56

57
**Returns:**
58
- `Record<string, T>`: New object with all keys converted to lowercase, values unchanged
59

60
**Behavior:**
61
- Creates a new object (does not modify the original)
62
- Converts all keys to lowercase using JavaScript's `String.toLowerCase()`
63
- Preserves all original values and their types exactly
64
- Maintains object property order (ES2015+ environments)
65

66
**Usage Examples:**
67

68
```javascript
69
// Simple object transformation
70
const config = lowercaseKeys({
71
  API_KEY: 'abc123',
72
  Database_URL: 'localhost:5432',
73
  debug: true
74
});
75
// => {api_key: 'abc123', database_url: 'localhost:5432', debug: true}
76

77
// Works with any value types
78
const mixed = lowercaseKeys({
79
  Count: 42,
80
  Items: ['a', 'b', 'c'],
81
  Settings: { enabled: true },
82
  Handler: function() { return 'hello'; }
83
});
84
// => {count: 42, items: ['a', 'b', 'c'], settings: { enabled: true }, handler: function() { return 'hello'; }}
85

86
// Empty object
87
const empty = lowercaseKeys({});
88
// => {}
89
```
90

91
**TypeScript Support:**
92

93
The function is fully typed with generic type preservation:
94

95
```typescript
96
// Type is preserved through transformation
97
const typed: Record<string, number> = lowercaseKeys({FOO: 1, BAR: 2});
98
// typed has type Record<string, number>
99

100
// Works with interface types
101
interface User {
102
  name: string;
103
  age: number;
104
}
105

106
const users: Record<string, User> = lowercaseKeys({
107
  'USER_1': { name: 'Alice', age: 25 },
108
  'USER_2': { name: 'Bob', age: 30 }
109
});
110
// users has type Record<string, User>
111
```