caseparser 6.0.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 +191 -129
- package/dist/index.cjs +6 -12
- package/dist/index.d.cts +0 -4
- package/dist/index.d.ts +0 -4
- package/dist/index.js +6 -12
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -1,57 +1,79 @@
|
|
|
1
|
-
|
|
1
|
+
<div align="center">
|
|
2
2
|
|
|
3
|
-
|
|
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>
|
|
9
|
+
|
|
10
|
+
<h3>Convert strings and object keys to any case, from any case, with the result typed by TypeScript.</h3>
|
|
11
|
+
|
|
12
|
+
[](https://www.npmjs.com/package/caseparser)
|
|
4
13
|
[](https://jsr.io/@nandomb/caseparser)
|
|
5
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)
|
|
6
20
|
[](https://socket.dev/npm/package/caseparser)
|
|
7
|
-
[](https://github.com/NandoMB/caseparser/actions/workflows/main.yml)
|
|
8
|
-
[](https://www.npmjs.com/package/caseparser)
|
|
9
|
-
[](./LICENSE)
|
|
10
21
|
|
|
11
|
-
|
|
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>
|
|
12
40
|
|
|
13
|
-
|
|
14
|
-
- **Deep:** nested objects and objects inside arrays are converted too
|
|
15
|
-
- **Typed:** your editor autocompletes the converted keys
|
|
16
|
-
- Zero dependencies, tree-shakeable, ESM and CommonJS, on [npm](https://www.npmjs.com/package/caseparser) and [JSR](https://jsr.io/@nandomb/caseparser)
|
|
41
|
+
<br>
|
|
17
42
|
|
|
18
|
-
|
|
19
|
-
>
|
|
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>
|
|
20
51
|
|
|
21
|
-
|
|
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.
|
|
22
53
|
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
- [Cases](#cases)
|
|
26
|
-
- [Options](#options): [`allowSymbols`](#allowsymbols), [`ignore`](#ignore), [`transform`](#transform), [`separator`](#separator)
|
|
27
|
-
- [Type inference](#type-inference)
|
|
28
|
-
- [How keys are split into words](#how-keys-are-split-into-words)
|
|
29
|
-
- [Behavior and limitations](#behavior-and-limitations)
|
|
30
|
-
- [Benchmarks](#benchmarks)
|
|
31
|
-
- [Compatibility](#compatibility)
|
|
32
|
-
- [Security](#security)
|
|
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).
|
|
33
56
|
|
|
34
57
|
## Installation
|
|
35
58
|
|
|
36
59
|
```sh
|
|
37
60
|
npm add caseparser # or: pnpm add caseparser / yarn add caseparser
|
|
38
61
|
```
|
|
39
|
-
|
|
62
|
+
|
|
63
|
+
From JSR:
|
|
64
|
+
|
|
40
65
|
```sh
|
|
41
66
|
deno add jsr:@nandomb/caseparser
|
|
67
|
+
npx jsr add @nandomb/caseparser # or: bunx jsr add @nandomb/caseparser
|
|
42
68
|
```
|
|
69
|
+
|
|
43
70
|
```ts
|
|
44
71
|
import { toSnake } from '@nandomb/caseparser';
|
|
45
72
|
```
|
|
46
|
-
###### Bun / Node.js from JSR
|
|
47
|
-
```sh
|
|
48
|
-
bunx jsr add @nandomb/caseparser
|
|
49
|
-
npx jsr add @nandomb/caseparser
|
|
50
|
-
```
|
|
51
73
|
|
|
52
74
|
## Quick start
|
|
53
75
|
|
|
54
|
-
|
|
76
|
+
Pass in an object and every key comes back in the new case, at any depth, whatever case it started in:
|
|
55
77
|
|
|
56
78
|
```ts
|
|
57
79
|
import { toCamel } from 'caseparser'; // ESM
|
|
@@ -94,7 +116,7 @@ toCamel(response);
|
|
|
94
116
|
|
|
95
117
|
Strings work the same way: `toSnake('helloWorld')`, `toSnake('Hello World')` and `toSnake('HELLO-WORLD')` all return `'hello_world'`.
|
|
96
118
|
|
|
97
|
-
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:
|
|
98
120
|
|
|
99
121
|
```ts
|
|
100
122
|
import { toCamel, toSnake } from 'caseparser';
|
|
@@ -110,7 +132,7 @@ await fetch('/api/users/1', {
|
|
|
110
132
|
|
|
111
133
|
## Cases
|
|
112
134
|
|
|
113
|
-
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.
|
|
114
136
|
|
|
115
137
|
| Function | `'helloWorld'` → | `'LAST_login_AT'` → | Also known as |
|
|
116
138
|
| --- | --- | --- | --- |
|
|
@@ -130,7 +152,7 @@ There is one function per target case, and each one accepts input in any case:
|
|
|
130
152
|
| `toPath` | `hello/World` | `LAST/login/AT` | |
|
|
131
153
|
| `toSpace` | `hello World` | `LAST login AT` | |
|
|
132
154
|
|
|
133
|
-
`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).
|
|
134
156
|
|
|
135
157
|
## Options
|
|
136
158
|
|
|
@@ -138,7 +160,7 @@ Every function takes an optional second argument.
|
|
|
138
160
|
|
|
139
161
|
### `allowSymbols`
|
|
140
162
|
|
|
141
|
-
|
|
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:
|
|
142
164
|
|
|
143
165
|
```ts
|
|
144
166
|
const data = { $ref: 1, '@type': 'User', 'discount%': 10 };
|
|
@@ -147,31 +169,30 @@ toCamel(data); // { ref: 1, type: 'User', discount: 10
|
|
|
147
169
|
toCamel(data, { allowSymbols: true }); // { $ref: 1, '@type': 'User', 'discount%': 10 }
|
|
148
170
|
toCamel(data, { allowSymbols: ['$'] }); // { $ref: 1, type: 'User', discount: 10 }
|
|
149
171
|
|
|
150
|
-
// shorthand
|
|
151
|
-
toCamel(data,
|
|
152
|
-
toCamel(data, ['$']); // same as { allowSymbols: ['$'] }
|
|
172
|
+
toCamel(data, true); // shorthand for { allowSymbols: true }
|
|
173
|
+
toCamel(data, ['$']); // shorthand for { allowSymbols: ['$'] }
|
|
153
174
|
```
|
|
154
175
|
|
|
155
|
-
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).
|
|
156
177
|
|
|
157
178
|
### `ignore`
|
|
158
179
|
|
|
159
|
-
|
|
180
|
+
A list of object keys to leave alone, at any depth. Their values still get converted:
|
|
160
181
|
|
|
161
182
|
```ts
|
|
162
183
|
toCamel({ _id: 1, user_id: 2, extra_data: { inner_key: 3 } }, { ignore: ['_id', 'extra_data'] });
|
|
163
184
|
// { _id: 1, userId: 2, extra_data: { innerKey: 3 } }
|
|
164
185
|
```
|
|
165
186
|
|
|
166
|
-
Keys
|
|
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'`.
|
|
167
188
|
|
|
168
189
|
### `transform`
|
|
169
190
|
|
|
170
|
-
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'`:
|
|
171
192
|
|
|
172
193
|
```ts
|
|
173
|
-
toDot('LAST_login_AT');
|
|
174
|
-
toDot('LAST_login_AT', { transform: 'lowercase' });
|
|
194
|
+
toDot('LAST_login_AT'); // 'LAST.login.AT'
|
|
195
|
+
toDot('LAST_login_AT', { transform: 'lowercase' }); // 'last.login.at'
|
|
175
196
|
toPath('LAST_login_AT', { transform: 'uppercase' }); // 'LAST/LOGIN/AT'
|
|
176
197
|
|
|
177
198
|
toDot({ user_ID: 1, LAST_name: 'Doe' }, { transform: 'lowercase' });
|
|
@@ -180,23 +201,23 @@ toDot({ user_ID: 1, LAST_name: 'Doe' }, { transform: 'lowercase' });
|
|
|
180
201
|
toDot('$UserId', { allowSymbols: true, transform: 'lowercase' }); // '$user.id'
|
|
181
202
|
```
|
|
182
203
|
|
|
183
|
-
`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.
|
|
184
205
|
|
|
185
206
|
### `separator`
|
|
186
207
|
|
|
187
|
-
Only for `toPath`. It joins
|
|
208
|
+
Only for `toPath`. It joins words with `'/'` (the default) or `'\\'`:
|
|
188
209
|
|
|
189
210
|
```ts
|
|
190
|
-
toPath('users/profilePicture');
|
|
211
|
+
toPath('users/profilePicture'); // 'users/profile/Picture'
|
|
191
212
|
toPath('users/profilePicture', { separator: '\\' }); // 'users\\profile\\Picture'
|
|
192
|
-
toPath('users\\profilePicture', { separator: '/' });
|
|
213
|
+
toPath('users\\profilePicture', { separator: '/' }); // 'users/profile/Picture'
|
|
193
214
|
```
|
|
194
215
|
|
|
195
|
-
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.
|
|
196
217
|
|
|
197
218
|
## Type inference
|
|
198
219
|
|
|
199
|
-
|
|
220
|
+
TypeScript computes the converted keys, so your editor autocompletes them and flags typos:
|
|
200
221
|
|
|
201
222
|
```ts
|
|
202
223
|
const user = toCamel({ first_name: 'John', 'Home Addresses': [{ POSTAL_CODE: '61105' }] });
|
|
@@ -206,21 +227,21 @@ user.firstName; // ✅
|
|
|
206
227
|
user.first_name; // ❌ Property 'first_name' does not exist
|
|
207
228
|
```
|
|
208
229
|
|
|
209
|
-
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`.
|
|
210
231
|
|
|
211
232
|
## How keys are split into words
|
|
212
233
|
|
|
213
|
-
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:
|
|
214
235
|
|
|
215
|
-
-
|
|
216
|
-
-
|
|
217
|
-
-
|
|
218
|
-
-
|
|
219
|
-
-
|
|
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.
|
|
220
241
|
|
|
221
|
-
Digits stay
|
|
242
|
+
Digits stay with the word before them: `toSnake('html5Parser')` returns `'html5_parser'`.
|
|
222
243
|
|
|
223
|
-
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:
|
|
224
245
|
|
|
225
246
|
```ts
|
|
226
247
|
toSnake('$$hello$World$$hi'); // 'hello_world_hi'
|
|
@@ -233,95 +254,126 @@ The inferred types follow the same rules.
|
|
|
233
254
|
|
|
234
255
|
## Behavior and limitations
|
|
235
256
|
|
|
236
|
-
-
|
|
237
|
-
-
|
|
238
|
-
-
|
|
239
|
-
-
|
|
240
|
-
-
|
|
241
|
-
-
|
|
242
|
-
-
|
|
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.
|
|
243
264
|
|
|
244
265
|
### Design trade-offs
|
|
245
266
|
|
|
246
|
-
-
|
|
247
|
-
-
|
|
248
|
-
-
|
|
249
|
-
-
|
|
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`.
|
|
250
271
|
|
|
251
272
|
## Benchmarks
|
|
252
273
|
|
|
253
|
-
|
|
274
|
+
Measured on Node.js 24, on an Apple M3 Pro:
|
|
254
275
|
|
|
255
|
-
|
|
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).
|
|
256
280
|
|
|
257
|
-
|
|
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.
|
|
282
|
+
|
|
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.
|
|
258
289
|
|
|
259
290
|
| Case | caseparser | caseparser@5.1.0 | change-case | camelcase-keys | snakecase-keys | humps | es-toolkit |
|
|
260
291
|
| --- | ---: | ---: | ---: | ---: | ---: | ---: | ---: |
|
|
261
|
-
| camelCase | **
|
|
262
|
-
| PascalCase | **
|
|
263
|
-
| snake_case | **57 µs** |
|
|
264
|
-
| kebab-case | **
|
|
265
|
-
| UPPER_SNAKE | **58 µs** |
|
|
266
|
-
| UPPER-KEBAB | **58 µs** |
|
|
267
|
-
| Train-Case | **58 µs** | 1.
|
|
268
|
-
| Title Case | **58 µs** | 1.
|
|
269
|
-
| Sentence case | **
|
|
270
|
-
| Pascal_Snake | **58 µs** | 1.
|
|
271
|
-
| lower case | **57 µs** |
|
|
272
|
-
| UPPER CASE | **58 µs** |
|
|
273
|
-
| dot.case | **
|
|
274
|
-
| path/case | **57 µs** |
|
|
275
|
-
|
|
276
|
-
|
|
277
|
-
|
|
278
|
-
|
|
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>
|
|
308
|
+
|
|
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.
|
|
279
315
|
|
|
280
316
|
| Case | caseparser | caseparser@5.1.0 | change-case | camelcase-keys | snakecase-keys | humps | es-toolkit |
|
|
281
317
|
| --- | ---: | ---: | ---: | ---: | ---: | ---: | ---: |
|
|
282
|
-
| camelCase | **
|
|
283
|
-
| PascalCase | **
|
|
284
|
-
| snake_case | **
|
|
285
|
-
| kebab-case | **
|
|
286
|
-
| UPPER_SNAKE | **
|
|
287
|
-
| UPPER-KEBAB | **
|
|
288
|
-
| Train-Case | **
|
|
289
|
-
| Title Case | **
|
|
290
|
-
| Sentence case | **
|
|
291
|
-
| Pascal_Snake | **
|
|
292
|
-
| lower case | **
|
|
293
|
-
| UPPER CASE | **
|
|
294
|
-
| dot.case | **
|
|
295
|
-
| path/case | **
|
|
296
|
-
|
|
297
|
-
|
|
298
|
-
|
|
299
|
-
|
|
300
|
-
|
|
301
|
-
|
|
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 | ❌ |
|
|
332
|
+
|
|
333
|
+
</details>
|
|
334
|
+
|
|
335
|
+
<details>
|
|
336
|
+
<summary><b>Memory</b></summary>
|
|
337
|
+
|
|
338
|
+
<br>
|
|
339
|
+
|
|
340
|
+
Heap used on Node.js, with a fresh process for each library:
|
|
302
341
|
|
|
303
342
|
| Library | Loading the library | One call: API response | One call: 1,000 unique keys | Kept after converting 256,000 keys |
|
|
304
343
|
| --- | ---: | ---: | ---: | ---: |
|
|
305
|
-
| caseparser |
|
|
344
|
+
| caseparser | 71 KB | **121 KB** | **516 KB** | 0 |
|
|
306
345
|
| caseparser@5.1.0 | 289 KB | 2,348 KB | 2,719 KB | 0 |
|
|
307
|
-
| change-case |
|
|
308
|
-
| camelcase-keys |
|
|
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 |
|
|
309
348
|
| humps | **62 KB** | 1,183 KB | 759 KB | 0 |
|
|
310
|
-
| es-toolkit |
|
|
349
|
+
| es-toolkit | 623 KB | 1,745 KB | 1,062 KB | 0 |
|
|
350
|
+
|
|
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>
|
|
311
354
|
|
|
312
|
-
|
|
355
|
+
<details>
|
|
356
|
+
<summary><b>Features compared with the same libraries</b></summary>
|
|
313
357
|
|
|
314
|
-
|
|
358
|
+
<br>
|
|
315
359
|
|
|
316
|
-
|
|
317
|
-
|
|
318
|
-
|
|
319
|
-
|
|
320
|
-
|
|
321
|
-
|
|
322
|
-
|
|
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 |
|
|
323
369
|
|
|
324
|
-
|
|
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).
|
|
373
|
+
|
|
374
|
+
</details>
|
|
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:
|
|
325
377
|
|
|
326
378
|
```sh
|
|
327
379
|
pnpm install
|
|
@@ -338,16 +390,26 @@ pnpm benchmark
|
|
|
338
390
|
| Browsers | Any ES2015 browser (via bundler) |
|
|
339
391
|
| Edge | Cloudflare Workers ([example](./examples/cloudflare-worker)) |
|
|
340
392
|
|
|
341
|
-
|
|
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.
|
|
342
394
|
|
|
343
395
|
## Security
|
|
344
396
|
|
|
345
|
-
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)).
|
|
346
404
|
|
|
347
|
-
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.
|
|
348
406
|
|
|
349
|
-
|
|
407
|
+
To report a vulnerability, follow [SECURITY.md](./SECURITY.md) and report it privately.
|
|
350
408
|
|
|
351
409
|
## License
|
|
352
410
|
|
|
353
|
-
|
|
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>
|
package/dist/index.cjs
CHANGED
|
@@ -1,5 +1,5 @@
|
|
|
1
1
|
Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
|
|
2
|
-
|
|
2
|
+
// src/utils.ts
|
|
3
3
|
function isString(input) {
|
|
4
4
|
return typeof input === "string";
|
|
5
5
|
}
|
|
@@ -11,8 +11,7 @@ function isObject(input) {
|
|
|
11
11
|
function isArray(input) {
|
|
12
12
|
return Array.isArray(input);
|
|
13
13
|
}
|
|
14
|
-
|
|
15
|
-
//#region src/parser/objectParser.ts
|
|
14
|
+
// src/parser/objectParser.ts
|
|
16
15
|
function objectParser(input, context) {
|
|
17
16
|
const result = {};
|
|
18
17
|
const keys = Object.keys(input);
|
|
@@ -39,8 +38,7 @@ function objectParser(input, context) {
|
|
|
39
38
|
}
|
|
40
39
|
return result;
|
|
41
40
|
}
|
|
42
|
-
|
|
43
|
-
//#region src/parser/arrayParser.ts
|
|
41
|
+
// src/parser/arrayParser.ts
|
|
44
42
|
function arrayParser(input, context) {
|
|
45
43
|
if (!context.cache) context.cache = /* @__PURE__ */ new Map();
|
|
46
44
|
const length = input.length;
|
|
@@ -54,8 +52,7 @@ function arrayParser(input, context) {
|
|
|
54
52
|
}
|
|
55
53
|
return result;
|
|
56
54
|
}
|
|
57
|
-
|
|
58
|
-
//#region src/parser/parser.ts
|
|
55
|
+
// src/parser/parser.ts
|
|
59
56
|
/** Converts a string, or the keys of an object/array (deeply), with `convertKey`. Keys in `ignore` are kept as they are. */
|
|
60
57
|
function convert(input, convertKey, ignore) {
|
|
61
58
|
if (isString(input)) return convertKey(input);
|
|
@@ -68,8 +65,7 @@ function convert(input, convertKey, ignore) {
|
|
|
68
65
|
}
|
|
69
66
|
return array ? arrayParser(input, context) : objectParser(input, context);
|
|
70
67
|
}
|
|
71
|
-
|
|
72
|
-
//#region src/anyCase/words.ts
|
|
68
|
+
// src/anyCase/words.ts
|
|
73
69
|
const SYMBOLS = "!\"#$%&'()*+,/:;<=>?@[\\]^`{|}~";
|
|
74
70
|
const OTHER = 0;
|
|
75
71
|
const SEPARATOR = 1;
|
|
@@ -216,8 +212,7 @@ const ToPath = (str, keep, transform, separator = "/") => applyTransform(join(wo
|
|
|
216
212
|
const ToSpace = (str, keep) => join(words(str, keep, "keep"), " ", false, false);
|
|
217
213
|
const ToLower = (str, keep) => join(words(str, keep), " ", false, false);
|
|
218
214
|
const ToUpper = (str, keep) => join(words(str, keep, "upper"), " ", false, false);
|
|
219
|
-
|
|
220
|
-
//#region src/anyCase/anyCase.ts
|
|
215
|
+
// src/anyCase/anyCase.ts
|
|
221
216
|
const KEEP_NONE = { keep: false };
|
|
222
217
|
const KEEP_ALL = { keep: true };
|
|
223
218
|
/** Reads the second argument of a `toX` function: the `allowSymbols` shorthand, or an options object. */
|
|
@@ -295,7 +290,6 @@ function toUpper(input, options) {
|
|
|
295
290
|
const { keep, ignore } = parseOptions(options);
|
|
296
291
|
return convert(input, (key) => ToUpper(key, keep), ignore);
|
|
297
292
|
}
|
|
298
|
-
//#endregion
|
|
299
293
|
exports.toCamel = toCamel;
|
|
300
294
|
exports.toDot = toDot;
|
|
301
295
|
exports.toKebab = toKebab;
|
package/dist/index.d.cts
CHANGED
|
@@ -1,4 +1,3 @@
|
|
|
1
|
-
//#region src/anyCase/types.d.ts
|
|
2
1
|
/** Flattens an intersection/mapped type so editors show the resulting keys. */
|
|
3
2
|
type Prettify<T> = { [K in keyof T]: T[K]; } & {};
|
|
4
3
|
type Separator = "_" | "-" | "." | " ";
|
|
@@ -66,8 +65,6 @@ type IgnoreKey<K, I extends string, Converted> = [I] extends [never] ? Converted
|
|
|
66
65
|
* `P` the `separator` option of `toPath`, and `I` the keys in the `ignore` option.
|
|
67
66
|
*/
|
|
68
67
|
type CaseResult<T, C extends Case, S = false, X = undefined, P extends string = "/", I extends string = never> = T extends string ? string : T extends Array<unknown> ? { [K in keyof T]: CaseResult<T[K], C, S, X, P, I>; } : T extends object ? Prettify<{ [K in keyof T as IgnoreKey<K, I, boolean extends S ? string : string extends KeptSymbols<S> ? string : ApplyTransform<ConvertKey<K & string, C, KeptSymbols<S>, P>, X>>]: CaseResult<T[K], C, S, X, P, I>; }> : T;
|
|
69
|
-
//#endregion
|
|
70
|
-
//#region src/anyCase/anyCase.d.ts
|
|
71
68
|
/**
|
|
72
69
|
* Converts a string, or the keys of an object/array (deeply), from any case to camelCase.
|
|
73
70
|
*
|
|
@@ -453,5 +450,4 @@ export declare function toUpper<T extends object | string, S extends boolean | s
|
|
|
453
450
|
* @param options `allowSymbols`: symbols are removed by default; `true` keeps all of them, and an array keeps only some.
|
|
454
451
|
*/
|
|
455
452
|
export declare function toUpper<T extends object | string, S extends boolean | string = false, I extends string = never>(input: T, options: CaseOptions<S, I>): CaseResult<T, "Upper", S, undefined, "/", I>;
|
|
456
|
-
//#endregion
|
|
457
453
|
export type { AllowSymbols, Case, CaseOptions, CaseResult, PathCaseOptions, PathSeparator, Transform, TransformCaseOptions };
|
package/dist/index.d.ts
CHANGED
|
@@ -1,4 +1,3 @@
|
|
|
1
|
-
//#region src/anyCase/types.d.ts
|
|
2
1
|
/** Flattens an intersection/mapped type so editors show the resulting keys. */
|
|
3
2
|
type Prettify<T> = { [K in keyof T]: T[K]; } & {};
|
|
4
3
|
type Separator = "_" | "-" | "." | " ";
|
|
@@ -66,8 +65,6 @@ type IgnoreKey<K, I extends string, Converted> = [I] extends [never] ? Converted
|
|
|
66
65
|
* `P` the `separator` option of `toPath`, and `I` the keys in the `ignore` option.
|
|
67
66
|
*/
|
|
68
67
|
type CaseResult<T, C extends Case, S = false, X = undefined, P extends string = "/", I extends string = never> = T extends string ? string : T extends Array<unknown> ? { [K in keyof T]: CaseResult<T[K], C, S, X, P, I>; } : T extends object ? Prettify<{ [K in keyof T as IgnoreKey<K, I, boolean extends S ? string : string extends KeptSymbols<S> ? string : ApplyTransform<ConvertKey<K & string, C, KeptSymbols<S>, P>, X>>]: CaseResult<T[K], C, S, X, P, I>; }> : T;
|
|
69
|
-
//#endregion
|
|
70
|
-
//#region src/anyCase/anyCase.d.ts
|
|
71
68
|
/**
|
|
72
69
|
* Converts a string, or the keys of an object/array (deeply), from any case to camelCase.
|
|
73
70
|
*
|
|
@@ -453,5 +450,4 @@ export declare function toUpper<T extends object | string, S extends boolean | s
|
|
|
453
450
|
* @param options `allowSymbols`: symbols are removed by default; `true` keeps all of them, and an array keeps only some.
|
|
454
451
|
*/
|
|
455
452
|
export declare function toUpper<T extends object | string, S extends boolean | string = false, I extends string = never>(input: T, options: CaseOptions<S, I>): CaseResult<T, "Upper", S, undefined, "/", I>;
|
|
456
|
-
//#endregion
|
|
457
453
|
export type { AllowSymbols, Case, CaseOptions, CaseResult, PathCaseOptions, PathSeparator, Transform, TransformCaseOptions };
|
package/dist/index.js
CHANGED
|
@@ -1,4 +1,4 @@
|
|
|
1
|
-
|
|
1
|
+
// src/utils.ts
|
|
2
2
|
function isString(input) {
|
|
3
3
|
return typeof input === "string";
|
|
4
4
|
}
|
|
@@ -10,8 +10,7 @@ function isObject(input) {
|
|
|
10
10
|
function isArray(input) {
|
|
11
11
|
return Array.isArray(input);
|
|
12
12
|
}
|
|
13
|
-
|
|
14
|
-
//#region src/parser/objectParser.ts
|
|
13
|
+
// src/parser/objectParser.ts
|
|
15
14
|
function objectParser(input, context) {
|
|
16
15
|
const result = {};
|
|
17
16
|
const keys = Object.keys(input);
|
|
@@ -38,8 +37,7 @@ function objectParser(input, context) {
|
|
|
38
37
|
}
|
|
39
38
|
return result;
|
|
40
39
|
}
|
|
41
|
-
|
|
42
|
-
//#region src/parser/arrayParser.ts
|
|
40
|
+
// src/parser/arrayParser.ts
|
|
43
41
|
function arrayParser(input, context) {
|
|
44
42
|
if (!context.cache) context.cache = /* @__PURE__ */ new Map();
|
|
45
43
|
const length = input.length;
|
|
@@ -53,8 +51,7 @@ function arrayParser(input, context) {
|
|
|
53
51
|
}
|
|
54
52
|
return result;
|
|
55
53
|
}
|
|
56
|
-
|
|
57
|
-
//#region src/parser/parser.ts
|
|
54
|
+
// src/parser/parser.ts
|
|
58
55
|
/** Converts a string, or the keys of an object/array (deeply), with `convertKey`. Keys in `ignore` are kept as they are. */
|
|
59
56
|
function convert(input, convertKey, ignore) {
|
|
60
57
|
if (isString(input)) return convertKey(input);
|
|
@@ -67,8 +64,7 @@ function convert(input, convertKey, ignore) {
|
|
|
67
64
|
}
|
|
68
65
|
return array ? arrayParser(input, context) : objectParser(input, context);
|
|
69
66
|
}
|
|
70
|
-
|
|
71
|
-
//#region src/anyCase/words.ts
|
|
67
|
+
// src/anyCase/words.ts
|
|
72
68
|
const SYMBOLS = "!\"#$%&'()*+,/:;<=>?@[\\]^`{|}~";
|
|
73
69
|
const OTHER = 0;
|
|
74
70
|
const SEPARATOR = 1;
|
|
@@ -215,8 +211,7 @@ const ToPath = (str, keep, transform, separator = "/") => applyTransform(join(wo
|
|
|
215
211
|
const ToSpace = (str, keep) => join(words(str, keep, "keep"), " ", false, false);
|
|
216
212
|
const ToLower = (str, keep) => join(words(str, keep), " ", false, false);
|
|
217
213
|
const ToUpper = (str, keep) => join(words(str, keep, "upper"), " ", false, false);
|
|
218
|
-
|
|
219
|
-
//#region src/anyCase/anyCase.ts
|
|
214
|
+
// src/anyCase/anyCase.ts
|
|
220
215
|
const KEEP_NONE = { keep: false };
|
|
221
216
|
const KEEP_ALL = { keep: true };
|
|
222
217
|
/** Reads the second argument of a `toX` function: the `allowSymbols` shorthand, or an options object. */
|
|
@@ -294,5 +289,4 @@ function toUpper(input, options) {
|
|
|
294
289
|
const { keep, ignore } = parseOptions(options);
|
|
295
290
|
return convert(input, (key) => ToUpper(key, keep), ignore);
|
|
296
291
|
}
|
|
297
|
-
//#endregion
|
|
298
292
|
export { toCamel, toDot, toKebab, toLower, toPascal, toPascalSnake, toPath, toSentence, toSnake, toSpace, toTitle, toTrain, toUpper, toUpperKebab, toUpperSnake };
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "caseparser",
|
|
3
|
-
"version": "6.0.
|
|
3
|
+
"version": "6.0.1",
|
|
4
4
|
"description": "Convert Strings/Arrays/Objects from a type of case to another one.",
|
|
5
5
|
"author": "Fernando Machado Bernardino <fernandombernardino@gmail.com>",
|
|
6
6
|
"homepage": "https://github.com/NandoMB/caseparser#readme",
|