caseparser 5.1.0 → 6.0.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +229 -118
- package/dist/index.cjs +201 -1761
- package/dist/index.d.cts +28 -1333
- package/dist/index.d.ts +28 -1333
- package/dist/index.js +202 -1672
- package/package.json +9 -4
package/README.md
CHANGED
|
@@ -1,56 +1,79 @@
|
|
|
1
|
-
|
|
1
|
+
<div align="center">
|
|
2
2
|
|
|
3
|
-
|
|
4
|
-
|
|
5
|
-
|
|
6
|
-
|
|
7
|
-
|
|
8
|
-
|
|
9
|
-
|
|
10
|
-
Convert **strings** and **object keys** to any case, **whatever case they are in now**, with the resulting keys inferred by TypeScript.
|
|
11
|
-
|
|
12
|
-
- **Any case in:** no need to know or normalize the input first. Keys in different cases can even be mixed in the same object
|
|
13
|
-
- **Deep:** nested objects and objects inside arrays are converted too
|
|
14
|
-
- **Typed:** your editor autocompletes the converted keys
|
|
15
|
-
- Zero dependencies, tree-shakeable, ESM and CommonJS, on [npm](https://www.npmjs.com/package/caseparser) and [JSR](https://jsr.io/@nandomb/caseparser)
|
|
3
|
+
<a href="https://github.com/NandoMB/caseparser">
|
|
4
|
+
<picture>
|
|
5
|
+
<source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/NandoMB/caseparser/main/.github/assets/logo-dark.svg">
|
|
6
|
+
<img alt="caseparser" src="https://raw.githubusercontent.com/NandoMB/caseparser/main/.github/assets/logo-light.svg" height="76">
|
|
7
|
+
</picture>
|
|
8
|
+
</a>
|
|
16
9
|
|
|
17
|
-
|
|
18
|
-
> If you're looking for version 1.x.x, [click here](https://github.com/NandoMB/caseparser/tree/v1.x.x) to see the docs.
|
|
10
|
+
<h3>Convert strings and object keys to any case, from any case, with the result typed by TypeScript.</h3>
|
|
19
11
|
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
|
|
12
|
+
[](https://www.npmjs.com/package/caseparser)
|
|
13
|
+
[](https://jsr.io/@nandomb/caseparser)
|
|
14
|
+
[](https://jsr.io/@nandomb/caseparser)
|
|
15
|
+
[](https://github.com/NandoMB/caseparser/actions/workflows/main.yml)
|
|
16
|
+
[](https://bundlejs.com/?q=caseparser)
|
|
17
|
+
[](https://www.npmjs.com/package/caseparser)
|
|
18
|
+
[](#type-inference)
|
|
19
|
+
[](./LICENSE)
|
|
20
|
+
[](https://socket.dev/npm/package/caseparser)
|
|
21
|
+
|
|
22
|
+
<p>
|
|
23
|
+
<a href="#installation"><b>Install</b></a> ·
|
|
24
|
+
<a href="#quick-start"><b>Quick start</b></a> ·
|
|
25
|
+
<a href="#cases"><b>Cases</b></a> ·
|
|
26
|
+
<a href="#options"><b>Options</b></a> ·
|
|
27
|
+
<a href="#type-inference"><b>Types</b></a> ·
|
|
28
|
+
<a href="#benchmarks"><b>Benchmarks</b></a> ·
|
|
29
|
+
<a href="#security"><b>Security</b></a>
|
|
30
|
+
</p>
|
|
31
|
+
|
|
32
|
+
<br>
|
|
33
|
+
|
|
34
|
+
<picture>
|
|
35
|
+
<source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/NandoMB/caseparser/main/.github/assets/demo-dark.gif">
|
|
36
|
+
<img alt="toCamel converts snake_case keys to camelCase, toSnake converts them back, and TypeScript infers the new keys" src="https://raw.githubusercontent.com/NandoMB/caseparser/main/.github/assets/demo-light.gif" width="760">
|
|
37
|
+
</picture>
|
|
38
|
+
|
|
39
|
+
</div>
|
|
40
|
+
|
|
41
|
+
<br>
|
|
42
|
+
|
|
43
|
+
<table>
|
|
44
|
+
<tr>
|
|
45
|
+
<td width="25%" valign="top"><b>Any case in</b><br><sub>You don't need to know or normalize the input first. One object can mix keys in different cases.</sub></td>
|
|
46
|
+
<td width="25%" valign="top"><b>Deep</b><br><sub>Nested objects and objects inside arrays get converted too. Values stay as they are.</sub></td>
|
|
47
|
+
<td width="25%" valign="top"><b>Typed</b><br><sub>TypeScript infers the new keys, so your editor autocompletes them and catches typos.</sub></td>
|
|
48
|
+
<td width="25%" valign="top"><b>Fast and small</b><br><sub>5 to 25× faster on API responses. 1.8 KB gzipped with zero dependencies, and tree-shakeable.</sub></td>
|
|
49
|
+
</tr>
|
|
50
|
+
</table>
|
|
51
|
+
|
|
52
|
+
It ships as ESM and CommonJS on [npm](https://www.npmjs.com/package/caseparser) and [JSR](https://jsr.io/@nandomb/caseparser), and runs on Node.js, Bun, Deno, browsers and Cloudflare Workers.
|
|
53
|
+
|
|
54
|
+
> [!NOTE]
|
|
55
|
+
> The docs for version 1.x are on the [v1.x.x branch](https://github.com/NandoMB/caseparser/tree/v1.x.x).
|
|
32
56
|
|
|
33
57
|
## Installation
|
|
34
58
|
|
|
35
59
|
```sh
|
|
36
60
|
npm add caseparser # or: pnpm add caseparser / yarn add caseparser
|
|
37
61
|
```
|
|
38
|
-
|
|
62
|
+
|
|
63
|
+
From JSR:
|
|
64
|
+
|
|
39
65
|
```sh
|
|
40
66
|
deno add jsr:@nandomb/caseparser
|
|
67
|
+
npx jsr add @nandomb/caseparser # or: bunx jsr add @nandomb/caseparser
|
|
41
68
|
```
|
|
69
|
+
|
|
42
70
|
```ts
|
|
43
71
|
import { toSnake } from '@nandomb/caseparser';
|
|
44
72
|
```
|
|
45
|
-
###### Bun / Node.js from JSR
|
|
46
|
-
```sh
|
|
47
|
-
bunx jsr add @nandomb/caseparser
|
|
48
|
-
npx jsr add @nandomb/caseparser
|
|
49
|
-
```
|
|
50
73
|
|
|
51
74
|
## Quick start
|
|
52
75
|
|
|
53
|
-
|
|
76
|
+
Pass in an object and every key comes back in the new case, at any depth, whatever case it started in:
|
|
54
77
|
|
|
55
78
|
```ts
|
|
56
79
|
import { toCamel } from 'caseparser'; // ESM
|
|
@@ -93,7 +116,7 @@ toCamel(response);
|
|
|
93
116
|
|
|
94
117
|
Strings work the same way: `toSnake('helloWorld')`, `toSnake('Hello World')` and `toSnake('HELLO-WORLD')` all return `'hello_world'`.
|
|
95
118
|
|
|
96
|
-
The input is never mutated
|
|
119
|
+
The input is never mutated; you always get a new object. A common use is converting API payloads on the way in and on the way out:
|
|
97
120
|
|
|
98
121
|
```ts
|
|
99
122
|
import { toCamel, toSnake } from 'caseparser';
|
|
@@ -109,7 +132,7 @@ await fetch('/api/users/1', {
|
|
|
109
132
|
|
|
110
133
|
## Cases
|
|
111
134
|
|
|
112
|
-
There is one function per target case, and each one
|
|
135
|
+
There is one function per target case, and each one takes input in any case.
|
|
113
136
|
|
|
114
137
|
| Function | `'helloWorld'` → | `'LAST_login_AT'` → | Also known as |
|
|
115
138
|
| --- | --- | --- | --- |
|
|
@@ -129,7 +152,7 @@ There is one function per target case, and each one accepts input in any case:
|
|
|
129
152
|
| `toPath` | `hello/World` | `LAST/login/AT` | |
|
|
130
153
|
| `toSpace` | `hello World` | `LAST login AT` | |
|
|
131
154
|
|
|
132
|
-
`toDot`, `toPath` and `toSpace` only change the separator
|
|
155
|
+
`toDot`, `toPath` and `toSpace` only change the separator, so each word keeps its original case. To change it, use [`transform`](#transform).
|
|
133
156
|
|
|
134
157
|
## Options
|
|
135
158
|
|
|
@@ -137,7 +160,7 @@ Every function takes an optional second argument.
|
|
|
137
160
|
|
|
138
161
|
### `allowSymbols`
|
|
139
162
|
|
|
140
|
-
|
|
163
|
+
By default, symbols (ASCII punctuation such as `$`, `@`, `#` and `%`) are removed. Set it to `true` to keep all of them, or to an array to keep only the ones listed. You can also pass it directly as the second argument:
|
|
141
164
|
|
|
142
165
|
```ts
|
|
143
166
|
const data = { $ref: 1, '@type': 'User', 'discount%': 10 };
|
|
@@ -146,20 +169,30 @@ toCamel(data); // { ref: 1, type: 'User', discount: 10
|
|
|
146
169
|
toCamel(data, { allowSymbols: true }); // { $ref: 1, '@type': 'User', 'discount%': 10 }
|
|
147
170
|
toCamel(data, { allowSymbols: ['$'] }); // { $ref: 1, type: 'User', discount: 10 }
|
|
148
171
|
|
|
149
|
-
// shorthand
|
|
150
|
-
toCamel(data,
|
|
151
|
-
toCamel(data, ['$']); // same as { allowSymbols: ['$'] }
|
|
172
|
+
toCamel(data, true); // shorthand for { allowSymbols: true }
|
|
173
|
+
toCamel(data, ['$']); // shorthand for { allowSymbols: ['$'] }
|
|
152
174
|
```
|
|
153
175
|
|
|
154
|
-
A kept symbol sticks to the start of the next word
|
|
176
|
+
A kept symbol sticks to the start of the next word, so `toPascal('$id', true)` returns `'$Id'`. The rules are in [how keys are split into words](#how-keys-are-split-into-words).
|
|
177
|
+
|
|
178
|
+
### `ignore`
|
|
179
|
+
|
|
180
|
+
A list of object keys to leave alone, at any depth. Their values still get converted:
|
|
181
|
+
|
|
182
|
+
```ts
|
|
183
|
+
toCamel({ _id: 1, user_id: 2, extra_data: { inner_key: 3 } }, { ignore: ['_id', 'extra_data'] });
|
|
184
|
+
// { _id: 1, userId: 2, extra_data: { innerKey: 3 } }
|
|
185
|
+
```
|
|
186
|
+
|
|
187
|
+
Keys must match exactly as they appear in the input, and the inferred type keeps them unchanged too. `ignore` only applies to object keys, so `toSnake('userId', { ignore: ['userId'] })` still returns `'user_id'`.
|
|
155
188
|
|
|
156
189
|
### `transform`
|
|
157
190
|
|
|
158
|
-
Only for `toDot` and `toPath
|
|
191
|
+
Only for `toDot` and `toPath`. It sets the case of the whole result, object keys included, to `'lowercase'` or `'uppercase'`:
|
|
159
192
|
|
|
160
193
|
```ts
|
|
161
|
-
toDot('LAST_login_AT');
|
|
162
|
-
toDot('LAST_login_AT', { transform: 'lowercase' });
|
|
194
|
+
toDot('LAST_login_AT'); // 'LAST.login.AT'
|
|
195
|
+
toDot('LAST_login_AT', { transform: 'lowercase' }); // 'last.login.at'
|
|
163
196
|
toPath('LAST_login_AT', { transform: 'uppercase' }); // 'LAST/LOGIN/AT'
|
|
164
197
|
|
|
165
198
|
toDot({ user_ID: 1, LAST_name: 'Doe' }, { transform: 'lowercase' });
|
|
@@ -168,23 +201,23 @@ toDot({ user_ID: 1, LAST_name: 'Doe' }, { transform: 'lowercase' });
|
|
|
168
201
|
toDot('$UserId', { allowSymbols: true, transform: 'lowercase' }); // '$user.id'
|
|
169
202
|
```
|
|
170
203
|
|
|
171
|
-
`toSpace
|
|
204
|
+
For `toSpace`, use `toLower` or `toUpper` instead. Avoid chaining functions like `toUpper(toPath(...))`, because each one splits its input into words again and treats `/` and `.` as separators or symbols.
|
|
172
205
|
|
|
173
206
|
### `separator`
|
|
174
207
|
|
|
175
|
-
Only for `toPath`. It joins
|
|
208
|
+
Only for `toPath`. It joins words with `'/'` (the default) or `'\\'`:
|
|
176
209
|
|
|
177
210
|
```ts
|
|
178
|
-
toPath('users/profilePicture');
|
|
211
|
+
toPath('users/profilePicture'); // 'users/profile/Picture'
|
|
179
212
|
toPath('users/profilePicture', { separator: '\\' }); // 'users\\profile\\Picture'
|
|
180
|
-
toPath('users\\profilePicture', { separator: '/' });
|
|
213
|
+
toPath('users\\profilePicture', { separator: '/' }); // 'users/profile/Picture'
|
|
181
214
|
```
|
|
182
215
|
|
|
183
|
-
In `toPath`, `/`
|
|
216
|
+
In `toPath`, a `/` or `\` in the input also starts a new word, which lets you convert a path from one separator to the other. Every other function treats them as symbols.
|
|
184
217
|
|
|
185
218
|
## Type inference
|
|
186
219
|
|
|
187
|
-
|
|
220
|
+
TypeScript computes the converted keys, so your editor autocompletes them and flags typos:
|
|
188
221
|
|
|
189
222
|
```ts
|
|
190
223
|
const user = toCamel({ first_name: 'John', 'Home Addresses': [{ POSTAL_CODE: '61105' }] });
|
|
@@ -194,21 +227,21 @@ user.firstName; // ✅
|
|
|
194
227
|
user.first_name; // ❌ Property 'first_name' does not exist
|
|
195
228
|
```
|
|
196
229
|
|
|
197
|
-
The
|
|
230
|
+
The inference takes options into account: `toCamel({ $ref: 1 }, ['$'])` is typed `{ $ref: number }`, and `toDot({ UserId: 1 }, { transform: 'lowercase' })` is typed `{ 'user.id': number }`. If the options are only known at runtime, such as a `boolean` variable, the keys are typed as `string`.
|
|
198
231
|
|
|
199
232
|
## How keys are split into words
|
|
200
233
|
|
|
201
|
-
Every function first splits the input into words
|
|
234
|
+
Every function first splits the input into words and then joins them in the target case. A new word starts:
|
|
202
235
|
|
|
203
|
-
-
|
|
204
|
-
-
|
|
205
|
-
-
|
|
206
|
-
-
|
|
207
|
-
-
|
|
236
|
+
- at a separator (`_`, `-`, `.` or a space), which is removed. Repeated or leading separators are ignored, so `toSnake('__private_flag')` returns `'private_flag'`.
|
|
237
|
+
- at an uppercase letter that follows a lowercase letter or a digit: `helloWorld` becomes `hello` and `world`.
|
|
238
|
+
- at the last letter of an acronym: `XMLHttpRequest` becomes `xml`, `http` and `request`, and `userID` becomes `user` and `id`.
|
|
239
|
+
- at a symbol, whether it is kept or not.
|
|
240
|
+
- at `/` or `\`, in `toPath` only.
|
|
208
241
|
|
|
209
|
-
Digits stay
|
|
242
|
+
Digits stay with the word before them: `toSnake('html5Parser')` returns `'html5_parser'`.
|
|
210
243
|
|
|
211
|
-
A kept symbol sticks to the start of the next word, or to the end of the previous one
|
|
244
|
+
A kept symbol sticks to the start of the next word, or to the end of the previous one if no word follows:
|
|
212
245
|
|
|
213
246
|
```ts
|
|
214
247
|
toSnake('$$hello$World$$hi'); // 'hello_world_hi'
|
|
@@ -221,84 +254,162 @@ The inferred types follow the same rules.
|
|
|
221
254
|
|
|
222
255
|
## Behavior and limitations
|
|
223
256
|
|
|
224
|
-
-
|
|
225
|
-
-
|
|
226
|
-
-
|
|
227
|
-
-
|
|
228
|
-
-
|
|
229
|
-
-
|
|
257
|
+
- Only keys are converted. In `{ userName: 'johnDoe' }` the key becomes `user_name` and `'johnDoe'` stays as it is, and so do strings inside arrays.
|
|
258
|
+
- Only plain objects are traversed. `Date`, `Map`, `Set`, class instances and `Object.create(null)` objects come back as they are, with the same reference.
|
|
259
|
+
- Acronyms are kept together but not restored: `toSnake('userID')` returns `'user_id'`, and `toCamel('user_id')` returns `'userId'`.
|
|
260
|
+
- Words are lowercased first, except in `toDot`, `toPath` and `toSpace`, so `toCamel('X-API-Key')` returns `'xApiKey'`.
|
|
261
|
+
- Title Case capitalizes every word, short ones included: `toTitle('termsOfUse')` returns `'Terms Of Use'`.
|
|
262
|
+
- Very deep or circular objects throw `RangeError: Maximum call stack size exceeded`, starting at about 5,000 levels with the default Node.js stack. `JSON.parse` accepts that depth, so if you don't handle the error, limit the depth of untrusted input.
|
|
263
|
+
- Type inference works for keys up to about 120 characters. Longer keys fail to compile with `Type instantiation is excessively deep and possibly infinite`. The runtime has no such limit.
|
|
230
264
|
|
|
231
|
-
|
|
265
|
+
### Design trade-offs
|
|
232
266
|
|
|
233
|
-
|
|
234
|
-
|
|
235
|
-
|
|
236
|
-
|
|
237
|
-
|
|
238
|
-
|
|
239
|
-
|
|
267
|
+
- Nothing is cached between calls. Within a single call each distinct key is converted once, so an array of 100 items costs about as much as one item. Libraries that cache keys across calls (camelcase-keys keeps up to 2 × 100,000) are faster when the same small object is converted again and again, but they hold that memory for the life of the process, and untrusted keys can fill it. See [memory](./bench/results/memory.md).
|
|
268
|
+
- The key cache is only created for arrays, where objects usually share keys. A single object doesn't pay for it, but keys repeated in nested objects outside arrays are converted again.
|
|
269
|
+
- `toCamel` and `toSnake` on their own take 1.5 KB gzipped, against 0.8 KB in 5.1.0, because of the character tables and the key cache that make them faster. The whole package is smaller than before (1.8 KB gzipped, down from 3.1 KB in 5.1.0), since 6.0 removed the deprecated functions.
|
|
270
|
+
- Every function splits words the same way, including acronyms, digits, symbols and non-ASCII letters, even where a simpler rule would be faster for plain `snake_case` to `camelCase`.
|
|
271
|
+
|
|
272
|
+
## Benchmarks
|
|
273
|
+
|
|
274
|
+
Measured on Node.js 24, on an Apple M3 Pro:
|
|
275
|
+
|
|
276
|
+
- With an API response of 100 users (2,104 keys), caseparser is the fastest in every case, 5 to 25× faster than the others: about 57 µs, against 269 µs to 1.39 ms.
|
|
277
|
+
- With 1,000 unique keys, it is the fastest or tied with the fastest in every case.
|
|
278
|
+
- It allocates the least memory per call (121 KB for the API response, while the others use 1.2 to 2.9 MB) and keeps nothing between calls.
|
|
279
|
+
- When a small object (8 keys) is converted over and over, camelcase-keys is faster to camelCase (0.71 µs against 0.96 µs) thanks to its cross-call cache. caseparser is the fastest to snake_case (0.92 µs) and for strings (1.1 µs for 10 strings, against 1.4 µs for es-toolkit).
|
|
240
280
|
|
|
241
|
-
|
|
281
|
+
Each time is the mean of the medians of 3 rounds, with the libraries in a different order each round. Bold marks the fastest library and any library tied with it (overlapping rounds). ❌ means the library can't convert keys to that case.
|
|
242
282
|
|
|
243
|
-
|
|
283
|
+
<details>
|
|
284
|
+
<summary><b>Speed: API response with 100 users (2,104 keys)</b></summary>
|
|
285
|
+
|
|
286
|
+
<br>
|
|
287
|
+
|
|
288
|
+
Every user has the same keys, as in a real API response.
|
|
289
|
+
|
|
290
|
+
| Case | caseparser | caseparser@5.1.0 | change-case | camelcase-keys | snakecase-keys | humps | es-toolkit |
|
|
291
|
+
| --- | ---: | ---: | ---: | ---: | ---: | ---: | ---: |
|
|
292
|
+
| camelCase | **57 µs** | 936 µs | 929 µs | 269 µs | ❌ | 536 µs | 391 µs |
|
|
293
|
+
| PascalCase | **58 µs** | 1.04 ms | 1.01 ms | 361 µs | ❌ | 629 µs | 496 µs |
|
|
294
|
+
| snake_case | **57 µs** | 870 µs | 1.06 ms | ❌ | 1.34 ms | 397 µs | 377 µs |
|
|
295
|
+
| kebab-case | **57 µs** | 884 µs | 1.07 ms | ❌ | 1.38 ms | 399 µs | 382 µs |
|
|
296
|
+
| UPPER_SNAKE | **58 µs** | 923 µs | 1.11 ms | ❌ | ❌ | ❌ | 448 µs |
|
|
297
|
+
| UPPER-KEBAB | **58 µs** | 936 µs | 1.13 ms | ❌ | ❌ | ❌ | ❌ |
|
|
298
|
+
| Train-Case | **58 µs** | 1.07 ms | 1.17 ms | ❌ | ❌ | ❌ | ❌ |
|
|
299
|
+
| Title Case | **58 µs** | 1.08 ms | 1.16 ms | ❌ | ❌ | ❌ | ❌ |
|
|
300
|
+
| Sentence case | **57 µs** | 972 µs | 1.14 ms | ❌ | ❌ | ❌ | ❌ |
|
|
301
|
+
| Pascal_Snake | **58 µs** | 1.07 ms | 1.15 ms | ❌ | ❌ | ❌ | ❌ |
|
|
302
|
+
| lower case | **57 µs** | 902 µs | 1.07 ms | ❌ | 1.39 ms | 402 µs | ❌ |
|
|
303
|
+
| UPPER CASE | **58 µs** | 936 µs | 1.13 ms | ❌ | ❌ | ❌ | ❌ |
|
|
304
|
+
| dot.case | **56 µs** | 879 µs | 1.07 ms | ❌ | 1.38 ms | 402 µs | ❌ |
|
|
305
|
+
| path/case | **57 µs** | 946 µs | 1.07 ms | ❌ | 1.38 ms | 401 µs | ❌ |
|
|
306
|
+
|
|
307
|
+
</details>
|
|
244
308
|
|
|
245
|
-
>
|
|
309
|
+
<details>
|
|
310
|
+
<summary><b>Speed: one object with 1,000 unique keys</b></summary>
|
|
311
|
+
|
|
312
|
+
<br>
|
|
313
|
+
|
|
314
|
+
No key repeats, so this measures the cost of converting each key. The scenario creates a lot of garbage, so results vary by up to ~20% between rounds for every library.
|
|
315
|
+
|
|
316
|
+
| Case | caseparser | caseparser@5.1.0 | change-case | camelcase-keys | snakecase-keys | humps | es-toolkit |
|
|
317
|
+
| --- | ---: | ---: | ---: | ---: | ---: | ---: | ---: |
|
|
318
|
+
| camelCase | **276 µs** | 1.94 ms | 740 µs | 1.09 ms | ❌ | 526 µs | 417 µs |
|
|
319
|
+
| PascalCase | **346 µs** | 1.48 ms | 827 µs | 1.33 ms | ❌ | 596 µs | 502 µs |
|
|
320
|
+
| snake_case | **291 µs** | 1.90 ms | 813 µs | ❌ | 892 µs | **421 µs** | **385 µs** |
|
|
321
|
+
| kebab-case | **413 µs** | 1.34 ms | 906 µs | ❌ | 960 µs | **468 µs** | **422 µs** |
|
|
322
|
+
| UPPER_SNAKE | **392 µs** | 1.98 ms | 911 µs | ❌ | ❌ | ❌ | **453 µs** |
|
|
323
|
+
| UPPER-KEBAB | **482 µs** | 874 µs | 949 µs | ❌ | ❌ | ❌ | ❌ |
|
|
324
|
+
| Train-Case | **381 µs** | 2.08 ms | 936 µs | ❌ | ❌ | ❌ | ❌ |
|
|
325
|
+
| Title Case | **461 µs** | 937 µs | 979 µs | ❌ | ❌ | ❌ | ❌ |
|
|
326
|
+
| Sentence case | **362 µs** | 1.98 ms | 900 µs | ❌ | ❌ | ❌ | ❌ |
|
|
327
|
+
| Pascal_Snake | **444 µs** | 1.45 ms | 961 µs | ❌ | ❌ | ❌ | ❌ |
|
|
328
|
+
| lower case | **343 µs** | 1.67 ms | 877 µs | ❌ | 938 µs | **444 µs** | ❌ |
|
|
329
|
+
| UPPER CASE | **464 µs** | 853 µs | 951 µs | ❌ | ❌ | ❌ | ❌ |
|
|
330
|
+
| dot.case | **367 µs** | 1.94 ms | 871 µs | ❌ | 934 µs | **444 µs** | ❌ |
|
|
331
|
+
| path/case | **449 µs** | 855 µs | 917 µs | ❌ | 974 µs | 521 µs | ❌ |
|
|
246
332
|
|
|
247
|
-
|
|
333
|
+
</details>
|
|
334
|
+
|
|
335
|
+
<details>
|
|
336
|
+
<summary><b>Memory</b></summary>
|
|
248
337
|
|
|
249
|
-
|
|
338
|
+
<br>
|
|
250
339
|
|
|
251
|
-
|
|
340
|
+
Heap used on Node.js, with a fresh process for each library:
|
|
252
341
|
|
|
253
|
-
|
|
|
254
|
-
| --- |
|
|
255
|
-
|
|
|
256
|
-
|
|
|
257
|
-
|
|
|
258
|
-
|
|
|
259
|
-
|
|
|
342
|
+
| Library | Loading the library | One call: API response | One call: 1,000 unique keys | Kept after converting 256,000 keys |
|
|
343
|
+
| --- | ---: | ---: | ---: | ---: |
|
|
344
|
+
| caseparser | 71 KB | **121 KB** | **516 KB** | 0 |
|
|
345
|
+
| caseparser@5.1.0 | 289 KB | 2,348 KB | 2,719 KB | 0 |
|
|
346
|
+
| change-case | 135 KB | 2,850 KB | 1,610 KB | 0 |
|
|
347
|
+
| camelcase-keys | 210 KB | 1,516 KB | 1,742 KB | 11,488 KB |
|
|
348
|
+
| humps | **62 KB** | 1,183 KB | 759 KB | 0 |
|
|
349
|
+
| es-toolkit | 623 KB | 1,745 KB | 1,062 KB | 0 |
|
|
260
350
|
|
|
261
|
-
|
|
351
|
+
"One call" is the memory allocated to convert to camelCase, including the result (62 KB and 48 KB). "Kept" is what is still in use after the calls; 0 means under 10 KB, which is within the noise of the measurement.
|
|
352
|
+
|
|
353
|
+
</details>
|
|
262
354
|
|
|
263
355
|
<details>
|
|
264
|
-
<summary>
|
|
356
|
+
<summary><b>Features compared with the same libraries</b></summary>
|
|
265
357
|
|
|
266
|
-
|
|
358
|
+
<br>
|
|
267
359
|
|
|
268
|
-
|
|
|
269
|
-
| --- |
|
|
270
|
-
|
|
|
271
|
-
|
|
|
272
|
-
| `
|
|
273
|
-
|
|
|
274
|
-
|
|
|
275
|
-
|
|
|
276
|
-
|
|
|
277
|
-
|
|
278
|
-
|
|
279
|
-
|
|
280
|
-
|
|
281
|
-
- **camelCase:** `camelToPascal`, `camelToSnake`, `camelToDash`, `camelToUpperSnake`, `camelToUpperDash`, `camelToTrain`, `camelToDot`, `camelToTitle`, `camelToSentence`
|
|
282
|
-
- **PascalCase:** `pascalToCamel`, `pascalToSnake`, `pascalToDash`, `pascalToUpperSnake`, `pascalToUpperDash`, `pascalToTrain`, `pascalToDot`, `pascalToTitle`, `pascalToSentence`
|
|
283
|
-
- **snake_case:** `snakeToCamel`, `snakeToPascal`, `snakeToDash`, `snakeToUpperSnake`, `snakeToUpperDash`, `snakeToTrain`, `snakeToDot`, `snakeToTitle`, `snakeToSentence`
|
|
284
|
-
- **dash-case:** `dashToCamel`, `dashToPascal`, `dashToSnake`, `dashToUpperSnake`, `dashToUpperDash`, `dashToTrain`, `dashToDot`, `dashToTitle`, `dashToSentence`
|
|
285
|
-
- **UPPER_SNAKE_CASE:** `upperSnakeToCamel`, `upperSnakeToPascal`, `upperSnakeToSnake`, `upperSnakeToDash`, `upperSnakeToUpperDash`, `upperSnakeToTrain`, `upperSnakeToDot`, `upperSnakeToTitle`, `upperSnakeToSentence`
|
|
286
|
-
- **UPPER-DASH-CASE:** `upperDashToCamel`, `upperDashToPascal`, `upperDashToSnake`, `upperDashToDash`, `upperDashToUpperSnake`, `upperDashToTrain`, `upperDashToDot`, `upperDashToTitle`, `upperDashToSentence`
|
|
287
|
-
- **Train-Case:** `trainToCamel`, `trainToPascal`, `trainToSnake`, `trainToDash`, `trainToUpperSnake`, `trainToUpperDash`, `trainToDot`, `trainToTitle`, `trainToSentence`
|
|
288
|
-
- **dot.case:** `dotToCamel`, `dotToPascal`, `dotToSnake`, `dotToDash`, `dotToUpperSnake`, `dotToUpperDash`, `dotToTrain`, `dotToTitle`, `dotToSentence`
|
|
289
|
-
- **Title Case:** `titleToCamel`, `titleToPascal`, `titleToSnake`, `titleToDash`, `titleToUpperSnake`, `titleToUpperDash`, `titleToTrain`, `titleToDot`, `titleToSentence`
|
|
290
|
-
- **Sentence case:** `sentenceToCamel`, `sentenceToPascal`, `sentenceToSnake`, `sentenceToDash`, `sentenceToUpperSnake`, `sentenceToUpperDash`, `sentenceToTrain`, `sentenceToDot`, `sentenceToTitle`
|
|
360
|
+
| | caseparser | change-case | camelcase-keys | snakecase-keys | humps | es-toolkit |
|
|
361
|
+
| --- | :---: | :---: | :---: | :---: | :---: | :---: |
|
|
362
|
+
| Cases for object keys | 14 | 14 | 2 | 5 | 7 | 5 |
|
|
363
|
+
| Mixed cases in one object | ✅ | ✅ | ✅ | ✅ | ❌ | ✅ |
|
|
364
|
+
| `Date` and `Map` values still work | ✅ | ❌ | ✅ | ❌ | ❌ | ✅ |
|
|
365
|
+
| Class instances kept as they are | ✅ | ❌ | ❌ | ❌ | ❌ | ✅ |
|
|
366
|
+
| Types the converted keys | ✅ | ❌ | ✅ | ✅ | ❌ | ⚠️ |
|
|
367
|
+
| Can skip keys | ✅ | ❌ | ✅ | ✅ | ✅ | ❌ |
|
|
368
|
+
| Dependencies | 0 | 0 | 5 | 3 | 0 | 0 |
|
|
369
|
+
|
|
370
|
+
change-case types the result as `unknown` and humps as `object`, and es-toolkit types some keys differently from what it returns. snakecase-keys and humps break `Map` values, and change-case breaks `Date` and `Map`. camelcase-keys, snakecase-keys and humps turn class instances into plain objects. With `__proto__` in untrusted JSON, `humps.decamelizeKeys` replaces the result's prototype, and snakecase-keys throws on a `constructor` key. The others, caseparser included, convert both.
|
|
371
|
+
|
|
372
|
+
Edge cases also differ: `userID` can become `user_id` or `user_i_d`, and `html5Parser` can become `html5_parser` or `html_5_parser`. See [what each library returns](./bench/results/edge-cases.md).
|
|
291
373
|
|
|
292
374
|
</details>
|
|
293
375
|
|
|
376
|
+
Before anything is timed, each library's output is checked against the expected result. Each library is called from [its own file](./bench/libraries) with its documented options. The method, the raw numbers of every round, the date and the versions are in [`bench/`](./bench). To run the benchmarks yourself:
|
|
377
|
+
|
|
378
|
+
```sh
|
|
379
|
+
pnpm install
|
|
380
|
+
pnpm benchmark
|
|
381
|
+
```
|
|
382
|
+
|
|
383
|
+
## Compatibility
|
|
384
|
+
|
|
385
|
+
| Environment | Supported |
|
|
386
|
+
| --- | --- |
|
|
387
|
+
| ESM (`import`) | Node.js 22+, Deno, Bun, bundlers |
|
|
388
|
+
| CommonJS (`require`) | Node.js 22+, Bun |
|
|
389
|
+
| TypeScript | 4.7+ (any `moduleResolution`: `node`, `node16`/`nodenext`, `bundler`) |
|
|
390
|
+
| Browsers | Any ES2015 browser (via bundler) |
|
|
391
|
+
| Edge | Cloudflare Workers ([example](./examples/cloudflare-worker)) |
|
|
392
|
+
|
|
393
|
+
CI runs the tests on Node.js 22, 24 and 26, Bun, Deno, Chromium, Firefox and WebKit, and runs [a Cloudflare Worker](./examples/cloudflare-worker) on workerd against the packed package. It also checks the package with [publint](https://publint.dev) and [Are the Types Wrong?](https://arethetypeswrong.github.io) for ESM, CommonJS and every `moduleResolution`, and compiles the type declarations with TypeScript 4.7.
|
|
394
|
+
|
|
294
395
|
## Security
|
|
295
396
|
|
|
296
|
-
caseparser is safe to use
|
|
397
|
+
caseparser is safe to use on untrusted input, such as request bodies or `JSON.parse` output:
|
|
398
|
+
|
|
399
|
+
- `__proto__` is copied as a regular key and never changes an object's prototype.
|
|
400
|
+
- An object with a `constructor` key is converted like any other.
|
|
401
|
+
- Only own properties are converted, and nothing is kept between calls.
|
|
402
|
+
|
|
403
|
+
If you don't handle the `RangeError` thrown on very deep objects, limit the depth of untrusted input (see [limitations](#behavior-and-limitations)).
|
|
297
404
|
|
|
298
|
-
Releases are built and published from GitHub Actions
|
|
405
|
+
Releases are built and published from GitHub Actions with OIDC instead of long-lived tokens, and with [npm provenance](https://docs.npmjs.com/generating-provenance-statements), so you can trace every version back to the commit and workflow that built it. New npm versions are [staged](https://docs.npmjs.com/staged-publishing/) and only go live after a maintainer approves them with 2FA.
|
|
299
406
|
|
|
300
|
-
|
|
407
|
+
To report a vulnerability, follow [SECURITY.md](./SECURITY.md) and report it privately.
|
|
301
408
|
|
|
302
409
|
## License
|
|
303
410
|
|
|
304
|
-
|
|
411
|
+
<p align="center">
|
|
412
|
+
<img src="https://raw.githubusercontent.com/NandoMB/caseparser/main/.github/assets/mark.svg" alt="" width="40"><br>
|
|
413
|
+
<a href="./LICENSE">MIT</a> © 2017 <a href="https://github.com/NandoMB">Fernando Machado Bernardino</a><br>
|
|
414
|
+
<sub>If caseparser saves you time, a ⭐ on <a href="https://github.com/NandoMB/caseparser">GitHub</a> helps others find it.</sub>
|
|
415
|
+
</p>
|