Skip to content

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 Added in v4.0.0 Source

Combinators

andLeft

Added in v4.0.0 Source

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

andRight

Added in v4.0.0 Source

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

compose

Added in v4.0.0 Source

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

composePassthrough

Added in v4.0.0 Source

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

Added in v4.0.0 Source

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

Added in v4.0.0 Source

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

zipWith

Added in v4.0.0 Source

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

Added in v4.0.0 Source

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

Added in v4.0.0 Source

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

Signature

declare const boolean: Filter<unknown, boolean>;

date

Added in v4.0.0 Source

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

Signature

declare const date: Filter<unknown, Date>;

equals

Added in v4.0.0 Source

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

Added in v4.0.0 Source

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

Added in v4.0.0 Source

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

fromPredicateOption

Added in v4.0.0 Source

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

Added in v4.0.0 Source

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

Added in v4.0.0 Source

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

Signature

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

make

Added in v4.0.0 Source

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

makeEffect

Added in v4.0.0 Source

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

number

Added in v4.0.0 Source

A predefined filter that only passes through number values.

Signature

declare const number: Filter<unknown, number>;

reason

Added in v4.0.0 Source

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

Added in v4.0.0 Source

A predefined filter that only passes through string values.

Signature

declare const string: Filter<unknown, string>;

symbol

Added in v4.0.0 Source

A predefined filter that only passes through Symbol values.

Signature

declare const symbol: Filter<unknown, symbol>;

tagged

Added in v4.0.0 Source

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

Added in v4.0.0 Source

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

Signature

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

toPredicate

Added in v4.0.0 Source

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

Added in v4.0.0 Source

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

Signature

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

Mapping

mapFail

Added in v4.0.0 Source

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

Added in v4.0.0 Source

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

FilterEffect interface

Added in v4.0.0 Source

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

Other

try

Source

Signature

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