caseparser 4.2.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 +63 -13
- package/dist/index.cjs +481 -34
- package/dist/index.d.cts +396 -1
- package/dist/index.d.ts +396 -1
- package/dist/index.js +472 -35
- package/package.json +1 -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.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 |
|
|
@@ -121,14 +155,30 @@ All 90 functions:
|
|
|
121
155
|
- **Title Case:** `titleToCamel`, `titleToPascal`, `titleToSnake`, `titleToDash`, `titleToUpperSnake`, `titleToUpperDash`, `titleToTrain`, `titleToDot`, `titleToSentence`
|
|
122
156
|
- **Sentence case:** `sentenceToCamel`, `sentenceToPascal`, `sentenceToSnake`, `sentenceToDash`, `sentenceToUpperSnake`, `sentenceToUpperDash`, `sentenceToTrain`, `sentenceToDot`, `sentenceToTitle`
|
|
123
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:
|
|
163
|
+
|
|
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'` |
|
|
170
|
+
|
|
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.
|
|
172
|
+
|
|
124
173
|
## Behavior and limitations
|
|
125
174
|
|
|
126
175
|
- **Only keys are converted, never values.** In `{ userName: 'johnDoe' }`, `userName` becomes `user_name` but `'johnDoe'` is kept. Strings inside arrays are kept too.
|
|
127
176
|
- **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
|
-
- **
|
|
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.
|
|
132
182
|
|
|
133
183
|
## Security
|
|
134
184
|
|