type-fest
Version:
A collection of essential TypeScript types
185 lines (151 loc) • 8.13 kB
TypeScript
import type {AsciiPunctuationCharacter} from './ascii-punctuation-character.d.ts';
import type {WordSeparators} from './internal/index.d.ts';
import type {DigitCharacter} from './characters.d.ts';
import type {ApplyDefaultOptions} from './apply-default-options.d.ts';
import type {IsLowercase} from './is-lowercase.d.ts';
import type {UnwrapBrandedPrimitive} from './unwrap-branded-primitive.d.ts';
import type {IsStringLiteral} from './is-string-literal.d.ts';
import type {IsUppercase} from './is-uppercase.d.ts';
type SkipEmptyWord<Word extends string> = Word extends '' ? [] : [Word];
type RemoveLastCharacter<
Sentence extends string,
Character extends string,
> = Sentence extends `${infer LeftSide}${Character}`
? SkipEmptyWord<LeftSide>
: never;
/**
Options for the `Words` type.
@see {@link Words}
*/
export type WordsOptions = {
/**
Split on numeric sequence.
@default `true` for `Words`, and `false` for the case conversion types, such as `CamelCase` and `KebabCase`
@example
```
import type {Words} from 'type-fest';
type Example1 = Words<'p2pNetwork', {splitOnNumbers: true}>;
//=> ['p', '2', 'p', 'Network']
type Example2 = Words<'p2pNetwork', {splitOnNumbers: false}>;
//=> ['p2p', 'Network']
```
*/
splitOnNumbers?: boolean;
/**
Split on {@link AsciiPunctuationCharacter | ASCII punctuation characters} (for example, `#`, `&`, `*`, `:`, `?`, `@`, `~`). Hyphens and underscores always separate words, regardless of this option.
@default true
@example
```
import type {Words} from 'type-fest';
type Example1 = Words<'hello:world', {splitOnPunctuation: true}>;
//=> ['hello', 'world']
type Example2 = Words<'hello:world', {splitOnPunctuation: false}>;
//=> ['hello:world']
```
*/
splitOnPunctuation?: boolean;
};
export type _DefaultWordsOptions = {
splitOnNumbers: true;
splitOnPunctuation: true;
};
/**
Split a string similar to Lodash's `_.words()` function.
- Split on each word that begins with a capital letter.
- Split on each {@link WordSeparators}.
- Split on each {@link AsciiPunctuationCharacter} (unless {@link WordsOptions.splitOnPunctuation} is disabled).
- Split on numeric sequence.
@example
```
import type {Words} from 'type-fest';
type Words0 = Words<'helloWorld'>;
//=> ['hello', 'World']
type Words1 = Words<'helloWORLD'>;
//=> ['hello', 'WORLD']
type Words2 = Words<'hello-world'>;
//=> ['hello', 'world']
type Words3 = Words<'--hello the_world'>;
//=> ['hello', 'the', 'world']
type Words4 = Words<'lifeIs42'>;
//=> ['life', 'Is', '42']
type Words5 = Words<'p2pNetwork', {splitOnNumbers: false}>;
//=> ['p2p', 'Network']
type Words6 = Words<'hello:world'>;
//=> ['hello', 'world']
type Words7 = Words<'hello:world', {splitOnPunctuation: false}>;
//=> ['hello:world']
type Words8 = Words<'hello::world'>;
//=> ['hello', 'world']
```
@category Change case
@category Template literal
*/
export type Words<Sentence extends string, Options extends WordsOptions = {}> = Sentence extends unknown // For distributing `Sentence`
// A branded or tagged string can be a literal, so remove the brand once before classification and walking; an intersection with a non-empty object type does not match a template literal pattern.
? (Sentence extends object ? UnwrapBrandedPrimitive<Sentence> : Sentence) extends infer Input extends string
? IsStringLiteral<Input> extends true // A string type with an infinite set of possible values cannot be walked character by character, so only the element type survives.
// Option objects are not distributed, so for a union of option objects, an option that differs between the members reads as `boolean`, which is unsupported.
? _Words<Input, ApplyDefaultOptions<WordsOptions, _DefaultWordsOptions, Options>>
: string[]
: never
: never; // Should never happen, since `Sentence` is a string
/**
Splits a known unbranded string literal using resolved options. Casing types reuse this entry point after checking and normalizing their own inputs.
*/
export type _Words<
Sentence extends string,
Options extends Required<WordsOptions>,
LastCharacter extends string = '',
CurrentWord extends string = '',
// The words found so far are kept in `Result`, so the recursion is in tail position and a long sentence does not hit the recursion limit.
Result extends string[] = [],
> = Sentence extends `${infer FirstCharacter}${infer RemainingCharacters}`
? FirstCharacter extends WordSeparators | (Options['splitOnPunctuation'] extends false ? never : AsciiPunctuationCharacter)
// Skip word separator
? _Words<RemainingCharacters, Options, '', '', [...Result, ...SkipEmptyWord<CurrentWord>]>
: LastCharacter extends ''
// First character of word
? _Words<RemainingCharacters, Options, FirstCharacter, FirstCharacter, Result>
// Case change between numeric and non-numeric characters.
: [IsDigit<LastCharacter>, IsDigit<FirstCharacter>] extends [false, true] | [true, false]
? Options['splitOnNumbers'] extends true
// Split on number: push word
? _Words<RemainingCharacters, Options, FirstCharacter, FirstCharacter, [...Result, ...SkipEmptyWord<CurrentWord>]>
// No split on number: concat word
: _Words<RemainingCharacters, Options, FirstCharacter, `${CurrentWord}${FirstCharacter}`, Result>
// No case change: concat word
: [true, true] extends [IsDigit<LastCharacter>, IsDigit<FirstCharacter>]
? _Words<RemainingCharacters, Options, FirstCharacter, `${CurrentWord}${FirstCharacter}`, Result>
// Case change: lower to upper, push word
: [true, true] extends [IsLowercase<LastCharacter>, IsUppercase<FirstCharacter>]
// Only a capital letter starts a new word. A character with no case at all, such as a Han character or an emoji, satisfies both case predicates but is its own lowercase form, so it is not one.
? IsCapitalLetter<FirstCharacter> extends true
? _Words<RemainingCharacters, Options, FirstCharacter, FirstCharacter, [...Result, ...SkipEmptyWord<CurrentWord>]>
: _Words<RemainingCharacters, Options, FirstCharacter, `${CurrentWord}${FirstCharacter}`, Result>
// Case change: upper to lower, brings back the last character, push word
: [true, true] extends [IsUppercase<LastCharacter>, IsLowercase<FirstCharacter>]
// Only a capital followed by a lowercase letter starts a new word. Punctuation or a character with no case after an acronym, as in `userID?`, satisfies both case predicates, so it would otherwise split off the last capital.
? [IsCapitalLetter<LastCharacter>, IsLowercaseLetter<FirstCharacter>] extends [true, true]
? _Words<
RemainingCharacters, Options, FirstCharacter, `${LastCharacter}${FirstCharacter}`,
[...Result, ...RemoveLastCharacter<CurrentWord, LastCharacter>]
>
: _Words<RemainingCharacters, Options, FirstCharacter, `${CurrentWord}${FirstCharacter}`, Result>
// No case change: concat word
: _Words<RemainingCharacters, Options, FirstCharacter, `${CurrentWord}${FirstCharacter}`, Result>
: [...Result, ...SkipEmptyWord<CurrentWord>];
/**
Whether the given character is an ASCII decimal digit.
*/
type IsDigit<Character extends string> = Character extends DigitCharacter ? true : false;
/**
Whether the given character is a capital letter, which is what decides whether it begins a new word.
A character with no case at all, such as a Han character or an emoji, is its own lowercase form and so is not a capital. Every other cased character is, in any script, so this is deliberately not restricted to ASCII: `É` and `Ä` are capitals just as `A` is.
*/
type IsCapitalLetter<Character extends string> = Lowercase<Character> extends Character ? false : true;
/**
Whether the given character is a lowercase letter, which is what decides whether a preceding capital begins a new word.
Like {@link IsCapitalLetter}, a character with no case at all, such as punctuation, a Han character, or an emoji, is its own uppercase form and so is not a lowercase letter.
*/
type IsLowercaseLetter<Character extends string> = Uppercase<Character> extends Character ? false : true;
export {};