Filter

Defines composable checks that can also transform values.

A Filter<Input, Pass, Fail> receives an input and returns a Result. Success means the value passed the filter, and failure means the value was filtered out. Filters may also narrow or transform the passing value. This module includes constructors from predicates, options, and effects, built-in filters for common JavaScript values and tags, helpers for combining filters, and conversions to predicates, options, and results.

30 exports Since v4.0.0 Source

Combinators

andLeft

Since v4.0.0

Combines two filters but only returns the result of the left filter.

Signature

declare const andLeft: {
  <InputR, PassR, FailR>(right: Filter<InputR, PassR, FailR>): <InputL, PassL, FailL>(left: Filter<InputL, PassL, FailL>) => Filter<InputL & InputR, PassL, FailR | FailL>;
  <InputL, PassL, FailL, InputR, PassR, FailR>(left: Filter<InputL, PassL, FailL>, right: Filter<InputR, PassR, FailR>): Filter<InputL & InputR, PassL, FailL | FailR>;
}

Example Keeping the left filter result

import { Filter, Result } from "effect"

const positiveNumbers = Filter.fromPredicate((n: number) => n > 0)
const evenNumbers = Filter.fromPredicate((n: number) => n % 2 === 0)

const positiveEven = Filter.andLeft(positiveNumbers, evenNumbers)
positiveEven(2) // => Result.succeed(2)

andRight

Since v4.0.0

Combines two filters but only returns the result of the right filter.

Signature

declare const andRight: {
  <InputR, PassR, FailR>(right: Filter<InputR, PassR, FailR>): <InputL, PassL, FailL>(left: Filter<InputL, PassL, FailL>) => Filter<InputL & InputR, PassR, FailR | FailL>;
  <InputL, PassL, FailL, InputR, PassR, FailR>(left: Filter<InputL, PassL, FailL>, right: Filter<InputR, PassR, FailR>): Filter<InputL & InputR, PassR, FailL | FailR>;
}

Example Keeping the right filter result

import { Filter, Result } from "effect"

const positiveNumbers = Filter.fromPredicate((n: number) => n > 0)
const doubleNumbers = Filter.make((n: number) =>
  n > 0 ? Result.succeed(n * 2) : Result.fail(n)
)

const positiveDoubled = Filter.andRight(positiveNumbers, doubleNumbers)
positiveDoubled(2) // => Result.succeed(4)

compose

Since v4.0.0

Composes two filters sequentially, feeding the output of the first into the second.

Signature

declare const compose: {
  <PassL, PassR, FailR>(right: Filter<PassL, PassR, FailR>): <InputL, FailL>(left: Filter<InputL, PassL, FailL>) => Filter<InputL, PassR, FailR | FailL>;
  <InputL, PassL, FailL, PassR, FailR>(left: Filter<InputL, PassL, FailL>, right: Filter<PassL, PassR, FailR>): Filter<InputL, PassR, FailL | FailR>;
}

Example Composing filters

import { Filter, Result } from "effect"

const stringFilter = Filter.string
const nonEmptyUpper = Filter.make((s: string) =>
  s.length > 0 ? Result.succeed(s.toUpperCase()) : Result.fail(s)
)

const stringToUpper = Filter.compose(stringFilter, nonEmptyUpper)
stringToUpper("hello") // => Result.succeed("HELLO")

composePassthrough

Since v4.0.0

Composes two filters sequentially, passing the successful output of the first filter to the second.

Details

If either filter fails, the returned filter fails with the original input instead of the intermediate failure value.

Signature

declare const composePassthrough: {
  <InputL, PassL, PassR, FailR>(right: Filter<PassL, PassR, FailR>): <FailL>(left: Filter<InputL, PassL, FailL>) => Filter<InputL, PassR, InputL>;
  <InputL, PassL, FailL, PassR, FailR>(left: Filter<InputL, PassL, FailL>, right: Filter<PassL, PassR, FailR>): Filter<InputL, PassR, InputL>;
}

