type-fest
Version:
A collection of essential TypeScript types
113 lines (91 loc) • 3.84 kB
TypeScript
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 {};