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

Predicate overview

Added in v2.0.0

Table of contents

combinators

and

Combines two predicates into a new predicate that returns true if both of the predicates returns true.

Signature

export declare const and: {
  <A, C extends A>(that: Refinement<A, C>): <B extends A>(self: Refinement<A, B>) => Refinement<A, B & C>
  <A, B extends A, C extends A>(self: Refinement<A, B>, that: Refinement<A, C>): Refinement<A, B & C>
  <A>(that: Predicate<A>): (self: Predicate<A>) => Predicate<A>
  <A>(self: Predicate<A>, that: Predicate<A>): Predicate<A>
}

Example

import { Predicate } from "effect"

const minLength = (n: number) => (s: string) => s.length >= n
const maxLength = (n: number) => (s: string) => s.length <= n

const length = (n: number) => Predicate.and(minLength(n), maxLength(n))

assert.deepStrictEqual(length(2)("aa"), true)
assert.deepStrictEqual(length(2)("a"), false)
assert.deepStrictEqual(length(2)("aaa"), false)

Added in v2.0.0

eqv

Signature

export declare const eqv: {
  <A>(that: Predicate<A>): (self: Predicate<A>) => Predicate<A>
  <A>(self: Predicate<A>, that: Predicate<A>): Predicate<A>
}

Added in v2.0.0

implies

Represents the logical implication combinator for predicates. In formal logic, the implication operator -> denotes that if the first proposition (antecedent) is true, then the second proposition (consequent) must also be true. In simpler terms, p implies q can be interpreted as “if p then q”. If the first predicate holds, then the second predicate must hold for the given context.

In practical terms within TypeScript, p implies q is equivalent to !p || (p && q).

Note that if the antecedent is false, the result is true by default because the outcome of the consequent cannot be determined.

This function is useful in situations where you need to enforce rules or constraints that are contingent on certain conditions. It proves especially helpful in defining property tests.

The example below illustrates the transitive property of order using the implies function. In simple terms, if a <= b and b <= c, then a <= c must be true.

Signature

export declare const implies: {
  <A>(consequent: Predicate<A>): (antecedent: Predicate<A>) => Predicate<A>
  <A>(antecedent: Predicate<A>, consequent: Predicate<A>): Predicate<A>
}

Example

import { Predicate } from "effect"

type Triple = {
  readonly a: number
  readonly b: number
  readonly c: number
}

const transitivity = Predicate.implies(
  // antecedent
  (input: Triple) => input.a <= input.b && input.b <= input.c,
  // consequent
  (input: Triple) => input.a <= input.c
)

assert.equal(transitivity({ a: 1, b: 2, c: 3 }), true)
// antecedent is `false`, so the result is `true`
assert.equal(transitivity({ a: 1, b: 0, c: 0 }), true)

Added in v2.0.0

mapInput

Given a Predicate<A> returns a Predicate<B>

Signature

export declare const mapInput: {
  <B, A>(f: (b: B) => A): (self: Predicate<A>) => Predicate<B>
  <A, B>(self: Predicate<A>, f: (b: B) => A): Predicate<B>
}

Example

import { Predicate, Number } from "effect"

const minLength3 = Predicate.mapInput(Number.greaterThan(2), (s: string) => s.length)

assert.deepStrictEqual(minLength3("a"), false)
assert.deepStrictEqual(minLength3("aa"), false)
assert.deepStrictEqual(minLength3("aaa"), true)
assert.deepStrictEqual(minLength3("aaaa"), true)

Added in v2.0.0

nand

Signature

export declare const nand: {
  <A>(that: Predicate<A>): (self: Predicate<A>) => Predicate<A>
  <A>(self: Predicate<A>, that: Predicate<A>): Predicate<A>
}

Added in v2.0.0

nor

Signature

export declare const nor: {
  <A>(that: Predicate<A>): (self: Predicate<A>) => Predicate<A>
  <A>(self: Predicate<A>, that: Predicate<A>): Predicate<A>
}

Added in v2.0.0

not

Negates the result of a given predicate.

Signature

export declare const not: <A>(self: Predicate<A>) => Predicate<A>

Example

import { Predicate, Number } from "effect"

const isPositive = Predicate.not(Number.lessThan(0))

