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 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 { camelToSnake } from 'caseparser'; // ESM
58
- // const { camelToSnake } = require('caseparser'); // CommonJS
57
+ import { toSnake } from 'caseparser'; // ESM
58
+ // const { toSnake } = require('caseparser'); // CommonJS
59
59
 
60
- camelToSnake('helloWorld'); // 'hello_world'
60
+ toSnake('helloWorld'); // 'hello_world'
61
61
 
62
- camelToSnake({ firstName: 'John', addresses: [{ postalCode: '61105' }] });
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 { snakeToCamel, camelToSnake } from 'caseparser';
101
+ import { toCamel, toSnake } from 'caseparser';
72
102
 
73
103
  const res = await fetch('/api/users/1');
74
- const user = snakeToCamel(await res.json()); // { firstName, lastName, ... }
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(camelToSnake(user)), // back to { first_name, ... }
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 = snakeToCamel({ first_name: 'John', addresses: [{ postal_code: '61105' }] });
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 split letter by letter**, because every uppercase letter starts a new word: `camelToSnake('userID')` → `'user_i_d'`. Prefer `userId` style keys.
129
- - **Train-Case, Title Case and Sentence case words are lowercased** before converting, so `trainToCamel('X-API-Key')` → `'xApiKey'` and `titleToCamel('First Name')` → `'firstName'`.
130
- - **Title Case capitalizes every word**, including short ones: `camelToTitle('termsOfUse')` → `'Terms Of Use'`.
131
- - **Numbers are not word boundaries:** `camelToSnake('html5Parser')` → `'html5_parser'`, `snakeToCamel('user_1_name')` → `'user1Name'`.
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