Predicate.Refinement — API

Predicate.Refinementinterfaceeffect/Predicate.ts:113

(a: A): a is B

A predicate that also narrows the input type when it returns true.

When to use

Use when you want a runtime check that refines A to B for TypeScript, especially when composing type guards with compose or safely checking unknown values.

Details

A refinement returns a type predicate (a is B). Use it with if or filter to narrow types.

Example (Narrowing unknown values)

import { Predicate } from "effect"

const isString: Predicate.Refinement<unknown, string> = (u): u is string => typeof u === "string"

const data: unknown = "hello"
if (isString(data)) {
  console.log(data.toUpperCase())
}

modelscompose Predicate isString

Source effect/Predicate.ts:113196 lines

export interface Refinement<in A, out B extends A> {
  (a: A): a is B
}

/**
 * Type-level utilities for working with {@link Predicate} types.
 *
 * **When to use**
 *
 * Use when you need to extract input types from predicate signatures while
 * writing generic helpers over predicate types.
 *
 * **Details**
 *
 * These utilities are type-only, create no runtime values, and the namespace is
 * erased at runtime.
 *
 * **Example** (Extracting predicate input)
 *
 * ```ts
 * import { Predicate } from "effect"
 *
 * type IsString = Predicate.Predicate<string>
 * type Input = Predicate.Predicate.In<IsString>
 * ```
 *
 * @see {@link Predicate}
 * @see {@link Refinement}
 * @since 3.6.0
 */
export declare namespace Predicate {
  /**
   * Extracts the input type `A` from a `Predicate<A>`.
   *
   * **When to use**
   *
   * Use when you want to infer the input type from a predicate type while
   * defining generic utilities over predicates.
   *
   * **Details**
   *
   * This is type-only and creates no runtime value. It resolves to `never` if
   * the type does not match `Predicate`.
   *
   * **Example** (Inferring the input type)
   *
   * ```ts
   * import { Predicate } from "effect"
   *
   * type P = Predicate.Predicate<number>
   * type Input = Predicate.Predicate.In<P>
   * ```
   *
   * @see {@link Predicate.Any}
   * @see {@link Refinement.In}
   * @category utility types
   * @since 3.6.0
   */
  export type In<T extends Any> = [T] extends [Predicate<infer _A>] ? _A : never

  /**
   * A utility type representing any predicate type.
   *
   * **When to use**
   *
   * Use when you need a constraint for "any predicate" in generic code.
   *
   * **Details**
   *
   * This is type-only and creates no runtime value.
   *
   * **Example** (Using generic constraints)
   *
   * ```ts
   * import { Predicate } from "effect"
   *
   * type AnyPredicate = Predicate.Predicate.Any
   * ```
   *
   * @see {@link Predicate.In}
   * @category utility types
   * @since 3.6.0
   */
  export type Any = Predicate<any>
}

/**
 * Type-level utilities for working with {@link Refinement} types.
 *
 * **When to use**
 *
 * Use when you need to extract input and output types from refinement
 * signatures while writing generic helpers over refinements.
 *
 * **Details**
 *
 * These utilities are type-only, create no runtime values, and the namespace is
 * erased at runtime.
 *
 * **Example** (Extracting refinement types)
 *
 * ```ts
 * import { Predicate } from "effect"
 *
 * type IsString = Predicate.Refinement<unknown, string>
 * type Input = Predicate.Refinement.In<IsString>
 * type Output = Predicate.Refinement.Out<IsString>
 * ```
 *
 * @see {@link Refinement}
 * @see {@link Predicate}
 * @since 3.6.0
 */
export declare namespace Refinement {
  /**
   * Extracts the input type `A` from a `Refinement<A, B>`.
   *
   * **When to use**
   *
   * Use when you want to infer the input type from a refinement type.
   *
   * **Details**
   *
   * This is type-only and creates no runtime value. It resolves to `never` if
   * the type does not match `Refinement`.
   *
   * **Example** (Inferring the input type)
   *
   * ```ts
   * import { Predicate } from "effect"
   *
   * type R = Predicate.Refinement<unknown, string>
   * type Input = Predicate.Refinement.In<R>
   * ```
   *
   * @see {@link Refinement.Out}
   * @see {@link Predicate.In}
   * @category utility types
   * @since 3.6.0
   */

  export type In<T extends Any> = [T] extends [Refinement<infer _A, infer _>] ? _A : never

  /**
   * Extracts the output type `B` from a `Refinement<A, B>`.
   *
   * **When to use**
   *
   * Use when you want to infer the narrowed type from a refinement type.
   *
   * **Details**
   *
   * This is type-only and creates no runtime value. It resolves to `never` if
   * the type does not match `Refinement`.
   *
   * **Example** (Inferring the output type)
   *
   * ```ts
   * import { Predicate } from "effect"
   *
   * type R = Predicate.Refinement<unknown, string>
   * type Output = Predicate.Refinement.Out<R>
   * ```
   *
   * @see {@link Refinement.In}
   * @category utility types
   * @since 3.6.0
   */
  export type Out<T extends Any> = [T] extends [Refinement<infer _, infer _B>] ? _B : never

  /**
   * A utility type representing any refinement type.
   *
   * **When to use**
   *
   * Use when you need a constraint for "any refinement" in generic code.
   *
   * **Details**
   *
   * This is type-only and creates no runtime value.
   *
   * **Example** (Using generic constraints)
   *
   * ```ts
   * import { Predicate } from "effect"
   *
   * type AnyRefinement = Predicate.Refinement.Any
   * ```
   *
   * @see {@link Refinement.In}
   * @see {@link Refinement.Out}
   * @category utility types
   * @since 3.6.0
   */
  export type Any = Refinement<any, any>
}