Skip to main content Link Search Menu Expand Document (external link)

Match overview

Added in v1.0.0


Table of contents


combinators

discriminator

Signature

export declare const discriminator: <D extends string>(
  field: D
) => <R, P extends Types.Tags<D, R> & string, Ret, B extends Ret>(
  ...pattern: [first: P, ...values: P[], f: (_: Extract<R, Record<D, P>>) => B]
) => <I, F, A, Pr>(
  self: Matcher<I, F, R, A, Pr, Ret>
) => Matcher<
  I,
  Types.AddWithout<F, Extract<R, Record<D, P>>>,
  Types.ApplyFilters<I, Types.AddWithout<F, Extract<R, Record<D, P>>>>,
  B | A,
  Pr,
  Ret
>

Added in v1.0.0

discriminatorStartsWith

Signature

export declare const discriminatorStartsWith: <D extends string>(
  field: D
) => <R, P extends string, Ret, B extends Ret>(
  pattern: P,
  f: (_: Extract<R, Record<D, `${P}${string}`>>) => B
) => <I, F, A, Pr>(
  self: Matcher<I, F, R, A, Pr, Ret>
) => Matcher<
  I,
  Types.AddWithout<F, Extract<R, Record<D, `${P}${string}`>>>,
  Types.ApplyFilters<I, Types.AddWithout<F, Extract<R, Record<D, `${P}${string}`>>>>,
  B | A,
  Pr,
  Ret
>

Added in v1.0.0

discriminators

Signature

export declare const discriminators: <D extends string>(
  field: D
) => <
  R,
  Ret,
  P extends { readonly [Tag in Types.Tags<D, R> & string]?: ((_: Extract<R, Record<D, Tag>>) => Ret) | undefined } & {
    readonly [Tag in Exclude<keyof P, Types.Tags<D, R>>]: never
  }
>(
  fields: P
) => <I, F, A, Pr>(
  self: Matcher<I, F, R, A, Pr, Ret>
) => Matcher<
  I,
  Types.AddWithout<F, Extract<R, Record<D, keyof P>>>,
  Types.ApplyFilters<I, Types.AddWithout<F, Extract<R, Record<D, keyof P>>>>,
  A | ReturnType<P[keyof P] & {}>,
  Pr,
  Ret
>

Added in v1.0.0

discriminatorsExhaustive

Signature

export declare const discriminatorsExhaustive: <D extends string>(
  field: D
) => <
  R,
  Ret,
  P extends { readonly [Tag in Types.Tags<D, R> & string]: (_: Extract<R, Record<D, Tag>>) => Ret } & {
    readonly [Tag in Exclude<keyof P, Types.Tags<D, R>>]: never
  }
>(
  fields: P
) => <I, F, A, Pr>(
  self: Matcher<I, F, R, A, Pr, Ret>
) => [Pr] extends [never] ? (u: I) => Unify<A | ReturnType<P[keyof P]>> : Unify<A | ReturnType<P[keyof P]>>

Added in v1.0.0

not

Signature

export declare const not: <
  R,
  const P extends Types.PatternPrimitive<R> | Types.PatternBase<R>,
  Ret,
  Fn extends (_: Exclude<R, Types.ExtractMatch<R, Types.PForExclude<P>>>) => Ret
>(
  pattern: P,
  f: Fn
) => <I, F, A, Pr>(
  self: Matcher<I, F, R, A, Pr, Ret>
) => Matcher<
  I,
  Types.AddOnly<F, Types.WhenMatch<R, P>>,
  Types.ApplyFilters<I, Types.AddOnly<F, Types.WhenMatch<R, P>>>,
  A | ReturnType<Fn>,
  Pr,
  Ret
>

Added in v1.0.0

tag

Signature

