0
# humps
1

2
humps is a lightweight JavaScript library that provides comprehensive case conversion utilities for strings and object keys. It enables seamless transformation between camelCase, PascalCase, and underscore-separated naming conventions, with deep object processing and customizable conversion behavior.
3

4
## Package Information
5

6
- **Package Name**: humps
7
- **Package Type**: npm
8
- **Language**: JavaScript
9
- **Installation**: `npm install humps` or `bower install humps`
10

11
## Core Imports
12

13
```javascript
14
const humps = require("humps");
15
```
16

17
For ES modules:
18

19
```javascript
20
import humps from "humps";
21
```
22

23
Individual imports:
24

25
```javascript
26
const { camelize, decamelize, camelizeKeys, decamelizeKeys } = require("humps");
27
```
28

29
Browser (global):
30

31
```html
32
<script src="humps.js"></script>
33
<script>
34
  // Access via global humps object
35
  humps.camelize("hello_world");
36
</script>
37
```
38

39
## Basic Usage
40

41
```javascript
42
const humps = require("humps");
43

44
// String conversions
45
const camelCased = humps.camelize("hello_world"); // "helloWorld"
46
const underscored = humps.decamelize("helloWorld"); // "hello_world"
47
const pascalCased = humps.pascalize("hello_world"); // "HelloWorld"
48

49
// Object key conversions
50
const obj = { first_name: "John", last_name: "Doe" };
51
const camelObj = humps.camelizeKeys(obj); // { firstName: "John", lastName: "Doe" }
52
const snakeObj = humps.decamelizeKeys(camelObj); // { first_name: "John", last_name: "Doe" }
53

54
// Deep object processing
55
const nested = {
56
  user_info: {
57
    first_name: "Jane",
58
    contact_details: [
59
      { phone_number: "123-456-7890" },
60
      { email_address: "jane@example.com" }
61
    ]
62
  }
63
};
64
const camelNested = humps.camelizeKeys(nested);
65
// Result: { userInfo: { firstName: "Jane", contactDetails: [{ phoneNumber: "123-456-7890" }, { emailAddress: "jane@example.com" }] } }
66
```
67

68
## Capabilities
69

70
### String Conversion
71

72
#### Camelize
73

74
Converts underscore/hyphen/space-separated strings to camelCase.
75

76
```javascript { .api }
77
/**
78
 * Converts underscore/hyphen/space-separated strings to camelCase
79
 * @param {string} string - The string to convert
80
 * @returns {string} The camelCased string
81
 */
82
function camelize(string);
83
```
84

85
**Usage Examples:**
86

87
```javascript
88
humps.camelize("hello_world"); // "helloWorld"
89
humps.camelize("hello-world"); // "helloWorld"
90
humps.camelize("hello world"); // "helloWorld"
91
humps.camelize("HelloWorld"); // "helloWorld" (first char lowercased)
92
humps.camelize("123"); // "123" (numbers unchanged)
93
```
94

95
#### Decamelize
96

97
Converts camelCase strings to underscore-separated (or custom separator).
98

99
```javascript { .api }
100
/**
101
 * Converts camelCase strings to underscore-separated strings
102
 * @param {string} string - The camelCase string to convert
103
 * @param {Object} [options] - Configuration options
104
 * @param {string} [options.separator="_"] - Custom separator character
105
 * @param {RegExp} [options.split=/(?=[A-Z])/] - Custom word splitting pattern
106
 * @returns {string} The converted string
107
 */
108
function decamelize(string, options);
109
```
110

111
**Usage Examples:**
112

113
```javascript
114
humps.decamelize("helloWorld"); // "hello_world"
115
humps.decamelize("helloWorld", { separator: "-" }); // "hello-world"
116
humps.decamelize("helloWorld1"); // "hello_world1" (numbers not split by default)
117
humps.decamelize("helloWorld1", { split: /(?=[A-Z0-9])/ }); // "hello_world_1"
118
```
119

120
#### Pascalize
121

122
Converts underscore/hyphen/space-separated strings to PascalCase.
123

124
```javascript { .api }
125
/**
126
 * Converts underscore/hyphen/space-separated strings to PascalCase
127
 * @param {string} string - The string to convert
128
 * @returns {string} The PascalCased string
129
 */
130
function pascalize(string);
131
```
132

