caseparser 4.2.0 → 5.0.0
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 +103 -13
- package/dist/index.cjs +638 -34
- package/dist/index.d.cts +522 -1
- package/dist/index.d.ts +522 -1
- package/dist/index.js +624 -35
- package/package.json +5 -1
package/README.md
CHANGED
|
@@ -43,7 +43,7 @@ npx jsr add @nandomb/caseparser
|
|
|
43
43
|
| --- | --- |
|
|
44
44
|
| ESM (`import`) | Node.js 12.22+, Deno, Bun, bundlers |
|
|
45
45
|
| CommonJS (`require`) | Node.js 8+, Bun |
|
|
46
|
-
| TypeScript | 4.1+ (any `moduleResolution`: `node`, `node16`/`nodenext`, `bundler`) |
|
|
46
|
+
| TypeScript | 4.5+ for the `toX` functions, 4.1+ for the deprecated `<from>To<To>` functions (any `moduleResolution`: `node`, `node16`/`nodenext`, `bundler`) |
|
|
47
47
|
| Browsers | Any ES2015 browser (via bundler) |
|
|
48
48
|
| Edge | Cloudflare Workers |
|
|
49
49
|
|
|
@@ -54,28 +54,58 @@ Ready-to-run projects for each environment (Node.js ESM/CommonJS, TypeScript, Ty
|
|
|
54
54
|
## How to use
|
|
55
55
|
|
|
56
56
|
```ts
|
|
57
|
-
import {
|
|
58
|
-
// const {
|
|
57
|
+
import { toSnake } from 'caseparser'; // ESM
|
|
58
|
+
// const { toSnake } = require('caseparser'); // CommonJS
|
|
59
59
|
|
|
60
|
-
|
|
60
|
+
toSnake('helloWorld'); // 'hello_world'
|
|
61
61
|
|
|
62
|
-
|
|
62
|
+
toSnake({ firstName: 'John', addresses: [{ postalCode: '61105' }] });
|
|
63
63
|
// { first_name: 'John', addresses: [{ postal_code: '61105' }] }
|
|
64
64
|
```
|
|
65
65
|
|
|
66
66
|
Objects are converted deeply, including objects inside arrays. The input is never mutated: a new object is returned.
|
|
67
67
|
|
|
68
|
+
There is one function per target case, and the input can be in any case (see [From any case](#from-any-case)). Converting `'helloWorld'`:
|
|
69
|
+
|
|
70
|
+
| Function | Result | Also known as |
|
|
71
|
+
| --- | --- | --- |
|
|
72
|
+
| `toCamel` | `helloWorld` | lowerCamelCase |
|
|
73
|
+
| `toPascal` | `HelloWorld` | UpperCamelCase |
|
|
74
|
+
| `toSnake` | `hello_world` | |
|
|
75
|
+
| `toKebab` | `hello-world` | dash-case, param-case |
|
|
76
|
+
| `toUpperSnake` | `HELLO_WORLD` | CONSTANT_CASE, SCREAMING_SNAKE_CASE |
|
|
77
|
+
| `toUpperKebab` | `HELLO-WORLD` | COBOL-CASE, SCREAMING-KEBAB-CASE |
|
|
78
|
+
| `toTrain` | `Hello-World` | Header-Case |
|
|
79
|
+
| `toDot` | `hello.World` | dot.notation |
|
|
80
|
+
| `toTitle` | `Hello World` | Capital Case |
|
|
81
|
+
| `toSentence` | `Hello world` | |
|
|
82
|
+
| `toPascalSnake` | `Hello_World` | Ada_Case, Title_Snake_Case |
|
|
83
|
+
| `toPath` | `hello/World` | |
|
|
84
|
+
| `toSpace` | `hello World` | |
|
|
85
|
+
| `toLower` | `hello world` | no case |
|
|
86
|
+
| `toUpper` | `HELLO WORLD` | |
|
|
87
|
+
|
|
88
|
+
`toSpace`, `toPath` and `toDot` keep the original case of each word (`toPath('UserProfile')` → `'User/Profile'`); all the others lowercase the words first. To change the case of a whole string, use `toLowerCase()` or `toUpperCase()` on the result:
|
|
89
|
+
|
|
90
|
+
```ts
|
|
91
|
+
toPath('helloWorld'); // 'hello/World'
|
|
92
|
+
toPath('helloWorld').toLowerCase(); // 'hello/world'
|
|
93
|
+
toPath('helloWorld').toUpperCase(); // 'HELLO/WORLD'
|
|
94
|
+
```
|
|
95
|
+
|
|
96
|
+
Don't chain `toX` functions for this (`toUpper(toPath(...))`): each one splits its input into words again, so `/` and `.` would be treated as separators or symbols.
|
|
97
|
+
|
|
68
98
|
### Typical use: API responses
|
|
69
99
|
|
|
70
100
|
```ts
|
|
71
|
-
import {
|
|
101
|
+
import { toCamel, toSnake } from 'caseparser';
|
|
72
102
|
|
|
73
103
|
const res = await fetch('/api/users/1');
|
|
74
|
-
const user =
|
|
104
|
+
const user = toCamel(await res.json()); // { firstName, lastName, ... }
|
|
75
105
|
|
|
76
106
|
await fetch('/api/users/1', {
|
|
77
107
|
method: 'PUT',
|
|
78
|
-
body: JSON.stringify(
|
|
108
|
+
body: JSON.stringify(toSnake(user)), // back to { first_name, ... }
|
|
79
109
|
});
|
|
80
110
|
```
|
|
81
111
|
|
|
@@ -84,15 +114,58 @@ await fetch('/api/users/1', {
|
|
|
84
114
|
The resulting keys are inferred at the type level, so your editor autocompletes the converted names:
|
|
85
115
|
|
|
86
116
|
```ts
|
|
87
|
-
const user =
|
|
117
|
+
const user = toCamel({ first_name: 'John', addresses: [{ postal_code: '61105' }] });
|
|
88
118
|
// ^? { firstName: string; addresses: { postalCode: string }[] }
|
|
89
119
|
|
|
90
120
|
user.firstName; // ✅
|
|
91
121
|
user.first_name; // ❌ Property 'first_name' does not exist
|
|
92
122
|
```
|
|
93
123
|
|
|
124
|
+
### From any case
|
|
125
|
+
|
|
126
|
+
You don't need to know the input's case: the input is split into words whatever its case, so keys in different cases can even be mixed in the same object:
|
|
127
|
+
|
|
128
|
+
```ts
|
|
129
|
+
import { toCamel, toSnake } from 'caseparser';
|
|
130
|
+
|
|
131
|
+
toSnake('helloWorld'); // 'hello_world'
|
|
132
|
+
toSnake('Hello World'); // 'hello_world'
|
|
133
|
+
toSnake('HELLO-WORLD'); // 'hello_world'
|
|
134
|
+
|
|
135
|
+
toCamel({ user_id: 1, 'Last-Name': 'Doe', XMLHttpRequest: true });
|
|
136
|
+
// ^? { userId: number; lastName: string; xmlHttpRequest: boolean }
|
|
137
|
+
```
|
|
138
|
+
|
|
139
|
+
Words are split on `_`, `-`, `.` and spaces, and before an uppercase letter that starts a new word.
|
|
140
|
+
|
|
141
|
+
### Symbols
|
|
142
|
+
|
|
143
|
+
Symbols (ASCII punctuation such as `$`, `@`, `#` or `%`) are removed by default. Pass a second argument to keep them: `true` keeps all of them, and an array keeps only the listed ones:
|
|
144
|
+
|
|
145
|
+
```ts
|
|
146
|
+
toCamel({ $ref: 1, '@type': 'user' }); // { ref: 1, type: 'user' }
|
|
147
|
+
toCamel({ $ref: 1, '@type': 'user' }, true); // { $ref: 1, '@type': 'user' }
|
|
148
|
+
toCamel({ $ref: 1, '@type': 'user' }, ['$']); // { $ref: 1, type: 'user' }
|
|
149
|
+
|
|
150
|
+
toCamel('$Hello-world', true); // '$helloWorld'
|
|
151
|
+
toPascal('$id', true); // '$Id'
|
|
152
|
+
```
|
|
153
|
+
|
|
154
|
+
A symbol always starts a new word, so the words are the same whether symbols are kept or not. A kept symbol sticks to the start of the next word, or to the end of the previous one when no word follows:
|
|
155
|
+
|
|
156
|
+
```ts
|
|
157
|
+
toSnake('$$hello$World$$hi'); // 'hello_world_hi'
|
|
158
|
+
toSnake('$$hello$World$$hi', true); // '$$hello_$world_$$hi'
|
|
159
|
+
toSnake('user@name', true); // 'user_@name'
|
|
160
|
+
toSnake('total%_count', true); // 'total%_count'
|
|
161
|
+
```
|
|
162
|
+
|
|
163
|
+
The inferred types follow the same rules. `_`, `-` and `.` are separators, not symbols, so `_links` always becomes `links`.
|
|
164
|
+
|
|
94
165
|
## Conversion Types
|
|
95
166
|
|
|
167
|
+
> **Deprecated:** the `<from>To<To>` functions below are deprecated in favor of the `toX` functions ([How to use](#how-to-use)) and will be removed in the next major version, which will also require TypeScript 4.7+. They keep working until then. See [Migrating to `toX`](#migrating-to-tox).
|
|
168
|
+
|
|
96
169
|
Every function is named `<from>To<To>`, e.g. `snakeToCamel`. The case names are:
|
|
97
170
|
|
|
98
171
|
| Name | Example |
|
|
@@ -121,14 +194,31 @@ All 90 functions:
|
|
|
121
194
|
- **Title Case:** `titleToCamel`, `titleToPascal`, `titleToSnake`, `titleToDash`, `titleToUpperSnake`, `titleToUpperDash`, `titleToTrain`, `titleToDot`, `titleToSentence`
|
|
122
195
|
- **Sentence case:** `sentenceToCamel`, `sentenceToPascal`, `sentenceToSnake`, `sentenceToDash`, `sentenceToUpperSnake`, `sentenceToUpperDash`, `sentenceToTrain`, `sentenceToDot`, `sentenceToTitle`
|
|
123
196
|
|
|
197
|
+
## Migrating to `toX`
|
|
198
|
+
|
|
199
|
+
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`.
|
|
200
|
+
|
|
201
|
+
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:
|
|
202
|
+
|
|
203
|
+
| Call | `<from>To<To>` result | `toX` result |
|
|
204
|
+
| --- | --- | --- |
|
|
205
|
+
| `camelToSnake('userID')` / `toSnake('userID')` | `'user_i_d'` | `'user_id'` |
|
|
206
|
+
| `camelToSnake('XMLHttpRequest')` / `toSnake('XMLHttpRequest')` | `'_x_m_l_http_request'` | `'xml_http_request'` |
|
|
207
|
+
| `camelToSnake('HelloWorld')` / `toSnake('HelloWorld')` | `'_hello_world'` | `'hello_world'` |
|
|
208
|
+
| `snakeToCamel('user_ID')` / `toCamel('user_ID')` | `'userID'` | `'userId'` |
|
|
209
|
+
| `camelToDot('helloWorld')` / `toDot('helloWorld')` | `'hello.world'` | `'hello.World'` |
|
|
210
|
+
|
|
211
|
+
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.
|
|
212
|
+
|
|
124
213
|
## Behavior and limitations
|
|
125
214
|
|
|
126
215
|
- **Only keys are converted, never values.** In `{ userName: 'johnDoe' }`, `userName` becomes `user_name` but `'johnDoe'` is kept. Strings inside arrays are kept too.
|
|
127
216
|
- **Only plain objects are traversed.** `Date`, `Map`, `Set` and class instances are returned as they are (same reference), without converting their contents.
|
|
128
|
-
- **Acronyms are
|
|
129
|
-
- **
|
|
130
|
-
- **Title Case capitalizes every word**, including short ones: `
|
|
131
|
-
- **
|
|
217
|
+
- **Acronyms are kept together, but not restored:** `toSnake('userID')` → `'user_id'`, and back `toCamel('user_id')` → `'userId'`.
|
|
218
|
+
- **Words are lowercased** before converting (except by `toSpace`, `toPath` and `toDot`), so `toCamel('X-API-Key')` → `'xApiKey'` and `toCamel('First Name')` → `'firstName'`.
|
|
219
|
+
- **Title Case capitalizes every word**, including short ones: `toTitle('termsOfUse')` → `'Terms Of Use'`.
|
|
220
|
+
- **Digits stay attached to the previous word:** `toSnake('html5Parser')` → `'html5_parser'`, `toSnake('user1Name')` → `'user1_name'`.
|
|
221
|
+
- **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. The `toX` functions infer keys up to ~120 characters; longer keys fail to compile with `Type instantiation is excessively deep and possibly infinite`. The runtime conversion has no limit.
|
|
132
222
|
|
|
133
223
|
## Security
|
|
134
224
|
|