Add preserveConsecutiveUppercase option to CamelCase and add SplitWords type (#501)

Author: skarab42

source/camel-case.d.ts

@@ -1,39 +1,42 @@
-import type {WordSeparators} from '../source/internal';
-import type {Split} from './split';
+import type {SplitWords} from './split-words';
 
 /**
-Step by step takes the first item in an array literal, formats it and adds it to a string literal, and then recursively appends the remainder.
+CamelCase options.
 
-Only to be used by `CamelCaseStringArray<>`.
-
-@see CamelCaseStringArray
+@see {@link CamelCase}
 */
-type InnerCamelCaseStringArray<Parts extends readonly any[], PreviousPart> =
-	Parts extends [`${infer FirstPart}`, ...infer RemainingParts]
-		? FirstPart extends undefined
-			? ''
-			: FirstPart extends ''
-				? InnerCamelCaseStringArray<RemainingParts, PreviousPart>
-				: `${PreviousPart extends '' ? FirstPart : Capitalize<FirstPart>}${InnerCamelCaseStringArray<RemainingParts, FirstPart>}`
-		: '';
-
-/**
-Starts fusing the output of `Split<>`, an array literal of strings, into a camel-cased string literal.
+export type CamelCaseOptions = {
+	/**
+	Whether to preserved consecutive uppercase letter.
 
-It's separate from `InnerCamelCaseStringArray<>` to keep a clean API outwards to the rest of the code.
+	@default true
+	*/
+	preserveConsecutiveUppercase?: boolean;
+};
 
-@see Split
+/**
+Convert an array of words to camel-case.
 */
-type CamelCaseStringArray<Parts extends readonly string[]> =
-	Parts extends [`${infer FirstPart}`, ...infer RemainingParts]
-		? Uncapitalize<`${FirstPart}${InnerCamelCaseStringArray<RemainingParts, FirstPart>}`>
-		: never;
+type CamelCaseFromArray<
+	Words extends string[],
+	Options extends CamelCaseOptions,
+	OutputString extends string = '',
+> = Words extends [
+	infer FirstWord extends string,
+	...infer RemainingWords extends string[],
+]
+	? Options['preserveConsecutiveUppercase'] extends true
+		? `${Capitalize<FirstWord>}${CamelCaseFromArray<RemainingWords, Options>}`
+		: `${Capitalize<Lowercase<FirstWord>>}${CamelCaseFromArray<RemainingWords, Options>}`
+	: OutputString;
 
 /**
 Convert a string literal to camel-case.
 
 This can be useful when, for example, converting some kebab-cased command-line flags or a snake-cased database result.
 
+By default, consecutive uppercase letter are preserved. See {@link CamelCaseOptions.preserveConsecutiveUppercase preserveConsecutiveUppercase} option to change this behaviour.
+
 @example
 ```
 import type {CamelCase} from 'type-fest';
@@ -70,4 +73,6 @@ const dbResult: CamelCasedProperties<RawOptions> = {
 @category Change case
 @category Template literal
 */
-export type CamelCase<K> = K extends string ? CamelCaseStringArray<Split<K extends Uppercase<K> ? Lowercase<K> : K, WordSeparators>> : K;
+export type CamelCase<Type, Options extends CamelCaseOptions = {preserveConsecutiveUppercase: true}> = Type extends string
+	? Uncapitalize<CamelCaseFromArray<SplitWords<Type extends Uppercase<Type> ? Lowercase<Type> : Type>, Options>>
+	: Type;

source/camel-cased-properties-deep.d.ts

@@ -1,4 +1,4 @@
-import type {CamelCase} from './camel-case';
+import type {CamelCase, CamelCaseOptions} from './camel-case';
 
 /**
 Convert object properties to camel case recursively.
@@ -44,11 +44,11 @@ const result: CamelCasedPropertiesDeep<UserWithFriends> = {
 @category Template literal
 @category Object
 */
-export type CamelCasedPropertiesDeep<Value> = Value extends Function
+export type CamelCasedPropertiesDeep<Value, Options extends CamelCaseOptions = {preserveConsecutiveUppercase: true}> = Value extends Function
 	? Value
 	: Value extends Array<infer U>