assert.deepStrictEqual(isPositive(-1), false)
assert.deepStrictEqual(isPositive(0), true)
assert.deepStrictEqual(isPositive(1), true)

Added in v2.0.0

or

Combines two predicates into a new predicate that returns true if at least one of the predicates returns true.

Signature

export declare const or: {
  <A, C extends A>(that: Refinement<A, C>): <B extends A>(self: Refinement<A, B>) => Refinement<A, C | B>
  <A, B extends A, C extends A>(self: Refinement<A, B>, that: Refinement<A, C>): Refinement<A, B | C>
  <A>(that: Predicate<A>): (self: Predicate<A>) => Predicate<A>
  <A>(self: Predicate<A>, that: Predicate<A>): Predicate<A>
}

Example

import { Predicate, Number } from "effect"

const nonZero = Predicate.or(Number.lessThan(0), Number.greaterThan(0))

assert.deepStrictEqual(nonZero(-1), true)
assert.deepStrictEqual(nonZero(0), false)
assert.deepStrictEqual(nonZero(1), true)

Added in v2.0.0

xor

Signature

export declare const xor: {
  <A>(that: Predicate<A>): (self: Predicate<A>) => Predicate<A>
  <A>(self: Predicate<A>, that: Predicate<A>): Predicate<A>
}

Added in v2.0.0

combining

all

Signature

export declare const all: <A>(collection: Iterable<Predicate<A>>) => Predicate<readonly A[]>

Added in v2.0.0

product

Signature

export declare const product: <A, B>(self: Predicate<A>, that: Predicate<B>) => Predicate<readonly [A, B]>

Added in v2.0.0

productMany

Signature

export declare const productMany: <A>(
  self: Predicate<A>,
  collection: Iterable<Predicate<A>>
) => Predicate<readonly [A, ...A[]]>

Added in v2.0.0

elements

every

Signature

export declare const every: <A>(collection: Iterable<Predicate<A>>) => Predicate<A>

Added in v2.0.0

some

Signature

export declare const some: <A>(collection: Iterable<Predicate<A>>) => Predicate<A>

Added in v2.0.0

guards

hasProperty

Checks whether a value is an object containing a specified property key.

Signature

export declare const hasProperty: {
  <P extends PropertyKey>(property: P): (self: unknown) => self is { [K in P]: unknown }
  <P extends PropertyKey>(self: unknown, property: P): self is { [K in P]: unknown }
}

Added in v2.0.0

isBigInt

Tests if a value is a bigint.

Signature

export declare const isBigInt: (input: unknown) => input is bigint

Example

import { isBigInt } from "effect/Predicate"

assert.deepStrictEqual(isBigInt(1n), true)

assert.deepStrictEqual(isBigInt(1), false)

Added in v2.0.0

isBoolean

Tests if a value is a boolean.

Signature

export declare const isBoolean: (input: unknown) => input is boolean

Example

import { isBoolean } from "effect/Predicate"

assert.deepStrictEqual(isBoolean(true), true)

assert.deepStrictEqual(isBoolean("true"), false)

Added in v2.0.0

isDate

A guard that succeeds when the input is a Date.

Signature

export declare const isDate: (input: unknown) => input is Date

Example

import { isDate } from "effect/Predicate"

assert.deepStrictEqual(isDate(new Date()), true)

assert.deepStrictEqual(isDate(null), false)
assert.deepStrictEqual(isDate({}), false)

Added in v2.0.0

isError

A guard that succeeds when the input is an Error.

Signature

export declare const isError: (input: unknown) => input is Error

Example

import { isError } from "effect/Predicate"

assert.deepStrictEqual(isError(new Error()), true)

assert.deepStrictEqual(isError(null), false)
assert.deepStrictEqual(isError({}), false)

Added in v2.0.0

isFunction

Tests if a value is a function.

Signature

export declare const isFunction: (input: unknown) => input is Function

Example

import { isFunction } from "effect/Predicate"

assert.deepStrictEqual(isFunction(isFunction), true)

assert.deepStrictEqual(isFunction("function"), false)

Added in v2.0.0

isIterable

A guard that succeeds when the input is an Iterable.

Signature

export declare const isIterable: (input: unknown) => input is Iterable<unknown>

Example

import { isIterable } from "effect/Predicate"

assert.deepStrictEqual(isIterable([]), true)
assert.deepStrictEqual(isIterable(new Set()), true)