or

Since v4.0.0

Combines two filters with logical OR semantics.

Signature

declare const or: {
  <Input2, Pass2, Fail2>(that: Filter<Input2, Pass2, Fail2>): <Input1, Pass2, Fail2>(self: Filter<Input1, Pass2>) => Filter<Input1 & Input2, Pass2, Fail2>;
  <Input1, Pass1, Fail1, Input2, Pass2, Fail2>(self: Filter<Input1, Pass1, Fail1>, that: Filter<Input2, Pass2, Fail2>): Filter<Input1 & Input2, Pass1 | Pass2, Fail2>;
}

zip

Since v4.0.0

Combines two filters into a tuple of their results.

Details

Both filters must succeed for the combination to succeed. If both pass, their outputs are combined into a tuple.

Signature

declare const zip: {
  <InputR, PassR, FailR>(right: Filter<InputR, PassR, FailR>): <InputL, PassL, FailL>(left: Filter<InputL, PassL, FailL>) => Filter<InputL & InputR, [PassL, PassR], FailR | FailL>;
  <InputL, PassL, FailL, InputR, PassR, FailR>(left: Filter<InputL, PassL, FailL>, right: Filter<InputR, PassR, FailR>): Filter<InputL & InputR, [PassL, PassR], FailL | FailR>;
}

Example Zipping filters

import { Filter, Result } from "effect"

const positiveNumbers = Filter.fromPredicate((n: number) => n > 0)
const evenNumbers = Filter.fromPredicate((n: number) => n % 2 === 0)

const positiveAndEven = Filter.zip(positiveNumbers, evenNumbers)
positiveAndEven(2) // => Result.succeed([2, 2])

zipWith

Since v4.0.0

Combines two filters and applies a function to their results.

When to use

Use to combine two filters with a custom function to merge their outputs.

Details

Both filters must succeed (not return fail) for the combination to succeed. If both filters pass, their outputs are combined using the provided function.

See

zip for combining two filters into a tuple

Signature

declare const zipWith: {
  <PassL, InputR, PassR, FailR, A>(right: Filter<InputR, PassR, FailR>, f: (left: PassL, right: PassR) => A): <InputL, FailL>(left: Filter<InputL, PassL, FailL>) => Filter<InputL & InputR, A, FailR | FailL>;
  <InputL, PassL, FailL, InputR, PassR, FailR, A>(left: Filter<InputL, PassL, FailL>, right: Filter<InputR, PassR, FailR>, f: (left: PassL, right: PassR) => A): Filter<InputL & InputR, A, FailL | FailR>;
}

Constructors

bigint

Since v4.0.0

A predefined filter that only passes through bigint primitive values.

When to use

Use to keep primitive big integer values from unknown input while staying in the composable Filter / Result pipeline.

Details

Implemented with fromPredicate(Predicate.isBigInt), so values where typeof input === "bigint" succeed and all other inputs fail with the original input.

Gotchas

This filter does not coerce numbers or strings; 1n passes while 1 fails.

See

number for JavaScript number values
Predicate.isBigInt for the underlying guard

Signature

declare const bigint: Filter<unknown, bigint>

boolean

Since v4.0.0

A predefined filter that only passes through boolean values.

When to use

Use when accepting an unknown input only if it is already a boolean and you want a Filter result rather than a plain predicate result.

Details

Implemented with fromPredicate(Predicate.isBoolean), so true and false succeed and non-booleans fail with the original input.

See

Predicate.isBoolean for the underlying guard
fromPredicate for custom predicate-based filters

Signature

declare const boolean: Filter<unknown, boolean>

date

Since v4.0.0

A predefined filter that only passes through Date objects.

When to use

Use when you need to narrow unknown input to JavaScript Date instances with a reusable Filter.

Details

Implemented with fromPredicate(Predicate.isDate), so passing values return Result.succeed(input) and failing values return Result.fail(input).