-		? Array<CamelCasedPropertiesDeep<U>>
+		? Array<CamelCasedPropertiesDeep<U, Options>>
 		: Value extends Set<infer U>
-			? Set<CamelCasedPropertiesDeep<U>> : {
-				[K in keyof Value as CamelCase<K>]: CamelCasedPropertiesDeep<Value[K]>;
+			? Set<CamelCasedPropertiesDeep<U, Options>> : {
+				[K in keyof Value as CamelCase<K, Options>]: CamelCasedPropertiesDeep<Value[K], Options>;
 			};

source/camel-cased-properties.d.ts

@@ -1,4 +1,4 @@
-import type {CamelCase} from './camel-case';
+import type {CamelCase, CamelCaseOptions} from './camel-case';
 
 /**
 Convert object properties to camel case but not recursively.
@@ -27,10 +27,10 @@ const result: CamelCasedProperties<User> = {
 @category Template literal
 @category Object
 */
-export type CamelCasedProperties<Value> = Value extends Function
+export type CamelCasedProperties<Value, Options extends CamelCaseOptions = {preserveConsecutiveUppercase: true}> = Value extends Function
 	? Value
 	: Value extends Array<infer U>
 		? Value
 		: {
-			[K in keyof Value as CamelCase<K>]: Value[K];
+			[K in keyof Value as CamelCase<K, Options>]: Value[K];
 		};

source/internal.d.ts

@@ -93,3 +93,18 @@ export type FirstArrayElement<TArray extends UnknownArrayOrTuple> = TArray exten
 Extracts the type of an array or tuple minus the first element.
 */
 export type ArrayTail<TArray extends UnknownArrayOrTuple> = TArray extends readonly [unknown, ...infer TTail] ? TTail : [];
+
+/**
+Returns a boolean for whether the string is lowercased.
+*/
+export type IsLowerCase<T extends string> = T extends Lowercase<T> ? true : false;
+
+/**
+Returns a boolean for whether the string is uppercased.
+*/
+export type IsUpperCase<T extends string> = T extends Uppercase<T> ? true : false;
+
+/**
+Returns a boolean for whether the string is numeric.
+*/
+export type IsNumeric<T extends string> = T extends `${number}` ? true : false;

source/split-words.d.ts

@@ -0,0 +1,57 @@
+import type {IsLowerCase, IsNumeric, IsUpperCase, WordSeparators} from './internal';
+
+type SkipEmptyWord<Word extends string> = Word extends '' ? [] : [Word];
+
+type RemoveLastCharacter<Sentence extends string, Character extends string> = Sentence extends `${infer LeftSide}${Character}`
+	? SkipEmptyWord<LeftSide>
+	: never;
+
+/**
+Split a string (almost) like Lodash's `_.words()` function.
+
+- Split on each word that begins with a capital letter.
+- Split on each {@link WordSeparators}.
+- Split on numeric sequence.
+
+@example
+```
+type Words0 = SplitWords<'helloWorld'>; // ['hello', 'World']
+type Words1 = SplitWords<'helloWORLD'>; // ['hello', 'WORLD']
+type Words2 = SplitWords<'hello-world'>; // ['hello', 'world']
+type Words3 = SplitWords<'--hello the_world'>; // ['hello', 'the', 'world']
+type Words4 = SplitWords<'lifeIs42'>; // ['life', 'Is', '42']
+```
+
+@internal
+@category Change case
+@category Template literal
+*/
+export type SplitWords<
+	Sentence extends string,
+	LastCharacter extends string = '',
+	CurrentWord extends string = '',
+> = Sentence extends `${infer FirstCharacter}${infer RemainingCharacters}`
+	? FirstCharacter extends WordSeparators
+		// Skip word separator
+		? [...SkipEmptyWord<CurrentWord>, ...SplitWords<RemainingCharacters, LastCharacter>]
+		: LastCharacter extends ''
+			// Fist char of word
+			? SplitWords<RemainingCharacters, FirstCharacter, FirstCharacter>
+			// Case change: non-numeric to numeric, push word
+			: [false, true] extends [IsNumeric<LastCharacter>, IsNumeric<FirstCharacter>]
+				? [...SkipEmptyWord<CurrentWord>, ...SplitWords<RemainingCharacters, FirstCharacter, FirstCharacter>]
+				// Case change: numeric to non-numeric, push word
+				: [true, false] extends [IsNumeric<LastCharacter>, IsNumeric<FirstCharacter>]
+					? [...SkipEmptyWord<CurrentWord>, ...SplitWords<RemainingCharacters, FirstCharacter, FirstCharacter>]
+					// No case change: concat word
+					: [true, true] extends [IsNumeric<LastCharacter>, IsNumeric<FirstCharacter>]
+						? SplitWords<RemainingCharacters, FirstCharacter, `${CurrentWord}${FirstCharacter}`>
+					// Case change: lower to upper, push word
+						: [true, true] extends [IsLowerCase<LastCharacter>, IsUpperCase<FirstCharacter>]
+							? [...SkipEmptyWord<CurrentWord>, ...SplitWords<RemainingCharacters, FirstCharacter, FirstCharacter>]
+						// Case change: upper to lower, brings back the last character, push word
+							: [true, true] extends [IsUpperCase<LastCharacter>, IsLowerCase<FirstCharacter>]
+								? [...RemoveLastCharacter<CurrentWord, LastCharacter>, ...SplitWords<RemainingCharacters, FirstCharacter, `${LastCharacter}${FirstCharacter}`>]
+							// No case change: concat word
+								: SplitWords<RemainingCharacters, FirstCharacter, `${CurrentWord}${FirstCharacter}`>
+	: [...SkipEmptyWord<CurrentWord>];

test-d/camel-case.ts

@@ -1,9 +1,5 @@
 import {expectType, expectAssignable} from 'tsd';
-import type {CamelCase, Split} from '../index';
-
-// Split
-const prefixSplit: Split<'--very-prefixed', '-'> = ['', '', 'very', 'prefixed'];
-expectType<['', '', 'very', 'prefixed']>(prefixSplit);
+import type {CamelCase} from '../index';
 
 // CamelCase
 const camelFromPascal: CamelCase<'FooBar'> = 'fooBar';
@@ -70,3 +66,12 @@ expectAssignable<CamelCasedProperties<RawOptions>>({
 	quzQux: 6,
 	otherField: false,
 });
+
+expectType<CamelCase<'fooBAR'>>('fooBAR');
+expectType<CamelCase<'fooBAR', {preserveConsecutiveUppercase: false}>>('fooBar');
+
+expectType<CamelCase<'fooBARBiz'>>('fooBARBiz');
+expectType<CamelCase<'fooBARBiz', {preserveConsecutiveUppercase: false}>>('fooBarBiz');
+
+expectType<CamelCase<'foo BAR-Biz_BUZZ'>>('fooBARBizBUZZ');
+expectType<CamelCase<'foo BAR-Biz_BUZZ', {preserveConsecutiveUppercase: false}>>('fooBarBizBuzz');

test-d/camel-cased-properties-deep.ts

@@ -11,6 +11,14 @@ expectType<() => {a: string}>(fooBar);
 declare const bar: CamelCasedPropertiesDeep<Set<{fooBar: string}>>;
 expectType<Set<{fooBar: string}>>(bar);
 
+type bazBizDeep = {fooBAR: number; baz: {fooBAR: number; BARFoo: string}};
+
+declare const baz: CamelCasedPropertiesDeep<bazBizDeep>;
+expectType<{fooBAR: number; baz: {fooBAR: number; bARFoo: string}}>(baz);
+
+declare const biz: CamelCasedPropertiesDeep<bazBizDeep, {preserveConsecutiveUppercase: false}>;
+expectType<{fooBar: number; baz: {fooBar: number; barFoo: string}}>(biz);
+
 // Verify example
 type User = {
 	UserId: number;

test-d/camel-cased-properties.ts

@@ -2,7 +2,6 @@ import {expectType} from 'tsd';
 import type {CamelCasedProperties} from '../index';
 
 declare const foo: CamelCasedProperties<{A: number; B: {C: string}}>;
-
 expectType<{a: number; b: {C: string}}>(foo);
 
 declare const bar: CamelCasedProperties<Array<{helloWorld: string}>>;
@@ -11,6 +10,12 @@ expectType<Array<{helloWorld: string}>>(bar);
 declare const fooBar: CamelCasedProperties<() => {a: string}>;
 expectType<() => {a: string}>(fooBar);
 
+declare const baz: CamelCasedProperties<{fooBAR: number; BARFoo: string}>;
+expectType<{fooBAR: number; bARFoo: string}>(baz);
+
+declare const biz: CamelCasedProperties<{fooBAR: number; BARFoo: string}, {preserveConsecutiveUppercase: false}>;
+expectType<{fooBar: number; barFoo: string}>(biz);
+
 // Verify example
 type User = {
 	UserId: number;

test-d/split-words.ts

@@ -0,0 +1,91 @@
+import {expectType} from 'tsd';
+import type {SplitWords} from '../source/split-words';
+
+expectType<SplitWords<''>>([]);
+expectType<SplitWords<'a'>>(['a']);
+expectType<SplitWords<'B'>>(['B']);
+expectType<SplitWords<'aa'>>(['aa']);
+expectType<SplitWords<'aB'>>(['a', 'B']);
+expectType<SplitWords<'Ba'>>(['Ba']);
+expectType<SplitWords<'BB'>>(['BB']);
+expectType<SplitWords<'aaa'>>(['aaa']);
+expectType<SplitWords<'aaB'>>(['aa', 'B']);
+expectType<SplitWords<'aBa'>>(['a', 'Ba']);
+expectType<SplitWords<'aBB'>>(['a', 'BB']);
+expectType<SplitWords<'Baa'>>(['Baa']);
+expectType<SplitWords<'BaB'>>(['Ba', 'B']);
+expectType<SplitWords<'BBa'>>(['B', 'Ba']);
+expectType<SplitWords<'BBB'>>(['BBB']);
+expectType<SplitWords<'aaaa'>>(['aaaa']);
+expectType<SplitWords<'aaaB'>>(['aaa', 'B']);
+expectType<SplitWords<'aaBa'>>(['aa', 'Ba']);
+expectType<SplitWords<'aaBB'>>(['aa', 'BB']);
+expectType<SplitWords<'aBaa'>>(['a', 'Baa']);
+expectType<SplitWords<'aBaB'>>(['a', 'Ba', 'B']);
+expectType<SplitWords<'aBBa'>>(['a', 'B', 'Ba']);
+expectType<SplitWords<'aBBB'>>(['a', 'BBB']);
+expectType<SplitWords<'Baaa'>>(['Baaa']);
+expectType<SplitWords<'BaaB'>>(['Baa', 'B']);
+expectType<SplitWords<'BaBa'>>(['Ba', 'Ba']);
+expectType<SplitWords<'BaBB'>>(['Ba', 'BB']);
+expectType<SplitWords<'BBaa'>>(['B', 'Baa']);
+expectType<SplitWords<'BBaB'>>(['B', 'Ba', 'B']);
+expectType<SplitWords<'BBBa'>>(['BB', 'Ba']);
+expectType<SplitWords<'BBBB'>>(['BBBB']);
+expectType<SplitWords<'aaaaa'>>(['aaaaa']);
+expectType<SplitWords<'aaaaB'>>(['aaaa', 'B']);
+expectType<SplitWords<'aaaBa'>>(['aaa', 'Ba']);
+expectType<SplitWords<'aaaBB'>>(['aaa', 'BB']);
+expectType<SplitWords<'aaBaa'>>(['aa', 'Baa']);
+expectType<SplitWords<'aaBaB'>>(['aa', 'Ba', 'B']);
+expectType<SplitWords<'aaBBa'>>(['aa', 'B', 'Ba']);
+expectType<SplitWords<'aaBBB'>>(['aa', 'BBB']);
+expectType<SplitWords<'aBaaa'>>(['a', 'Baaa']);
+expectType<SplitWords<'aBaaB'>>(['a', 'Baa', 'B']);
+expectType<SplitWords<'aBaBa'>>(['a', 'Ba', 'Ba']);
+expectType<SplitWords<'aBaBB'>>(['a', 'Ba', 'BB']);
+expectType<SplitWords<'aBBaa'>>(['a', 'B', 'Baa']);
+expectType<SplitWords<'aBBaB'>>(['a', 'B', 'Ba', 'B']);
+expectType<SplitWords<'aBBBa'>>(['a', 'BB', 'Ba']);
+expectType<SplitWords<'aBBBB'>>(['a', 'BBBB']);
+expectType<SplitWords<'Baaaa'>>(['Baaaa']);
+expectType<SplitWords<'BaaaB'>>(['Baaa', 'B']);
+expectType<SplitWords<'BaaBa'>>(['Baa', 'Ba']);
+expectType<SplitWords<'BaaBB'>>(['Baa', 'BB']);
+expectType<SplitWords<'BaBaa'>>(['Ba', 'Baa']);
+expectType<SplitWords<'BaBaB'>>(['Ba', 'Ba', 'B']);
+expectType<SplitWords<'BaBBa'>>(['Ba', 'B', 'Ba']);
+expectType<SplitWords<'BaBBB'>>(['Ba', 'BBB']);
+expectType<SplitWords<'BBaaa'>>(['B', 'Baaa']);
+expectType<SplitWords<'BBaaB'>>(['B', 'Baa', 'B']);
+expectType<SplitWords<'BBaBa'>>(['B', 'Ba', 'Ba']);
+expectType<SplitWords<'BBaBB'>>(['B', 'Ba', 'BB']);
+expectType<SplitWords<'BBBaa'>>(['BB', 'Baa']);
+expectType<SplitWords<'BBBaB'>>(['BB', 'Ba', 'B']);
+expectType<SplitWords<'BBBBa'>>(['BBB', 'Ba']);
+expectType<SplitWords<'BBBBB'>>(['BBBBB']);
+
+expectType<SplitWords<'hello world'>>(['hello', 'world']);
+expectType<SplitWords<'Hello-world'>>(['Hello', 'world']);
+expectType<SplitWords<'hello_world'>>(['hello', 'world']);
+expectType<SplitWords<'hello  world'>>(['hello', 'world']);
+expectType<SplitWords<'Hello--world'>>(['Hello', 'world']);
+expectType<SplitWords<'hello__world'>>(['hello', 'world']);
+expectType<SplitWords<'   hello  world'>>(['hello', 'world']);
+expectType<SplitWords<'---Hello--world'>>(['Hello', 'world']);
+expectType<SplitWords<'___hello__world'>>(['hello', 'world']);
+expectType<SplitWords<'hello  world   '>>(['hello', 'world']);
+expectType<SplitWords<'Hello--world--'>>(['Hello', 'world']);
+expectType<SplitWords<'hello__world___'>>(['hello', 'world']);
+expectType<SplitWords<'___ hello -__  _world'>>(['hello', 'world']);
+expectType<SplitWords<'__HelloWorld-HELLOWorld helloWORLD'>>(['Hello', 'World', 'HELLO', 'World', 'hello', 'WORLD']);
+
+expectType<SplitWords<'item0'>>(['item', '0']);
+expectType<SplitWords<'item01'>>(['item', '01']);
+expectType<SplitWords<'item10'>>(['item', '10']);
+expectType<SplitWords<'item010'>>(['item', '010']);
+expectType<SplitWords<'0item0'>>(['0', 'item', '0']);
+expectType<SplitWords<'01item01'>>(['01', 'item', '01']);
+expectType<SplitWords<'10item10'>>(['10', 'item', '10']);
+expectType<SplitWords<'010item010'>>(['010', 'item', '010']);
+expectType<SplitWords<'item0_item_1 item -2'>>(['item', '0', 'item', '1', 'item', '2']);