caseparser 4.3.0 → 5.1.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
@@ -7,17 +7,28 @@
7
7
  [![npm downloads](https://img.shields.io/npm/dm/caseparser.svg)](https://www.npmjs.com/package/caseparser)
8
8
  [![license](https://img.shields.io/npm/l/caseparser.svg)](./LICENSE)
9
9
 
10
- Convert **Strings** and **JSON (Object Keys)** from a **case type** to another one with **type inference** based on parameter's type.
11
-
12
- - Zero dependencies
13
- - Written in TypeScript, published as ESM and CommonJS with type declarations
14
- - Available on [npm](https://www.npmjs.com/package/caseparser) and [JSR](https://jsr.io/@nandomb/caseparser)
15
- - Tree-shakeable
10
+ Convert **strings** and **object keys** to any case, **whatever case they are in now**, with the resulting keys inferred by TypeScript.
16
11
 
12
+ - **Any case in:** no need to know or normalize the input first. Keys in different cases can even be mixed in the same object
13
+ - **Deep:** nested objects and objects inside arrays are converted too
14
+ - **Typed:** your editor autocompletes the converted keys
15
+ - Zero dependencies, tree-shakeable, ESM and CommonJS, on [npm](https://www.npmjs.com/package/caseparser) and [JSR](https://jsr.io/@nandomb/caseparser)
17
16
 
18
17
  ###### Note:
19
18
  > If you're looking for version 1.x.x, [click here](https://github.com/NandoMB/caseparser/tree/v1.x.x) to see the docs.
20
19
 
20
+ ## Contents
21
+
22
+ - [Installation](#installation)
23
+ - [Quick start](#quick-start)
24
+ - [Cases](#cases)
25
+ - [Options](#options): [`allowSymbols`](#allowsymbols), [`transform`](#transform), [`separator`](#separator)
26
+ - [Type inference](#type-inference)
27
+ - [How keys are split into words](#how-keys-are-split-into-words)
28
+ - [Behavior and limitations](#behavior-and-limitations)
29
+ - [Compatibility](#compatibility)
30
+ - [Deprecated `<from>To<To>` functions](#deprecated-fromtoto-functions)
31
+ - [Security](#security)
21
32
 
22
33
  ## Installation
23
34
 
@@ -29,7 +40,7 @@ npm add caseparser # or: pnpm add caseparser / yarn add caseparser
29
40
  deno add jsr:@nandomb/caseparser
30
41
  ```
31
42
  ```ts
32
- import { camelToSnake } from '@nandomb/caseparser';
43
+ import { toSnake } from '@nandomb/caseparser';
33
44
  ```
34
45
  ###### Bun / Node.js from JSR
35
46
  ```sh
@@ -37,95 +48,220 @@ bunx jsr add @nandomb/caseparser
37
48
  npx jsr add @nandomb/caseparser
38
49
  ```
39
50
 
40
- ## Compatibility
51
+ ## Quick start
41
52
 
42
- | Environment | Supported |
43
- | --- | --- |
44
- | ESM (`import`) | Node.js 12.22+, Deno, Bun, bundlers |
45
- | CommonJS (`require`) | Node.js 8+, Bun |
46
- | TypeScript | 4.1+ (any `moduleResolution`: `node`, `node16`/`nodenext`, `bundler`). The `toX` type inference needs 4.5+ for keys longer than ~20 characters |
47
- | Browsers | Any ES2015 browser (via bundler) |
48
- | Edge | Cloudflare Workers |
53
+ The input doesn't need a specific or consistent shape. Every key below is in a different case, and one call converts all of them, deeply:
49
54
 
50
- Every change is tested in CI on Node.js 22, 24 and 26, Bun, Deno, Cloudflare Workers, and in Chromium, Firefox and WebKit.
55
+ ```ts
56
+ import { toCamel } from 'caseparser'; // ESM
57
+ // const { toCamel } = require('caseparser'); // CommonJS
58
+
59
+ const response = {
60
+ userId: 42, // camelCase
61
+ FirstName: 'Ada', // PascalCase
62
+ last_name: 'Lovelace', // snake_case
63
+ 'birth-date': '1815-12-10', // kebab-case
64
+ ACCOUNT_STATUS: 'active', // UPPER_SNAKE_CASE
65
+ 'Content-Type': 'application/json', // Train-Case
66
+ 'Display Name': 'Countess', // Title Case
67
+ XMLHttpRequest: false, // acronym + word
68
+ $ref: '#/users/42', // symbol
69
+ 'billing address': { // nested objects...
70
+ 'Postal Code': '61105',
71
+ countryISO: 'US'
72
+ },
73
+ 'recent.orders': [{ order_id: 1, TotalAmount: 99.9 }], // ...and objects inside arrays
74
+ tags: ['someTag', 'another_tag'] // values are never converted
75
+ };
76
+
77
+ toCamel(response);
78
+ // {
79
+ // userId: 42,
80
+ // firstName: 'Ada',
81
+ // lastName: 'Lovelace',
82
+ // birthDate: '1815-12-10',
83
+ // accountStatus: 'active',
84
+ // contentType: 'application/json',
85
+ // displayName: 'Countess',
86
+ // xmlHttpRequest: false,
87
+ // ref: '#/users/42',
88
+ // billingAddress: { postalCode: '61105', countryIso: 'US' },
89
+ // recentOrders: [{ orderId: 1, totalAmount: 99.9 }],
90
+ // tags: ['someTag', 'another_tag']
91
+ // }
92
+ ```
51
93
 
52
- Ready-to-run projects for each environment (Node.js ESM/CommonJS, TypeScript, TypeScript 4.1, Bun, Deno, the browser and Cloudflare Workers) are in [examples/](./examples).
94
+ Strings work the same way: `toSnake('helloWorld')`, `toSnake('Hello World')` and `toSnake('HELLO-WORLD')` all return `'hello_world'`.
53
95
 
54
- ## How to use
96
+ The input is never mutated: a new object is returned. A typical use is converting API payloads on the way in and out:
55
97
 
56
98
  ```ts
57
- import { toSnake } from 'caseparser'; // ESM
58
- // const { toSnake } = require('caseparser'); // CommonJS
99
+ import { toCamel, toSnake } from 'caseparser';
59
100
 
60
- toSnake('helloWorld'); // 'hello_world'
101
+ const res = await fetch('/api/users/1');
102
+ const user = toCamel(await res.json()); // { firstName, lastName, ... }
61
103
 
62
- toSnake({ firstName: 'John', addresses: [{ postalCode: '61105' }] });
63
- // { first_name: 'John', addresses: [{ postal_code: '61105' }] }
104
+ await fetch('/api/users/1', {
105
+ method: 'PUT',
106
+ body: JSON.stringify(toSnake(user)), // back to { first_name, ... }
107
+ });
64
108
  ```
65
109
 
66
- Objects are converted deeply, including objects inside arrays. The input is never mutated: a new object is returned.
110
+ ## Cases
111
+
112
+ There is one function per target case, and each one accepts input in any case:
67
113
 
68
- There is one function per target case, and the input can be in any case (see [From any case](#from-any-case)):
114
+ | Function | `'helloWorld'` → | `'LAST_login_AT'` → | Also known as |
115
+ | --- | --- | --- | --- |
116
+ | `toCamel` | `helloWorld` | `lastLoginAt` | lowerCamelCase |
117
+ | `toPascal` | `HelloWorld` | `LastLoginAt` | UpperCamelCase |
118
+ | `toSnake` | `hello_world` | `last_login_at` | |
119
+ | `toKebab` | `hello-world` | `last-login-at` | dash-case, param-case |
120
+ | `toUpperSnake` | `HELLO_WORLD` | `LAST_LOGIN_AT` | CONSTANT_CASE, SCREAMING_SNAKE_CASE |
121
+ | `toUpperKebab` | `HELLO-WORLD` | `LAST-LOGIN-AT` | COBOL-CASE, SCREAMING-KEBAB-CASE |
122
+ | `toTrain` | `Hello-World` | `Last-Login-At` | Header-Case |
123
+ | `toTitle` | `Hello World` | `Last Login At` | Capital Case |
124
+ | `toSentence` | `Hello world` | `Last login at` | |
125
+ | `toPascalSnake` | `Hello_World` | `Last_Login_At` | Ada_Case, Title_Snake_Case |
126
+ | `toLower` | `hello world` | `last login at` | no case |
127
+ | `toUpper` | `HELLO WORLD` | `LAST LOGIN AT` | |
128
+ | `toDot` | `hello.World` | `LAST.login.AT` | dot.notation |
129
+ | `toPath` | `hello/World` | `LAST/login/AT` | |
130
+ | `toSpace` | `hello World` | `LAST login AT` | |
131
+
132
+ `toDot`, `toPath` and `toSpace` only change the separator: they keep the original case of each word (upper, lower or mixed). To change it, see [`transform`](#transform).
133
+
134
+ ## Options
135
+
136
+ Every function takes an optional second argument.
137
+
138
+ ### `allowSymbols`
139
+
140
+ Symbols (ASCII punctuation such as `$`, `@`, `#` or `%`) are removed by default. `allowSymbols: true` keeps all of them, and an array keeps only the listed ones. It can be passed inside the options object, or directly as the second argument:
69
141
 
70
142
  ```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'
143
+ const data = { $ref: 1, '@type': 'User', 'discount%': 10 };
144
+
145
+ toCamel(data); // { ref: 1, type: 'User', discount: 10 }
146
+ toCamel(data, { allowSymbols: true }); // { $ref: 1, '@type': 'User', 'discount%': 10 }
147
+ toCamel(data, { allowSymbols: ['$'] }); // { $ref: 1, type: 'User', discount: 10 }
148
+
149
+ // shorthand
150
+ toCamel(data, true); // same as { allowSymbols: true }
151
+ toCamel(data, ['$']); // same as { allowSymbols: ['$'] }
81
152
  ```
82
153
 
83
- ### Typical use: API responses
154
+ A kept symbol sticks to the start of the next word: `toPascal('$id', true)` → `'$Id'`. See [How keys are split into words](#how-keys-are-split-into-words) for the details.
155
+
156
+ ### `transform`
157
+
158
+ Only for `toDot` and `toPath`, which keep the original case of each word by default. `'lowercase'` or `'uppercase'` changes the case of the whole result, object keys included:
84
159
 
85
160
  ```ts
86
- import { toCamel, toSnake } from 'caseparser';
161
+ toDot('LAST_login_AT'); // 'LAST.login.AT'
162
+ toDot('LAST_login_AT', { transform: 'lowercase' }); // 'last.login.at'
163
+ toPath('LAST_login_AT', { transform: 'uppercase' }); // 'LAST/LOGIN/AT'
87
164
 
88
- const res = await fetch('/api/users/1');
89
- const user = toCamel(await res.json()); // { firstName, lastName, ... }
165
+ toDot({ user_ID: 1, LAST_name: 'Doe' }, { transform: 'lowercase' });
166
+ // { 'user.id': 1, 'last.name': 'Doe' }
90
167
 
91
- await fetch('/api/users/1', {
92
- method: 'PUT',
93
- body: JSON.stringify(toSnake(user)), // back to { first_name, ... }
94
- });
168
+ toDot('$UserId', { allowSymbols: true, transform: 'lowercase' }); // '$user.id'
95
169
  ```
96
170
 
97
- ### Type inference
171
+ `toSpace` has no `transform`: use `toLower` or `toUpper` instead. Don't chain functions for this (`toUpper(toPath(...))`): each one splits its input into words again, so `/` and `.` would be treated as separators or symbols.
98
172
 
99
- The resulting keys are inferred at the type level, so your editor autocompletes the converted names:
173
+ ### `separator`
174
+
175
+ Only for `toPath`. It joins the words with `'/'` by default, or with `'\\'`:
100
176
 
101
177
  ```ts
102
- const user = toCamel({ first_name: 'John', addresses: [{ postal_code: '61105' }] });
103
- // ^? { firstName: string; addresses: { postalCode: string }[] }
178
+ toPath('users/profilePicture'); // 'users/profile/Picture'
179
+ toPath('users/profilePicture', { separator: '\\' }); // 'users\\profile\\Picture'
180
+ toPath('users\\profilePicture', { separator: '/' }); // 'users/profile/Picture'
181
+ ```
182
+
183
+ In `toPath`, `/` and `\` in the input also separate words, so paths can be converted from one separator to the other. In the other functions they are symbols.
184
+
185
+ ## Type inference
186
+
187
+ The converted keys are inferred at the type level, so your editor autocompletes them and catches typos:
188
+
189
+ ```ts
190
+ const user = toCamel({ first_name: 'John', 'Home Addresses': [{ POSTAL_CODE: '61105' }] });
191
+ // ^? { firstName: string; homeAddresses: { postalCode: string }[] }
104
192
 
105
193
  user.firstName; // ✅
106
194
  user.first_name; // ❌ Property 'first_name' does not exist
107
195
  ```
108
196
 
109
- ### From any case
197
+ The options are part of the inference: `toCamel({ $ref: 1 }, ['$'])` is typed `{ $ref: number }`, and `toDot({ UserId: 1 }, { transform: 'lowercase' })` is typed `{ 'user.id': number }`. When the options are only known at runtime (e.g. a `boolean` variable), the keys are typed as `string`.
110
198
 
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:
199
+ ## How keys are split into words
112
200
 
113
- ```ts
114
- import { toCamel, toSnake } from 'caseparser';
201
+ Every function first splits the input into words, then joins them in the target case. A new word starts:
115
202
 
116
- toSnake('helloWorld'); // 'hello_world'
117
- toSnake('Hello World'); // 'hello_world'
118
- toSnake('HELLO-WORLD'); // 'hello_world'
203
+ - **at a separator:** `_`, `-`, `.` or a space, which are removed. Repeated or leading separators are ignored: `toSnake('__private_flag')` → `'private_flag'`
204
+ - **at an uppercase letter after a lowercase letter or a digit:** `helloWorld` → `hello`, `world`
205
+ - **at the last letter of an acronym:** `XMLHttpRequest` → `xml`, `http`, `request`, and `userID` → `user`, `id`
206
+ - **at a symbol**, whether it's kept or not
207
+ - **at `/` or `\`, only in `toPath`** (in the other functions they are symbols)
119
208
 
120
- toCamel({ user_id: 1, 'Last-Name': 'Doe', XMLHttpRequest: true });
121
- // ^? { userId: number; lastName: string; xmlHttpRequest: boolean }
209
+ Digits stay attached to the previous word: `toSnake('html5Parser')` → `'html5_parser'`.
210
+
211
+ A kept symbol sticks to the start of the next word, or to the end of the previous one when no word follows:
212
+
213
+ ```ts
214
+ toSnake('$$hello$World$$hi'); // 'hello_world_hi'
215
+ toSnake('$$hello$World$$hi', true); // '$$hello_$world_$$hi'
216
+ toSnake('user@name', true); // 'user_@name'
217
+ toSnake('total%_count', true); // 'total%_count'
122
218
  ```
123
219
 
124
- Words are split on `_`, `-`, `.` and spaces, and before an uppercase letter that starts a new word.
220
+ The inferred types follow the same rules.
221
+
222
+ ## Behavior and limitations
223
+
224
+ - **Only keys are converted, never values.** In `{ userName: 'johnDoe' }`, `userName` becomes `user_name` but `'johnDoe'` is kept. Strings inside arrays are kept too.
225
+ - **Only plain objects are traversed.** `Date`, `Map`, `Set` and class instances are returned as they are (same reference), without converting their contents.
226
+ - **Acronyms are kept together, but not restored:** `toSnake('userID')` → `'user_id'`, and back `toCamel('user_id')` → `'userId'`.
227
+ - **Words are lowercased** before converting (except by `toDot`, `toPath` and `toSpace`), so `toCamel('X-API-Key')` → `'xApiKey'` and `toCamel('First Name')` → `'firstName'`.
228
+ - **Title Case capitalizes every word**, including short ones: `toTitle('termsOfUse')` → `'Terms Of Use'`.
229
+ - **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. Keys are inferred up to ~120 characters; longer keys fail to compile with `Type instantiation is excessively deep and possibly infinite`. The runtime conversion has no limit.
230
+
231
+ ## Compatibility
232
+
233
+ | Environment | Supported |
234
+ | --- | --- |
235
+ | ESM (`import`) | Node.js 12.22+, Deno, Bun, bundlers |
236
+ | CommonJS (`require`) | Node.js 8+, Bun |
237
+ | TypeScript | 4.5+ for the `toX` functions, 4.1+ for the deprecated `<from>To<To>` functions (any `moduleResolution`: `node`, `node16`/`nodenext`, `bundler`) |
238
+ | Browsers | Any ES2015 browser (via bundler) |
239
+ | Edge | Cloudflare Workers |
240
+
241
+ On every change, CI runs the test suite on Node.js 22, 24 and 26, Bun and Deno, and in Chromium, Firefox and WebKit. It also checks the packed 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.1.
242
+
243
+ ## Deprecated `<from>To<To>` functions
244
+
245
+ > **Deprecated:** the `<from>To<To>` functions (e.g. `snakeToCamel`) are deprecated in favor of the `toX` functions and will be removed in the next major version, which will also require TypeScript 4.7+. They keep working until then.
246
+
247
+ ### Migrating to `toX`
125
248
 
126
- ## Conversion Types
249
+ 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`.
127
250
 
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).
251
+ 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 (pass `{ transform: 'lowercase' }` to get the old result):
252
+
253
+ | Call | `<from>To<To>` result | `toX` result |
254
+ | --- | --- | --- |
255
+ | `camelToSnake('userID')` / `toSnake('userID')` | `'user_i_d'` | `'user_id'` |
256
+ | `camelToSnake('XMLHttpRequest')` / `toSnake('XMLHttpRequest')` | `'_x_m_l_http_request'` | `'xml_http_request'` |
257
+ | `camelToSnake('HelloWorld')` / `toSnake('HelloWorld')` | `'_hello_world'` | `'hello_world'` |
258
+ | `snakeToCamel('user_ID')` / `toCamel('user_ID')` | `'userID'` | `'userId'` |
259
+ | `camelToDot('helloWorld')` / `toDot('helloWorld')` | `'hello.world'` | `'hello.World'` |
260
+
261
+ 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.
262
+
263
+ <details>
264
+ <summary>All 90 deprecated functions</summary>
129
265
 
130
266
  Every function is named `<from>To<To>`, e.g. `snakeToCamel`. The case names are:
131
267
 
@@ -142,8 +278,6 @@ Every function is named `<from>To<To>`, e.g. `snakeToCamel`. The case names are:
142
278
  | `title` | `Hello World` |
143
279
  | `sentence` | `Hello world` |
144
280
 
145
- All 90 functions:
146
-
147
281
  - **camelCase:** `camelToPascal`, `camelToSnake`, `camelToDash`, `camelToUpperSnake`, `camelToUpperDash`, `camelToTrain`, `camelToDot`, `camelToTitle`, `camelToSentence`
148
282
  - **PascalCase:** `pascalToCamel`, `pascalToSnake`, `pascalToDash`, `pascalToUpperSnake`, `pascalToUpperDash`, `pascalToTrain`, `pascalToDot`, `pascalToTitle`, `pascalToSentence`
149
283
  - **snake_case:** `snakeToCamel`, `snakeToPascal`, `snakeToDash`, `snakeToUpperSnake`, `snakeToUpperDash`, `snakeToTrain`, `snakeToDot`, `snakeToTitle`, `snakeToSentence`
@@ -155,30 +289,7 @@ All 90 functions:
155
289
  - **Title Case:** `titleToCamel`, `titleToPascal`, `titleToSnake`, `titleToDash`, `titleToUpperSnake`, `titleToUpperDash`, `titleToTrain`, `titleToDot`, `titleToSentence`
156
290
  - **Sentence case:** `sentenceToCamel`, `sentenceToPascal`, `sentenceToSnake`, `sentenceToDash`, `sentenceToUpperSnake`, `sentenceToUpperDash`, `sentenceToTrain`, `sentenceToDot`, `sentenceToTitle`
157
291
 
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
-
173
- ## Behavior and limitations
174
-
175
- - **Only keys are converted, never values.** In `{ userName: 'johnDoe' }`, `userName` becomes `user_name` but `'johnDoe'` is kept. Strings inside arrays are kept too.
176
- - **Only plain objects are traversed.** `Date`, `Map`, `Set` and class instances are returned as they are (same reference), without converting their contents.
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.
292
+ </details>
182
293
 
183
294
  ## Security
184
295