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 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 { 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)):
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 { snakeToCamel, camelToSnake } from 'caseparser';
86
+ import { toCamel, toSnake } from 'caseparser';
72
87
 
73
88
  const res = await fetch('/api/users/1');
74
- const user = snakeToCamel(await res.json()); // { firstName, lastName, ... }
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(camelToSnake(user)), // back to { first_name, ... }
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 = snakeToCamel({ first_name: 'John', addresses: [{ postal_code: '61105' }] });
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
- All 56 functions:
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
- - **camelCase:** `camelToPascal`, `camelToSnake`, `camelToDash`, `camelToUpperSnake`, `camelToUpperDash`, `camelToTrain`, `camelToDot`
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 split letter by letter**, because every uppercase letter starts a new word: `camelToSnake('userID')` → `'user_i_d'`. Prefer `userId` style keys.
125
- - **Train-Case words are lowercased** before converting, so `trainToCamel('X-API-Key')` → `'xApiKey'`.
126
- - **Numbers are not word boundaries:** `camelToSnake('html5Parser')` → `'html5_parser'`, `snakeToCamel('user_1_name')` → `'user1Name'`.
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