Predicate
Defines runtime checks for values.
A Predicate<A> returns true or false for an A. A Refinement<A, B> is a predicate that also narrows the TypeScript type when it succeeds. This module includes guards for common JavaScript values, property and tag checks, tuple and struct checks, boolean combinators, and helpers for composing predicates and refinements.
Combinators
Signature
declare const and: {
<A, C>(that: Refinement<A, C>): <B>(self: Refinement<A, B>) => Refinement<A, B & C>;
<A, B, C>(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>;
};Composes two predicates or refinements into one.
When to use
Use when you want to compose two Predicate checks in sequence, especially when chaining refinements for progressive narrowing.
Details
For refinements, the output type is narrowed by both checks. Evaluation short-circuits on the first false.
See
Signature
declare const compose: {
<A, B, C>(bc: Refinement<B, C>): (ab: Refinement<A, B>) => Refinement<A, C>;
<A, B>(bc: Predicate<NoInfer<B>>): (ab: Refinement<A, B>) => Refinement<A, B>;
<A, B, C>(ab: Refinement<A, B>, bc: Refinement<B, C>): Refinement<A, C>;
<A, B>(ab: Refinement<A, B>, bc: Predicate<NoInfer<B>>): Refinement<A, B>;
};Creates a predicate that returns true when both predicates agree.
When to use
Use when you want to check equivalence of two Predicates.
Details
Returns true when both results are equal.
See
Signature
declare const eqv: {
<A>(that: Predicate<A>): (self: Predicate<A>) => Predicate<A>;
<A>(self: Predicate<A>, that: Predicate<A>): Predicate<A>;
};Creates a predicate representing logical implication: if antecedent, then consequent.
When to use
Use when you need to encode logical implication between Predicate rules, where one rule only applies when a precondition holds.
Details
Models constraints like "if A then B" and returns true when the antecedent is false.
See
Signature
declare const implies: {
<A>(consequent: Predicate<A>): (antecedent: Predicate<A>) => Predicate<A>;
<A>(antecedent: Predicate<A>, consequent: Predicate<A>): Predicate<A>;
};Transforms the input of a predicate using a mapping function.
When to use
Use when you have a predicate on A and want to check B values by mapping each B to an A, such as checking lengths or projections.
Details
Returns a new predicate that applies f before self. There is no additional short-circuiting beyond what self does.
See
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>;
};Creates a predicate that returns true unless both predicates are true.
When to use
Use when you want to combine two Predicates with logical NAND semantics.
Details
Returns the negation of and.
See
Signature
declare const nand: {
<A>(that: Predicate<A>): (self: Predicate<A>) => Predicate<A>;
<A>(self: Predicate<A>, that: Predicate<A>): Predicate<A>;
};Creates a predicate that returns true when neither predicate is true.
When to use
Use when you want to combine two Predicates with logical NOR semantics.
Details
Returns the negation of or.
See
Signature
declare const nor: {
<A>(that: Predicate<A>): (self: Predicate<A>) => Predicate<A>;
<A>(self: Predicate<A>, that: Predicate<A>): Predicate<A>;
};Negates a predicate.
When to use
Use when you want the inverse of an existing predicate.
Details
Returns a new predicate that flips the boolean result.
See
Signature
declare function not<A>(self: Predicate<A>): Predicate<A>;Creates a predicate that returns true if either predicate is true.
When to use
Use when you want to combine Predicates with OR, accepting values that satisfy at least one condition, including refinements that narrow to a union.
Details
Evaluation short-circuits on the first true. For refinements, the output type is a union.
See
Signature
declare const or: {
<A, C>(that: Refinement<A, C>): <B>(self: Refinement<A, B>) => Refinement<A, C | B>;
<A, B, C>(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>;
};Creates a predicate for objects by applying predicates to named properties.
When to use
Use when you want to validate a record shape at runtime by lifting property predicates into an object predicate.
Details
Returns a refinement if any field predicate is a refinement. Only the specified keys are checked, and extra keys are ignored.
See
Signature
declare function Struct<R extends Record<string, Any>>(
fields: R,
): [Extract<R[keyof R], Any>] extends [never]
? Predicate<{ [K in string | number | symbol]: In<R[K]> }>
: Refinement<
{ [K in string | number | symbol]: R[K] extends Any ? In<any[any]> : In<R[K]> },
{ [K in string | number | symbol]: R[K] extends Any ? Out<any[any]> : In<R[K]> }
>;Creates a predicate for tuples by applying predicates to each element.
When to use
Use when you want to validate tuple positions independently by lifting element predicates into a tuple predicate.
Details
Returns a refinement if any element predicate is a refinement. Evaluation stops at the first failing element.
See
Signature
declare function Tuple<T extends readonly Array<Any>>(elements: T): [Extract<T[number], Any>] extends [never] ? Predicate<{ [I in string | number | symbol]: In<T[I]> }> : Refinement<{ [I in string | number | symbol]: T[I] extends Any ? In<any[any]> : In<T[I]> }, { [I in string | number | symbol]: T[I] extends Any ? Out<any[any]> : In<T[I]> }>Creates a predicate that returns true if exactly one predicate is true.
When to use
Use when you want to combine two Predicates with exclusive-or semantics.
Details
Returns true when results differ.
See
Signature
declare const xor: {
<A>(that: Predicate<A>): (self: Predicate<A>) => Predicate<A>;
<A>(self: Predicate<A>, that: Predicate<A>): Predicate<A>;
};Combining
Creates a predicate that returns true if all predicates in the collection return true.
When to use
Use when you have a dynamic list of predicates to apply.
Details
Evaluation short-circuits on the first false. The collection is iterated each time the predicate is called.
See
Signature
declare function every<A>(collection: Iterable<Predicate<A>>): Predicate<A>;Creates a predicate that returns true if any predicate in the collection returns true.
When to use
Use when you have a dynamic list of predicates and only need one to pass.
Details
Evaluation short-circuits on the first true. The collection is iterated each time the predicate is called.
See
Signature
declare function some<A>(collection: Iterable<Predicate<A>>): Predicate<A>;Guards
hasProperty
Checks whether a value has a given property key.
When to use
Use when you need a Predicate guard for property access on unknown values with a simple structural object check.
Details
Uses the in operator and isObjectKeyword. This does not check property value types.
See
Signature
declare const hasProperty: {
<P extends PropertyKey>(property: P): (self: unknown) => self is { [K in PropertyKey]: unknown };
<P extends PropertyKey>(self: unknown, property: P): self is { [K in PropertyKey]: unknown };
};Checks whether a value is a bigint.
When to use
Use when you need a Predicate guard to narrow an unknown value to a bigint.
Details
Uses typeof input === "bigint".
See
Signature
declare function isBigInt(input: unknown): input is bigint;Checks whether a value is a boolean.
When to use
Use when you need a Predicate guard to narrow an unknown value to a boolean.
Details
Uses typeof input === "boolean".
See
Signature
declare function isBoolean(input: unknown): input is boolean;Checks whether a value is a Date.
When to use
Use when you need a Predicate runtime guard for dates.
Details
Uses instanceof Date.
See
Signature
declare function isDate(input: unknown): input is Date;Checks whether a value is an Error.
When to use
Use when you need a Predicate guard for errors caught from unknown sources.
Details
Uses instanceof Error.
See
Signature
declare function isError(input: unknown): input is Error;isFunction
Checks whether a value is a function.
When to use
Use when you need a Predicate guard to narrow an unknown value to a callable function.
Details
Uses typeof input === "function".
See
Signature
declare function isFunction(input: unknown): input is Function;isIterable
Checks whether a value is iterable.
When to use
Use when you need a Predicate guard before iterating an unknown value.
Details
Accepts strings as iterable and uses hasProperty for Symbol.iterator.
See
Signature
declare function isIterable(input: unknown): input is Iterable<unknown, any, any>;Checks whether a value is a Map.
When to use
Use when you need a Predicate runtime guard for Map values.
Details
Uses instanceof Map.
See
Signature
declare function isMap(input: unknown): input is Map<unknown, unknown>;Type guard that always returns false.
When to use
Use when you need a Predicate that never accepts, e.g. in default branches.
See
Signature
declare function isNever(_: unknown): _ is never;Checks whether a value is not null.
When to use
Use when you need a Predicate refinement that filters out null while preserving other falsy values.
Details
Returns a refinement that excludes null.
See
Signature
declare function isNotNull<A>(input: A): input is Exclude<A, null>;isNotNullish
Checks whether a value is not null and not undefined.
When to use
Use when you need a Predicate refinement that filters out nullish values but keeps other falsy ones.
Details
Uses input != null.
See
Signature
declare function isNotNullish<A>(input: A): input is NonNullable<A>;isNotUndefined
Checks whether a value is not undefined.
When to use
Use when you need a Predicate refinement that filters out undefined while preserving other falsy values.
Details
Returns a refinement that excludes undefined.
See
Signature
declare function isNotUndefined<A>(input: A): input is Exclude<A, undefined>;Checks whether a value is null.
When to use
Use when you need a Predicate guard for nullable values.
Details
Uses input === null.
See
Signature
declare function isNull(input: unknown): input is null;Checks whether a value is null or undefined.
When to use
Use when you need a Predicate guard for nullish values.
Details
Uses input === null || input === undefined.
See
Signature
declare function isNullish<A>(input: A): input is (A & null) | undefined;Checks whether a value is a number.
When to use
Use when you need a Predicate guard to narrow an unknown value to a number.
Details
Uses typeof input === "number" and does not exclude NaN or Infinity.
See
Signature
declare function isNumber(input: unknown): input is number;Checks whether a value is a non-null object value that is not an array.
When to use
Use to narrow unknown input to a non-null, non-array object with a Predicate guard.
Details
This is a structural runtime check using typeof input === "object", so it also accepts object instances such as Date, Map, class instances, and typed arrays. It excludes null and arrays.
See
Signature
declare function isObject(input: unknown): input is {
[x: string | number | symbol]: unknown;
};isObjectKeyword
Checks whether a value is an object in the JavaScript sense (objects, arrays, functions).
When to use
Use when you need a Predicate guard that accepts arrays and functions as well as objects.
Details
Returns true for arrays and functions, and false for null.
See
Signature
declare function isObjectKeyword(input: unknown): input is object;isObjectOrArray
Checks whether a value is an object or an array (non-null object).
When to use
Use when you need a Predicate guard that accepts plain objects and arrays, but not null.
Details
Uses typeof input === "object" && input !== null and includes arrays.
See
Signature
declare function isObjectOrArray(input: unknown): input is
| Array<unknown>
| {
[x: string | number | symbol]: unknown;
};Checks whether a value is a Promise-like object with then and catch.
When to use
Use when you need a Predicate guard for promise instances across realms.
Details
Performs a structural check for then and catch functions.
See
Signature
declare function isPromise(input: unknown): input is Promise<unknown>;isPromiseLike
Checks whether a value is PromiseLike (has a then method).
When to use
Use when you need a Predicate guard for promise-like values with a callable then method.
Details
Performs a structural check for a callable then.
See
Signature
declare function isPromiseLike(input: unknown): input is PromiseLike<unknown>;isPropertyKey
Checks whether a value is a valid PropertyKey (string, number, or symbol).
When to use
Use when you need a Predicate guard for unknown property keys before indexing.
Details
Uses isString, isNumber, and isSymbol.
See
Signature
declare function isPropertyKey(u: unknown): u is PropertyKey;isReadonlyObject
Checks whether a value is a non-null, non-array object and narrows it to a readonly indexable object type.
When to use
Use to narrow unknown input to a readonly view of a non-null, non-array object with a Predicate guard.
Details
Readonly-ness is a TypeScript type-level view; it is not observable at runtime. This delegates to isObject, so class instances and built-in object instances are accepted.
See
Signature
declare function isReadonlyObject(input: unknown): input is {
[x: string | number | symbol]: unknown;
};Checks whether a value is a RegExp.
When to use
Use when you need a Predicate runtime guard for regular expressions.
Details
Uses instanceof RegExp.
See
Signature
declare function isRegExp(input: unknown): input is RegExp;Checks whether a value is a Set.
When to use
Use when you need a Predicate runtime guard for Set values.
Details
Uses instanceof Set.
See
Signature
declare function isSet(input: unknown): input is Set<unknown>;Checks whether a value is a string.
When to use
Use when you need a Predicate guard to narrow an unknown value to a string.
Details
Uses typeof input === "string".
See
Signature
declare function isString(input: unknown): input is string;Checks whether a value is a symbol.
When to use
Use when you need a Predicate guard to narrow an unknown value to a symbol.
Details
Uses typeof input === "symbol".
See
Signature
declare function isSymbol(input: unknown): input is symbol;Checks whether a value has a _tag property equal to the given tag.
When to use
Use when you model tagged unions with a _tag field and want a quick Predicate guard for tagged values.
Details
Uses hasProperty and strict equality on _tag.
See
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;
};
};Checks whether a readonly array has exactly n elements.
When to use
Use when you need a Predicate guard for exact tuple length that narrows ReadonlyArray<T> to TupleOf<N, T>.
Details
This only checks length, not element types, and returns a refinement on the array type.
See
Signature
declare const isTupleOf: {
<N extends number>(n: N): <T>(self: readonly Array<T>) => self is TupleOf<N, T>;
<T, N extends number>(self: readonly Array<T>, n: N): self is TupleOf<N, T>;
}isTupleOfAtLeast
Checks whether a readonly array has at least n elements.
When to use
Use when you need a Predicate guard for tuple-like minimum length that narrows ReadonlyArray<T> to TupleOfAtLeast<N, T>.
Details
This only checks length, not element types, and returns a refinement on the array type.
See
Signature
declare const isTupleOfAtLeast: {
<N extends number>(n: N): <T>(self: readonly Array<T>) => self is [...Array<TupleOf<N, T>>, ...Array<T>];
<T, N extends number>(self: readonly Array<T>, n: N): self is [...Array<TupleOf<N, T>>, ...Array<T>];
}isUint8Array
Checks whether a value is a Uint8Array.
When to use
Use when you need a Predicate runtime guard for binary data.
Details
Uses instanceof Uint8Array.
See
Signature
declare function isUint8Array(input: unknown): input is Uint8Array<ArrayBufferLike>;isUndefined
Checks whether a value is undefined.
When to use
Use when you need a Predicate guard for values that are exactly undefined.
Details
Uses input === undefined.
See
Signature
declare function isUndefined(input: unknown): input is undefined;Type guard that always returns true.
When to use
Use when you need a Predicate that always accepts, e.g. as a placeholder.
See
Signature
declare function isUnknown(_: unknown): _ is unknown;Models
A function that decides whether a value of type A satisfies a condition.
When to use
Use when you want a reusable boolean check for A, especially when you plan to combine checks with and/or or pass a predicate to arrays and iterables.
Details
A predicate returns true or false and never throws by itself. It does not narrow types unless you use Refinement.
See
Signature
interface Predicate<in A> {
(a: A): boolean;
}Refinement interface
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.
See
Signature
interface Refinement<in A, out B extends A> {
(a: A): a is B;
}Other
Type-level utilities for working with 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.
See
Refinement
Type-level utilities for working with 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.
See
Predicates
Checks whether a value is truthy.
When to use
Use when you want a predicate that mirrors JavaScript truthiness and filters out falsy values like 0, "", and false.
Details
This uses !!input and treats 0, "", false, null, and undefined as false.
See
Signature
declare function isTruthy(input: unknown): boolean;Utility Types
PredicateTypeLambda interface
Type-level lambda for higher-kinded usage of Predicate.
When to use
Use when you are defining APIs that abstract over predicates with HKTs and need a TypeLambda instance for predicate-based type classes.
Details
This is type-only, creates no runtime value, and does not affect emitted JavaScript.
See
Signature
interface PredicateTypeLambda extends TypeLambda {
readonly type: Predicate<unknown>;
}
Creates a predicate that returns
trueonly if both predicates aretrue.When to use
Use when you want to combine
Predicates with AND, accepting values that satisfy multiple conditions, including refinements that narrow to an intersection.Details
Evaluation short-circuits on the first
false. For refinements, the output type is an intersection.See
ornot