type-fest
Version:
A collection of essential TypeScript types
83 lines (62 loc) • 3.38 kB
TypeScript
import type {UnwrapBrandedPrimitive} from './unwrap-branded-primitive.d.ts';
import type {IsAny} from './is-any.d.ts';
import type {IsNever} from './is-never.d.ts';
import type {IsStringLiteral} from './is-string-literal.d.ts';
/**
Returns a boolean for whether the given string starts with the given prefix.
Useful for filtering or validating event names, routes, and other string literal unions. Matching is case-sensitive. A union of literal prefixes matches if any member matches. With a literal prefix, a union of literal inputs distributes: `true` when every member matches, `false` when none matches, and `boolean` when the members disagree.
A `never` in either position returns `false`. Otherwise, an `any` in either position returns `boolean`. The empty prefix `''` returns `true` for every input that is not `never` or `any`.
Apart from `never` and `any`, a non-literal prefix, including a union that contains one, returns `boolean`. With a literal prefix, a non-literal input returns `true` when its known start guarantees a match, and `boolean` otherwise, even when the known part already differs from the prefix.
Matching follows TypeScript's template literal rules. Prefixes that end in the middle of a UTF-16 surrogate pair are unsupported, and their result depends on the TypeScript compiler.
@example
```
import type {StartsWith} from 'type-fest';
type A = StartsWith<'user:created', 'user:'>;
//=> true
type B = StartsWith<'order:created', 'user:'>;
//=> false
type C = StartsWith<string, 'user:'>;
//=> boolean
type D = StartsWith<'user:created', 'user:' | 'order:'>;
//=> true
type E = StartsWith<`user:${string}`, 'user:'>;
//=> true
type F = StartsWith<`order:${string}`, 'user:'>;
//=> boolean
type G = StartsWith<'user:created', `user:${string}`>;
//=> boolean
```
@example
```
import type {StartsWith} from 'type-fest';
type UserEvents<Event extends string> = Event extends unknown
? StartsWith<Event, 'user:'> extends true ? Event : never
: never;
type Events = UserEvents<'user:created' | 'order:created' | 'user:deleted'>;
//=> 'user:created' | 'user:deleted'
```
@category String
@category Template literal
@category Type Guard
*/
export type StartsWith<Value extends string, Prefix extends string> = _StartsWith<Value extends object ? UnwrapBrandedPrimitive<Value> : Value, Prefix extends object ? UnwrapBrandedPrimitive<Prefix> : Prefix>;
/**
Check each input against the complete prefix union, falling back to `boolean` when a template match cannot decide an unknown value. The literal-prefix check must come before the template match: for a non-literal prefix such as `string`, the template pattern collapses to a plain string and would match every input other than `never` and `any`.
Each operand is checked for `any` before `never`, so generic code that wraps the result keeps resolving it after instantiation.
*/
type _StartsWith<Value extends string, Prefix extends string> = IsAny<Value> extends true
? IsNever<Prefix> extends true ? false : boolean
: IsNever<Value> extends true
? false
: Value extends unknown
? IsAny<Prefix> extends true
? boolean
: IsNever<Prefix> extends true
? false
: IsStringLiteral<Prefix> extends true
? Value extends `${Prefix}${string}`
? true
: IsStringLiteral<Value> extends true ? false : boolean
: boolean
: never;
export {};