effect 4.0.0-beta.66 → 4.0.0-beta.68

package/dist/Filter.d.ts

@@ -1,4 +1,38 @@
 /**
+ * The `Filter` module provides composable functions for accepting, rejecting,
+ * narrowing, and transforming values. A `Filter<Input, Pass, Fail>` receives an
+ * input and returns a `Result`: success means the value passed the filter, while
+ * failure means the value was filtered out.
+ *
+ * **Mental model**
+ *
+ * - A filter is a typed predicate that can also transform the successful value
+ * - Predicate-based filters pass the original input when the predicate returns `true`
+ * - Refinement-based filters narrow the successful type, for example from `unknown` to `string`
+ * - Custom filters return `Result.succeed(pass)` or `Result.fail(fail)` directly
+ * - Filters compose with logical and sequential combinators instead of throwing exceptions
+ * - `FilterEffect` is the effectful form for filters that need asynchronous work, errors, or services
+ *
+ * **Common tasks**
+ *
+ * - Build filters: {@link make}, {@link makeEffect}, {@link fromPredicate}, {@link fromPredicateOption}
+ * - Narrow unknown values: {@link string}, {@link number}, {@link boolean}, {@link bigint}, {@link symbol}, {@link date}
+ * - Match shapes and variants: {@link instanceOf}, {@link tagged}, {@link reason}, {@link has}
+ * - Match exact values: {@link equals}, {@link equalsStrict}
+ * - Combine alternatives: {@link or}
+ * - Require multiple filters: {@link zip}, {@link zipWith}, {@link andLeft}, {@link andRight}
+ * - Run filters in sequence: {@link compose}, {@link composePassthrough}
+ * - Convert results: {@link toPredicate}, {@link toOption}, {@link toResult}
+ * - Adjust failure values: {@link mapFail}
+ *
+ * **Gotchas**
+ *
+ * - A failed filter is data in the `Result` failure channel; it is not an exception
+ * - `compose` preserves intermediate failure values, while {@link composePassthrough} fails with the original input
+ * - `equalsStrict` uses JavaScript `===`; use {@link equals} for structural equality
+ * - `fromPredicateOption` fails with the original input when the returned `Option` is `None`
+ * - Prefer refinement predicates when you want TypeScript to narrow the successful value type
+ *
  * @since 4.0.0
  */
 import type { Effect } from "./Effect.ts";