export declare const tag: <R, P extends Types.Tags<"_tag", R> & string, Ret, B extends Ret>(
  ...pattern: [first: P, ...values: P[], f: (_: Extract<R, Record<"_tag", P>>) => B]
) => <I, F, A, Pr>(
  self: Matcher<I, F, R, A, Pr, Ret>
) => Matcher<
  I,
  Types.AddWithout<F, Extract<R, Record<"_tag", P>>>,
  Types.ApplyFilters<I, Types.AddWithout<F, Extract<R, Record<"_tag", P>>>>,
  B | A,
  Pr,
  Ret
>

Added in v1.0.0

tagStartsWith

Signature

export declare const tagStartsWith: <R, P extends string, Ret, B extends Ret>(
  pattern: P,
  f: (_: Extract<R, Record<"_tag", `${P}${string}`>>) => B
) => <I, F, A, Pr>(
  self: Matcher<I, F, R, A, Pr, Ret>
) => Matcher<
  I,
  Types.AddWithout<F, Extract<R, Record<"_tag", `${P}${string}`>>>,
  Types.ApplyFilters<I, Types.AddWithout<F, Extract<R, Record<"_tag", `${P}${string}`>>>>,
  B | A,
  Pr,
  Ret
>

Added in v1.0.0

tags

Signature

export declare const tags: <
  R,
  Ret,
  P extends {
    readonly [Tag in Types.Tags<"_tag", R> & string]?: ((_: Extract<R, Record<"_tag", Tag>>) => Ret) | undefined
  } & { readonly [Tag in Exclude<keyof P, Types.Tags<"_tag", R>>]: never }
>(
  fields: P
) => <I, F, A, Pr>(
  self: Matcher<I, F, R, A, Pr, Ret>
) => Matcher<
  I,
  Types.AddWithout<F, Extract<R, Record<"_tag", keyof P>>>,
  Types.ApplyFilters<I, Types.AddWithout<F, Extract<R, Record<"_tag", keyof P>>>>,
  A | ReturnType<P[keyof P] & {}>,
  Pr,
  Ret
>

Added in v1.0.0

tagsExhaustive

Signature

export declare const tagsExhaustive: <
  R,
  Ret,
  P extends { readonly [Tag in Types.Tags<"_tag", R> & string]: (_: Extract<R, Record<"_tag", Tag>>) => Ret } & {
    readonly [Tag in Exclude<keyof P, Types.Tags<"_tag", R>>]: never
  }
>(
  fields: P
) => <I, F, A, Pr>(
  self: Matcher<I, F, R, A, Pr, Ret>
) => [Pr] extends [never] ? (u: I) => Unify<A | ReturnType<P[keyof P]>> : Unify<A | ReturnType<P[keyof P]>>

Added in v1.0.0

when

Signature

export declare const when: <
  R,
  const P extends Types.PatternPrimitive<R> | Types.PatternBase<R>,
  Ret,
  Fn extends (_: Types.WhenMatch<R, P>) => Ret
>(
  pattern: P,
  f: Fn
) => <I, F, A, Pr>(
  self: Matcher<I, F, R, A, Pr, Ret>
) => Matcher<
  I,
  Types.AddWithout<F, Types.PForExclude<P>>,
  Types.ApplyFilters<I, Types.AddWithout<F, Types.PForExclude<P>>>,
  A | ReturnType<Fn>,
  Pr,
  Ret
>

Added in v1.0.0

whenAnd

Signature

export declare const whenAnd: <
  R,
  const P extends readonly (Types.PatternPrimitive<R> | Types.PatternBase<R>)[],
  Ret,
  Fn extends (_: Types.WhenMatch<R, UnionToIntersection<P[number]>>) => Ret
>(
  ...args: [...patterns: P, f: Fn]
) => <I, F, A, Pr>(
  self: Matcher<I, F, R, A, Pr, Ret>
) => Matcher<
  I,
  Types.AddWithout<F, Types.PForExclude<UnionToIntersection<P[number]>>>,
  Types.ApplyFilters<I, Types.AddWithout<F, Types.PForExclude<UnionToIntersection<P[number]>>>>,
  A | ReturnType<Fn>,
  Pr,
  any