assert.deepStrictEqual(isIterable(null), false)
assert.deepStrictEqual(isIterable({}), false)

Added in v2.0.0

isMap

Tests if a value is a Map.

Signature

export declare const isMap: (input: unknown) => input is Map<unknown, unknown>

Example

import { isMap } from "effect/Predicate"

assert.deepStrictEqual(isMap(new Map()), true)
assert.deepStrictEqual(isMap({}), false)
assert.deepStrictEqual(isMap(null), false)
assert.deepStrictEqual(isMap(undefined), false)

Added in v2.0.0

isNever

A guard that always fails.

Signature

export declare const isNever: (input: unknown) => input is never

Example

import { isNever } from "effect/Predicate"

assert.deepStrictEqual(isNever(null), false)
assert.deepStrictEqual(isNever(undefined), false)
assert.deepStrictEqual(isNever({}), false)
assert.deepStrictEqual(isNever([]), false)

Added in v2.0.0

isNotNull

Tests if a value is not null.

Signature

export declare const isNotNull: <A>(input: A) => input is Exclude<A, null>

Example

import { isNotNull } from "effect/Predicate"

assert.deepStrictEqual(isNotNull(undefined), true)
assert.deepStrictEqual(isNotNull("null"), true)

assert.deepStrictEqual(isNotNull(null), false)

Added in v2.0.0

isNotNullable

A guard that succeeds when the input is not null or undefined.

Signature

export declare const isNotNullable: <A>(input: A) => input is NonNullable<A>

Example

import { isNotNullable } from "effect/Predicate"

assert.deepStrictEqual(isNotNullable({}), true)
assert.deepStrictEqual(isNotNullable([]), true)

assert.deepStrictEqual(isNotNullable(null), false)
assert.deepStrictEqual(isNotNullable(undefined), false)

Added in v2.0.0

isNotUndefined

Tests if a value is not undefined.

Signature

export declare const isNotUndefined: <A>(input: A) => input is Exclude<A, undefined>

Example

import { isNotUndefined } from "effect/Predicate"

assert.deepStrictEqual(isNotUndefined(null), true)
assert.deepStrictEqual(isNotUndefined("undefined"), true)

assert.deepStrictEqual(isNotUndefined(undefined), false)

Added in v2.0.0

isNull

Tests if a value is null.

Signature

export declare const isNull: (input: unknown) => input is null

Example

import { isNull } from "effect/Predicate"

assert.deepStrictEqual(isNull(null), true)

assert.deepStrictEqual(isNull(undefined), false)
assert.deepStrictEqual(isNull("null"), false)

Added in v2.0.0

isNullable

A guard that succeeds when the input is null or undefined.

Signature

export declare const isNullable: <A>(input: A) => input is Extract<A, null | undefined>

Example

import { isNullable } from "effect/Predicate"

assert.deepStrictEqual(isNullable(null), true)
assert.deepStrictEqual(isNullable(undefined), true)

assert.deepStrictEqual(isNullable({}), false)
assert.deepStrictEqual(isNullable([]), false)

Added in v2.0.0

isNumber

Tests if a value is a number.

Signature

export declare const isNumber: (input: unknown) => input is number

Example

import { isNumber } from "effect/Predicate"

assert.deepStrictEqual(isNumber(2), true)

assert.deepStrictEqual(isNumber("2"), false)

Added in v2.0.0

isObject

Tests if a value is an object.

Signature

export declare const isObject: (input: unknown) => input is object

Example

import { isObject } from "effect/Predicate"

assert.deepStrictEqual(isObject({}), true)
assert.deepStrictEqual(isObject([]), true)

assert.deepStrictEqual(isObject(null), false)
assert.deepStrictEqual(isObject(undefined), false)

Added in v2.0.0

isPromise

A guard that succeeds when the input is a Promise.

Signature

export declare const isPromise: (input: unknown) => input is Promise<unknown>

Example

import { isPromise } from "effect/Predicate"

assert.deepStrictEqual(isPromise({}), false)
assert.deepStrictEqual(isPromise(Promise.resolve("hello")), true)

Added in v2.0.0

isPromiseLike

Signature

export declare const isPromiseLike: (input: unknown) => input is PromiseLike<unknown>

