Filter.ts

Filter.ts overview

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.

Since v4.0.0

---

Exports Grouped by Category

• combinators
  • andLeft
  • andRight
  • compose
  • composePassthrough
  • or
  • zip
  • zipWith
• constructors
  • bigint
  • boolean
  • date
  • equals
  • equalsStrict
  • fromPredicate
  • fromPredicateOption
  • has
  • instanceOf
  • make
  • makeEffect
  • number
  • reason
  • string
  • symbol
  • tagged
  • try
• converting
  • toOption
  • toPredicate
  • toResult
• mapping
  • mapFail
• models
  • Filter (interface)
  • FilterEffect (interface)

---

combinators

andLeft

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

Example (Keeping the left filter result)

import { Filter } 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)

Signature

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

Source

Since v4.0.0

andRight

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

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)

Signature

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

Source

Since v4.0.0

compose

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

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)

Signature

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

Source

Since v4.0.0

composePassthrough

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

Source

Since v4.0.0

or

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 | Pass2, Fail2>
  <Input1, Pass1, Fail1, Input2, Pass2, Fail2>(
    self: Filter<Input1, Pass1, Fail1>,
    that: Filter<Input2, Pass2, Fail2>
  ): Filter<Input1 & Input2, Pass1 | Pass2, Fail2>
}

Source

Since v4.0.0

zip

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.

Example (Zipping filters)

import { Filter } 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)

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], FailL | FailR>
  <InputL, PassL, FailL, InputR, PassR, FailR>(
    left: Filter<InputL, PassL, FailL>,
    right: Filter<InputR, PassR, FailR>
  ): Filter<InputL & InputR, [PassL, PassR], FailL | FailR>
}

Source

Since v4.0.0

zipWith

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, FailL | FailR>
  <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>
}

Source

Since v4.0.0

constructors

bigint

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, unknown>

Source

Since v4.0.0

boolean

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, unknown>

Source

Since v4.0.0

date

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, unknown>

Source

Since v4.0.0

equals

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 const equals: <const A, Input = unknown>(
  value: A
) => Filter<Input, A, EqualsWith<Input, A, A, Exclude<Input, A>>>

Source

Since v4.0.0

equalsStrict

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 const equalsStrict: <const A, Input = unknown>(
  value: A
) => Filter<Input, A, EqualsWith<Input, A, A, Exclude<Input, A>>>

Source

Since v4.0.0

fromPredicate

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.

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")

Signature

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

Source

Since v4.0.0

fromPredicateOption

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

Signature

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

Source

Since v4.0.0

has

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 const has: <K>(
  key: K
) => <Input extends { readonly has: (key: K) => boolean }>(input: Input) => Result.Result<Input, Input>

Source

Since v4.0.0

instanceOf

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 const instanceOf: <K extends new (...args: any) => any>(
  constructor: K
) => <Input>(u: Input) => Result.Result<InstanceType<K>, Exclude<Input, InstanceType<K>>>

Source

Since v4.0.0

make

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

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

Signature

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

Source

Since v4.0.0

makeEffect

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.

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

Signature

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

Source

Since v4.0.0

number

A predefined filter that only passes through number values.

Example (Filtering numbers)

import { Filter, Result } from "effect"

console.log(Filter.number(42)) // Result.succeed(42)
console.log(Filter.number("42")) // fail

Signature

declare const number: Filter<unknown, number, unknown>

Source

Since v4.0.0

reason

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

Signature

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

Source

Since v4.0.0

string

A predefined filter that only passes through string values.

Example (Filtering strings)

import { Filter, Result } from "effect"

console.log(Filter.string("hello")) // Result.succeed("hello")
console.log(Filter.string(42)) // fail

Signature

declare const string: Filter<unknown, string, unknown>

Source

Since v4.0.0

symbol

A predefined filter that only passes through Symbol values.

Signature

declare const symbol: Filter<unknown, symbol, unknown>

Source

Since v4.0.0

tagged

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>(): <const Tag extends Tags<Input>>(tag: Tag) => Filter<Input, ExtractTag<Input, Tag>, ExcludeTag<Input, Tag>>
  <Input, const Tag extends Tags<Input>>(tag: Tag): Filter<Input, ExtractTag<Input, Tag>, ExcludeTag<Input, Tag>>
  <const Tag extends string>(
    tag: Tag
  ): <Input>(input: Input) => Result.Result<ExtractTag<Input, Tag>, ExcludeTag<Input, Tag>>
}

Source

Since v4.0.0

try

Creates a Filter that tries to apply a function and returns fail on error.

Signature

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

Source

Since v4.0.0

converting

toOption

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 const toOption: <A, Pass, Fail>(self: Filter<A, Pass, Fail>) => (input: A) => Option.Option<Pass>

Source

Since v4.0.0

toPredicate

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 const toPredicate: <A, Pass, Fail>(self: Filter<A, Pass, Fail>) => Predicate.Predicate<A>

Source

Since v4.0.0

toResult

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 const toResult: <A, Pass, Fail>(self: Filter<A, Pass, Fail>) => (input: A) => Result.Result<Pass, Fail>

Source

Since v4.0.0

mapping

mapFail

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

Source

Since v4.0.0

models

Filter (interface)

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.

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

console.log(positiveFilter(5)) // Result.succeed(5)
console.log(positiveFilter(-3)) // Result.fail(-3)

Signature

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

Source

Since v4.0.0

FilterEffect (interface)

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.

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

Signature

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

Source

Since v4.0.0