Gotchas

The check uses instanceof Date, so invalid Date objects still pass; the filter does not validate the timestamp.

See

Predicate.isDate for the underlying guard
instanceOf for constructor-based filtering
fromPredicate for custom date checks

Signature

declare const date: Filter<unknown, Date>

equals

Since v4.0.0

Creates a filter that only passes values equal to the specified value using structural equality.

When to use

Use to accept inputs that are structurally equal to a known expected value while staying in a composable Filter / Result pipeline.

Details

Delegates to Equal.equals. On success it returns Result.succeed(value); on failure it returns Result.fail(input).

See

equalsStrict for JavaScript === matching instead of structural equality
Equal.equals for the underlying structural equality semantics

Signature

declare function equals<A, Input = unknown>(value: A): Filter<Input, A, EqualsWith<Input, A, A, Exclude<Input, A>>>

equalsStrict

Since v4.0.0

Creates a Filter that passes only values strictly equal to the specified value using JavaScript === comparison.

When to use

Use when you need a Filter that accepts only the exact primitive value or object reference using JavaScript strict equality in a Filter / Result pipeline.

Gotchas

NaN never passes, even when the expected value is NaN, and objects pass only when they are the same reference.

See

equals for structural equality when distinct values with equal contents should pass

Signature

declare function equalsStrict<A, Input = unknown>(value: A): Filter<Input, A, EqualsWith<Input, A, A, Exclude<Input, A>>>

fromPredicate

Since v4.0.0

Creates a Filter from a predicate or refinement function.

Details

This is a convenient way to create filters from boolean-returning functions. When the predicate returns true, the input value is passed through unchanged. When it returns false, the fail type is returned.

Signature

declare const fromPredicate: {
  <A, B>(refinement: Refinement<A, B>): Filter<A, B, EqualsWith<A, B, A, Exclude<A, B>>>;
  <A>(predicate: Predicate<A>): Filter<A>;
}

Example Creating filters from predicates

import { Filter, Result } from "effect"

// Create filter from predicate
const positiveNumbers = Filter.fromPredicate((n: number) => n > 0)
const nonEmptyStrings = Filter.fromPredicate((s: string) => s.length > 0)

// Type refinement
const isString = Filter.fromPredicate((x: unknown): x is string =>
  typeof x === "string"
)
positiveNumbers(1) // => Result.succeed(1)
nonEmptyStrings("") // => Result.fail("")
isString("ok") // => Result.succeed("ok")

fromPredicateOption

Since v4.0.0

Creates a Filter from a function that returns an Option; Some(value) passes with value, and None fails with the original input.

Signature

declare function fromPredicateOption<A, B>(predicate: (a: A) => Option<B>): Filter<A, B>

has

Since v4.0.0

Creates a Filter that passes inputs whose has(key) method returns true for the specified key.

When to use

Use to keep inputs that expose a has method, such as Set or Map, when they contain a required key.

See

fromPredicate for custom predicate filters or inputs without a has method
Predicate.hasProperty for guarding property presence instead of calling an input's has method

Signature

declare function has<K>(key: K): <Input extends {
  readonly has: (key: K) => boolean;
}>(input: Input) => Result<Input, Input>

instanceOf

Since v4.0.0

Creates a filter that only passes instances of the given constructor.

When to use

Use to narrow unknown input to values created by a specific JavaScript constructor while keeping the result in the Filter / Result pipeline.

Details

The filter succeeds when the input satisfies instanceof constructor. Otherwise it fails with the original input.

Gotchas

This uses JavaScript instanceof semantics, including prototype-chain and realm behavior.

See

fromPredicate for custom predicate-based narrowing

Signature

declare function instanceOf<K extends (...args: any) => any>(constructor: K): <Input>(u: Input) => Result<InstanceType<K>, Exclude<Input, InstanceType<K>>>

make

Since v4.0.0

Creates a Filter from a function that returns either a pass or fail value.

