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

Predicate.ts overview

Since v2.0.0

Exports Grouped by Category

combinators

and

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

Example

import * as assert from "node:assert"
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)

Signature

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>
}

Source

Since v2.0.0

eqv

Signature

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

Source

Since 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.

Example

import * as assert from "node:assert"
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)

Signature

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

Source

Since v2.0.0

mapInput

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

Example

import * as assert from "node:assert"
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)

Signature

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>
}

Source

Since v2.0.0

nand

Signature

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

Source

Since v2.0.0

nor

Signature

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

Source

Since v2.0.0

not

Negates the result of a given predicate.

Example

import * as assert from "node:assert"
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)

Signature

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

Source

Since v2.0.0

or

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

Example

import * as assert from "node:assert"
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)

Signature

declare const or: {
  <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>
}

Source

Since v2.0.0

xor

Signature

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

Source

Since v2.0.0

combining

all

Signature

declare const all: <A>(collection: Iterable<Predicate<A>>) => Predicate<ReadonlyArray<A>>

Source

Since v2.0.0

product

Signature

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

Source

Since v2.0.0

productMany

Signature

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

Source

Since v2.0.0

elements

every

Signature

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

Source

Since v2.0.0

some

Signature

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

Source

Since v2.0.0

guards

hasProperty

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

Signature

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 }
}

Source

Since v2.0.0

isBigInt

Tests if a value is a bigint.

Example

import * as assert from "node:assert"
import { isBigInt } from "effect/Predicate"

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

assert.deepStrictEqual(isBigInt(1), false)

Signature

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

Source

Since v2.0.0

isBoolean

Tests if a value is a boolean.

Example

import * as assert from "node:assert"
import { isBoolean } from "effect/Predicate"

assert.deepStrictEqual(isBoolean(true), true)

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

Signature

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

Source

Since v2.0.0

isDate

A guard that succeeds when the input is a Date.

Example

import * as assert from "node:assert"
import { isDate } from "effect/Predicate"

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

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

Signature

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

Source

Since v2.0.0

isError

A guard that succeeds when the input is an Error.

Example

import * as assert from "node:assert"
import { isError } from "effect/Predicate"

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

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

Signature

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

Source

Since v2.0.0

isFunction

Tests if a value is a function.

Example

import * as assert from "node:assert"
import { isFunction } from "effect/Predicate"

assert.deepStrictEqual(isFunction(isFunction), true)

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

Signature

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

Source

Since v2.0.0

isIterable

A guard that succeeds when the input is an Iterable.

Example

import * as assert from "node:assert"
import { isIterable } from "effect/Predicate"

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

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

Signature

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

Source

Since v2.0.0

isMap

Tests if a value is a Map.

Example

import * as assert from "node:assert"
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)

Signature

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

Source

Since v2.0.0

isNever

A guard that always fails.

Example

import * as assert from "node:assert"
import { isNever } from "effect/Predicate"

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

Signature

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

Source

Since v2.0.0

isNotNull

Tests if a value is not null.

Example

import * as assert from "node:assert"
import { isNotNull } from "effect/Predicate"

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

assert.deepStrictEqual(isNotNull(null), false)

Signature

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

Source

Since v2.0.0

isNotNullable

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

Example

import * as assert from "node:assert"
import { isNotNullable } from "effect/Predicate"

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

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

Signature

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

Source

Since v2.0.0

isNotUndefined

Tests if a value is not undefined.

Example

import * as assert from "node:assert"
import { isNotUndefined } from "effect/Predicate"

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

assert.deepStrictEqual(isNotUndefined(undefined), false)

Signature

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

Source

Since v2.0.0

isNull

Tests if a value is null.

Example

import * as assert from "node:assert"
import { isNull } from "effect/Predicate"

assert.deepStrictEqual(isNull(null), true)

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

Signature

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

Source

Since v2.0.0

isNullable

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

Example

import * as assert from "node:assert"
import { isNullable } from "effect/Predicate"

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

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

Signature

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

Source

Since v2.0.0

isNumber

Tests if a value is a number.

Example

import * as assert from "node:assert"
import { isNumber } from "effect/Predicate"

assert.deepStrictEqual(isNumber(2), true)

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

Signature

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

Source

Since v2.0.0

isObject

Tests if a value is an object.

Example

import * as assert from "node:assert"
import { isObject } from "effect/Predicate"

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

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

Signature

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

Source

Since v2.0.0

isPromise

A guard that succeeds when the input is a Promise.

Example

import * as assert from "node:assert"
import { isPromise } from "effect/Predicate"

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

Signature

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

Source

Since v2.0.0

isPromiseLike

Signature

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

Source

Since v2.0.0

isReadonlyRecord

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

Example

import * as assert from "node:assert"
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)

Signature

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

Source

Since v2.0.0

isRecord

A guard that succeeds when the input is a record.

Example

import * as assert from "node:assert"
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
)

Signature

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

Source

Since v2.0.0

isRegExp

Tests if a value is a RegExp.

Example

import * as assert from "node:assert"
import { Predicate } from "effect"

assert.deepStrictEqual(Predicate.isRegExp(/a/), true)
assert.deepStrictEqual(Predicate.isRegExp("a"), false)