@@ -12,7 +46,8 @@ import type { EqualsWith, ExcludeTag, ExtractReason, ExtractTag, ReasonTags, Tag
  * 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
+ * **Example** (Defining a positive number filter)
+ *
  * ```ts
  * import { Filter, Result } from "effect"
  *
@@ -23,8 +58,8 @@ import type { EqualsWith, ExcludeTag, ExtractReason, ExtractTag, ReasonTags, Tag
  * console.log(positiveFilter(-3)) // Result.fail(-3)
  * ```
  *
+ * @category models
  * @since 4.0.0
- * @category Models
  */
 export interface Filter<in Input, out Pass = Input, out Fail = Input> {
     (input: Input): Result.Result<Pass, Fail>;
@@ -35,7 +70,8 @@ export interface Filter<in Input, out Pass = Input, out Fail = Input> {
  * Similar to a regular Filter, but the filtering operation itself can be effectful,
  * allowing for asynchronous operations, error handling, and dependency injection.
  *
- * @example
+ * **Example** (Defining an effectful user filter)
+ *
  * ```ts
  * import { Effect, Filter, Result } from "effect"
  *
@@ -56,8 +92,8 @@ export interface Filter<in Input, out Pass = Input, out Fail = Input> {
  *   })
  * ```
  *
+ * @category models
  * @since 4.0.0
- * @category Models
  */
 export interface FilterEffect<in Input, out Pass, out Fail, out E = never, out R = never> {
     (input: Input): Effect<Result.Result<Pass, Fail>, E, R>;
@@ -68,7 +104,8 @@ export interface FilterEffect<in Input, out Pass, out Fail, out E = never, out R
  * This is the primary constructor for creating custom filters. The function
  * should return either `Result.succeed(value)` or `Result.fail(value)`.
  *
- * @example
+ * **Example** (Creating custom filters)
+ *
  * ```ts
  * import { Filter, Result } from "effect"
  *
@@ -81,8 +118,8 @@ export interface FilterEffect<in Input, out Pass, out Fail, out E = never, out R
  * )
  * ```
  *
+ * @category constructors
  * @since 4.0.0
- * @category Constructors
  */
 export declare const make: <Input, Pass, Fail>(f: (input: Input) => Result.Result<Pass, Fail>) => Filter<Input, Pass, Fail>;
 /**
@@ -92,7 +129,8 @@ export declare const make: <Input, Pass, Fail>(f: (input: Input) => Result.Resul
  * effectful computations, such as async operations, error handling, or
  * accessing services from the environment.
  *
- * @example
+ * **Example** (Creating effectful filters)
+ *
  * ```ts
  * import { Effect, Filter, Result } from "effect"
  *
@@ -105,23 +143,32 @@ export declare const make: <Input, Pass, Fail>(f: (input: Input) => Result.Resul
  * )
  * ```
  *
+ * @category constructors
  * @since 4.0.0
- * @category Constructors
  */
 export declare const makeEffect: <Input, Pass, Fail, E, R>(f: (input: Input) => Effect<Result.Result<Pass, Fail>, E, R>) => FilterEffect<Input, Pass, Fail, E, R>;
 /**
+ * Transforms the failure value produced by a `Filter`, leaving successful
+ * results unchanged.
+ *
+ * @category mapping
  * @since 4.0.0
- * @category Mapping
  */
 export declare const mapFail: {
     /**
+     * Transforms the failure value produced by a `Filter`, leaving successful
+     * results unchanged.
+     *
+     * @category mapping
      * @since 4.0.0
-     * @category Mapping
      */
     <Fail, Fail2>(f: (fail: Fail) => Fail2): <Input, Pass>(self: Filter<Input, Pass, Fail>) => Filter<Input, Pass, Fail2>;
     /**
+     * Transforms the failure value produced by a `Filter`, leaving successful
+     * results unchanged.
+     *
+     * @category mapping
      * @since 4.0.0
-     * @category Mapping
      */
     <Input, Pass, Fail, Fail2>(self: Filter<Input, Pass, Fail>, f: (fail: Fail) => Fail2): Filter<Input, Pass, Fail2>;
 };
@@ -131,8 +178,8 @@ export {
  * Creates a Filter that tries to apply a function and returns `fail` on
  * error.
  *
+ * @category constructors
  * @since 4.0.0
- * @category Constructors
  */
 try_ as try };
 /**
@@ -142,7 +189,8 @@ try_ as try };
  * When the predicate returns true, the input value is passed through unchanged.
  * When it returns false, the `fail` type is returned.
  *
- * @example
+ * **Example** (Creating filters from predicates)
+ *
  * ```ts
  * import { Filter, Result } from "effect"
  *
@@ -156,8 +204,8 @@ try_ as try };
  * )
  * ```
  *
+ * @category constructors
  * @since 4.0.0
- * @category Constructors
  */
 export declare const fromPredicate: {
     /**
@@ -167,7 +215,8 @@ export declare const fromPredicate: {
      * When the predicate returns true, the input value is passed through unchanged.
      * When it returns false, the `fail` type is returned.
      *
-     * @example
+     * **Example** (Creating filters from predicates)
+     *
      * ```ts
      * import { Filter, Result } from "effect"
      *
@@ -181,8 +230,8 @@ export declare const fromPredicate: {
      * )
      * ```
      *
+     * @category constructors
      * @since 4.0.0
-     * @category Constructors
      */
     <A, B extends A>(refinement: Predicate.Refinement<A, B>): Filter<A, B, EqualsWith<A, B, A, Exclude<A, B>>>;
     /**
@@ -192,7 +241,8 @@ export declare const fromPredicate: {
      * When the predicate returns true, the input value is passed through unchanged.
      * When it returns false, the `fail` type is returned.
      *
-     * @example
+     * **Example** (Creating filters from predicates)
+     *
      * ```ts
      * import { Filter, Result } from "effect"
      *
@@ -206,29 +256,32 @@ export declare const fromPredicate: {
      * )
      * ```
      *
+     * @category constructors
      * @since 4.0.0
-     * @category Constructors
      */
     <A>(predicate: Predicate.Predicate<A>): Filter<A>;
 };
 /**
- * Creates a Filter from a function that returns an Option.
+ * Creates a `Filter` from a function that returns an `Option`.
+ *
+ * `Some(value)` passes with `value`. `None` fails with the original input.
  *
+ * @category constructors
  * @since 4.0.0
- * @category Constructors
  */
 export declare const fromPredicateOption: <A, B>(predicate: (a: A) => Option.Option<B>) => Filter<A, B>;
 /**
  * Converts a Filter into a predicate function.
  *
+ * @category constructors
  * @since 4.0.0
- * @category Constructors
  */
 export declare const toPredicate: <A, Pass, Fail>(self: Filter<A, Pass, Fail>) => Predicate.Predicate<A>;
 /**
  * A predefined filter that only passes through string values.
  *
- * @example
+ * **Example** (Filtering strings)
+ *
  * ```ts
  * import { Filter, Result } from "effect"
  *
@@ -236,18 +289,24 @@ export declare const toPredicate: <A, Pass, Fail>(self: Filter<A, Pass, Fail>) =
  * console.log(Filter.string(42)) // fail
  * ```
  *
+ * @category constructors
  * @since 4.0.0
- * @category Constructors
  */
 export declare const string: Filter<unknown, string>;
 /**
+ * Creates a `Filter` that passes only values strictly equal to the specified
+ * value using JavaScript `===` comparison.
+ *
+ * @category constructors
  * @since 4.0.0
- * @category Constructors
  */
 export declare const equalsStrict: <const A, Input = unknown>(value: A) => Filter<Input, A, EqualsWith<Input, A, A, Exclude<Input, A>>>;
 /**
+ * Creates a `Filter` that passes inputs whose `has(key)` method returns
+ * `true` for the specified key.
+ *
+ * @category constructors
  * @since 4.0.0
- * @category Constructors
  */
 export declare const has: <K>(key: K) => <Input extends {
     readonly has: (key: K) => boolean;
@@ -255,14 +314,15 @@ export declare const has: <K>(key: K) => <Input extends {
 /**
  * Creates a filter that only passes instances of the given constructor.
  *
+ * @category constructors
  * @since 4.0.0
- * @category Constructors
  */
 export declare const instanceOf: <K extends new (...args: any) => any>(constructor: K) => <Input>(u: Input) => Result.Result<InstanceType<K>, Exclude<Input, InstanceType<K>>>;
 /**
  * A predefined filter that only passes through number values.
  *
- * @example
+ * **Example** (Filtering numbers)
+ *
  * ```ts
  * import { Filter, Result } from "effect"
  *
@@ -270,122 +330,122 @@ export declare const instanceOf: <K extends new (...args: any) => any>(construct
  * console.log(Filter.number("42")) // fail
  * ```
  *
+ * @category constructors
  * @since 4.0.0
- * @category Constructors
  */
 export declare const number: Filter<unknown, number>;
 /**
  * A predefined filter that only passes through boolean values.
  *
+ * @category constructors
  * @since 4.0.0
- * @category Constructors
  */
 export declare const boolean: Filter<unknown, boolean>;
 /**
  * A predefined filter that only passes through BigInt values.
  *
+ * @category constructors
  * @since 4.0.0
- * @category Constructors
  */
 export declare const bigint: Filter<unknown, bigint>;
 /**
  * A predefined filter that only passes through Symbol values.
  *
+ * @category constructors
  * @since 4.0.0
- * @category Constructors
  */
 export declare const symbol: Filter<unknown, symbol>;
 /**
  * A predefined filter that only passes through Date objects.
  *
+ * @category constructors
  * @since 4.0.0
- * @category Constructors
  */
 export declare const date: Filter<unknown, Date>;
 /**
  * Creates a filter that checks if an input is tagged with a specific tag.
  *
+ * @category constructors
  * @since 4.0.0
- * @category Constructors
  */
 export declare const tagged: {
     /**
      * Creates a filter that checks if an input is tagged with a specific tag.
      *
+     * @category constructors
      * @since 4.0.0
-     * @category Constructors
      */
     <Input>(): <const Tag extends Tags<Input>>(tag: Tag) => Filter<Input, ExtractTag<Input, Tag>, ExcludeTag<Input, Tag>>;
     /**
      * Creates a filter that checks if an input is tagged with a specific tag.
      *
+     * @category constructors
      * @since 4.0.0
-     * @category Constructors
      */
     <Input, const Tag extends Tags<Input>>(tag: Tag): Filter<Input, ExtractTag<Input, Tag>, ExcludeTag<Input, Tag>>;
     /**
      * Creates a filter that checks if an input is tagged with a specific tag.
      *
+     * @category constructors
      * @since 4.0.0
-     * @category Constructors
      */
     <const Tag extends string>(tag: Tag): <Input>(input: Input) => Result.Result<ExtractTag<Input, Tag>, ExcludeTag<Input, Tag>>;
 };
 /**
  * Creates a filter that extracts a reason from a tagged error.
  *
+ * @category constructors
  * @since 4.0.0
- * @category Constructors
  */
 export declare const reason: {
     /**
      * Creates a filter that extracts a reason from a tagged error.
      *
+     * @category constructors
      * @since 4.0.0
-     * @category Constructors
      */
     <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>;
     /**
      * Creates a filter that extracts a reason from a tagged error.
      *
+     * @category constructors
      * @since 4.0.0
-     * @category Constructors
      */
     <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>;
     /**
      * Creates a filter that extracts a reason from a tagged error.
      *
+     * @category constructors
      * @since 4.0.0
-     * @category Constructors
      */
     <const Tag extends string, const ReasonTag extends string>(tag: Tag, reasonTag: ReasonTag): <Input>(input: Input) => Result.Result<ExtractReason<ExtractTag<Input, Tag>, ReasonTag>, Input>;
 };
 /**
  * Creates a filter that only passes values equal to the specified value using structural equality.
  *
+ * @category constructors
  * @since 4.0.0
- * @category Constructors
  */
 export declare const equals: <const A, Input = unknown>(value: A) => Filter<Input, A, EqualsWith<Input, A, A, Exclude<Input, A>>>;
 /**
  * Combines two filters with logical OR semantics.
  *
+ * @category combinators
  * @since 4.0.0
- * @category Combinators
  */
 export declare const or: {
     /**
      * Combines two filters with logical OR semantics.
      *
+     * @category combinators
      * @since 4.0.0
-     * @category Combinators
      */
     <Input2, Pass2, Fail2>(that: Filter<Input2, Pass2, Fail2>): <Input1, Pass2, Fail2>(self: Filter<Input1, Pass2>) => Filter<Input1 & Input2, Pass2 | Pass2, Fail2>;
     /**
      * Combines two filters with logical OR semantics.
      *
+     * @category combinators
      * @since 4.0.0
-     * @category Combinators
      */
     <Input1, Pass1, Fail1, Input2, Pass2, Fail2>(self: Filter<Input1, Pass1, Fail1>, that: Filter<Input2, Pass2, Fail2>): Filter<Input1 & Input2, Pass1 | Pass2, Fail2>;
 };
@@ -395,8 +455,8 @@ export declare const or: {
  * Both filters must succeed (not return `fail`) for the combination to succeed.
  * If both filters pass, their outputs are combined using the provided function.
  *
+ * @category combinators
  * @since 4.0.0
- * @category Combinators
  */
 export declare const zipWith: {
     /**
@@ -405,8 +465,8 @@ export declare const zipWith: {
      * Both filters must succeed (not return `fail`) for the combination to succeed.
      * If both filters pass, their outputs are combined using the provided function.
      *
+     * @category combinators
      * @since 4.0.0
-     * @category Combinators
      */
     <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>;
     /**
@@ -415,8 +475,8 @@ export declare const zipWith: {
      * Both filters must succeed (not return `fail`) for the combination to succeed.
      * If both filters pass, their outputs are combined using the provided function.
      *
+     * @category combinators
      * @since 4.0.0
-     * @category Combinators
      */
     <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>;
 };
@@ -426,7 +486,8 @@ export declare const zipWith: {
  * Both filters must succeed for the combination to succeed. If both pass,
  * their outputs are combined into a tuple.
  *
- * @example
+ * **Example** (Zipping filters)
+ *
  * ```ts
  * import { Filter } from "effect"
  *
@@ -436,8 +497,8 @@ export declare const zipWith: {
  * const positiveAndEven = Filter.zip(positiveNumbers, evenNumbers)
  * ```
  *
+ * @category combinators
  * @since 4.0.0
- * @category Combinators
  */
 export declare const zip: {
     /**
@@ -446,7 +507,8 @@ export declare const zip: {
      * Both filters must succeed for the combination to succeed. If both pass,
      * their outputs are combined into a tuple.
      *
-     * @example
+     * **Example** (Zipping filters)
+     *
      * ```ts
      * import { Filter } from "effect"
      *
@@ -456,8 +518,8 @@ export declare const zip: {
      * const positiveAndEven = Filter.zip(positiveNumbers, evenNumbers)
      * ```
      *
+     * @category combinators
      * @since 4.0.0
-     * @category Combinators
      */
     <InputR, PassR, FailR>(right: Filter<InputR, PassR, FailR>): <InputL, PassL, FailL>(left: Filter<InputL, PassL, FailL>) => Filter<InputL & InputR, [PassL, PassR], FailL | FailR>;
     /**
@@ -466,7 +528,8 @@ export declare const zip: {
      * Both filters must succeed for the combination to succeed. If both pass,
      * their outputs are combined into a tuple.
      *
-     * @example
+     * **Example** (Zipping filters)
+     *
      * ```ts
      * import { Filter } from "effect"
      *
@@ -476,15 +539,16 @@ export declare const zip: {
      * const positiveAndEven = Filter.zip(positiveNumbers, evenNumbers)
      * ```
      *
+     * @category combinators
      * @since 4.0.0
-     * @category Combinators
      */
     <InputL, PassL, FailL, InputR, PassR, FailR>(left: Filter<InputL, PassL, FailL>, right: Filter<InputR, PassR, FailR>): Filter<InputL & InputR, [PassL, PassR], FailL | FailR>;
 };
 /**
  * Combines two filters but only returns the result of the left filter.
  *
- * @example
+ * **Example** (Keeping the left filter result)
+ *
  * ```ts
  * import { Filter } from "effect"
  *
@@ -494,14 +558,15 @@ export declare const zip: {
  * const positiveEven = Filter.andLeft(positiveNumbers, evenNumbers)
  * ```
  *
+ * @category combinators
  * @since 4.0.0
- * @category Combinators
  */
 export declare const andLeft: {
     /**
      * Combines two filters but only returns the result of the left filter.
      *
-     * @example
+     * **Example** (Keeping the left filter result)
+     *
      * ```ts
      * import { Filter } from "effect"
      *
@@ -511,14 +576,15 @@ export declare const andLeft: {
      * const positiveEven = Filter.andLeft(positiveNumbers, evenNumbers)
      * ```
      *
+     * @category combinators
      * @since 4.0.0
-     * @category Combinators
      */
     <InputR, PassR, FailR>(right: Filter<InputR, PassR, FailR>): <InputL, PassL, FailL>(left: Filter<InputL, PassL, FailL>) => Filter<InputL & InputR, PassL, FailL | FailR>;
     /**
      * Combines two filters but only returns the result of the left filter.
      *
-     * @example
+     * **Example** (Keeping the left filter result)
+     *
      * ```ts
      * import { Filter } from "effect"
      *
@@ -528,15 +594,16 @@ export declare const andLeft: {
      * const positiveEven = Filter.andLeft(positiveNumbers, evenNumbers)
      * ```
      *
+     * @category combinators
      * @since 4.0.0
-     * @category Combinators
      */
     <InputL, PassL, FailL, InputR, PassR, FailR>(left: Filter<InputL, PassL, FailL>, right: Filter<InputR, PassR, FailR>): Filter<InputL & InputR, PassL, FailL | FailR>;
 };
 /**
  * Combines two filters but only returns the result of the right filter.
  *
- * @example
+ * **Example** (Keeping the right filter result)
+ *
  * ```ts
  * import { Filter, Result } from "effect"
  *
@@ -548,14 +615,15 @@ export declare const andLeft: {
  * const positiveDoubled = Filter.andRight(positiveNumbers, doubleNumbers)
  * ```
  *
+ * @category combinators
  * @since 4.0.0
- * @category Combinators
  */
 export declare const andRight: {
     /**
      * Combines two filters but only returns the result of the right filter.
      *
-     * @example
+     * **Example** (Keeping the right filter result)
+     *
      * ```ts
      * import { Filter, Result } from "effect"
      *
@@ -567,14 +635,15 @@ export declare const andRight: {
      * const positiveDoubled = Filter.andRight(positiveNumbers, doubleNumbers)
      * ```
      *
+     * @category combinators
      * @since 4.0.0
-     * @category Combinators
      */
     <InputR, PassR, FailR>(right: Filter<InputR, PassR, FailR>): <InputL, PassL, FailL>(left: Filter<InputL, PassL, FailL>) => Filter<InputL & InputR, PassR, FailL | FailR>;
     /**
      * Combines two filters but only returns the result of the right filter.
      *
-     * @example
+     * **Example** (Keeping the right filter result)
+     *
      * ```ts
      * import { Filter, Result } from "effect"
      *
@@ -586,15 +655,16 @@ export declare const andRight: {
      * const positiveDoubled = Filter.andRight(positiveNumbers, doubleNumbers)
      * ```
      *
+     * @category combinators
      * @since 4.0.0
-     * @category Combinators
      */
     <InputL, PassL, FailL, InputR, PassR, FailR>(left: Filter<InputL, PassL, FailL>, right: Filter<InputR, PassR, FailR>): Filter<InputL & InputR, PassR, FailL | FailR>;
 };
 /**
  * Composes two filters sequentially, feeding the output of the first into the second.
  *
- * @example
+ * **Example** (Composing filters)
+ *
  * ```ts
  * import { Filter, Result } from "effect"
  *
@@ -606,14 +676,15 @@ export declare const andRight: {
  * const stringToUpper = Filter.compose(stringFilter, nonEmptyUpper)
  * ```
  *
+ * @category combinators
  * @since 4.0.0
- * @category Combinators
  */
 export declare const compose: {
     /**
      * Composes two filters sequentially, feeding the output of the first into the second.
      *
-     * @example
+     * **Example** (Composing filters)
+     *
      * ```ts
      * import { Filter, Result } from "effect"
      *
@@ -625,14 +696,15 @@ export declare const compose: {
      * const stringToUpper = Filter.compose(stringFilter, nonEmptyUpper)
      * ```
      *
+     * @category combinators
      * @since 4.0.0
-     * @category Combinators
      */
     <PassL, PassR, FailR>(right: Filter<PassL, PassR, FailR>): <InputL, FailL>(left: Filter<InputL, PassL, FailL>) => Filter<InputL, PassR, FailL | FailR>;
     /**
      * Composes two filters sequentially, feeding the output of the first into the second.
      *
-     * @example
+     * **Example** (Composing filters)
+     *
      * ```ts
      * import { Filter, Result } from "effect"
      *
@@ -644,53 +716,59 @@ export declare const compose: {
      * const stringToUpper = Filter.compose(stringFilter, nonEmptyUpper)
      * ```
      *
+     * @category combinators
      * @since 4.0.0
-     * @category Combinators
      */
     <InputL, PassL, FailL, PassR, FailR>(left: Filter<InputL, PassL, FailL>, right: Filter<PassL, PassR, FailR>): Filter<InputL, PassR, FailL | FailR>;
 };
 /**
- * Composes two filters sequentially, allowing the output of the first to be
- * passed to the second.
+ * Composes two filters sequentially, passing the successful output of the
+ * first filter to the second.
  *
- * This is similar to `compose`, but it will always fail with the original
- * input.
+ * If either filter fails, the returned filter fails with the original input
+ * instead of the intermediate failure value.
  *
+ * @category combinators
  * @since 4.0.0
- * @category Combinators
  */
 export declare const composePassthrough: {
     /**
-     * Composes two filters sequentially, allowing the output of the first to be
-     * passed to the second.
+     * Composes two filters sequentially, passing the successful output of the
+     * first filter to the second.
      *
-     * This is similar to `compose`, but it will always fail with the original
-     * input.
+     * If either filter fails, the returned filter fails with the original input
+     * instead of the intermediate failure value.
      *
+     * @category combinators
      * @since 4.0.0
-     * @category Combinators
      */
     <InputL, PassL, PassR, FailR>(right: Filter<PassL, PassR, FailR>): <FailL>(left: Filter<InputL, PassL, FailL>) => Filter<InputL, PassR, InputL>;
     /**
-     * Composes two filters sequentially, allowing the output of the first to be
-     * passed to the second.
+     * Composes two filters sequentially, passing the successful output of the
+     * first filter to the second.
      *
-     * This is similar to `compose`, but it will always fail with the original
-     * input.
+     * If either filter fails, the returned filter fails with the original input
+     * instead of the intermediate failure value.
      *
+     * @category combinators
      * @since 4.0.0
-     * @category Combinators
      */
     <InputL, PassL, FailL, PassR, FailR>(left: Filter<InputL, PassL, FailL>, right: Filter<PassL, PassR, FailR>): Filter<InputL, PassR, InputL>;
 };
 /**
+ * Converts a `Filter` into a function that returns `Some` for passed values
+ * and `None` for filtered-out values.
+ *
+ * @category converting
  * @since 4.0.0
- * @category Conversions
  */
 export declare const toOption: <A, Pass, Fail>(self: Filter<A, Pass, Fail>) => (input: A) => Option.Option<Pass>;
 /**
+ * Converts a `Filter` into a function that returns the underlying
+ * `Result.Result` for each input.
+ *
+ * @category converting
  * @since 4.0.0
- * @category Conversions
  */
 export declare const toResult: <A, Pass, Fail>(self: Filter<A, Pass, Fail>) => (input: A) => Result.Result<Pass, Fail>;
 //# sourceMappingURL=Filter.d.ts.map