Added in v2.0.0

isReadonlyRecord

A guard that succeeds when the input is a readonly record.

Signature

export declare const isReadonlyRecord: (
  input: unknown
) => input is { readonly [x: string]: unknown; readonly [x: symbol]: unknown }

Example

import { isReadonlyRecord } from "effect/Predicate"

assert.deepStrictEqual(isReadonlyRecord({}), true)
assert.deepStrictEqual(isReadonlyRecord({ a: 1 }), true)

assert.deepStrictEqual(isReadonlyRecord([]), false)
assert.deepStrictEqual(isReadonlyRecord([1, 2, 3]), false)
assert.deepStrictEqual(isReadonlyRecord(null), false)
assert.deepStrictEqual(isReadonlyRecord(undefined), false)

Added in v2.0.0

isRecord

A guard that succeeds when the input is a record.

Signature

export declare const isRecord: (input: unknown) => input is { [x: string]: unknown; [x: symbol]: unknown }

Example

import { isRecord } from "effect/Predicate"

assert.deepStrictEqual(isRecord({}), true)
assert.deepStrictEqual(isRecord({ a: 1 }), true)

assert.deepStrictEqual(isRecord([]), false)
assert.deepStrictEqual(isRecord([1, 2, 3]), false)
assert.deepStrictEqual(isRecord(null), false)
assert.deepStrictEqual(isRecord(undefined), false)
assert.deepStrictEqual(
  isRecord(() => null),
  false
)

Added in v2.0.0

isSet

Tests if a value is a Set.

Signature

export declare const isSet: (input: unknown) => input is Set<unknown>

Example

import { isSet } from "effect/Predicate"

assert.deepStrictEqual(isSet(new Set([1, 2])), true)
assert.deepStrictEqual(isSet(new Set()), true)
assert.deepStrictEqual(isSet({}), false)
assert.deepStrictEqual(isSet(null), false)
assert.deepStrictEqual(isSet(undefined), false)

Added in v2.0.0

isString

Tests if a value is a string.

Signature

export declare const isString: (input: unknown) => input is string

Example

import { isString } from "effect/Predicate"

assert.deepStrictEqual(isString("a"), true)

assert.deepStrictEqual(isString(1), false)

Added in v2.0.0

isSymbol

Tests if a value is a symbol.

Signature

export declare const isSymbol: (input: unknown) => input is symbol

Example

import { isSymbol } from "effect/Predicate"

assert.deepStrictEqual(isSymbol(Symbol.for("a")), true)

assert.deepStrictEqual(isSymbol("a"), false)

Added in v2.0.0

isTagged

Tests if a value is an object with a property _tag that matches the given tag.

Signature

export declare const isTagged: {
  <K extends string>(tag: K): (self: unknown) => self is { _tag: K }
  <K extends string>(self: unknown, tag: K): self is { _tag: K }
}

Example

import { isTagged } from "effect/Predicate"

assert.deepStrictEqual(isTagged(1, "a"), false)
assert.deepStrictEqual(isTagged(null, "a"), false)
assert.deepStrictEqual(isTagged({}, "a"), false)
assert.deepStrictEqual(isTagged({ a: "a" }, "a"), false)
assert.deepStrictEqual(isTagged({ _tag: "a" }, "a"), true)
assert.deepStrictEqual(isTagged("a")({ _tag: "a" }), true)

Added in v2.0.0

isTruthy

Tests if a value is truthy.

Signature

export declare const isTruthy: (input: unknown) => boolean

Example

import { isTruthy } from "effect/Predicate"

assert.deepStrictEqual(isTruthy(1), true)
assert.deepStrictEqual(isTruthy(0), false)
assert.deepStrictEqual(isTruthy(""), false)

Added in v2.0.0

isTupleOf

Determine if an Array is a tuple with exactly N elements, narrowing down the type to TupleOf.

An Array is considered to be a TupleOf if its length is exactly N.

Signature

export declare const isTupleOf: {
  <N extends number>(n: N): <T>(self: readonly T[]) => self is TupleOf<N, T>
  <T, N extends number>(self: readonly T[], n: N): self is TupleOf<N, T>
}

Example

import { isTupleOf } from "effect/Predicate"

