Predicate overview
Added in v2.0.0
Table of contents
- combinators
- combining
- elements
- guards
- hasProperty
- isBigInt
- isBoolean
- isDate
- isError
- isFunction
- isIterable
- isMap
- isNever
- isNotNull
- isNotNullable
- isNotUndefined
- isNull
- isNullable
- isNumber
- isObject
- isPromise
- isPromiseLike
- isReadonlyRecord
- isRecord
- isRegExp
- isSet
- isString
- isSymbol
- isTagged
- isTruthy
- isTupleOf
- isTupleOfAtLeast
- isUint8Array
- isUndefined
- isUnknown
- models
- type lambdas
- type-level
- utils
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, 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, 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<ReadonlyArray<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, ...Array<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 | 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 | 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
isRegExp
Tests if a value is a RegExp
.
Signature
export declare const isRegExp: (input: unknown) => input is RegExp
Example
import { Predicate } from "effect"
assert.deepStrictEqual(Predicate.isRegExp(/a/), true)
assert.deepStrictEqual(Predicate.isRegExp("a"), false)
Added in v3.9.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: ReadonlyArray<T>) => self is TupleOf<N, T>
<T, N extends number>(self: ReadonlyArray<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: ReadonlyArray<T>) => self is TupleOfAtLeast<N, T>
<T, N extends number>(self: ReadonlyArray<T>, n: N): self is TupleOfAtLeast<N, 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
type-level
Predicate (namespace)
Added in v3.6.0
Any (type alias)
Signature
export type Any = Predicate<never>
Added in v3.6.0
In (type alias)
Signature
export type In<T extends Any> = [T] extends [Predicate<infer _A>] ? _A : never
Added in v3.6.0
Refinement (namespace)
Added in v3.6.0
Any (type alias)
Signature
export type Any = Refinement<any, any>
Added in v3.6.0
In (type alias)
Signature
export type In<T extends Any> = [T] extends [Refinement<infer _A, infer _>] ? _A : never
Added in v3.6.0
Out (type alias)
Signature
export type Out<T extends Any> = [T] extends [Refinement<infer _, infer _B>] ? _B : never
Added in v3.6.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
{ 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
export 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]> }
>
Added in v2.0.0
tuple
Similar to Promise.all
but operates on Predicate
s.
[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
export 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]> }
>
Added in v2.0.0