UNPKG

type-fest

Version:

A collection of essential TypeScript types

113 lines (91 loc) • 3.84 kB
import type {And} from './and.d.ts'; import type {UnwrapBrandedPrimitive} from './unwrap-branded-primitive.d.ts'; import type {ApplyDefaultOptions} from './apply-default-options.d.ts'; import type {Not} from './not.d.ts'; import type {IsStringLiteral} from './is-string-literal.d.ts'; import type {Or} from './or.d.ts'; import type {StringToArray} from './string-to-array.d.ts'; /** Options for the `Split` type. @see {@link Split} */ export type SplitOptions = { /** When enabled, instantiations with non-literal string types (e.g., `string`, `Uppercase<string>`, `on${string}`) simply return back `string[]` without performing any splitting, as the exact structure cannot be statically determined. @default true @example ```ts import type {Split} from 'type-fest'; type Example1 = Split<`foo.${string}.bar`, '.', {strict: false}>; //=> ['foo', string, 'bar'] type Example2 = Split<`foo.${string}`, '.', {strict: true}>; //=> string[] type Example3 = Split<'foobarbaz', `b${string}`, {strict: false}>; //=> ['foo', 'r', 'z'] type Example4 = Split<'foobarbaz', `b${string}`, {strict: true}>; //=> string[] ``` */ strict?: boolean; }; type DefaultSplitOptions = { strict: true; }; /** Represents an array of strings split using a given character or character set. Use-case: Defining the return type of a method like `String.prototype.split`. Note: With an empty delimiter, whether a supplementary Unicode character, such as an emoji, counts as one character or two depends on the TypeScript compiler. TypeScript 7 counts it as one, unlike `String#split('')`. @example ``` import type {Split} from 'type-fest'; declare function split<S extends string, D extends string>(string: S, separator: D): Split<S, D>; type Item = 'foo' | 'bar' | 'baz' | 'waldo'; const items = 'foo,bar,baz,waldo'; const array: Item[] = split(items, ','); ``` @see {@link SplitOptions} @category String @category Template literal */ export type Split< S extends string, Delimiter extends string, Options extends SplitOptions = {}, > = _Split<S extends object ? UnwrapBrandedPrimitive<S> : S, Delimiter extends object ? UnwrapBrandedPrimitive<Delimiter> : Delimiter, Options>; type _Split< S extends string, Delimiter extends string, Options extends SplitOptions, > = S extends string // For distributing `S` ? Delimiter extends string // For distributing `Delimiter` // If `S` and `Delimiter` both are string literals OR `strict` is `false`, then perform the split. Known literals do not depend on resolving generic options. ? Or< And<IsStringLiteral<S>, IsStringLiteral<Delimiter>>, Not<ApplyDefaultOptions<SplitOptions, DefaultSplitOptions, Options>['strict']> > extends true ? (Delimiter extends '' ? IsStringLiteral<S> : false) extends true // Reuse the chunked character conversion instead of rebuilding the tuple one character at a time. ? StringToArray<S> // The `extends infer` step keeps `_SplitOnDelimiter` out of this conditional's tail-recursion chain, so the loop gets the full recursion budget to itself. : _SplitOnDelimiter<S, Delimiter> extends infer Result ? Result : never // Otherwise, return `string[]` : string[] : never // Should never happen : never; // Should never happen /** Splits `S` on `Delimiter`. `_Split` distributes and checks both inputs before recursion, so this loop does not repeat those checks on every step. `ParsePathToStringSegments` fixes its delimiter and permits non-literal paths. */ export type _SplitOnDelimiter< S extends string, Delimiter extends string, Accumulator extends string[] = [], > = S extends `${infer Head}${Delimiter}${infer Tail}` ? _SplitOnDelimiter<Tail, Delimiter, [...Accumulator, Head]> : Delimiter extends '' ? S extends '' ? Accumulator : [...Accumulator, S] : [...Accumulator, S]; export {};