Details

This is the primary constructor for creating custom filters. The function should return either Result.succeed(value) or Result.fail(value).

Signature

declare function make<Input, Pass, Fail>(f: (input: Input) => Result<Pass, Fail>): Filter<Input, Pass, Fail>

Example Creating custom filters

import { Filter, Result } from "effect"

// Create a filter for positive numbers
const positiveFilter = Filter.make((n: number) => n > 0 ? Result.succeed(n) : Result.fail(n))

// Create a filter that transforms strings to uppercase
const uppercaseFilter = Filter.make((s: string) =>
  s.length > 0 ? Result.succeed(s.toUpperCase()) : Result.fail(s)
)
positiveFilter(1) // => Result.succeed(1)
uppercaseFilter("ok") // => Result.succeed("OK")

makeEffect

Since v4.0.0

Creates an effectful Filter from a function that returns an Effect.

Details

This constructor is used when the filtering operation needs to perform effectful computations, such as async operations, error handling, or accessing services from the environment.

Signature

declare function makeEffect<Input, Pass, Fail, E, R>(f: (input: Input) => Effect<Result<Pass, Fail>, E, R>): FilterEffect<Input, Pass, Fail, E, R>

Example Creating effectful filters

import { Effect, Filter, Result } from "effect"

// Create an effectful filter that validates async
const asyncValidate = Filter.makeEffect((id: string) =>
  Effect.gen(function*() {
    const isValid = yield* Effect.succeed(id.length > 0)
    return isValid ? Result.succeed(id) : Result.fail(id)
  })
)

await Effect.runPromise(asyncValidate("id")) // => Result.succeed("id")

number

Since v4.0.0

A predefined filter that only passes through number values.

Signature

declare const number: Filter<unknown, number>

Example Filtering numbers

import { Filter, Result } from "effect"

Filter.number(42) // => Result.succeed(42)
Filter.number("42") // => Result.fail("42")

reason

Since v4.0.0

Creates a filter that extracts a reason from a tagged error.

Signature

declare const reason: {
  <Input>(): <Tag extends string, ReasonTag extends string>(tag: Tag, reasonTag: ReasonTag) => Filter<Input, ExtractReason<ExtractTag<Input, Tag>, ReasonTag>, Input>;
  <Input, Tag extends string, ReasonTag extends string>(tag: Tag, reasonTag: ReasonTag): Filter<Input, ExtractReason<ExtractTag<Input, Tag>, ReasonTag>, Input>;
  <Tag extends string, ReasonTag extends string>(tag: Tag, reasonTag: ReasonTag): <Input>(input: Input) => Result<ExtractReason<ExtractTag<Input, Tag>, ReasonTag>, Input>;
}

string

Since v4.0.0

A predefined filter that only passes through string values.

Signature

declare const string: Filter<unknown, string>

Example Filtering strings

import { Filter, Result } from "effect"

Filter.string("hello") // => Result.succeed("hello")
Filter.string(42) // => Result.fail(42)

symbol

Since v4.0.0

A predefined filter that only passes through Symbol values.

Signature

declare const symbol: Filter<unknown, symbol>

tagged

Since v4.0.0

Creates a filter that checks if an input is tagged with a specific tag.

When to use

Use to keep only the matching member of a _tag-discriminated union while staying in a composable Filter / Result pipeline.

Details

The filter succeeds when Predicate.isTagged(input, tag) returns true. Otherwise it fails with the original input.

Gotchas

This only checks _tag; it does not validate the rest of the variant fields.

See

Predicate.isTagged for the underlying boolean guard when a Filter result is not needed
reason for extracting a nested reason variant from tagged errors

Signature

declare const tagged: {
  <Input>(): <Tag extends string>(tag: Tag) => Filter<Input, ExtractTag<Input, Tag>, ExcludeTag<Input, Tag>>;
  <Input, Tag extends string>(tag: Tag): Filter<Input, ExtractTag<Input, Tag>, ExcludeTag<Input, Tag>>;
  <Tag extends string>(tag: Tag): <Input>(input: Input) => Result<ExtractTag<Input, Tag>, ExcludeTag<Input, Tag>>;
}