>

Added in v1.0.0

whenOr

Signature

export declare const whenOr: <
  R,
  const P extends readonly (Types.PatternPrimitive<R> | Types.PatternBase<R>)[],
  Ret,
  Fn extends (_: Types.WhenMatch<R, P[number]>) => Ret
>(
  ...args: [...patterns: P, f: Fn]
) => <I, F, A, Pr>(
  self: Matcher<I, F, R, A, Pr, Ret>
) => Matcher<
  I,
  Types.AddWithout<F, Types.PForExclude<P[number]>>,
  Types.ApplyFilters<I, Types.AddWithout<F, Types.PForExclude<P[number]>>>,
  A | ReturnType<Fn>,
  Pr,
  Ret
>

Added in v1.0.0

withReturnType

Signature

export declare const withReturnType: <Ret>() => <I, F, R, A, Pr, _>(
  self: Matcher<I, F, R, A, Pr, _>
) => Ret extends ([A] extends [never] ? any : A)
  ? Matcher<I, F, R, A, Pr, Ret>
  : "withReturnType constraint does not extend Result type"

Added in v1.0.0

constructors

type

Signature

export declare const type: <I>() => Matcher<I, Types.Without<never>, I, never, never, any>

Added in v1.0.0

typeTags

Signature

export declare const typeTags: <I>() => <
  P extends { readonly [Tag in Types.Tags<"_tag", I> & string]: (_: Extract<I, { readonly _tag: Tag }>) => any } & {
    readonly [Tag in Exclude<keyof P, Types.Tags<"_tag", I>>]: never
  }
>(
  fields: P
) => (input: I) => Unify<ReturnType<P[keyof P]>>

Added in v1.0.0

value

Signature

export declare const value: <const I>(i: I) => Matcher<I, Types.Without<never>, I, never, I, any>

Added in v1.0.0

valueTags

Signature

export declare const valueTags: <
  const I,
  P extends { readonly [Tag in Types.Tags<"_tag", I> & string]: (_: Extract<I, { readonly _tag: Tag }>) => any } & {
    readonly [Tag in Exclude<keyof P, Types.Tags<"_tag", I>>]: never
  }
>(
  fields: P
) => (input: I) => Unify<ReturnType<P[keyof P]>>

Added in v1.0.0

conversions

either

Signature

export declare const either: <I, F, R, A, Pr, Ret>(
  self: Matcher<I, F, R, A, Pr, Ret>
) => [Pr] extends [never] ? (input: I) => Either.Either<Unify<A>, R> : Either.Either<Unify<A>, R>

Added in v1.0.0

exhaustive

Signature

export declare const exhaustive: <I, F, A, Pr, Ret>(
  self: Matcher<I, F, never, A, Pr, Ret>
) => [Pr] extends [never] ? (u: I) => Unify<A> : Unify<A>

Added in v1.0.0

option

Signature

export declare const option: <I, F, R, A, Pr, Ret>(
  self: Matcher<I, F, R, A, Pr, Ret>
) => [Pr] extends [never] ? (input: I) => Option.Option<Unify<A>> : Option.Option<Unify<A>>

Added in v1.0.0

orElse

Signature

export declare const orElse: <RA, Ret, B extends Ret>(
  f: (b: RA) => B
) => <I, R, A, Pr>(
  self: Matcher<I, R, RA, A, Pr, Ret>
) => [Pr] extends [never] ? (input: I) => Unify<B | A> : Unify<B | A>

Added in v1.0.0

orElseAbsurd

Signature

export declare const orElseAbsurd: <I, R, RA, A, Pr, Ret>(
  self: Matcher<I, R, RA, A, Pr, Ret>
) => [Pr] extends [never] ? (input: I) => Unify<A> : Unify<A>

Added in v1.0.0

model

Case (type alias)

Signature

export type Case = When | Not

Added in v1.0.0

Matcher (type alias)

Signature

