effect 4.0.0-beta.67 → 4.0.0-beta.69

package/src/Filter.ts

@@ -61,7 +61,7 @@ import type { EqualsWith, ExcludeTag, ExtractReason, ExtractTag, ReasonTags, Tag
  * console.log(positiveFilter(-3)) // Result.fail(-3)
  * ```
  *
- * @category Models
+ * @category models
  * @since 4.0.0
  */
 export interface Filter<in Input, out Pass = Input, out Fail = Input> {
@@ -96,7 +96,7 @@ export interface Filter<in Input, out Pass = Input, out Fail = Input> {
  *   })
  * ```
  *
- * @category Models
+ * @category models
  * @since 4.0.0
  */
 export interface FilterEffect<
@@ -133,7 +133,7 @@ export interface FilterEffect<
  * )
  * ```
  *
- * @category Constructors
+ * @category constructors
  * @since 4.0.0
  */
 export const make = <Input, Pass, Fail>(
@@ -161,7 +161,7 @@ export const make = <Input, Pass, Fail>(
  * )
  * ```
  *
- * @category Constructors
+ * @category constructors
  * @since 4.0.0
  */
 export const makeEffect = <Input, Pass, Fail, E, R>(
@@ -172,7 +172,7 @@ export const makeEffect = <Input, Pass, Fail, E, R>(
  * Transforms the failure value produced by a `Filter`, leaving successful
  * results unchanged.
  *
- * @category Mapping
+ * @category mapping
  * @since 4.0.0
  */
 export const mapFail: {
@@ -180,7 +180,7 @@ export const mapFail: {
    * Transforms the failure value produced by a `Filter`, leaving successful
    * results unchanged.
    *
-   * @category Mapping
+   * @category mapping
    * @since 4.0.0
    */
   <Fail, Fail2>(f: (fail: Fail) => Fail2): <Input, Pass>(self: Filter<Input, Pass, Fail>) => Filter<Input, Pass, Fail2>
@@ -188,7 +188,7 @@ export const mapFail: {
    * Transforms the failure value produced by a `Filter`, leaving successful
    * results unchanged.
    *
-   * @category Mapping
+   * @category mapping
    * @since 4.0.0
    */
   <Input, Pass, Fail, Fail2>(self: Filter<Input, Pass, Fail>, f: (fail: Fail) => Fail2): Filter<Input, Pass, Fail2>
@@ -211,7 +211,7 @@ export {
    * Creates a Filter that tries to apply a function and returns `fail` on
    * error.
    *
-   * @category Constructors
+   * @category constructors
    * @since 4.0.0
    */
   try_ as try
@@ -239,7 +239,7 @@ export {
  * )
  * ```
  *
- * @category Constructors
+ * @category constructors
  * @since 4.0.0
  */
 export const fromPredicate: {
@@ -265,7 +265,7 @@ export const fromPredicate: {
    * )
    * ```
    *
-   * @category Constructors
+   * @category constructors
    * @since 4.0.0
    */
   <A, B extends A>(refinement: Predicate.Refinement<A, B>): Filter<A, B, EqualsWith<A, B, A, Exclude<A, B>>>
@@ -291,7 +291,7 @@ export const fromPredicate: {
    * )
    * ```
    *
-   * @category Constructors
+   * @category constructors
    * @since 4.0.0
    */
   <A>(predicate: Predicate.Predicate<A>): Filter<A>
@@ -303,7 +303,7 @@ export const fromPredicate: {
  *
  * `Some(value)` passes with `value`. `None` fails with the original input.
  *
- * @category Constructors
+ * @category constructors
  * @since 4.0.0
  */
 export const fromPredicateOption = <A, B>(predicate: (a: A) => Option.Option<B>): Filter<A, B> => (input) => {
@@ -314,7 +314,7 @@ export const fromPredicateOption = <A, B>(predicate: (a: A) => Option.Option<B>)
 /**
  * Converts a Filter into a predicate function.
  *
- * @category Constructors
+ * @category constructors
  * @since 4.0.0
  */
 export const toPredicate = <A, Pass, Fail>(
@@ -334,7 +334,7 @@ export const toPredicate = <A, Pass, Fail>(
  * console.log(Filter.string(42)) // fail
  * ```
  *
- * @category Constructors
+ * @category constructors
  * @since 4.0.0
  */
 export const string: Filter<unknown, string> = fromPredicate(Predicate.isString)
@@ -343,7 +343,7 @@ export const string: Filter<unknown, string> = fromPredicate(Predicate.isString)
  * Creates a `Filter` that passes only values strictly equal to the specified
  * value using JavaScript `===` comparison.
  *
- * @category Constructors
+ * @category constructors
  * @since 4.0.0
  */
 export const equalsStrict =
@@ -354,7 +354,7 @@ export const equalsStrict =
  * Creates a `Filter` that passes inputs whose `has(key)` method returns
  * `true` for the specified key.
  *
- * @category Constructors
+ * @category constructors
  * @since 4.0.0
  */
 export const has =
@@ -364,7 +364,7 @@ export const has =
 /**
  * Creates a filter that only passes instances of the given constructor.
  *
- * @category Constructors
+ * @category constructors
  * @since 4.0.0
  */
 export const instanceOf =
@@ -384,7 +384,7 @@ export const instanceOf =
  * console.log(Filter.number("42")) // fail
  * ```
  *
- * @category Constructors
+ * @category constructors
  * @since 4.0.0
  */
 export const number: Filter<unknown, number> = fromPredicate(Predicate.isNumber)
@@ -392,7 +392,7 @@ export const number: Filter<unknown, number> = fromPredicate(Predicate.isNumber)
 /**
  * A predefined filter that only passes through boolean values.
  *
- * @category Constructors
+ * @category constructors
  * @since 4.0.0
  */
 export const boolean: Filter<unknown, boolean> = fromPredicate(Predicate.isBoolean)
@@ -400,7 +400,7 @@ export const boolean: Filter<unknown, boolean> = fromPredicate(Predicate.isBoole
 /**
  * A predefined filter that only passes through BigInt values.
  *
- * @category Constructors
+ * @category constructors
  * @since 4.0.0
  */
 export const bigint: Filter<unknown, bigint> = fromPredicate(Predicate.isBigInt)
@@ -408,7 +408,7 @@ export const bigint: Filter<unknown, bigint> = fromPredicate(Predicate.isBigInt)
 /**
  * A predefined filter that only passes through Symbol values.
  *
- * @category Constructors
+ * @category constructors
  * @since 4.0.0
  */
 export const symbol: Filter<unknown, symbol> = fromPredicate(Predicate.isSymbol)
@@ -416,7 +416,7 @@ export const symbol: Filter<unknown, symbol> = fromPredicate(Predicate.isSymbol)
 /**
  * A predefined filter that only passes through Date objects.
  *
- * @category Constructors
+ * @category constructors
  * @since 4.0.0
  */
 export const date: Filter<unknown, Date> = fromPredicate(Predicate.isDate)
@@ -424,28 +424,28 @@ export const date: Filter<unknown, Date> = fromPredicate(Predicate.isDate)
 /**
  * Creates a filter that checks if an input is tagged with a specific tag.
  *
- * @category Constructors
+ * @category constructors
  * @since 4.0.0
  */
 export const tagged: {
   /**
    * Creates a filter that checks if an input is tagged with a specific tag.
    *
-   * @category Constructors
+   * @category constructors
    * @since 4.0.0
    */
   <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
+   * @category constructors
    * @since 4.0.0
    */
   <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
+   * @category constructors
    * @since 4.0.0
    */
   <const Tag extends string>(tag: Tag): <Input>(input: Input) => Result.Result<ExtractTag<Input, Tag>, ExcludeTag<Input, Tag>>
@@ -461,14 +461,14 @@ const taggedImpl =
 /**
  * Creates a filter that extracts a reason from a tagged error.
  *
- * @category Constructors
+ * @category constructors
  * @since 4.0.0
  */
 export const reason: {
   /**
    * Creates a filter that extracts a reason from a tagged error.
    *
-   * @category Constructors
+   * @category constructors
    * @since 4.0.0
    */
   <Input>(): <const Tag extends Tags<Input>, const ReasonTag extends ReasonTags<ExtractTag<Input, Tag>>>(
@@ -478,14 +478,14 @@ export const reason: {
   /**
    * Creates a filter that extracts a reason from a tagged error.
    *
-   * @category Constructors
+   * @category constructors
    * @since 4.0.0
    */
   <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
+   * @category constructors
    * @since 4.0.0
    */
   <const Tag extends string, const ReasonTag extends string>(tag: Tag, reasonTag: ReasonTag): <Input>(input: Input) => Result.Result<ExtractReason<ExtractTag<Input, Tag>, ReasonTag>, Input>
@@ -508,7 +508,7 @@ const reasonImpl =
 /**
  * Creates a filter that only passes values equal to the specified value using structural equality.
  *
- * @category Constructors
+ * @category constructors
  * @since 4.0.0
  */
 export const equals =
@@ -518,21 +518,21 @@ export const equals =
 /**
  * Combines two filters with logical OR semantics.
  *
- * @category Combinators
+ * @category combinators
  * @since 4.0.0
  */
 export const or: {
   /**
    * Combines two filters with logical OR semantics.
    *
-   * @category Combinators
+   * @category combinators
    * @since 4.0.0
    */
   <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
+   * @category combinators
    * @since 4.0.0
    */
   <Input1, Pass1, Fail1, Input2, Pass2, Fail2>(self: Filter<Input1, Pass1, Fail1>, that: Filter<Input2, Pass2, Fail2>): Filter<Input1 & Input2, Pass1 | Pass2, Fail2>
@@ -551,7 +551,7 @@ export 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
+ * @category combinators
  * @since 4.0.0
  */
 export const zipWith: {
@@ -561,7 +561,7 @@ export 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
+   * @category combinators
    * @since 4.0.0
    */
   <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>
@@ -571,7 +571,7 @@ export 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
+   * @category combinators
    * @since 4.0.0
    */
   <InputL, PassL, FailL, InputR, PassR, FailR, A>(
@@ -609,7 +609,7 @@ export const zipWith: {
  * const positiveAndEven = Filter.zip(positiveNumbers, evenNumbers)
  * ```
  *
- * @category Combinators
+ * @category combinators
  * @since 4.0.0
  */
 export const zip: {
@@ -630,7 +630,7 @@ export const zip: {
    * const positiveAndEven = Filter.zip(positiveNumbers, evenNumbers)
    * ```
    *
-   * @category Combinators
+   * @category combinators
    * @since 4.0.0
    */
   <InputR, PassR, FailR>(right: Filter<InputR, PassR, FailR>): <InputL, PassL, FailL>(
@@ -653,7 +653,7 @@ export const zip: {
    * const positiveAndEven = Filter.zip(positiveNumbers, evenNumbers)
    * ```
    *
-   * @category Combinators
+   * @category combinators
    * @since 4.0.0
    */
   <InputL, PassL, FailL, InputR, PassR, FailR>(left: Filter<InputL, PassL, FailL>, right: Filter<InputR, PassR, FailR>): Filter<InputL & InputR, [PassL, PassR], FailL | FailR>
@@ -677,7 +677,7 @@ export const zip: {
  * const positiveEven = Filter.andLeft(positiveNumbers, evenNumbers)
  * ```
  *
- * @category Combinators
+ * @category combinators
  * @since 4.0.0
  */
 export const andLeft: {
@@ -695,7 +695,7 @@ export const andLeft: {
    * const positiveEven = Filter.andLeft(positiveNumbers, evenNumbers)
    * ```
    *
-   * @category Combinators
+   * @category combinators
    * @since 4.0.0
    */
   <InputR, PassR, FailR>(right: Filter<InputR, PassR, FailR>): <InputL, PassL, FailL>(
@@ -715,7 +715,7 @@ export const andLeft: {
    * const positiveEven = Filter.andLeft(positiveNumbers, evenNumbers)
    * ```
    *
-   * @category Combinators
+   * @category combinators
    * @since 4.0.0
    */
   <InputL, PassL, FailL, InputR, PassR, FailR>(left: Filter<InputL, PassL, FailL>, right: Filter<InputR, PassR, FailR>): Filter<InputL & InputR, PassL, FailL | FailR>
@@ -740,7 +740,7 @@ export const andLeft: {
  * const positiveDoubled = Filter.andRight(positiveNumbers, doubleNumbers)
  * ```
  *
- * @category Combinators
+ * @category combinators
  * @since 4.0.0
  */
 export const andRight: {
@@ -760,7 +760,7 @@ export const andRight: {
    * const positiveDoubled = Filter.andRight(positiveNumbers, doubleNumbers)
    * ```
    *
-   * @category Combinators
+   * @category combinators
    * @since 4.0.0
    */
   <InputR, PassR, FailR>(right: Filter<InputR, PassR, FailR>): <InputL, PassL, FailL>(
@@ -782,7 +782,7 @@ export const andRight: {
    * const positiveDoubled = Filter.andRight(positiveNumbers, doubleNumbers)
    * ```
    *
-   * @category Combinators
+   * @category combinators
    * @since 4.0.0
    */
   <InputL, PassL, FailL, InputR, PassR, FailR>(left: Filter<InputL, PassL, FailL>, right: Filter<InputR, PassR, FailR>): Filter<InputL & InputR, PassR, FailL | FailR>
@@ -807,7 +807,7 @@ export const andRight: {
  * const stringToUpper = Filter.compose(stringFilter, nonEmptyUpper)
  * ```
  *
- * @category Combinators
+ * @category combinators
  * @since 4.0.0
  */
 export const compose: {
@@ -827,7 +827,7 @@ export const compose: {
    * const stringToUpper = Filter.compose(stringFilter, nonEmptyUpper)
    * ```
    *
-   * @category Combinators
+   * @category combinators
    * @since 4.0.0
    */
   <PassL, PassR, FailR>(right: Filter<PassL, PassR, FailR>): <InputL, FailL>(left: Filter<InputL, PassL, FailL>) => Filter<InputL, PassR, FailL | FailR>
@@ -847,7 +847,7 @@ export const compose: {
    * const stringToUpper = Filter.compose(stringFilter, nonEmptyUpper)
    * ```
    *
-   * @category Combinators
+   * @category combinators
    * @since 4.0.0
    */
   <InputL, PassL, FailL, PassR, FailR>(left: Filter<InputL, PassL, FailL>, right: Filter<PassL, PassR, FailR>): Filter<InputL, PassR, FailL | FailR>
@@ -868,7 +868,7 @@ export const compose: {
  * If either filter fails, the returned filter fails with the original input
  * instead of the intermediate failure value.
  *
- * @category Combinators
+ * @category combinators
  * @since 4.0.0
  */
 export const composePassthrough: {
@@ -879,7 +879,7 @@ export const composePassthrough: {
    * If either filter fails, the returned filter fails with the original input
    * instead of the intermediate failure value.
    *
-   * @category Combinators
+   * @category combinators
    * @since 4.0.0
    */
   <InputL, PassL, PassR, FailR>(right: Filter<PassL, PassR, FailR>): <FailL>(left: Filter<InputL, PassL, FailL>) => Filter<InputL, PassR, InputL>
@@ -890,7 +890,7 @@ export const composePassthrough: {
    * If either filter fails, the returned filter fails with the original input
    * instead of the intermediate failure value.
    *
-   * @category Combinators
+   * @category combinators
    * @since 4.0.0
    */
   <InputL, PassL, FailL, PassR, FailR>(left: Filter<InputL, PassL, FailL>, right: Filter<PassL, PassR, FailR>): Filter<InputL, PassR, InputL>
@@ -910,7 +910,7 @@ export const composePassthrough: {
  * Converts a `Filter` into a function that returns `Some` for passed values
  * and `None` for filtered-out values.
  *
- * @category Conversions
+ * @category converting
  * @since 4.0.0
  */
 export const toOption = <A, Pass, Fail>(
@@ -925,7 +925,7 @@ export const toOption = <A, Pass, Fail>(
  * Converts a `Filter` into a function that returns the underlying
  * `Result.Result` for each input.
  *
- * @category Conversions
+ * @category converting
  * @since 4.0.0
  */
 export const toResult = <A, Pass, Fail>(

package/src/Formatter.ts

@@ -80,7 +80,7 @@ import { getRedacted, redact, symbolRedactable } from "./Redactable.ts"
  *
  * See also: {@link format}, {@link formatJson}
  *
- * @category Model
+ * @category models
  * @since 4.0.0
  */
 export interface Formatter<in Value, out Format = string> {
@@ -156,7 +156,8 @@ export interface Formatter<in Value, out Format = string> {
  *
  * See also: {@link formatJson}, {@link Formatter}
  *
- * @since 4.0.0
+ * @category formatting
+ * @since 2.0.0
  */
 export function format(input: unknown, options?: {
   readonly space?: number | string | undefined
@@ -246,30 +247,6 @@ export function format(input: unknown, options?: {
 const CIRCULAR = "[Circular]"
 
 /**
- * Formats a single property key for display.
- *
- * When to use:
- * - You are building a custom formatter that needs to render object keys.
- *
- * Behavior:
- * - String keys are JSON-quoted (e.g. `"foo"`).
- * - Symbol and number keys are converted with `String()`.
- * - Pure function; does not mutate input.
- *
- * **Example** (Format property keys)
- *
- * ```ts
- * import { Formatter } from "effect"
- *
- * console.log(Formatter.formatPropertyKey("name"))
- * // "name"
- *
- * console.log(Formatter.formatPropertyKey(Symbol.for("id")))
- * // Symbol(id)
- * ```
- *
- * See also: {@link formatPath}, {@link format}
- *
  * @internal
  */
 export function formatPropertyKey(name: PropertyKey): string {
@@ -279,27 +256,6 @@ export function formatPropertyKey(name: PropertyKey): string {
 /**
  * Formats an array of property keys as a bracket-notation path string.
  *
- * When to use:
- * - You need to display a path through a nested object (e.g. in error
- *   messages or schema validation output).
- *
- * Behavior:
- * - Each key is wrapped in brackets and formatted via
- *   {@link formatPropertyKey}.
- * - Returns an empty string for an empty path.
- * - Pure function; does not mutate input.
- *
- * **Example** (Render a property path)
- *
- * ```ts
- * import { Formatter } from "effect"
- *
- * console.log(Formatter.formatPath(["users", 0, "name"]))
- * // ["users"][0]["name"]
- * ```
- *
- * See also: {@link formatPropertyKey}, {@link format}
- *
  * @internal
  */
 export function formatPath(path: ReadonlyArray<PropertyKey>): string {
@@ -310,29 +266,6 @@ export function formatPath(path: ReadonlyArray<PropertyKey>): string {
  * Formats a `Date` as an ISO 8601 string, returning `"Invalid Date"` for
  * invalid dates instead of throwing.
  *
- * When to use:
- * - You want a safe `toISOString()` that never throws.
- *
- * Behavior:
- * - Returns `date.toISOString()` on success.
- * - Returns `"Invalid Date"` if `toISOString()` throws (e.g. for
- *   `new Date(NaN)`).
- * - Pure function; does not mutate input.
- *
- * **Example** (Safe date formatting)
- *
- * ```ts
- * import { Formatter } from "effect"
- *
- * console.log(Formatter.formatDate(new Date("2024-01-15T10:30:00Z")))
- * // 2024-01-15T10:30:00.000Z
- *
- * console.log(Formatter.formatDate(new Date("invalid")))
- * // Invalid Date
- * ```
- *
- * See also: {@link format}
- *
  * @internal
  */
 export function formatDate(date: Date): string {
@@ -409,6 +342,7 @@ function safeToString(input: any): string {
  *
  * See also: {@link format}, {@link Formatter}
  *
+ * @category serialization
  * @since 4.0.0
  */
 export function formatJson(input: unknown, options?: {