@kaelyx/ts-kit

Appearance

@kaelyx/ts-kit / string / convertCase

Function: convertCase() ​

convertCase(input, options): string

Defined in: string/convert-case/convert-case.ts:72

Converts a string to another case, for example from camelCase to snake_case. The input can be in any case: the function splits it into words first, then writes the words in the new case.

Words are separated by any character that is not a letter or a digit, and by a change from lowercase to uppercase. A run of capitals is an acronym, so 'parseABCValue' has the words parse, ABC and Value. The options control how acronyms and digits are read:

  • Known acronyms (ConvertCaseAcronyms and acronyms) split a run of capitals that is made only of them, and they stay in capitals where a case starts a word with a capital.
  • unknownAcronyms and minAcronymLength control the other runs of capitals.
  • digits controls which word the digits go into.

Parameters ​

input ​

string

The string to convert. If it has no letters or digits, the result is ''.

options ​

ConvertCaseOptions

The case of the result, and how to read acronyms and digits. See ConvertCaseOptions.

Returns ​

string

The words of the input, written in the new case.

Throws ​

If options.to is not a ConvertCaseStyle.

Throws ​

If options.minAcronymLength is not an integer of 1 or more.

Example ​

ts
convertCase('helloWorld', { to: 'snake' }) // 'hello_world'
convertCase('hello world', { to: 'constant' }) // 'HELLO_WORLD'
convertCase('hello world', { to: 'ada' }) // 'Hello_World'
convertCase('HelloWorld', { to: 'kebab' }) // 'hello-world'
convertCase('hello_world', { to: 'cobol' }) // 'HELLO-WORLD'
convertCase('hello world', { to: 'train' }) // 'Hello-World'
convertCase('Hello World', { to: 'flat' }) // 'helloworld'
convertCase('hello-world', { to: 'upperFlat' }) // 'HELLOWORLD'
convertCase('hello_world', { to: 'pascal' }) // 'HelloWorld'
convertCase('HELLO_WORLD', { to: 'camel' }) // 'helloWorld'
convertCase('helloWorld', { to: 'lower' }) // 'hello world'
convertCase('helloWorld', { to: 'upper' }) // 'HELLO WORLD'
convertCase('hello_world', { to: 'title' }) // 'Hello World'
convertCase('', { to: 'camel' }) // ''

// The option values are also exported as objects
convertCase('helloWorld', { to: ConvertCaseStyle.snake }) // 'hello_world'
convertCase('base64Encode', { to: ConvertCaseStyle.snake, digits: ConvertCaseDigits.separate }) // 'base_64_encode'

// Acronyms
convertCase('XMLHTTPRequest', { to: 'snake' }) // 'xml_http_request'
convertCase('xml_http_request', { to: 'pascal' }) // 'XMLHTTPRequest'
convertCase('my_gql_api', { to: 'camel', acronyms: ['GQL'] }) // 'myGQLAPI'
convertCase('parseABCValue', { to: 'snake', unknownAcronyms: 'split' }) // 'parse_a_b_c_value'
convertCase('IOError', { to: 'snake', minAcronymLength: 3 }) // 'i_o_error'

// Digits
convertCase('base64Encode', { to: 'snake' }) // 'base64_encode'
convertCase('base64Encode', { to: 'snake', digits: 'right' }) // 'base_64encode'
convertCase('base64Encode', { to: 'snake', digits: 'separate' }) // 'base_64_encode'

convertCase('hello', { to: 'snake', minAcronymLength: 0 }) // throws RangeError

Types ​

ConvertCaseDigits type ​

ConvertCaseDigits = ValueOf<typeof ConvertCaseDigits>

Defined in: string/convert-case/convert-case.types.ts:85

Which word the digits go into. See the ConvertCaseDigits values.

ConvertCaseStyle type ​

ConvertCaseStyle = ValueOf<typeof ConvertCaseStyle>

Defined in: string/convert-case/convert-case.types.ts:18

A case that convertCase can produce. See the ConvertCaseStyle values.

ConvertCaseUnknownAcronyms type ​

ConvertCaseUnknownAcronyms = ValueOf<typeof ConvertCaseUnknownAcronyms>

Defined in: string/convert-case/convert-case.types.ts:61

How convertCase reads an unknown acronym. See the ConvertCaseUnknownAcronyms values.

ConvertCaseFormat interface ​

Defined in: string/convert-case/convert-case.types.ts:113

How one case writes the words: what goes between them, and how each word is cased. See ConvertCaseFormats.

Properties ​

separator ​

readonly separator: string

Defined in: string/convert-case/convert-case.types.ts:115

The text that goes between the words, such as '_' in snake case.

word ​

readonly word: (word, index, isAcronym) => string

Defined in: string/convert-case/convert-case.types.ts:124

Writes one word in the case.

Parameters ​
word ​

string

The word, as it is in the input.

index ​

number

The position of the word, from 0.

isAcronym ​

boolean

true if the word is a known acronym.

Returns ​

string

The word in the case.

ConvertCaseOptions interface ​

Defined in: string/convert-case/convert-case.types.ts:215

Options for convertCase.

Properties ​

acronyms? ​

readonly optional acronyms?: readonly string[]

Defined in: string/convert-case/convert-case.types.ts:231

More acronyms to know, in addition to ConvertCaseAcronyms. Case does not matter.

A known acronym has two effects:

  • A run of capitals that is made only of known acronyms is split into them: 'XMLHTTPRequest' gives XML, HTTP and Request.
  • Where a case starts a word with a capital (ada, train, pascal, camel after the first word, and title), a known acronym is written in capitals: 'parse_json' in camel case is 'parseJSON'.
Default ​
ts
[]
digits? ​

readonly optional digits?: "left" | "right" | "separate"

Defined in: string/convert-case/convert-case.types.ts:253

Which word the digits go into. See ConvertCaseDigits.

Default ​
ts
ConvertCaseDigits.left
minAcronymLength? ​

readonly optional minAcronymLength?: number

Defined in: string/convert-case/convert-case.types.ts:247

The smallest number of capitals that make an unknown acronym. A shorter run is split into single letters. With 3, 'IOError' gives I, O and Error. Must be an integer of 1 or more.

Default ​
ts
2
to ​

readonly to: "flat" | "snake" | "constant" | "ada" | "kebab" | "cobol" | "train" | "upperFlat" | "pascal" | "camel" | "lower" | "upper" | "title"

Defined in: string/convert-case/convert-case.types.ts:217

The case of the result. See ConvertCaseStyle.

unknownAcronyms? ​

readonly optional unknownAcronyms?: "split" | "together"

Defined in: string/convert-case/convert-case.types.ts:239

How to read a run of capitals that is not a known acronym. This applies only to a run that is next to lowercase letters, so an all-capital word such as HELLO in 'HELLO_WORLD' is always one word. See ConvertCaseUnknownAcronyms.

Default ​
ts
ConvertCaseUnknownAcronyms.together