export type Matcher<Input, Filters, RemainingApplied, Result, Provided, Return = any> =
  | TypeMatcher<Input, Filters, RemainingApplied, Result, Return>
  | ValueMatcher<Input, Filters, RemainingApplied, Result, Provided, Return>

Added in v1.0.0

Not (interface)

Signature

export interface Not {
  readonly _tag: "Not"
  guard(u: unknown): boolean
  evaluate(input: unknown): any
}

Added in v1.0.0

SafeRefinement (interface)

Signature

export interface SafeRefinement<in A, out R = A> {
  readonly [SafeRefinementId]: (a: A) => R
}

Added in v1.0.0

TypeMatcher (interface)

Signature

export interface TypeMatcher<in Input, out Filters, out Remaining, out Result, out Return = any> extends Pipeable {
  readonly _tag: "TypeMatcher"
  readonly [MatcherTypeId]: {
    readonly _input: Contravariant<Input>
    readonly _filters: Covariant<Filters>
    readonly _remaining: Covariant<Remaining>
    readonly _result: Covariant<Result>
    readonly _return: Covariant<Return>
  }
  readonly cases: ReadonlyArray<Case>
  add<I, R, RA, A>(_case: Case): TypeMatcher<I, R, RA, A>
}

Added in v1.0.0

ValueMatcher (interface)

Signature

export interface ValueMatcher<in Input, Filters, out Remaining, out Result, Provided, out Return = any>
  extends Pipeable {
  readonly _tag: "ValueMatcher"
  readonly [MatcherTypeId]: {
    readonly _input: Contravariant<Input>
    readonly _filters: Covariant<Filters>
    readonly _result: Covariant<Result>
    readonly _return: Covariant<Return>
  }
  readonly provided: Provided
  readonly value: Either.Either<Provided, Remaining>
  add<I, R, RA, A, Pr>(_case: Case): ValueMatcher<I, R, RA, A, Pr>
}

Added in v1.0.0

When (interface)

Signature

export interface When {
  readonly _tag: "When"
  guard(u: unknown): boolean
  evaluate(input: unknown): any
}

Added in v1.0.0

predicates

any

Signature

export declare const any: SafeRefinement<unknown, any>

Added in v1.0.0

bigint

Signature

export declare const bigint: Predicate.Refinement<unknown, bigint>

Added in v1.0.0

boolean

Signature

export declare const boolean: Predicate.Refinement<unknown, boolean>

Added in v1.0.0

date

Signature

export declare const date: Predicate.Refinement<unknown, Date>

Added in v1.0.0

defined

Signature

export declare const defined: <A>(u: A) => u is A & {}

Added in v1.0.0

instanceOf

Signature

export declare const instanceOf: <A extends abstract new (...args: any) => any>(
  constructor: A
) => SafeRefinement<InstanceType<A>, never>

Added in v1.0.0

instanceOfUnsafe

Signature

export declare const instanceOfUnsafe: <A extends abstract new (...args: any) => any>(
  constructor: A
) => SafeRefinement<InstanceType<A>, InstanceType<A>>

Added in v1.0.0

is

Signature

export declare const is: <Literals extends readonly (string | number | bigint | boolean | null)[]>(
  ...literals: Literals
) => Predicate.Refinement<unknown, Literals[number]>

Added in v1.0.0

nonEmptyString

Signature

export declare const nonEmptyString: SafeRefinement<string, never>

Added in v1.0.0

null

Signature

export declare const null: Predicate.Refinement<unknown, null>

Added in v1.0.0

number

Signature

export declare const number: Predicate.Refinement<unknown, number>

Added in v1.0.0

record

Signature

export declare const record: Predicate.Refinement<unknown, { [x: string]: unknown; [x: symbol]: unknown }>

Added in v1.0.0

string

Signature

export declare const string: Predicate.Refinement<unknown, string>

Added in v1.0.0

symbol

Signature

export declare const symbol: Predicate.Refinement<unknown, symbol>

Added in v1.0.0

