caseparser 4.1.0 → 4.3.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 +76 -21
- package/dist/index.cjs +996 -35
- package/dist/index.d.cts +788 -11
- package/dist/index.d.ts +788 -11
- package/dist/index.js +953 -36
- package/package.json +6 -2
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.1+ (any `moduleResolution`: `node`, `node16`/`nodenext`, `bundler`). The `toX` type inference needs 4.5+ for keys longer than ~20 characters |
|
|
47
47
|
| Browsers | Any ES2015 browser (via bundler) |
|
|
48
48
|
| Edge | Cloudflare Workers |
|
|
49
49
|
|
|
@@ -54,28 +54,43 @@ 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)):
|
|
69
|
+
|
|
70
|
+
```ts
|
|
71
|
+
toCamel('helloWorld'); // 'helloWorld'
|
|
72
|
+
toPascal('helloWorld'); // 'HelloWorld'
|
|
73
|
+
toSnake('helloWorld'); // 'hello_world'
|
|
74
|
+
toDash('helloWorld'); // 'hello-world'
|
|
75
|
+
toUpperSnake('helloWorld'); // 'HELLO_WORLD'
|
|
76
|
+
toUpperDash('helloWorld'); // 'HELLO-WORLD'
|
|
77
|
+
toTrain('helloWorld'); // 'Hello-World'
|
|
78
|
+
toDot('helloWorld'); // 'hello.world'
|
|
79
|
+
toTitle('helloWorld'); // 'Hello World'
|
|
80
|
+
toSentence('helloWorld'); // 'Hello world'
|
|
81
|
+
```
|
|
82
|
+
|
|
68
83
|
### Typical use: API responses
|
|
69
84
|
|
|
70
85
|
```ts
|
|
71
|
-
import {
|
|
86
|
+
import { toCamel, toSnake } from 'caseparser';
|
|
72
87
|
|
|
73
88
|
const res = await fetch('/api/users/1');
|
|
74
|
-
const user =
|
|
89
|
+
const user = toCamel(await res.json()); // { firstName, lastName, ... }
|
|
75
90
|
|
|
76
91
|
await fetch('/api/users/1', {
|
|
77
92
|
method: 'PUT',
|
|
78
|
-
body: JSON.stringify(
|
|
93
|
+
body: JSON.stringify(toSnake(user)), // back to { first_name, ... }
|
|
79
94
|
});
|
|
80
95
|
```
|
|
81
96
|
|
|
@@ -84,15 +99,34 @@ await fetch('/api/users/1', {
|
|
|
84
99
|
The resulting keys are inferred at the type level, so your editor autocompletes the converted names:
|
|
85
100
|
|
|
86
101
|
```ts
|
|
87
|
-
const user =
|
|
102
|
+
const user = toCamel({ first_name: 'John', addresses: [{ postal_code: '61105' }] });
|
|
88
103
|
// ^? { firstName: string; addresses: { postalCode: string }[] }
|
|
89
104
|
|
|
90
105
|
user.firstName; // ✅
|
|
91
106
|
user.first_name; // ❌ Property 'first_name' does not exist
|
|
92
107
|
```
|
|
93
108
|
|
|
109
|
+
### From any case
|
|
110
|
+
|
|
111
|
+
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:
|
|
112
|
+
|
|
113
|
+
```ts
|
|
114
|
+
import { toCamel, toSnake } from 'caseparser';
|
|
115
|
+
|
|
116
|
+
toSnake('helloWorld'); // 'hello_world'
|
|
117
|
+
toSnake('Hello World'); // 'hello_world'
|
|
118
|
+
toSnake('HELLO-WORLD'); // 'hello_world'
|
|
119
|
+
|
|
120
|
+
toCamel({ user_id: 1, 'Last-Name': 'Doe', XMLHttpRequest: true });
|
|
121
|
+
// ^? { userId: number; lastName: string; xmlHttpRequest: boolean }
|
|
122
|
+
```
|
|
123
|
+
|
|
124
|
+
Words are split on `_`, `-`, `.` and spaces, and before an uppercase letter that starts a new word.
|
|
125
|
+
|
|
94
126
|
## Conversion Types
|
|
95
127
|
|
|
128
|
+
> **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. They keep working until then. See [Migrating to `toX`](#migrating-to-tox).
|
|
129
|
+
|
|
96
130
|
Every function is named `<from>To<To>`, e.g. `snakeToCamel`. The case names are:
|
|
97
131
|
|
|
98
132
|
| Name | Example |
|
|
@@ -105,25 +139,46 @@ Every function is named `<from>To<To>`, e.g. `snakeToCamel`. The case names are:
|
|
|
105
139
|
| `upperDash` | `HELLO-WORLD` |
|
|
106
140
|
| `train` | `Hello-World` |
|
|
107
141
|
| `dot` | `hello.world` |
|
|
142
|
+
| `title` | `Hello World` |
|
|
143
|
+
| `sentence` | `Hello world` |
|
|
144
|
+
|
|
145
|
+
All 90 functions:
|
|
146
|
+
|
|
147
|
+
- **camelCase:** `camelToPascal`, `camelToSnake`, `camelToDash`, `camelToUpperSnake`, `camelToUpperDash`, `camelToTrain`, `camelToDot`, `camelToTitle`, `camelToSentence`
|
|
148
|
+
- **PascalCase:** `pascalToCamel`, `pascalToSnake`, `pascalToDash`, `pascalToUpperSnake`, `pascalToUpperDash`, `pascalToTrain`, `pascalToDot`, `pascalToTitle`, `pascalToSentence`
|
|
149
|
+
- **snake_case:** `snakeToCamel`, `snakeToPascal`, `snakeToDash`, `snakeToUpperSnake`, `snakeToUpperDash`, `snakeToTrain`, `snakeToDot`, `snakeToTitle`, `snakeToSentence`
|
|
150
|
+
- **dash-case:** `dashToCamel`, `dashToPascal`, `dashToSnake`, `dashToUpperSnake`, `dashToUpperDash`, `dashToTrain`, `dashToDot`, `dashToTitle`, `dashToSentence`
|
|
151
|
+
- **UPPER_SNAKE_CASE:** `upperSnakeToCamel`, `upperSnakeToPascal`, `upperSnakeToSnake`, `upperSnakeToDash`, `upperSnakeToUpperDash`, `upperSnakeToTrain`, `upperSnakeToDot`, `upperSnakeToTitle`, `upperSnakeToSentence`
|
|
152
|
+
- **UPPER-DASH-CASE:** `upperDashToCamel`, `upperDashToPascal`, `upperDashToSnake`, `upperDashToDash`, `upperDashToUpperSnake`, `upperDashToTrain`, `upperDashToDot`, `upperDashToTitle`, `upperDashToSentence`
|
|
153
|
+
- **Train-Case:** `trainToCamel`, `trainToPascal`, `trainToSnake`, `trainToDash`, `trainToUpperSnake`, `trainToUpperDash`, `trainToDot`, `trainToTitle`, `trainToSentence`
|
|
154
|
+
- **dot.case:** `dotToCamel`, `dotToPascal`, `dotToSnake`, `dotToDash`, `dotToUpperSnake`, `dotToUpperDash`, `dotToTrain`, `dotToTitle`, `dotToSentence`
|
|
155
|
+
- **Title Case:** `titleToCamel`, `titleToPascal`, `titleToSnake`, `titleToDash`, `titleToUpperSnake`, `titleToUpperDash`, `titleToTrain`, `titleToDot`, `titleToSentence`
|
|
156
|
+
- **Sentence case:** `sentenceToCamel`, `sentenceToPascal`, `sentenceToSnake`, `sentenceToDash`, `sentenceToUpperSnake`, `sentenceToUpperDash`, `sentenceToTrain`, `sentenceToDot`, `sentenceToTitle`
|
|
157
|
+
|
|
158
|
+
## Migrating to `toX`
|
|
159
|
+
|
|
160
|
+
Replace each `<from>To<To>` function with the `toX` function for its target case, whatever the source case: `camelToSnake`, `dashToSnake`, `titleToSnake`... all become `toSnake`.
|
|
161
|
+
|
|
162
|
+
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:
|
|
108
163
|
|
|
109
|
-
|
|
164
|
+
| Call | `<from>To<To>` result | `toX` result |
|
|
165
|
+
| --- | --- | --- |
|
|
166
|
+
| `camelToSnake('userID')` / `toSnake('userID')` | `'user_i_d'` | `'user_id'` |
|
|
167
|
+
| `camelToSnake('XMLHttpRequest')` / `toSnake('XMLHttpRequest')` | `'_x_m_l_http_request'` | `'xml_http_request'` |
|
|
168
|
+
| `camelToSnake('HelloWorld')` / `toSnake('HelloWorld')` | `'_hello_world'` | `'hello_world'` |
|
|
169
|
+
| `snakeToCamel('user_ID')` / `toCamel('user_ID')` | `'userID'` | `'userId'` |
|
|
110
170
|
|
|
111
|
-
|
|
112
|
-
- **PascalCase:** `pascalToCamel`, `pascalToSnake`, `pascalToDash`, `pascalToUpperSnake`, `pascalToUpperDash`, `pascalToTrain`, `pascalToDot`
|
|
113
|
-
- **snake_case:** `snakeToCamel`, `snakeToPascal`, `snakeToDash`, `snakeToUpperSnake`, `snakeToUpperDash`, `snakeToTrain`, `snakeToDot`
|
|
114
|
-
- **dash-case:** `dashToCamel`, `dashToPascal`, `dashToSnake`, `dashToUpperSnake`, `dashToUpperDash`, `dashToTrain`, `dashToDot`
|
|
115
|
-
- **UPPER_SNAKE_CASE:** `upperSnakeToCamel`, `upperSnakeToPascal`, `upperSnakeToSnake`, `upperSnakeToDash`, `upperSnakeToUpperDash`, `upperSnakeToTrain`, `upperSnakeToDot`
|
|
116
|
-
- **UPPER-DASH-CASE:** `upperDashToCamel`, `upperDashToPascal`, `upperDashToSnake`, `upperDashToDash`, `upperDashToUpperSnake`, `upperDashToTrain`, `upperDashToDot`
|
|
117
|
-
- **Train-Case:** `trainToCamel`, `trainToPascal`, `trainToSnake`, `trainToDash`, `trainToUpperSnake`, `trainToUpperDash`, `trainToDot`
|
|
118
|
-
- **dot.case:** `dotToCamel`, `dotToPascal`, `dotToSnake`, `dotToDash`, `dotToUpperSnake`, `dotToUpperDash`, `dotToTrain`
|
|
171
|
+
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.
|
|
119
172
|
|
|
120
173
|
## Behavior and limitations
|
|
121
174
|
|
|
122
175
|
- **Only keys are converted, never values.** In `{ userName: 'johnDoe' }`, `userName` becomes `user_name` but `'johnDoe'` is kept. Strings inside arrays are kept too.
|
|
123
176
|
- **Only plain objects are traversed.** `Date`, `Map`, `Set` and class instances are returned as they are (same reference), without converting their contents.
|
|
124
|
-
- **Acronyms are
|
|
125
|
-
- **
|
|
126
|
-
- **
|
|
177
|
+
- **Acronyms are kept together, but not restored:** `toSnake('userID')` → `'user_id'`, and back `toCamel('user_id')` → `'userId'`.
|
|
178
|
+
- **Words are lowercased** before converting, so `toCamel('X-API-Key')` → `'xApiKey'` and `toCamel('First Name')` → `'firstName'`.
|
|
179
|
+
- **Title Case capitalizes every word**, including short ones: `toTitle('termsOfUse')` → `'Terms Of Use'`.
|
|
180
|
+
- **Digits stay attached to the previous word:** `toSnake('html5Parser')` → `'html5_parser'`, `toSnake('user1Name')` → `'user1_name'`.
|
|
181
|
+
- **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. With TypeScript 4.5+, the `toX` functions infer keys up to ~120 characters; with TypeScript 4.1 to 4.4, only up to ~20 characters. Longer keys fail to compile with `Type instantiation is excessively deep and possibly infinite`. The runtime conversion has no limit.
|
|
127
182
|
|
|
128
183
|
## Security
|
|
129
184
|
|