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 CHANGED
@@ -1,56 +1,79 @@
1
- # [CaseParser](https://github.com/NandoMB/caseparser)
1
+ <div align="center">
2
2
 
3
- [![npm version](https://img.shields.io/npm/v/caseparser.svg)](https://www.npmjs.com/package/caseparser)
4
- [![JSR](https://jsr.io/badges/@nandomb/caseparser)](https://jsr.io/@nandomb/caseparser)
5
- [![JSR Score](https://jsr.io/badges/@nandomb/caseparser/score)](https://jsr.io/@nandomb/caseparser)
6
- [![CI](https://github.com/NandoMB/caseparser/actions/workflows/main.yml/badge.svg)](https://github.com/NandoMB/caseparser/actions/workflows/main.yml)
7
- [![npm downloads](https://img.shields.io/npm/dm/caseparser.svg)](https://www.npmjs.com/package/caseparser)
8
- [![license](https://img.shields.io/npm/l/caseparser.svg)](./LICENSE)
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
- ###### Note:
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
- ## Contents
21
-
22
- - [Installation](#installation)
23
- - [Quick start](#quick-start)
24
- - [Cases](#cases)
25
- - [Options](#options): [`allowSymbols`](#allowsymbols), [`transform`](#transform), [`separator`](#separator)
26
- - [Type inference](#type-inference)
27
- - [How keys are split into words](#how-keys-are-split-into-words)
28
- - [Behavior and limitations](#behavior-and-limitations)
29
- - [Compatibility](#compatibility)
30
- - [Deprecated `<from>To<To>` functions](#deprecated-fromtoto-functions)
31
- - [Security](#security)
12
+ [![npm version](https://img.shields.io/npm/v/caseparser?style=flat-square&color=5B5BF6&label=npm)](https://www.npmjs.com/package/caseparser)
13
+ [![JSR](https://jsr.io/badges/@nandomb/caseparser)](https://jsr.io/@nandomb/caseparser)
14
+ [![JSR Score](https://jsr.io/badges/@nandomb/caseparser/score)](https://jsr.io/@nandomb/caseparser)
15
+ [![CI](https://img.shields.io/github/actions/workflow/status/NandoMB/caseparser/main.yml?branch=main&style=flat-square&label=CI)](https://github.com/NandoMB/caseparser/actions/workflows/main.yml)
16
+ [![bundle size](https://img.shields.io/bundlejs/size/caseparser?style=flat-square&color=5B5BF6)](https://bundlejs.com/?q=caseparser)
17
+ [![npm downloads](https://img.shields.io/npm/dm/caseparser?style=flat-square&color=5B5BF6)](https://www.npmjs.com/package/caseparser)
18
+ [![types](https://img.shields.io/badge/types-TypeScript-3178C6?style=flat-square&logo=typescript&logoColor=white)](#type-inference)
19
+ [![license](https://img.shields.io/npm/l/caseparser?style=flat-square&color=5B5BF6)](./LICENSE)
20
+ [![Socket Badge](https://badge.socket.dev/npm/package/caseparser)](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
- ###### Deno (JSR)
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
- The input doesn't need a specific or consistent shape. Every key below is in a different case, and one call converts all of them, deeply:
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: a new object is returned. A typical use is converting API payloads on the way in and out:
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 accepts input in any case:
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: they keep the original case of each word (upper, lower or mixed). To change it, see [`transform`](#transform).
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
- Symbols (ASCII punctuation such as `$`, `@`, `#` or `%`) are removed by default. `allowSymbols: true` keeps all of them, and an array keeps only the listed ones. It can be passed inside the options object, or directly as the second argument:
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, true); // same as { allowSymbols: true }
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: `toPascal('$id', true)` → `'$Id'`. See [How keys are split into words](#how-keys-are-split-into-words) for the details.
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`, which keep the original case of each word by default. `'lowercase'` or `'uppercase'` changes the case of the whole result, object keys included:
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'); // 'LAST.login.AT'
162
- toDot('LAST_login_AT', { transform: 'lowercase' }); // 'last.login.at'
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` has no `transform`: use `toLower` or `toUpper` instead. Don't chain functions for this (`toUpper(toPath(...))`): each one splits its input into words again, so `/` and `.` would be treated as separators or symbols.
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 the words with `'/'` by default, or with `'\\'`:
208
+ Only for `toPath`. It joins words with `'/'` (the default) or `'\\'`:
176
209
 
177
210
  ```ts
178
- toPath('users/profilePicture'); // 'users/profile/Picture'
211
+ toPath('users/profilePicture'); // 'users/profile/Picture'
179
212
  toPath('users/profilePicture', { separator: '\\' }); // 'users\\profile\\Picture'
180
- toPath('users\\profilePicture', { separator: '/' }); // 'users/profile/Picture'
213
+ toPath('users\\profilePicture', { separator: '/' }); // 'users/profile/Picture'
181
214
  ```
182
215
 
183
- In `toPath`, `/` and `\` in the input also separate words, so paths can be converted from one separator to the other. In the other functions they are symbols.
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
- The converted keys are inferred at the type level, so your editor autocompletes them and catches typos:
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 options are part of the inference: `toCamel({ $ref: 1 }, ['$'])` is typed `{ $ref: number }`, and `toDot({ UserId: 1 }, { transform: 'lowercase' })` is typed `{ 'user.id': number }`. When the options are only known at runtime (e.g. a `boolean` variable), the keys are typed as `string`.
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, then joins them in the target case. A new word starts:
234
+ Every function first splits the input into words and then joins them in the target case. A new word starts:
202
235
 
203
- - **at a separator:** `_`, `-`, `.` or a space, which are removed. Repeated or leading separators are ignored: `toSnake('__private_flag')` → `'private_flag'`
204
- - **at an uppercase letter after a lowercase letter or a digit:** `helloWorld` → `hello`, `world`
205
- - **at the last letter of an acronym:** `XMLHttpRequest` → `xml`, `http`, `request`, and `userID` → `user`, `id`
206
- - **at a symbol**, whether it's kept or not
207
- - **at `/` or `\`, only in `toPath`** (in the other functions they are symbols)
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 attached to the previous word: `toSnake('html5Parser')` → `'html5_parser'`.
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 when no word follows:
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
- - **Only keys are converted, never values.** In `{ userName: 'johnDoe' }`, `userName` becomes `user_name` but `'johnDoe'` is kept. Strings inside arrays are kept too.
225
- - **Only plain objects are traversed.** `Date`, `Map`, `Set` and class instances are returned as they are (same reference), without converting their contents.
226
- - **Acronyms are kept together, but not restored:** `toSnake('userID')` → `'user_id'`, and back `toCamel('user_id')` → `'userId'`.
227
- - **Words are lowercased** before converting (except by `toDot`, `toPath` and `toSpace`), so `toCamel('X-API-Key')` → `'xApiKey'` and `toCamel('First Name')` → `'firstName'`.
228
- - **Title Case capitalizes every word**, including short ones: `toTitle('termsOfUse')` → `'Terms Of Use'`.
229
- - **Type inference has a key length limit.** TypeScript limits how deeply a type can recurse, and keys are converted character by character at the type level. Keys are inferred up to ~120 characters; longer keys fail to compile with `Type instantiation is excessively deep and possibly infinite`. The runtime conversion has no limit.
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
- ## Compatibility
265
+ ### Design trade-offs
232
266
 
233
- | Environment | Supported |
234
- | --- | --- |
235
- | ESM (`import`) | Node.js 12.22+, Deno, Bun, bundlers |
236
- | CommonJS (`require`) | Node.js 8+, Bun |
237
- | TypeScript | 4.5+ for the `toX` functions, 4.1+ for the deprecated `<from>To<To>` functions (any `moduleResolution`: `node`, `node16`/`nodenext`, `bundler`) |
238
- | Browsers | Any ES2015 browser (via bundler) |
239
- | Edge | Cloudflare Workers |
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
- On every change, CI runs the test suite on Node.js 22, 24 and 26, Bun and Deno, and in Chromium, Firefox and WebKit. It also checks the packed 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.1.
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
- ## Deprecated `<from>To<To>` functions
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
- > **Deprecated:** the `<from>To<To>` functions (e.g. `snakeToCamel`) are deprecated in favor of the `toX` functions and will be removed in the next major version, which will also require TypeScript 4.7+. They keep working until then.
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
- ### Migrating to `toX`
333
+ </details>
334
+
335
+ <details>
336
+ <summary><b>Memory</b></summary>
248
337
 
249
- Replace each `<from>To<To>` function with the `toX` function for its target case, whatever the source case: `camelToSnake`, `dashToSnake`, `titleToSnake`... all become `toSnake`. The dash cases were renamed: `<from>ToDash` becomes `toKebab`, and `<from>ToUpperDash` becomes `toUpperKebab`.
338
+ <br>
250
339
 
251
- For well-formed keys (`firstName`, `first_name`) the result is the same. It differs when a key has consecutive uppercase letters or doesn't match the source case, and `toDot` keeps the original case of each word (pass `{ transform: 'lowercase' }` to get the old result):
340
+ Heap used on Node.js, with a fresh process for each library:
252
341
 
253
- | Call | `<from>To<To>` result | `toX` result |
254
- | --- | --- | --- |
255
- | `camelToSnake('userID')` / `toSnake('userID')` | `'user_i_d'` | `'user_id'` |
256
- | `camelToSnake('XMLHttpRequest')` / `toSnake('XMLHttpRequest')` | `'_x_m_l_http_request'` | `'xml_http_request'` |
257
- | `camelToSnake('HelloWorld')` / `toSnake('HelloWorld')` | `'_hello_world'` | `'hello_world'` |
258
- | `snakeToCamel('user_ID')` / `toCamel('user_ID')` | `'userID'` | `'userId'` |
259
- | `camelToDot('helloWorld')` / `toDot('helloWorld')` | `'hello.world'` | `'hello.World'` |
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
- If your code reads keys like `user_i_d` produced by the old functions, update those reads when migrating. The inferred types follow the new results, so TypeScript points out every place to change.
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>All 90 deprecated functions</summary>
356
+ <summary><b>Features compared with the same libraries</b></summary>
265
357
 
266
- Every function is named `<from>To<To>`, e.g. `snakeToCamel`. The case names are:
358
+ <br>
267
359
 
268
- | Name | Example |
269
- | --- | --- |
270
- | `camel` | `helloWorld` |
271
- | `pascal` | `HelloWorld` |
272
- | `snake` | `hello_world` |
273
- | `dash` | `hello-world` |
274
- | `upperSnake` | `HELLO_WORLD` |
275
- | `upperDash` | `HELLO-WORLD` |
276
- | `train` | `Hello-World` |
277
- | `dot` | `hello.world` |
278
- | `title` | `Hello World` |
279
- | `sentence` | `Hello world` |
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 with untrusted input (e.g. request bodies or `JSON.parse` output): keys such as `__proto__` are copied as regular keys and never change an object's prototype, and only the object's own properties are converted.
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 without long-lived tokens (OIDC), with [npm provenance](https://docs.npmjs.com/generating-provenance-statements), so every published version can be traced back to the exact commit and workflow that built it. On npm, new versions are [staged](https://docs.npmjs.com/staged-publishing/) and only go live after a maintainer approves them with 2FA.
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
- Found a vulnerability? Please report it privately, see [SECURITY.md](./SECURITY.md).
407
+ To report a vulnerability, follow [SECURITY.md](./SECURITY.md) and report it privately.
301
408
 
302
409
  ## License
303
410
 
304
- [MIT](./LICENSE) © 2017 Fernando Machado Bernardino
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>