@effect/platform 0.66.2 → 0.66.3

package/src/HttpClient.ts

@@ -94,9 +94,17 @@ export const HttpClient: Context.Tag<HttpClient.Service, HttpClient.Service> = i
  * @category error handling
  */
 export const catchAll: {
+  /**
+   * @since 1.0.0
+   * @category error handling
+   */
   <E, E2, R2, A2>(
     f: (e: E) => Effect.Effect<A2, E2, R2>
   ): <A, R>(self: HttpClient<A, E, R>) => HttpClient<A2 | A, E2, R2 | R>
+  /**
+   * @since 1.0.0
+   * @category error handling
+   */
   <A, E, R, A2, E2, R2>(
     self: HttpClient<A, E, R>,
     f: (e: E) => Effect.Effect<A2, E2, R2>
@@ -108,10 +116,18 @@ export const catchAll: {
  * @category error handling
  */
 export const catchTag: {
+  /**
+   * @since 1.0.0
+   * @category error handling
+   */
   <E extends { _tag: string }, K extends E["_tag"] & string, A1, E1, R1>(
     tag: K,
     f: (e: Extract<E, { _tag: K }>) => Effect.Effect<A1, E1, R1>
   ): <A, R>(self: HttpClient<A, E, R>) => HttpClient<A1 | A, E1 | Exclude<E, { _tag: K }>, R1 | R>
+  /**
+   * @since 1.0.0
+   * @category error handling
+   */
   <A, E extends { _tag: string }, R, K extends E["_tag"] & string, A1, E1, R1>(
     self: HttpClient<A, E, R>,
     tag: K,
@@ -124,12 +140,14 @@ export const catchTag: {
  * @category error handling
  */
 export const catchTags: {
+  /**
+   * @since 1.0.0
+   * @category error handling
+   */
   <
     E extends { _tag: string },
     Cases extends { [K in E["_tag"]]+?: ((error: Extract<E, { _tag: K }>) => Effect.Effect<any, any, any>) | undefined }
-  >(
-    cases: Cases
-  ): <A, R>(
+  >(cases: Cases): <A, R>(
     self: HttpClient<A, E, R>
   ) => HttpClient<
     | A
@@ -145,15 +163,16 @@ export const catchTags: {
       [K in keyof Cases]: Cases[K] extends (...args: Array<any>) => Effect.Effect<any, any, infer R> ? R : never
     }[keyof Cases]
   >
+  /**
+   * @since 1.0.0
+   * @category error handling
+   */
   <
     A,
     E extends { _tag: string },
     R,
     Cases extends { [K in E["_tag"]]+?: ((error: Extract<E, { _tag: K }>) => Effect.Effect<any, any, any>) | undefined }
-  >(
-    self: HttpClient<A, E, R>,
-    cases: Cases
-  ): HttpClient<
+  >(self: HttpClient<A, E, R>, cases: Cases): HttpClient<
     | A
     | {
       [K in keyof Cases]: Cases[K] extends (...args: Array<any>) => Effect.Effect<infer A, any, any> ? A : never
@@ -176,21 +195,45 @@ export const catchTags: {
  * @category filters
  */
 export const filterOrElse: {
+  /**
+   * Filters the result of a response, or runs an alternative effect if the predicate fails.
+   *
+   * @since 1.0.0
+   * @category filters
+   */
   <A, B extends A, C, E2, R2>(
     refinement: Predicate.Refinement<NoInfer<A>, B>,
     orElse: (a: NoInfer<A>) => Effect.Effect<C, E2, R2>
   ): <E, R>(self: HttpClient<A, E, R>) => HttpClient<B | C, E | E2, R | R2>
+  /**
+   * Filters the result of a response, or runs an alternative effect if the predicate fails.
+   *
+   * @since 1.0.0
+   * @category filters
+   */
   <A, B, E2, R2>(
     predicate: Predicate.Predicate<NoInfer<A>>,
     orElse: (a: NoInfer<A>) => Effect.Effect<B, E2, R2>
   ): <E, R>(
     self: HttpClient<A, E, R>
   ) => HttpClient<A | B, E2 | E, R2 | R>
+  /**
+   * Filters the result of a response, or runs an alternative effect if the predicate fails.
+   *
+   * @since 1.0.0
+   * @category filters
+   */
   <A, E, R, B extends A, C, E2, R2>(
     self: HttpClient<A, E, R>,
     refinement: Predicate.Refinement<A, B>,
     orElse: (a: A) => Effect.Effect<C, E2, R2>
   ): HttpClient<B | C, E | E2, R | R2>
+  /**
+   * Filters the result of a response, or runs an alternative effect if the predicate fails.
+   *
+   * @since 1.0.0
+   * @category filters
+   */
   <A, E, R, B, E2, R2>(
     self: HttpClient<A, E, R>,
     predicate: Predicate.Predicate<A>,
@@ -205,19 +248,43 @@ export const filterOrElse: {
  * @category filters
  */
 export const filterOrFail: {
+  /**
+   * Filters the result of a response, or throws an error if the predicate fails.
+   *
+   * @since 1.0.0
+   * @category filters
+   */
   <A, B extends A, E2>(
     refinement: Predicate.Refinement<NoInfer<A>, B>,
     orFailWith: (a: NoInfer<A>) => E2
   ): <E, R>(self: HttpClient<A, E, R>) => HttpClient<B, E | E2, R>
+  /**
+   * Filters the result of a response, or throws an error if the predicate fails.
+   *
+   * @since 1.0.0
+   * @category filters
+   */
   <A, E2>(
     predicate: Predicate.Predicate<NoInfer<A>>,
     orFailWith: (a: NoInfer<A>) => E2
   ): <E, R>(self: HttpClient<A, E, R>) => HttpClient<A, E2 | E, R>
+  /**
+   * Filters the result of a response, or throws an error if the predicate fails.
+   *
+   * @since 1.0.0
+   * @category filters
+   */
   <A, B extends A, E, R, E2>(
     self: HttpClient<A, E, R>,
     refinement: Predicate.Refinement<A, B>,
     orFailWith: (a: A) => E2
   ): HttpClient<B, E2 | E, R>
+  /**
+   * Filters the result of a response, or throws an error if the predicate fails.
+   *
+   * @since 1.0.0
+   * @category filters
+   */
   <A, E, R, E2>(
     self: HttpClient<A, E, R>,
     predicate: Predicate.Predicate<A>,
@@ -232,9 +299,21 @@ export const filterOrFail: {
  * @category filters
  */
 export const filterStatus: {
+  /**
+   * Filters responses by HTTP status code.
+   *
+   * @since 1.0.0
+   * @category filters
+   */
   (
     f: (status: number) => boolean
   ): <E, R>(self: HttpClient.WithResponse<E, R>) => HttpClient.WithResponse<E | Error.ResponseError, R>
+  /**
+   * Filters responses by HTTP status code.
+   *
+   * @since 1.0.0
+   * @category filters
+   */
   <E, R>(
     self: HttpClient.WithResponse<E, R>,
     f: (status: number) => boolean
@@ -278,9 +357,17 @@ export const makeService: (
  * @category mapping & sequencing
  */
 export const transform: {
+  /**
+   * @since 1.0.0
+   * @category mapping & sequencing
+   */
   <A, E, R, A1, E1, R1>(
     f: (effect: Effect.Effect<A, E, R>, request: ClientRequest.HttpClientRequest) => Effect.Effect<A1, E1, R1>
   ): (self: HttpClient<A, E, R>) => HttpClient<A1, E | E1, R | R1>
+  /**
+   * @since 1.0.0
+   * @category mapping & sequencing
+   */
   <A, E, R, A1, E1, R1>(
     self: HttpClient<A, E, R>,
     f: (effect: Effect.Effect<A, E, R>, request: ClientRequest.HttpClientRequest) => Effect.Effect<A1, E1, R1>
@@ -292,9 +379,17 @@ export const transform: {
  * @category mapping & sequencing
  */
 export const transformResponse: {
+  /**
+   * @since 1.0.0
+   * @category mapping & sequencing
+   */
   <A, E, R, A1, E1, R1>(
     f: (effect: Effect.Effect<A, E, R>) => Effect.Effect<A1, E1, R1>
   ): (self: HttpClient<A, E, R>) => HttpClient<A1, E1, R1>
+  /**
+   * @since 1.0.0
+   * @category mapping & sequencing
+   */
   <A, E, R, A1, E1, R1>(
     self: HttpClient<A, E, R>,
     f: (effect: Effect.Effect<A, E, R>) => Effect.Effect<A1, E1, R1>
@@ -308,7 +403,19 @@ export const transformResponse: {
  * @category mapping & sequencing
  */
 export const map: {
+  /**
+   * Transforms the result of a request.
+   *
+   * @since 1.0.0
+   * @category mapping & sequencing
+   */
   <A, B>(f: (a: A) => B): <E, R>(self: HttpClient<A, E, R>) => HttpClient<B, E, R>
+  /**
+   * Transforms the result of a request.
+   *
+   * @since 1.0.0
+   * @category mapping & sequencing
+   */
   <A, E, R, B>(self: HttpClient<A, E, R>, f: (a: A) => B): HttpClient<B, E, R>
 } = internal.map
 
@@ -319,9 +426,21 @@ export const map: {
  * @category mapping & sequencing
  */
 export const mapEffect: {
+  /**
+   * Transforms the result of a request using an effectful function.
+   *
+   * @since 1.0.0
+   * @category mapping & sequencing
+   */
   <A, B, E2, R2>(
     f: (a: A) => Effect.Effect<B, E2, R2>
   ): <E, R>(self: HttpClient<A, E, R>) => HttpClient<B, E2 | E, R2 | R>
+  /**
+   * Transforms the result of a request using an effectful function.
+   *
+   * @since 1.0.0
+   * @category mapping & sequencing
+   */
   <A, E, R, B, E2, R2>(self: HttpClient<A, E, R>, f: (a: A) => Effect.Effect<B, E2, R2>): HttpClient<B, E | E2, R2 | R>
 } = internal.mapEffect
 
@@ -332,9 +451,21 @@ export const mapEffect: {
  * @category mapping & sequencing
  */
 export const mapRequest: {
+  /**
+   * Appends a transformation of the request object before sending it.
+   *
+   * @since 1.0.0
+   * @category mapping & sequencing
+   */
   (
     f: (a: ClientRequest.HttpClientRequest) => ClientRequest.HttpClientRequest
   ): <A, E, R>(self: HttpClient<A, E, R>) => HttpClient<A, E, R>
+  /**
+   * Appends a transformation of the request object before sending it.
+   *
+   * @since 1.0.0
+   * @category mapping & sequencing
+   */
   <A, E, R>(
     self: HttpClient<A, E, R>,
     f: (a: ClientRequest.HttpClientRequest) => ClientRequest.HttpClientRequest
@@ -348,9 +479,21 @@ export const mapRequest: {
  * @category mapping & sequencing
  */
 export const mapRequestEffect: {
+  /**
+   * Appends an effectful transformation of the request object before sending it.
+   *
+   * @since 1.0.0
+   * @category mapping & sequencing
+   */
   <E2, R2>(
     f: (a: ClientRequest.HttpClientRequest) => Effect.Effect<ClientRequest.HttpClientRequest, E2, R2>
   ): <A, E, R>(self: HttpClient<A, E, R>) => HttpClient<A, E2 | E, R2 | R>
+  /**
+   * Appends an effectful transformation of the request object before sending it.
+   *
+   * @since 1.0.0
+   * @category mapping & sequencing
+   */
   <A, E, R, E2, R2>(
     self: HttpClient<A, E, R>,
     f: (a: ClientRequest.HttpClientRequest) => Effect.Effect<ClientRequest.HttpClientRequest, E2, R2>
@@ -364,9 +507,21 @@ export const mapRequestEffect: {
  * @category mapping & sequencing
  */
 export const mapRequestInput: {
+  /**
+   * Prepends a transformation of the request object before sending it.
+   *
+   * @since 1.0.0
+   * @category mapping & sequencing
+   */
   (
     f: (a: ClientRequest.HttpClientRequest) => ClientRequest.HttpClientRequest
   ): <A, E, R>(self: HttpClient<A, E, R>) => HttpClient<A, E, R>
+  /**
+   * Prepends a transformation of the request object before sending it.
+   *
+   * @since 1.0.0
+   * @category mapping & sequencing
+   */
   <A, E, R>(
     self: HttpClient<A, E, R>,
     f: (a: ClientRequest.HttpClientRequest) => ClientRequest.HttpClientRequest
@@ -380,9 +535,21 @@ export const mapRequestInput: {
  * @category mapping & sequencing
  */
 export const mapRequestInputEffect: {
+  /**
+   * Prepends an effectful transformation of the request object before sending it.
+   *
+   * @since 1.0.0
+   * @category mapping & sequencing
+   */
   <E2, R2>(
     f: (a: ClientRequest.HttpClientRequest) => Effect.Effect<ClientRequest.HttpClientRequest, E2, R2>
   ): <A, E, R>(self: HttpClient<A, E, R>) => HttpClient<A, E2 | E, R2 | R>
+  /**
+   * Prepends an effectful transformation of the request object before sending it.
+   *
+   * @since 1.0.0
+   * @category mapping & sequencing
+   */
   <A, E, R, E2, R2>(
     self: HttpClient<A, E, R>,
     f: (a: ClientRequest.HttpClientRequest) => Effect.Effect<ClientRequest.HttpClientRequest, E2, R2>
@@ -419,14 +586,70 @@ export declare namespace Retry {
  * @category error handling
  */
 export const retry: {
+  /**
+   * Retries the request based on a provided schedule or policy.
+   *
+   * @since 1.0.0
+   * @category error handling
+   */
   <E, O extends Effect.Retry.Options<E>>(options: O): <A, R>(self: HttpClient<A, E, R>) => Retry.Return<R, E, A, O>
+  /**
+   * Retries the request based on a provided schedule or policy.
+   *
+   * @since 1.0.0
+   * @category error handling
+   */
   <B, E, R1>(
     policy: Schedule.Schedule<B, NoInfer<E>, R1>
   ): <A, R>(self: HttpClient<A, E, R>) => HttpClient<A, E, R1 | R>
+  /**
+   * Retries the request based on a provided schedule or policy.
+   *
+   * @since 1.0.0
+   * @category error handling
+   */
   <A, E, R, O extends Effect.Retry.Options<E>>(self: HttpClient<A, E, R>, options: O): Retry.Return<R, E, A, O>
+  /**
+   * Retries the request based on a provided schedule or policy.
+   *
+   * @since 1.0.0
+   * @category error handling
+   */
   <A, E, R, B, R1>(self: HttpClient<A, E, R>, policy: Schedule.Schedule<B, E, R1>): HttpClient<A, E, R1 | R>
 } = internal.retry
 
+/**
+ * Retries common transient errors, such as rate limiting or network issues.
+ *
+ * @since 1.0.0
+ * @category error handling
+ */
+export const retryTransient: {
+  /**
+   * Retries common transient errors, such as rate limiting or network issues.
+   *
+   * @since 1.0.0
+   * @category error handling
+   */
+  <B, E, R1 = never>(
+    options:
+      | { readonly schedule?: Schedule.Schedule<B, NoInfer<E>, R1>; readonly times?: number }
+      | Schedule.Schedule<B, NoInfer<E>, R1>
+  ): <A, R>(self: HttpClient<A, E, R>) => HttpClient<A, E, R1 | R>
+  /**
+   * Retries common transient errors, such as rate limiting or network issues.
+   *
+   * @since 1.0.0
+   * @category error handling
+   */
+  <A, E, R, B, R1 = never>(
+    self: HttpClient<A, E, R>,
+    options:
+      | { readonly schedule?: Schedule.Schedule<B, NoInfer<E>, R1>; readonly times?: number }
+      | Schedule.Schedule<B, NoInfer<E>, R1>
+  ): HttpClient<A, E, R1 | R>
+} = internal.retryTransient
+
 /**
  * Ensures resources are properly scoped and released after execution.
  *
@@ -442,14 +665,23 @@ export const scoped: <A, E, R>(self: HttpClient<A, E, R>) => HttpClient<A, E, Ex
  * @category schema
  */
 export const schemaFunction: {
-  <SA, SI, SR>(
-    schema: Schema.Schema<SA, SI, SR>,
-    options?: ParseOptions | undefined
-  ): <A, E, R>(
+  /**
+   * Creates a function that validates request data against a schema before sending it.
+   *
+   * @since 1.0.0
+   * @category schema
+   */
+  <SA, SI, SR>(schema: Schema.Schema<SA, SI, SR>, options?: ParseOptions | undefined): <A, E, R>(
     self: HttpClient<A, E, R>
   ) => (
     request: ClientRequest.HttpClientRequest
   ) => (a: SA) => Effect.Effect<A, Error.RequestError | E | ParseResult.ParseError, SR | R>
+  /**
+   * Creates a function that validates request data against a schema before sending it.
+   *
+   * @since 1.0.0
+   * @category schema
+   */
   <A, E, R, SA, SI, SR>(
     self: HttpClient<A, E, R>,
     schema: Schema.Schema<SA, SI, SR>,
@@ -466,9 +698,21 @@ export const schemaFunction: {
  * @category mapping & sequencing
  */
 export const tap: {
+  /**
+   * Performs an additional effect after a successful request.
+   *
+   * @since 1.0.0
+   * @category mapping & sequencing
+   */
   <A, _, E2, R2>(
     f: (a: A) => Effect.Effect<_, E2, R2>
   ): <E, R>(self: HttpClient<A, E, R>) => HttpClient<A, E2 | E, R2 | R>
+  /**
+   * Performs an additional effect after a successful request.
+   *
+   * @since 1.0.0
+   * @category mapping & sequencing
+   */
   <A, E, R, _, E2, R2>(self: HttpClient<A, E, R>, f: (a: A) => Effect.Effect<_, E2, R2>): HttpClient<A, E | E2, R2 | R>
 } = internal.tap
 
@@ -479,9 +723,21 @@ export const tap: {
  * @category mapping & sequencing
  */
 export const tapRequest: {
+  /**
+   * Performs an additional effect on the request before sending it.
+   *
+   * @since 1.0.0
+   * @category mapping & sequencing
+   */
   <_, E2, R2>(
     f: (a: ClientRequest.HttpClientRequest) => Effect.Effect<_, E2, R2>
   ): <A, E, R>(self: HttpClient<A, E, R>) => HttpClient<A, E2 | E, R2 | R>
+  /**
+   * Performs an additional effect on the request before sending it.
+   *
+   * @since 1.0.0
+   * @category mapping & sequencing
+   */
   <A, E, R, _, E2, R2>(
     self: HttpClient<A, E, R>,
     f: (a: ClientRequest.HttpClientRequest) => Effect.Effect<_, E2, R2>
@@ -495,7 +751,19 @@ export const tapRequest: {
  * @category cookies
  */
 export const withCookiesRef: {
+  /**
+   * Associates a `Ref` of cookies with the client for handling cookies across requests.
+   *
+   * @since 1.0.0
+   * @category cookies
+   */
   (ref: Ref<Cookies>): <E, R>(self: HttpClient.WithResponse<E, R>) => HttpClient.WithResponse<E, R>
+  /**
+   * Associates a `Ref` of cookies with the client for handling cookies across requests.
+   *
+   * @since 1.0.0
+   * @category cookies
+   */
   <E, R>(self: HttpClient.WithResponse<E, R>, ref: Ref<Cookies>): HttpClient.WithResponse<E, R>
 } = internal.withCookiesRef
 
@@ -506,7 +774,19 @@ export const withCookiesRef: {
  * @category redirects
  */
 export const followRedirects: {
+  /**
+   * Follows HTTP redirects up to a specified number of times.
+   *
+   * @since 1.0.0
+   * @category redirects
+   */
   (maxRedirects?: number | undefined): <E, R>(self: HttpClient.WithResponse<E, R>) => HttpClient.WithResponse<E, R>
+  /**
+   * Follows HTTP redirects up to a specified number of times.
+   *
+   * @since 1.0.0
+   * @category redirects
+   */
   <E, R>(self: HttpClient.WithResponse<E, R>, maxRedirects?: number | undefined): HttpClient.WithResponse<E, R>
 } = internal.followRedirects
 
@@ -524,9 +804,21 @@ export const currentTracerDisabledWhen: FiberRef.FiberRef<Predicate.Predicate<Cl
  * @category fiber refs
  */
 export const withTracerDisabledWhen: {
+  /**
+   * Disables tracing for specific requests based on a provided predicate.
+   *
+   * @since 1.0.0
+   * @category fiber refs
+   */
   (
     predicate: Predicate.Predicate<ClientRequest.HttpClientRequest>
   ): <A, E, R>(effect: Effect.Effect<A, E, R>) => Effect.Effect<A, E, R>
+  /**
+   * Disables tracing for specific requests based on a provided predicate.
+   *
+   * @since 1.0.0
+   * @category fiber refs
+   */
   <A, E, R>(
     effect: Effect.Effect<A, E, R>,
     predicate: Predicate.Predicate<ClientRequest.HttpClientRequest>
@@ -546,7 +838,19 @@ export const currentTracerPropagation: FiberRef.FiberRef<boolean> = internal.cur
  * @category fiber refs
  */
 export const withTracerPropagation: {
+  /**
+   * Enables or disables tracing propagation for the request.
+   *
+   * @since 1.0.0
+   * @category fiber refs
+   */
   (enabled: boolean): <A, E, R>(effect: Effect.Effect<A, E, R>) => Effect.Effect<A, E, R>
+  /**
+   * Enables or disables tracing propagation for the request.
+   *
+   * @since 1.0.0
+   * @category fiber refs
+   */
   <A, E, R>(effect: Effect.Effect<A, E, R>, enabled: boolean): Effect.Effect<A, E, R>
 } = internal.withTracerPropagation
 

package/src/HttpClientError.ts

@@ -2,6 +2,7 @@
  * @since 1.0.0
  */
 import * as Error from "@effect/platform/Error"
+import { hasProperty } from "effect/Predicate"
 import type * as ClientRequest from "./HttpClientRequest.js"
 import type * as ClientResponse from "./HttpClientResponse.js"
 import * as internal from "./internal/httpClientError.js"
@@ -18,6 +19,12 @@ export const TypeId: unique symbol = internal.TypeId
  */
 export type TypeId = typeof TypeId
 
+/**
+ * @since 1.0.0
+ * @category guards
+ */
+export const isHttpClientError = (u: unknown): u is HttpClientError => hasProperty(u, TypeId)
+
 /**
  * @since 1.0.0
  * @category error