undefined

Signature

export declare const undefined: Predicate.Refinement<unknown, undefined>

Added in v1.0.0

type ids

MatcherTypeId

Signature

export declare const MatcherTypeId: typeof MatcherTypeId

Added in v1.0.0

MatcherTypeId (type alias)

Signature

export type MatcherTypeId = typeof MatcherTypeId

Added in v1.0.0

SafeRefinementId

Signature

export declare const SafeRefinementId: typeof SafeRefinementId

Added in v1.0.0

SafeRefinementId (type alias)

Signature

export type SafeRefinementId = typeof SafeRefinementId

Added in v1.0.0

utils

Types (namespace)

Added in v1.0.0

Only (interface)

Signature

export interface Only<out X> {
  readonly _tag: "Only"
  readonly _X: X
}

Added in v1.0.0

Without (interface)

Signature

export interface Without<out X> {
  readonly _tag: "Without"
  readonly _X: X
}

Added in v1.0.0

AddOnly (type alias)

Signature

export type AddOnly<A, X> = [A] extends [Without<infer WX>]
  ? [X] extends [WX]
    ? never
    : Only<X>
  : [A] extends [Only<infer OX>]
    ? [X] extends [OX]
      ? Only<X>
      : never
    : never

Added in v1.0.0

AddWithout (type alias)

Signature

export type AddWithout<A, X> = [A] extends [Without<infer WX>]
  ? Without<X | WX>
  : [A] extends [Only<infer OX>]
    ? Only<Exclude<OX, X>>
    : never

Added in v1.0.0

ApplyFilters (type alias)

Signature

export type ApplyFilters<I, A> = A extends Only<infer X> ? X : A extends Without<infer X> ? Exclude<I, X> : never

Added in v1.0.0

ArrayToIntersection (type alias)

Signature

export type ArrayToIntersection<A extends ReadonlyArray<any>> = UnionToIntersection<A[number]>

Added in v1.0.0

ExtractMatch (type alias)

Signature

export type ExtractMatch<I, P> = [ExtractAndNarrow<I, P>] extends [infer EI] ? EI : never

Added in v1.0.0

NotMatch (type alias)

Signature

export type NotMatch<R, P> = Exclude<R, ExtractMatch<R, PForExclude<P>>>

Added in v1.0.0

PForExclude (type alias)

Signature

export type PForExclude<P> = [SafeRefinementR<ToSafeRefinement<P>>] extends [infer X] ? X : never

Added in v1.0.0

PForMatch (type alias)

Signature

export type PForMatch<P> = [SafeRefinementP<ResolvePred<P>>] extends [infer X] ? X : never

Added in v1.0.0

PatternBase (type alias)

Signature

export type PatternBase<A> =
  A extends ReadonlyArray<infer _T>
    ? ReadonlyArray<any> | PatternPrimitive<A>
    : A extends Record<string, any>
      ? Partial<{ [K in keyof A]: PatternPrimitive<A[K] & {}> | PatternBase<A[K] & {}> }>
      : never

Added in v1.0.0

PatternPrimitive (type alias)

Signature

export type PatternPrimitive<A> = PredicateA<A> | A | SafeRefinement<any>

Added in v1.0.0

Tags (type alias)

Signature

export type Tags<D extends string, P> = P extends Record<D, infer X> ? X : never

Added in v1.0.0

WhenMatch (type alias)

Signature

export type WhenMatch<R, P> =
  // check for any
  [0] extends [1 & R]
    ? PForMatch<P>
    : P extends SafeRefinement<infer SP, never>
      ? SP
      : P extends Predicate.Refinement<infer _R, infer RP>
        ? // try to narrow refinement
          [Extract<R, RP>] extends [infer X]
          ? [X] extends [never]
            ? // fallback to original refinement
              RP
            : X
          : never
        : P extends PredicateA<infer PP>
          ? PP
          : ExtractMatch<R, PForMatch<P>>

Added in v1.0.0