type-fest
Version:
A collection of essential TypeScript types
146 lines (117 loc) • 5.42 kB
TypeScript
import type {UnwrapBrandedPrimitive} from './unwrap-branded-primitive.d.ts';
import type {ApplyDefaultOptions} from './apply-default-options.d.ts';
import type {IsStringLiteral} from './is-string-literal.d.ts';
import type {Merge} from './merge.d.ts';
import type {_DefaultWordsOptions, _Words, WordsOptions} from './words.d.ts';
/**
Options for the `CamelCase` type.
@see {@link CamelCase}
*/
export type CamelCaseOptions = WordsOptions & {
/**
Whether to preserve consecutive uppercase letters.
Note: A string that is entirely uppercase, such as `'FOO_BAR'`, is lowercased before it is split into words, so the option has no effect on it and the result is `'fooBar'` either way. This keeps `CamelCase<'FOO_BAR'>` the same regardless of the option.
@default false
*/
preserveConsecutiveUppercase?: boolean;
/**
Whether to preserve leading underscores, like in `_id` and `__typename`.
This matches the behavior of the [`camelcase`](https://github.com/sindresorhus/camelcase) package v9+. Unlike that package, a leading `$` is removed with the default `splitOnPunctuation` option, because it is ASCII punctuation, which separates words.
@default true
*/
preserveLeadingUnderscores?: boolean;
};
export type _DefaultCamelCaseOptions = Merge<_DefaultWordsOptions, {
splitOnNumbers: false;
preserveConsecutiveUppercase: false;
preserveLeadingUnderscores: true;
}>;
/**
Extract leading underscores from a string.
@example
```
type A = LeadingUnderscores<'__foo_bar'>;
//=> '__'
type B = LeadingUnderscores<'foo_bar'>;
//=> ''
```
*/
type LeadingUnderscores<Type extends string, Underscores extends string = ''> =
Type extends `_${infer Rest}`
? LeadingUnderscores<Rest, `_${Underscores}`>
: Underscores;
/**
Convert an array of words to camel-case.
The first word is uncapitalized and every other word is capitalized. The first word is never capitalized and then uncapitalized again, because `Capitalize<'ß'>` is `'SS'` and `Uncapitalize<'SS'>` is `'sS'`.
*/
type CamelCaseFromArray<
WordList extends string[],
Options extends Required<CamelCaseOptions>,
OutputString extends string = '',
> = WordList extends [
infer FirstWord extends string,
...infer RemainingWords extends string[],
]
? (Options['preserveConsecutiveUppercase'] extends true ? FirstWord : Lowercase<FirstWord>) extends infer Word extends string
? CamelCaseFromArray<RemainingWords, Options, OutputString extends '' ? Uncapitalize<Word> : `${OutputString}${Capitalize<Word>}`>
: never
: 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 letters are not preserved. See {@link CamelCaseOptions.preserveConsecutiveUppercase preserveConsecutiveUppercase} option to change this behaviour.
Leading underscores are kept, matching the runtime behavior of [`camelcase`](https://github.com/sindresorhus/camelcase) v9+. Set the `preserveLeadingUnderscores` option to `false` to remove them.
In a generic function, use concrete option values before relying on an exact result spelling. While any option is generic, TypeScript can read the result as if the default options were used.
@example
```
import type {CamelCase} from 'type-fest';
// Simple
const someVariable: CamelCase<'foo-bar'> = 'fooBar';
const preserveConsecutiveUppercase: CamelCase<'foo-BAR-baz', {preserveConsecutiveUppercase: true}> = 'fooBARBaz';
const noSplitOnNumbers: CamelCase<'p2p_network'> = 'p2pNetwork';
const splitOnNumbers: CamelCase<'p2p_network', {splitOnNumbers: true}> = 'p2PNetwork';
const splitOnPunctuation: CamelCase<'foo-bar:BAZ'> = 'fooBarBaz';
const noSplitOnPunctuation: CamelCase<'foo-bar:baz', {splitOnPunctuation: false}> = 'fooBar:baz';
const preserveLeadingUnderscores: CamelCase<'_foo_bar'> = '_fooBar';
const noPreserveLeadingUnderscores: CamelCase<'_foo_bar', {preserveLeadingUnderscores: false}> = 'fooBar';
// Advanced
type CamelCasedProperties<T> = {
[K in keyof T as CamelCase<K>]: T[K]
};
type RawOptions = {
'dry-run': boolean;
'full_family_name': string;
foo: number;
BAR: string;
QUZ_QUX: number;
'OTHER-FIELD': boolean;
};
const dbResult: CamelCasedProperties<RawOptions> = {
dryRun: true,
fullFamilyName: 'bar.js',
foo: 123,
bar: 'foo',
quzQux: 6,
otherField: false,
};
```
@category Change case
@category Template literal
*/
export type CamelCase<Type, Options extends CamelCaseOptions = {}> = Type extends string
? IsStringLiteral<Type> extends false
? Type
// The brand is removed first, because the entirely-uppercase pre-lowering and the leading underscores must read the string itself: an intersection with a brand does not reduce under `Uppercase` and does not match `_`. The word splitter can then reuse the normalized input and resolved options.
: CamelCaseUnbranded<UnwrapBrandedPrimitive<Type>, Options>
: Type;
type CamelCaseUnbranded<Type extends string, Options extends CamelCaseOptions> =
ApplyDefaultOptions<CamelCaseOptions, _DefaultCamelCaseOptions, Options> extends infer OptionsWithDefaults extends Required<CamelCaseOptions>
? `${OptionsWithDefaults['preserveLeadingUnderscores'] extends false
? ''
: LeadingUnderscores<Type>
}${CamelCaseFromArray<
_Words<Type extends Uppercase<Type> ? Lowercase<Type> : Type, OptionsWithDefaults>,
OptionsWithDefaults
>}`
: never;
export {};