assert.deepStrictEqual(isTupleOf([1, 2, 3], 3), true)
assert.deepStrictEqual(isTupleOf([1, 2, 3], 2), false)
assert.deepStrictEqual(isTupleOf([1, 2, 3], 4), false)

const arr: number[] = [1, 2, 3]
if (isTupleOf(arr, 3)) {
  console.log(arr)
  // ^? [number, number, number]
}

Added in v3.3.0

isTupleOfAtLeast

Determine if an Array is a tuple with at least N elements, narrowing down the type to TupleOfAtLeast.

An Array is considered to be a TupleOfAtLeast if its length is at least N.

Signature

export declare const isTupleOfAtLeast: {
  <N extends number>(n: N): <T>(self: readonly T[]) => self is [...TupleOf<N, T>, ...T[]]
  <T, N extends number>(self: readonly T[], n: N): self is [...TupleOf<N, T>, ...T[]]
}

Example

import { isTupleOfAtLeast } from "effect/Predicate"

assert.deepStrictEqual(isTupleOfAtLeast([1, 2, 3], 3), true)
assert.deepStrictEqual(isTupleOfAtLeast([1, 2, 3], 2), true)
assert.deepStrictEqual(isTupleOfAtLeast([1, 2, 3], 4), false)

const arr: number[] = [1, 2, 3, 4]
if (isTupleOfAtLeast(arr, 3)) {
  console.log(arr)
  // ^? [number, number, number, ...number[]]
}

Added in v3.3.0

isUint8Array

A guard that succeeds when the input is a Uint8Array.

Signature

export declare const isUint8Array: (input: unknown) => input is Uint8Array

Example

import { isUint8Array } from "effect/Predicate"

assert.deepStrictEqual(isUint8Array(new Uint8Array()), true)

assert.deepStrictEqual(isUint8Array(null), false)
assert.deepStrictEqual(isUint8Array({}), false)

Added in v2.0.0

isUndefined

Tests if a value is undefined.

Signature

export declare const isUndefined: (input: unknown) => input is undefined

Example

import { isUndefined } from "effect/Predicate"

assert.deepStrictEqual(isUndefined(undefined), true)

assert.deepStrictEqual(isUndefined(null), false)
assert.deepStrictEqual(isUndefined("undefined"), false)

Added in v2.0.0

isUnknown

A guard that always succeeds.

Signature

export declare const isUnknown: (input: unknown) => input is unknown

Example

import { isUnknown } from "effect/Predicate"

assert.deepStrictEqual(isUnknown(null), true)
assert.deepStrictEqual(isUnknown(undefined), true)

assert.deepStrictEqual(isUnknown({}), true)
assert.deepStrictEqual(isUnknown([]), true)

Added in v2.0.0

models

Predicate (interface)

Signature

export interface Predicate<in A> {
  (a: A): boolean
}

Added in v2.0.0

Refinement (interface)

Signature

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

Added in v2.0.0

type lambdas

PredicateTypeLambda (interface)

Signature

export interface PredicateTypeLambda extends TypeLambda {
  readonly type: Predicate<this["Target"]>
}

Added in v2.0.0

utils

compose

Signature

export declare const compose: {
  <A, B extends A, C extends B>(bc: Refinement<B, C>): (ab: Refinement<A, B>) => Refinement<A, C>
  <A, B extends A>(bc: Predicate<NoInfer<B>>): (ab: Refinement<A, B>) => Refinement<A, B>
  <A, B extends A, C extends B>(ab: Refinement<A, B>, bc: Refinement<B, C>): Refinement<A, C>
  <A, B extends A>(ab: Refinement<A, B>, bc: Predicate<NoInfer<B>>): Refinement<A, B>
}

Added in v2.0.0

struct

Signature

export declare const struct: <R extends Record<string, Predicate<any>>>(
  fields: R
) => Predicate<{ readonly [K in keyof R]: [R[K]] extends [Predicate<infer A>] ? A : never }>

Added in v2.0.0

tuple

Similar to Promise.all but operates on Predicates.

[Predicate<A>, Predicate<B>, ...] -> Predicate<[A, B, ...]>

Signature

export declare const tuple: <T extends readonly Predicate<any>[]>(
  ...elements: T
) => Predicate<Readonly<{ [I in keyof T]: [T[I]] extends [Predicate<infer A>] ? A : never }>>

Added in v2.0.0