133
**Usage Examples:**
134

135
```javascript
136
humps.pascalize("hello_world"); // "HelloWorld"
137
humps.pascalize("hello-world"); // "HelloWorld"
138
humps.pascalize("hello world"); // "HelloWorld"
139
```
140

141
#### Depascalize
142

143
Alias for decamelize function - converts PascalCase/camelCase strings to underscore-separated.
144

145
```javascript { .api }
146
/**
147
 * Alias for decamelize - converts PascalCase/camelCase strings to underscore-separated
148
 * @param {string} string - The PascalCase/camelCase string to convert
149
 * @param {Object} [options] - Configuration options (same as decamelize)
150
 * @returns {string} The converted string
151
 */
152
function depascalize(string, options);
153
```
154

155
### Object Key Conversion
156

157
#### Camelize Keys
158

159
Recursively converts object keys to camelCase.
160

161
```javascript { .api }
162
/**
163
 * Recursively converts object keys to camelCase
164
 * @param {Object|Array} object - Object or array to process
165
 * @param {Function|Object} [options] - Processing callback or options object
166
 * @returns {Object|Array} Object with camelCased keys
167
 */
168
function camelizeKeys(object, options);
169
```
170

171
**Callback Options:**
172

173
```javascript { .api }
174
/**
175
 * Custom processing callback for camelizeKeys
176
 * @param {string} key - The current key being processed
177
 * @param {Function} convert - The default conversion function
178
 * @returns {string} The processed key
179
 */
180
type ProcessorCallback = (key, convert) => string;
181
```
182

183
**Usage Examples:**
184

185
```javascript
186
// Basic usage
187
const obj = { first_name: "John", last_name: "Doe" };
188
humps.camelizeKeys(obj); // { firstName: "John", lastName: "Doe" }
189

190
// Array processing
191
const users = [{ first_name: "John" }, { first_name: "Jane" }];
192
humps.camelizeKeys(users); // [{ firstName: "John" }, { firstName: "Jane" }]
193

194
// Custom processing callback
195
humps.camelizeKeys(obj, function(key, convert) {
196
  return key === "first_name" ? key : convert(key);
197
}); // { first_name: "John", lastName: "Doe" }
198

199
// Nested objects
200
const nested = {
201
  user_info: {
202
    contact_details: { phone_number: "123-456-7890" }
203
  }
204
};
205
humps.camelizeKeys(nested);
206
// { userInfo: { contactDetails: { phoneNumber: "123-456-7890" } } }
207
```
208

209
#### Decamelize Keys
210

211
Recursively converts camelCase object keys to underscore-separated.
212

213
```javascript { .api }
214
/**
215
 * Recursively converts camelCase object keys to underscore-separated
216
 * @param {Object|Array} object - Object or array to process
217
 * @param {Function|Object} [options] - Processing callback or options object
218
 * @returns {Object|Array} Object with underscore-separated keys
219
 */
220
function decamelizeKeys(object, options);
221
```
222

223
**Options Object:**
224

225
```javascript { .api }
226
/**
227
 * Options for decamelizeKeys function
228
 * @typedef {Object} DecamelizeOptions
229
 * @property {string} [separator="_"] - Custom separator character
230
 * @property {RegExp} [split=/(?=[A-Z])/] - Custom word splitting pattern
231
 * @property {Function} [process] - Custom processing callback
232
 */
233
type DecamelizeOptions = {
234
  separator?: string;
235
  split?: RegExp;
236
  process?: (key: string, convert: Function, options: DecamelizeOptions) => string;
237
};
238
```
239

240
**Usage Examples:**
241

242
```javascript
243
// Basic usage
244
const obj = { firstName: "John", lastName: "Doe" };
245
humps.decamelizeKeys(obj); // { first_name: "John", last_name: "Doe" }
246

247
// Custom separator
248
humps.decamelizeKeys(obj, { separator: "-" }); // { "first-name": "John", "last-name": "Doe" }
249

250
// Custom processing with options object
251
humps.decamelizeKeys(obj, {
252
  separator: "-",
253
  process: function(key, convert, options) {
254
    return key === "firstName" ? key : convert(key, options);
255
  }
256
}); // { firstName: "John", "last-name": "Doe" }
257

258
// Direct callback (legacy format)
259
humps.decamelizeKeys(obj, function(key, convert, options) {
260
  return key === "firstName" ? key : convert(key, options);
261
}); // { firstName: "John", last_name: "Doe" }
262
```
263