Converting

toOption

Since v4.0.0

Converts a Filter into a function that returns Some for passed values and None for filtered-out values.

When to use

Use when adapting a Filter to Option-based code where passed values become Some and filtered-out inputs become None.

See

toResult for keeping the filter failure value
toPredicate for plain boolean pass/fail checks

Signature

declare function toOption<A, Pass, Fail>(self: Filter<A, Pass, Fail>): (input: A) => Option<Pass>

toPredicate

Since v4.0.0

Converts a Filter into a predicate function.

When to use

Use to reuse a Filter with APIs that accept only boolean predicates when the pass and fail payloads are not needed.

See

toOption for keeping passed values and discarding failure values
toResult for preserving both pass and failure values

Signature

declare function toPredicate<A, Pass, Fail>(self: Filter<A, Pass, Fail>): Predicate<A>

toResult

Since v4.0.0

Converts a Filter into a function that returns the underlying Result.Result for each input.

When to use

Use to adapt a Filter to APIs that expect a plain function returning Result, while preserving both the pass value and the failure value.

See

toOption for keeping only passed values
toPredicate for plain boolean pass/fail checks

Signature

declare function toResult<A, Pass, Fail>(self: Filter<A, Pass, Fail>): (input: A) => Result<Pass, Fail>

Mapping

mapFail

Since v4.0.0

Transforms the failure value produced by a Filter, leaving successful results unchanged.

Signature

declare const mapFail: {
  <Fail, Fail2>(f: (fail: Fail) => Fail2): <Input, Pass>(self: Filter<Input, Pass, Fail>) => Filter<Input, Pass, Fail2>;
  <Input, Pass, Fail, Fail2>(self: Filter<Input, Pass, Fail>, f: (fail: Fail) => Fail2): Filter<Input, Pass, Fail2>;
}

Models

Filter

interface

Since v4.0.0

Represents a filter function that can transform inputs to outputs or filter them out.

Details

A filter takes an input value and either returns a boxed pass value or the special fail type to indicate the value should be filtered out.

Signature

interface Filter<in Input, out Pass = Input, out Fail = Input> {
  (input: Input): Result<Pass, Fail>;
}

Example Defining a positive number filter

import { Filter, Result } from "effect"

// A filter that only passes positive numbers
const positiveFilter: Filter.Filter<number> = (n) => n > 0 ? Result.succeed(n) : Result.fail(n)

positiveFilter(5) // => Result.succeed(5)
positiveFilter(-3) // => Result.fail(-3)

FilterEffect

interface

Since v4.0.0

Represents an effectful filter function that can produce Effects.

Details

Similar to a regular Filter, but the filtering operation itself can be effectful, allowing for asynchronous operations, error handling, and dependency injection.

Signature

interface FilterEffect<in Input, out Pass, out Fail, out E = never, out R = never> {
  (input: Input): Effect<Result<Pass, Fail>, E, R>;
}

Example Defining an effectful user filter

import { Effect, Filter, Result } from "effect"

// An effectful filter that validates user data
type User = { id: string; isActive: boolean }
type ValidationError = { message: string }

const validateUser: Filter.FilterEffect<
  string,
  User,
  User,
  ValidationError,
  never
> = (id) =>
  Effect.gen(function*() {
    const user: User = { id, isActive: id.length > 0 }
    return user.isActive ? Result.succeed(user) : Result.fail(user)
  })

await Effect.runPromise(validateUser("alice")) // => Result.succeed({ id: "alice", isActive: true })
await Effect.runPromise(validateUser("")) // => Result.fail({ id: "", isActive: false })

Other

try

Signature

declare function try<Input, Output>(f: (input: Input) => Output): Filter<Input, Output>