Signature

declare const isRegExp: (input: unknown) => input is RegExp

Source

Since v3.9.0

isSet

Tests if a value is a Set.

Example

import * as assert from "node:assert"
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)

Signature

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

Source

Since v2.0.0

isString

Tests if a value is a string.

Example

import * as assert from "node:assert"
import { isString } from "effect/Predicate"

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

assert.deepStrictEqual(isString(1), false)

Signature

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

Source

Since v2.0.0

isSymbol

Tests if a value is a symbol.

Example

import * as assert from "node:assert"
import { isSymbol } from "effect/Predicate"

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

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

Signature

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

Source

Since v2.0.0

isTagged

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

Example

import * as assert from "node:assert"
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)

Signature

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 }
}

Source

Since v2.0.0

isTruthy

Tests if a value is truthy.

Example

import * as assert from "node:assert"
import { isTruthy } from "effect/Predicate"

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

Signature

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

Source

Since 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.

Example

import * as assert from "node:assert"
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]
}

Signature

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

Source

Since 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.

Example

import * as assert from "node:assert"
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[]]
}

Signature

declare const isTupleOfAtLeast: {
  <N extends number>(n: N): <T>(self: ReadonlyArray<T>) => self is TupleOfAtLeast<N, T>
  <T, N extends number>(self: ReadonlyArray<T>, n: N): self is TupleOfAtLeast<N, T>
}

Source

Since v3.3.0

isUint8Array

A guard that succeeds when the input is a Uint8Array.

Example

import * as assert from "node:assert"
import { isUint8Array } from "effect/Predicate"

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

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

Signature

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

Source

Since v2.0.0

isUndefined

Tests if a value is undefined.

Example

import * as assert from "node:assert"
import { isUndefined } from "effect/Predicate"

assert.deepStrictEqual(isUndefined(undefined), true)

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

Signature

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

Source

Since v2.0.0

isUnknown

A guard that always succeeds.

Example

import * as assert from "node:assert"
import { isUnknown } from "effect/Predicate"

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

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

Signature

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

Source

Since v2.0.0

models

Predicate (interface)

Signature

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

Source

Since v2.0.0

Refinement (interface)

Signature

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

Source

Since v2.0.0

type lambdas

PredicateTypeLambda (interface)

Signature

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

Source

Since v2.0.0

type-level

Predicate (namespace)

Source

Since v3.6.0

In (type alias)

Signature

type In<T> = [T] extends [Predicate<infer _A>] ? _A : never

Source

Since v3.6.0

Any (type alias)

Signature

type Any = Predicate<never>

Source

Since v3.6.0

Refinement (namespace)

Source

Since v3.6.0

In (type alias)

Signature

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

Source

Since v3.6.0

Out (type alias)

Signature

type Out<T> = [T] extends [Refinement<infer _, infer _B>] ? _B : never

Source

Since v3.6.0

Any (type alias)

Signature

type Any = Refinement<any, any>

Source

Since v3.6.0

utils

compose

Signature

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>
}

Source

Since v2.0.0

struct 

{ ab: Refinement<A, B>; cd: Refinement<C, D>, ... } -> Refinement<{ ab: A; cd: C; ... }, { ab: B; cd: D; ... }>
{ a: Predicate<A, B>; b: Predicate<B>, ... } -> Predicate<{ a: A; b: B; ... }>
{ ab: Refinement<A, B>; c: Predicate<C>, ... } -> Refinement<{ ab: A; c: C; ... }, { ab: B; c: ะก; ... }>

Signature

declare const struct: <R extends Record<string, Predicate.Any>>(
  fields: R
) => [Extract<R[keyof R], Refinement.Any>] extends [never]
  ? Predicate<{ readonly [K in keyof R]: Predicate.In<R[K]> }>
  : Refinement<
      { readonly [K in keyof R]: R[K] extends Refinement.Any ? Refinement.In<R[K]> : Predicate.In<R[K]> },
      { readonly [K in keyof R]: R[K] extends Refinement.Any ? Refinement.Out<R[K]> : Predicate.In<R[K]> }
    >

Source

Since v2.0.0

tuple

Similar to Promise.all but operates on Predicates.

[Refinement<A, B>, Refinement<C, D>, ...] -> Refinement<[A, C, ...], [B, D, ...]>
[Predicate<A>, Predicate<B>, ...] -> Predicate<[A, B, ...]>
[Refinement<A, B>, Predicate<C>, ...] -> Refinement<[A, C, ...], [B, C, ...]>

Signature

declare const tuple: <T extends ReadonlyArray<Predicate.Any>>(
  ...elements: T
) => [Extract<T[number], Refinement.Any>] extends [never]
  ? Predicate<{ readonly [I in keyof T]: Predicate.In<T[I]> }>
  : Refinement<
      { readonly [I in keyof T]: T[I] extends Refinement.Any ? Refinement.In<T[I]> : Predicate.In<T[I]> },
      { readonly [I in keyof T]: T[I] extends Refinement.Any ? Refinement.Out<T[I]> : Predicate.In<T[I]> }
    >

Source

Since v2.0.0