Type Alias Find<A, Criteria, Options>

Find: IsTuple<
    A,
    {
        $else: A extends Readonly<(infer T)[]>
            ? ArrayPlus.ElementMatch<T, Criteria, Options>
            : never;
        $then: $ResolveOptions<
            [Options["$tuple"], ArrayPlus.Find.DefaultOptions<Criteria>["$tuple"]],
        >;
    },
>

🦴 utilities 🔢 customizable

Finds the type in array A that matches Criteria.

Type Parameters

A extends readonly unknown[]
Criteria
Options extends ArrayPlus.Find.Options = ArrayPlus.Find.DefaultOptions<Criteria>

Example

type R = ArrayPlus.Find<Array<string>, string> // string
type R = ArrayPlus.Find<Array<1 | 2 | 'x'>, number> // 1 | 2 | undefined
type R = ArrayPlus.Find<Array<string | number>, number | string> // string | number
type R = ArrayPlus.Find<Array<number>, 1> // widen: 1 | undefined
type R = ArrayPlus.Find<Array<string | number>, number> // unionMiss: number | undefined

type R = ArrayPlus.Find<string[], number> // never

Type Param: Options['widen']

performs widen match. Default to true. With widen match, a narrowed type will match its widen type. e.g. matching 1 against number yields 1 | undefined

The widen behavior can be customized by Options['$widen']

Type Param: Options['$never']

return type when A is never. Default to never.

Type Param: Options['$notMatch']

Return value when T does not match Criteria. Default to never.

Type Param: Options['$tuple']

return type when A is a tuple. Default to not supported message.

Type Param: Options['$widen']

return type when T in A is a widen type of Criteria. Default to Criteria | undefined. Set it to never for a more type-centric behavior

Type Param: Options['$unionNotMatch']

Return value when a branch of the union T does not match Criteria. Default to never.

If you want the type to behave more like JavaScript, you can override it to return undefined.

Since it is a union, the result will be joined to the matched branch as union.