264
#### Pascalize Keys
265

266
Recursively converts object keys to PascalCase.
267

268
```javascript { .api }
269
/**
270
 * Recursively converts object keys to PascalCase
271
 * @param {Object|Array} object - Object or array to process
272
 * @param {Function} [options] - Processing callback
273
 * @returns {Object|Array} Object with PascalCased keys
274
 */
275
function pascalizeKeys(object, options);
276
```
277

278
**Usage Examples:**
279

280
```javascript
281
const obj = { first_name: "John", last_name: "Doe" };
282
humps.pascalizeKeys(obj); // { FirstName: "John", LastName: "Doe" }
283

284
// With callback
285
humps.pascalizeKeys(obj, function(key, convert) {
286
  return key === "first_name" ? key : convert(key);
287
}); // { first_name: "John", LastName: "Doe" }
288
```
289

290
#### Depascalize Keys
291

292
Alias for decamelizeKeys function - recursively converts PascalCase/camelCase object keys to underscore-separated.
293

294
```javascript { .api }
295
/**
296
 * Alias for decamelizeKeys - recursively converts PascalCase/camelCase object keys to underscore-separated
297
 * @param {Object|Array} object - Object or array to process
298
 * @param {Function|Object} [options] - Processing callback or options object (same as decamelizeKeys)
299
 * @returns {Object|Array} Object with underscore-separated keys
300
 */
301
function depascalizeKeys(object, options);
302
```
303

304
## Type Handling
305

306
The library handles various JavaScript types during object key processing:
307

308
- **Objects**: Keys are converted, values are recursively processed
309
- **Arrays**: Each element is recursively processed
310
- **Dates**: Preserved as-is (not converted)
311
- **RegExp**: Preserved as-is (not converted)
312
- **Functions**: Preserved as-is (not converted)
313
- **Booleans**: Preserved as-is (not converted)
314
- **Primitives**: Strings, numbers, null, undefined are preserved as-is
315

316
## Advanced Usage
317

318
### Custom Processing Callbacks
319

320
All object key conversion functions support custom processing callbacks for fine-grained control:
321

322
```javascript
323
// Skip conversion for keys matching certain patterns
324
const skipUppercase = (key, convert) => {
325
  return /^[A-Z0-9_]+$/.test(key) ? key : convert(key);
326
};
327

328
const obj = { API_KEY: "secret", user_name: "john" };
329
humps.camelizeKeys(obj, skipUppercase); // { API_KEY: "secret", userName: "john" }
330
```
331

332
### Integration with APIs
333

334
Common pattern for converting between JavaScript and Ruby/Rails API formats:
335

336
```javascript
337
// Converting Ruby/Rails API response to JavaScript format
338
const apiResponse = {
339
  user_data: {
340
    first_name: "John",
341
    last_name: "Doe",
342
    created_at: new Date(),
343
    contact_info: [
344
      { phone_number: "123-456-7890" },
345
      { email_address: "john@example.com" }
346
    ]
347
  }
348
};
349

350
const jsFormat = humps.camelizeKeys(apiResponse);
351
// Process in JavaScript...
352

353
// Converting back for API request
354
const railsFormat = humps.decamelizeKeys(jsFormat);
355
```
356

357
## Error Handling and Edge Cases
358

359
The humps library handles edge cases gracefully:
360

361
- **Numerical strings**: Numeric strings are preserved unchanged during string conversions
362
- **Empty objects/arrays**: Empty containers are processed without errors
363
- **Null/undefined values**: Primitive values are preserved as-is
364
- **Circular references**: While not explicitly handled, the library processes objects recursively
365
- **Special objects**: Dates, RegExp, Functions, and Booleans are preserved without key conversion
366

367
All functions are designed to be safe with various input types and will not throw errors on unexpected input.